# @m3rcena/weky 中文文档

规范地址：https://npmcn.com/package/%40m3rcena/weky/

版本：14\.28\.0
npm 元数据更新时间：2026-11-01T17:01:22.333Z
中文译文更新时间：2026-11-01T20:07:58.704Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40m3rcena/weky
原文对照：https://npmcn.com/package/%40m3rcena/weky/?lang=original
项目主页：https://github.com/M3rcena/m3rcena-weky#readme
源码仓库：https://github.com/M3rcena/m3rcena-weky

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.1 MB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：5 个
- 首次发布：2023-12-26T17:53:00.051Z
- 最新版本发布：2026-11-01T17:01:21.992Z
- 已发布版本数：74（近 12 个月 4 个）

## 中文简介

终极的Discord迷你游戏引擎，具有极快的@napi-rs/canvas图像，混合Slash/Message支持，以及零外部依赖。

## 安装

```sh
npm install @m3rcena/weky
```

也可以使用：`pnpm add @m3rcena/weky`、`yarn add @m3rcena/weky`、`bun add @m3rcena/weky`

## README

![Weky Logo](https://npmcn.com/package/%40m3rcena/weky/assets/logo.png)

# @m3rcena / weky

### 终极不和谐v14迷你游戏引擎

**极快的本地图形。严格的类型。零外部服务器依赖。**  
完全重制，现代游戏引擎的Discord机器人。

 [![NPM Version](https://img.shields.io/npm/v/@m3rcena/weky?style=for-the-badge&color=crimson)](https://www.npmjs.com/package/@m3rcena/weky)[![Downloads](https://img.shields.io/npm/dt/@m3rcena/weky?style=for-the-badge&color=success) ](https://www.npmjs.com/package/@m3rcena/weky)[![Discord Support](https://img.shields.io/discord/1447491639550410796?style=for-the-badge&label=Support&color=5865F2)](https://discord.gg/U4E2Pn2wyn)

![DJS v14](https://img.shields.io/badge/Discord.js-v14%20Ready-5865F2?style=flat-square&logo=discord) ![@napi-rs/canvas](https://img.shields.io/badge/Canvas-@napi--rs/canvas-orange?style=flat-square&logo=rust) ![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript) ![Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-green?style=flat-square)

* * *

## ⚡v14.28.0有什么新功能？

> **版本通知**： `@m3rcena/weky` 的版本号严格镜像 **`discord.js`** (现在 `14.28.0`）. 每当Discord.js发布更新时， `@m3rcena/weky` 发布一个相同的版本，以确保100%的API奇偶性，零对等依赖冲突，并即时支持Discord的最新功能，如 **组件V2**.

14.28.0版本引入了7个主要的、突破性的功能，使Discord游戏超越了简单的bot命令：

1.  🕹️ **街机中心(`weky.createArcadeHub`）**集中启动器将所有17个小游戏分成4个干净的类别，带有下拉菜单，街机游戏自定义(`gameOptions`)，以及互动赛前比赛设置界面(`configureBeforeLaunch: true`)，包括难度、boss和PvP对手选择。
2.  🏆 **自动锦标赛和帆布支架引擎(`weky.createTournament`）**：单淘汰赛（4至16名选手），直播 `@napi-rs/canvas` 分站赛，同时进行的预赛，以及公开的总决赛。
3.  🤖 **智能AI对手和RPG Boss决斗**：独自对抗Minimax TicTacToe AI，心理RPS预测器，或与3个独特的RPG boss战斗(_龙主权_， _网络的骑士_， _影子妖精_)在战斗！
4.  🔊 **Web Dashboard MP3 Soundboard Engine (`weky.soundboard`）**：高保真零延迟捆绑MP3音轨与播放器范围的目标(`targetUserIds`， `userId`)和主动仪表板状态过滤(`requireActiveDashboardUser`）。
5.  📈 **即插即用的ELO和Canvas排行榜(`weky.leaderboard`， `weky.renderLeaderboard`）**：数学ELO评级计算与开发人员自定义的指向和霓虹灯高分海报生成。
6.  🎟️ **“共享与灵活”玩家积分卡(`weky.renderShareCard`）**：可收集的全息玩家胜利票与自定义统计和排名徽章。
7.  🌐 **跨平台桥(`WekyBridge`）**：将Discord bot迷你游戏与web仪表板连接起来的双向实时状态同步。

* * *

## 🌟v14.28.0聚光灯功能和示例

### 🕹️1。Arcade Hub启动器

在一行代码中启动一个完整的街机柜接口！玩家可按类别浏览游戏(_经典的休闲游戏_， _PvP决斗_， _大脑与谜题_， _派对与社交_)，点击“🎲随机游戏”，或在启动前用互动按钮配置他们的比赛设置：

```typescript
// /arcade Slash Command or Message
await weky.createArcadeHub({
  context: interaction, // or message
  title: "Official Community Arcade Cabinet",
  configureBeforeLaunch: true, // Interactive setup screen with difficulty/boss/PvP buttons
  gameOptions: {
    fight: { startHealth: 250, embed: { title: "Arcade Colosseum Fight" } },
    tictactoe: { difficulty: "unbeatable", embed: { title: "Arcade TicTacToe" } },
    snake: { gridSize: 18 },
  },
});
```

### 🏆2。自动锦标赛和帆布支架

组织无缝4至16人的锦标赛与自动生成的可视化括号：

```typescript
await weky.createTournament({
  context: interaction,
  game: "tictactoe", // "tictactoe" | "rps" | "fight"
  players: [player1, player2, player3, player4], // User or GuildMember array
  title: "Autumn Invitational Cup 🏆",
});
```

### 🤖3。智能AI对手和Boss战斗

网上没有对手？独自对抗智能AI引擎！

```typescript
// Unbeatable Minimax Tic Tac Toe
await weky.createTicTacToe({
  context: interaction,
  ai: true,
  difficulty: "unbeatable", // "easy" | "medium" | "hard" | "unbeatable"
});

// Turn-Based RPG Fight vs Dragon Sovereign Boss
await weky.createFight({
  context: interaction,
  ai: true,
  boss: "dragon", // "dragon" | "cyber_knight" | "shadow_goblin"
});

// Psychological Rock Paper Scissors
await weky.createRPS({
  context: interaction,
  difficulty: "hard", // Heuristic win-stay / lose-shift predictor
});
```

### 📈4。即插即用的ELO和Canvas排行榜

使用标准FIDE公式计算ELO评级并渲染高分辨率街机海报：

```typescript
// 1. Record a 1v1 match outcome
const eloResult = await weky.leaderboard.recordMatch(
  winner.id,
  loser.id,
  "p1",
  { p1Username: winner.username, p2Username: loser.username }
);
console.log(`Winner ELO: ${eloResult.p1NewElo} (+${eloResult.p1Change})`);

// 2. Render an eSports-style High-Score Poster
const buffer = await weky.renderLeaderboard({
  title: "GLOBAL TOURNAMENT RANKINGS",
  subtitle: "SEASON 1 • TOP PLAYERS",
  entries: [
    { rank: 1, username: "Alice", scoreOrElo: "1,485 ELO", streak: 5 },
    { rank: 2, username: "Bob", scoreOrElo: "1,420 ELO", stats: "14W - 2L" },
  ],
});
```

### 🎟️5。“Share & Flex”玩家记分卡

生成可收集的玩家护照和胜利票：

```typescript
const ticketBuffer = await weky.renderShareCard({
  username: interaction.user.username,
  avatarUrl: interaction.user.displayAvatarURL({ extension: "png" }),
  gameName: "Retro Snake",
  headline: "NEW RECORD ACHIEVED! 🏆",
  primaryScore: "28,450 PTS",
  rankBadge: "GRANDMASTER",
  stats: [
    { label: "DIFFICULTY", value: "INSANE", color: "#ff4444" },
    { label: "APPLES", value: "94", color: "#57f287" },
    { label: "TIME", value: "11m 40s", color: "#00f7ff" },
    { label: "ACCURACY", value: "99.1%", color: "#ffd700" },
  ],
});
```

* * *

* * *

## 📚完整的文档和变更日志

寻找详尽的选项，回调签名，无头引擎挂钩，或画布渲染方法为所有17个小游戏？

-   📖 **[阅读完整文档（document .md）](https://npmcn.com/package/%40m3rcena/weky/DOCUMENTATION.md)**
-   📋 **[查看版本历史和变更日志（Changelog .md）](https://npmcn.com/package/%40m3rcena/weky/CHANGELOG.md)**

* * *

## 📦安装

```bash
npm install @m3rcena/weky @napi-rs/canvas discord.js
# or
yarn add @m3rcena/weky @napi-rs/canvas discord.js
# or
pnpm add @m3rcena/weky @napi-rs/canvas discord.js
```

* * *

## 🚀快速入门

### 1\. 初始化Weky Manager

```typescript
import { Client, GatewayIntentBits } from "discord.js";
import { WekyManager } from "@m3rcena/weky";

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent, GatewayIntentBits.GuildMessageTyping],
});

let weky: WekyManager;

client.once("ready", (c) => {
  console.log(`✅ ${c.user.tag} is online!`);
  // Initialize Weky with custom brand color, timeout, and update notifier
  weky = new WekyManager(c, {
    embedColor: "#5865F2", // Default brand color for all games
    defaultTimeout: 60_000, // Default timeout (ms)
    notifyUpdates: true, // Alerts in console when a new package version is on npm
  });
});

client.login("YOUR_BOT_TOKEN");
```

### 2\. 运行游戏（适用于斜杠命令和消息）

我们的环球 `ContextAdapter` 自动与 `ChatInputCommandInteraction`， `ButtonInteraction`，或标准 `Message`！

```typescript
// Inside your Slash Command or Message event:
await weky.create2048({
  context: interaction, // or message
  embed: {
    title: "2048 Challenge",
    color: "#5865F2", // Accepts Hex, Number (0x5865F2), or Discord color names
  },
});
```

### 3\. 终端更新通知框

当 `notifyUpdates` 启用（默认），Weky会在后台自动检查npm注册表，并在控制台中提醒你有更新可用：

```text
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│         New version of @m3rcena/weky is available!          │
│                     14.27.0 -> 14.28.0                      │
│    Registry: https://www.npmjs.com/package/@m3rcena/weky    │
│         Run npm i @m3rcena/weky@14.28.0 to update!          │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

* * *

## 🎮可选小游戏（17个游戏）

| 游戏 | 方法 | 描述 | 图形 |
| :-- | :-- | :-- | :-- |
| **2048** | `weky.create2048` | 滑动和合并瓷砖达到2048 | 🎨 `@napi-rs/canvas` |
| **蛇** | `weky.createSnake` | 带有d键控制的复古街机蛇 | 🎨 `@napi-rs/canvas` |
| **战斗RPG** | `weky.createFight` | 2人回合制战斗与武器和能量 | 🎨 `@napi-rs/canvas` |
| **刽子手** | `weky.createHangman` | 在绞刑架完成之前猜单词 | 🎨 `@napi-rs/canvas` |
| **猜猜poksammon** | `weky.createGuessThePokemon` | 标志性的“那个波克萨蒙是谁？”剪影测验 | 🎨 `@napi-rs/canvas` |
| **科学计算器** | `weky.createCalculator` | 全键盘计算器与公式模态 | 📟交互UI |
| **快速的类型** | `weky.createFastType` | 速度打字挑战与WPM计算和反作弊 | ⚡速度测试 |
| **混乱的词** | `weky.createChaosWords` | 搜索并发现嵌入在混乱文本中的单词 | 🧩拼图 |
| **猜猜数字** | `weky.createGuessTheNumber` | 单人模式或全通道模式的高/低范围线索 | 🔢逻辑 |
| **谎言苍蝇拍** | `weky.createLieSwatter` | 快速问答真心话或谎言，并附有解释 | 🧠琐事 |
| **我从来没有** | `weky.createNeverHaveIEver` | 团体投票派对游戏与现场百分比 | 👥社会 |
| **快速点击** | `weky.createQuickClick` | 反应速度游戏以毫秒计 | ⏱️反应 |
| **洗牌猜** | `weky.createShuffleGuess` | 用重新洗牌选项整理打乱的单词 | 🔀字谜游戏 |
| **你会按下按钮吗？** | `weky.createWillYouPressTheButton` | 全球社区统计的道德困境 | 🔘困境 |
| **你愿意吗？** | `weky.createWouldYouRather` | 选项A vs选项B，通过现场社区投票 | 🅰️🅱️选择 |
| **石头剪刀布** | `weky.createRPS` | 与Bot对抗或挑战其他用户 | 🪨📄✂️双模式 |
| **井字游戏** | `weky.createTicTacToe` | 交互式3x3回合制网格匹配 | ❌⭕策略 |

* * *

## 📖详细的游戏示例

### 🟢1。2048

使用方向按钮在4x4网格上滑动编号的瓷砖。内置高性能画布渲染。

```typescript
await weky.create2048({
  context: interaction,
  embed: { title: "2048 Arcade", color: "Blurple" },
  time: 120_000,
});
```

### 🐍2。蛇

直接在Discord中玩经典的蛇街机游戏。具有定向运动，发光苹果生成，碰撞检测和得分跟踪。

```typescript
await weky.createSnake({
  context: interaction,
  gridSize: 15,
  embed: { title: "Retro Snake", color: "Green" },
});
```

### ⚔️3。回合制RPG战斗

向对手挑战决斗！包括HP条，硬币收集，常规和重型攻击，治疗，盾牌升级，双重伤害buff和投降选项。

```typescript
const opponent = interaction.options.getUser("opponent");

await weky.createFight({
  context: interaction,
  opponent: opponent,
  embed: { title: "Battle Arena" },
});
```

### 🔎4。那个波克萨蒙是谁？

生成一个黑暗的波卡姆剪影在一个真正的波卡姆卡。玩家通过聊天或模式猜测，在胜利或暂停时显示充满活力的全彩poksammon ！

```typescript
await weky.createGuessThePokemon({
  context: interaction,
  embed: { title: "Who's That Pokémon?" },
  time: 60_000,
});
```

### 🪢5。刽子手

特色逼真的木架和棍棒绘图。支持类别，如动物，国家，技术，游戏和食品，或自定义词！

```typescript
await weky.createHangman({
  context: interaction,
  category: "Technology", // or custom word: { word: "DISCORD" }
});
```

### 🔢6。科学计算器

一个安全，功能齐全的Discord计算器，具有标准数字，括号，幂，根号，三角函数（sin, cos, tan），对数和模态公式输入。

```typescript
await weky.createCalculator({
  context: interaction,
  embed: { title: "Scientific Calculator", color: "Blurple" },
});
```

### ⚡7。快速的类型

计算简单、中等或困难文本的准确每分钟字数（WPM）。

```typescript
await weky.createFastType({
  context: interaction,
  difficulty: "medium", // 'easy' | 'medium' | 'hard'
});
```

* * *

## 🌐Web仪表板和无头引擎

`@m3rcena/weky` 不只是为Discord机器人准备的！您可以为web仪表板，移动应用程序，电子桌面应用程序和REST/WebSocket api提供动力 **无头游戏引擎** 和 **独立画布集线器**—— **不需要任何Discord依赖**.

### 🎮无头发动机厂(`WekyEngine`）

运行游戏逻辑，处理移动，提取与框架无关的UI控制模式：

```javascript
import { WekyEngine } from "@m3rcena/weky";

// 1. Initialize Headless 2048 Game
const game2048 = WekyEngine.game2048();

// Move tiles ("UP" | "DOWN" | "LEFT" | "RIGHT")
game2048.move("LEFT");

// Current game state
console.log(game2048.getState());
// -> { board: [[2, 4, ...], ...], score: 64, isGameOver: false, isWon: false }

// Universal UI Controls Schema (ideal for React, Vue, Svelte, or HTML buttons)
const controls = game2048.getControls();
// -> [{ components: [{ id: "UP", label: "▲", style: "primary", disabled: false }] }]

// Render high-res canvas directly to web-ready Data URL
const cardDataUrl = await game2048.renderDataURL();
// -> "data:image/png;base64,iVBORw0KGgoAAAANSUh..."
```

### 🎨直接画布渲染(`WekyCanvas`）

渲染任何小游戏卡直接到PNG缓冲区，base64字符串，或数据url：

```javascript
import { WekyCanvas } from "@m3rcena/weky";

// Render Battle Card between two players
const buffer = await WekyCanvas.fight.battle({ id: "1", username: "Knight", avatarUrl: "https://...", health: 85, coins: 30 }, { id: "2", username: "Dragon", avatarUrl: "https://...", health: 40, coins: 15 }, "1", "Knight used Heavy Attack for 28 damage!");

// Convert to web-ready Data URL for <img src="..." />
const dataUrl = WekyCanvas.toDataURL(buffer);
```

* * *

## 💡纯JavaScript类型安全和自动完成

使用普通JavaScript而不是TypeScript？你还是会得到 **100%严格的自动完成，内联悬停文档和智能感知** 在VS Code， WebStorm和Cursor！

-   **代码中不需要类型注释**编写标准的CommonJS `require` 或ESM `import`.
-   **JS消费者无需任何构建步骤**:发出 `.cjs` 和 `.js` 代码是纯JavaScript。
-   **丰富的参数建议**：全选项类型，表情符号和回调签名自动完成通过捆绑 `.d.ts` 和 `.d.mts` 宣言的地图。

* * *

## \[推荐\]️测试和开发

在所有数学解析器、画布渲染器、Components V2和无头仪表板引擎上运行自动验证套件：

```bash
npm run test
```

启动交互式测试机器人：

```bash
npm run test:bot
```

构建双ESM/CJS发行版：

```bash
npm run build
```

* * *

## 📄许可证

根据 **apache 2.0许可**． 看到 [许可证](https://npmcn.com/package/%40m3rcena/weky/LICENSE) 获取详细信息。

* * *

由❤️ **M3rcena**

## 常见问题

### @m3rcena/weky 是什么？

终极的Discord迷你游戏引擎，具有极快的@napi-rs/canvas图像，混合Slash/Message支持，以及零外部依赖。

### 如何安装 @m3rcena/weky？

在项目目录运行 npm install @m3rcena/weky，或使用 pnpm add / yarn add / bun add。

### @m3rcena/weky 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @m3rcena/weky 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @m3rcena/weky 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @m3rcena/weky 可以商用吗？

@m3rcena/weky 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @m3rcena/weky 还在维护吗？

最新版本 14\.28\.0 发布于 2026/11/02（1 天前）；至今共发布 74 个版本，其中过去 12 个月发布了 4 个；首次发布于 2023/12/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。