@zhin.js/game-shared 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# @zhin.js/game-shared
+
+Zhin.js 游戏插件通用工具包，提供网格棋盘、会话管理等通用抽象。
+
+## 安装
+
+```bash
+pnpm add @zhin.js/game-shared
+```
+
+## 功能
+
+### 网格键盘 (`grid-keyboard.ts`)
+
+构建任意尺寸的按钮网格棋盘（井字棋、五子棋等）。
+
+### 选项键盘 (`choice-keyboard.ts`)
+
+构建分支选项按钮（文字冒险、问答、剧情选择等）：
+
+```typescript
+import { buildChoiceKeyboard, parseChoicePayload } from '@zhin.js/game-shared';
+
+const content = buildChoiceKeyboard({
+  gamePrefix: 'adv',
+  sessionId: 's123',
+  narrative: '石门在前，雾霭缭绕……',
+  choices: [
+    { id: 'enter', label: '🚪 推门而入' },
+    { id: 'leave', label: '🏃 离开', style: 'danger' },
+  ],
+  buttonsPerRow: 2,
+  fallbackHint: '回复数字选择',
+});
+```
+
+```typescript
+import { buildGridKeyboard, parseGridPayload, parseCellButtonId } from '@zhin.js/game-shared';
+
+// 构建 3×3 井字棋键盘
+const content = buildGridKeyboard({
+  gamePrefix: 'ttt',
+  sessionId: 's123',
+  rows: 3,
+  cols: 3,
+  cells: board.map((state, i) => ({
+    state,
+    label: state === 0 ? '·' : state === 1 ? '✕' : '○',
+    disabled: state !== 0,
+  })),
+  statusLine: '轮到 玩家A (✕)',
+  omitAsciiBoard: message.$adapter === 'qq',
+  renderAscii: (cells, rows, cols) => { /* ... */ },
+  fallbackHint: '回复数字 1-9 落子',
+});
+
+// 解析 action payload
+const parsed = parseGridPayload('ttt:s123:4');
+// => { prefix: 'ttt', sessionId: 's123', cell: 4 }
+
+// 解析按钮 ID（QQ 等平台）
+const cell = parseCellButtonId('c4');
+// => 4
+```
+
+### 棋盘消息发送
+
+消息发送/编辑由 `Adapter.editMessage()` 统一处理：
+
+```typescript
+import { channelKey } from '@zhin.js/game-shared';
+import type { Adapter } from 'zhin.js';
+
+// 构建频道键
+const chKey = channelKey(message);
+
+// 发送或编辑棋盘消息（Adapter 层统一接口）
+const adapter = plugin.root.inject(message.$adapter) as Adapter;
+
+if (session.board_message_id) {
+  // Adapter.editMessage 内部处理平台差异：
+  // - 支持编辑的平台（Discord、Telegram）：调用平台 API 编辑
+  // - 不支持编辑的平台（QQ）：自动 fallback 到发送新消息
+  const msgId = await adapter.editMessage({
+    messageId: session.board_message_id,
+    context: message.$adapter,
+    endpoint: message.$endpoint,
+    id: message.$channel.id,
+    type: message.$channel.type,
+    content,
+  });
+} else {
+  const msgId = await message.$reply?.(content);
+}
+```
+
+### 游戏会话 (`game-session.ts`)
+
+通用回合制游戏会话接口：
+
+```typescript
+import {
+  type TurnBasedSession,
+  generateSessionId,
+  currentPlayerId,
+  isPlayerTurn,
+  nextTurn,
+} from '@zhin.js/game-shared';
+
+// 会话结构
+interface MyGameSession extends TurnBasedSession {
+  board: number[];
+}
+
+// 回合验证
+if (!isPlayerTurn(session, message.$sender.id)) {
+  return '还没轮到你';
+}
+
+// 切换回合
+session.turn = nextTurn(session.turn);
+```
+
+### 游戏大厅（`game` 服务）
+
+与 `addCommand` 同构：在 root 上注册 **`game` 服务**，通过 `usePlugin().registerGame()` 登记游戏。
+
+```typescript
+import { ensureGameHubService } from '@zhin.js/game-shared';
+import { usePlugin } from 'zhin.js';
+
+const plugin = usePlugin();
+ensureGameHubService(plugin); // 幂等，注册 game 服务
+
+const { registerGame } = plugin;
+
+registerGame({
+  id: 'my-game',
+  title: '我的游戏',
+  icon: '🎮',
+  description: '简介',
+  commandPrefix: '我的游戏',
+  menus: [{ id: 'start', label: '🎮 开始', style: 'primary' }],
+  runAction: async (actionId, ctx) => { /* ... */ },
+});
+```
+
+首个游戏 `registerGame` 后自动挂载 `游戏` / `game` 命令；卸载插件时 `onDispose` 对称清理。
+
+## 架构原则
+
+**平台能力封装在适配器层**：游戏代码不关心平台是否支持消息编辑，统一调用 `Adapter.editMessage()`，由各适配器内部决定是真编辑还是 fallback 到发新消息。
+
+**入站文本中间件**：须用 `registerGameTextMiddleware(plugin, …)` 注册到 **root**（子插件 `addMiddleware` 不会进入入站管线）。
+
+## 支持的游戏模式
+
+| 功能 | 井字棋 | 五子棋 | 四子棋 | ...  |
+|------|--------|--------|--------|------|
+| 网格尺寸 | 3×3 | 15×15 | 7×6 | 任意 |
+| 回合制 | ✓ | ✓ | ✓ | ✓ |
+| 人机 | ✓ | 可选 | 可选 | ✓ |
+| PvP 排队 | ✓ | ✓ | ✓ | ✓ |

package/lib/board-sender.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 游戏棋盘消息辅助工具
+ * 提供会话键生成和消息 ID 更新回调封装
+ *
+ * 注意：实际的发送/编辑逻辑由 Adapter.editMessage 统一处理
+ * - 支持编辑的平台：调用平台 API 编辑
+ * - 不支持编辑的平台：自动 fallback 到发送新消息
+ */
+import type { Message } from 'zhin.js';
+/**
+ * 构建频道唯一键（用于会话查找）
+ */
+export declare function channelKey(message: Message<any>): string;
+//# sourceMappingURL=board-sender.d.ts.map

package/lib/board-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-sender.d.ts","sourceRoot":"","sources":["../src/board-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAExD"}

package/lib/board-sender.js

@@ -0,0 +1,7 @@
+/**
+ * 构建频道唯一键（用于会话查找）
+ */
+export function channelKey(message) {
+    return `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+}
+//# sourceMappingURL=board-sender.js.map

package/lib/board-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-sender.js","sourceRoot":"","sources":["../src/board-sender.ts"],"names":[],"mappings":"AAUA;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAqB;IAC9C,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;AACpG,CAAC"}

package/lib/choice-keyboard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 选项式交互键盘（文字冒险、问答、剧情分支等）
+ */
+import { type SendContent } from 'zhin.js';
+export interface ChoiceOption {
+    /** 选项 ID，写入 payload */
+    id: string;
+    label: string;
+    disabled?: boolean;
+    style?: 'primary' | 'danger' | 'secondary';
+}
+export interface ChoiceKeyboardOptions {
+    gamePrefix: string;
+    sessionId: string;
+    /** 剧情/题干正文 */
+    narrative: string;
+    choices: ChoiceOption[];
+    terminal?: boolean;
+    /** 文本 fallback 提示 */
+    fallbackHint?: string;
+    /** 每行最多几个按钮（默认全部一行） */
+    buttonsPerRow?: number;
+}
+export declare function buildChoiceFallbackMap(gamePrefix: string, sessionId: string, choices: ChoiceOption[]): Record<string, string>;
+/**
+ * 构建选项键盘消息：正文 + 一行或多行按钮
+ */
+export declare function buildChoiceKeyboard(options: ChoiceKeyboardOptions): SendContent;
+/**
+ * 解析选项 payload：`{prefix}:{sessionId}:{choiceId}`
+ */
+export declare function parseChoicePayload(payload: string, expectedPrefix?: string): {
+    prefix: string;
+    sessionId: string;
+    choiceId: string;
+} | null;
+//# sourceMappingURL=choice-keyboard.d.ts.map

package/lib/choice-keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice-keyboard.d.ts","sourceRoot":"","sources":["../src/choice-keyboard.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;CAC5C;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,EAAE,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AAWD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,WAAW,CAkC/E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMhE"}

package/lib/choice-keyboard.js

@@ -0,0 +1,60 @@
+/**
+ * 选项式交互键盘（文字冒险、问答、剧情分支等）
+ */
+import { segment } from 'zhin.js';
+export function buildChoiceFallbackMap(gamePrefix, sessionId, choices) {
+    const map = {};
+    let n = 1;
+    for (const choice of choices) {
+        if (!choice.disabled) {
+            map[String(n)] = `${gamePrefix}:${sessionId}:${choice.id}`;
+            n++;
+        }
+    }
+    return map;
+}
+function chunkChoices(items, size) {
+    if (size <= 0 || items.length <= size)
+        return [items];
+    const rows = [];
+    for (let i = 0; i < items.length; i += size) {
+        rows.push(items.slice(i, i + size));
+    }
+    return rows;
+}
+/**
+ * 构建选项键盘消息：正文 + 一行或多行按钮
+ */
+export function buildChoiceKeyboard(options) {
+    const { gamePrefix, sessionId, narrative, choices, terminal, fallbackHint, buttonsPerRow, } = options;
+    const enabled = choices.filter((c) => !c.disabled);
+    const buttonRows = chunkChoices(enabled, buttonsPerRow ?? enabled.length).map((row) => row.map((choice) => segment.button({
+        id: choice.id,
+        label: choice.label,
+        payload: `${gamePrefix}:${sessionId}:${choice.id}`,
+        disabled: terminal || choice.disabled,
+        style: choice.style ?? 'secondary',
+    })));
+    const fallback = buildChoiceFallbackMap(gamePrefix, sessionId, choices);
+    return [
+        segment.text(narrative),
+        segment.keyboard(buttonRows, {
+            fallback: fallbackHint && Object.keys(fallback).length > 0
+                ? { hint: fallbackHint, map: fallback }
+                : undefined,
+        }).toElement(),
+    ];
+}
+/**
+ * 解析选项 payload：`{prefix}:{sessionId}:{choiceId}`
+ */
+export function parseChoicePayload(payload, expectedPrefix) {
+    const m = /^([a-z0-9_]+):([^:]+):([a-z0-9_-]+)$/i.exec(payload);
+    if (!m)
+        return null;
+    const prefix = m[1];
+    if (expectedPrefix && prefix !== expectedPrefix)
+        return null;
+    return { prefix, sessionId: m[2], choiceId: m[3] };
+}
+//# sourceMappingURL=choice-keyboard.js.map

package/lib/choice-keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice-keyboard.js","sourceRoot":"","sources":["../src/choice-keyboard.ts"],"names":[],"mappings":"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"}

package/lib/game-action-alias.d.ts

@@ -0,0 +1,8 @@
+export declare function normalizeTttAction(raw: string): string;
+export declare function normalizeAdvAction(raw: string): string;
+export declare function normalizeRpsAction(raw: string): string;
+export declare function normalizeGuessAction(raw: string): string;
+export declare function normalizeDiceAction(raw: string): string;
+export declare function normalizeChainAction(raw: string): string;
+export declare function normalizeRiddleAction(raw: string): string;
+//# sourceMappingURL=game-action-alias.d.ts.map

package/lib/game-action-alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-action-alias.d.ts","sourceRoot":"","sources":["../src/game-action-alias.ts"],"names":[],"mappings":"AAsEA,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAkCD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/lib/game-action-alias.js

@@ -0,0 +1,117 @@
+const TTT_ACTIONS = {
+    bot: 'bot',
+    join: 'join',
+    leave: 'leave',
+    quit: 'quit',
+    spectate: 'spectate',
+    help: 'help',
+    人机: 'bot',
+    排队: 'join',
+    加入: 'join',
+    离开: 'leave',
+    认输: 'quit',
+    观战: 'spectate',
+    帮助: 'help',
+};
+const ADV_ACTIONS = {
+    start: 'start',
+    continue: 'continue',
+    map: 'map',
+    achievements: 'achievements',
+    achievement: 'achievements',
+    quit: 'quit',
+    help: 'help',
+    开始: 'start',
+    继续: 'continue',
+    地图: 'map',
+    成就: 'achievements',
+    放弃: 'quit',
+    退出: 'quit',
+    帮助: 'help',
+};
+const RPS_ACTIONS = {
+    start: 'start',
+    continue: 'continue',
+    quit: 'quit',
+    help: 'help',
+    开始: 'start',
+    继续: 'continue',
+    放弃: 'quit',
+    帮助: 'help',
+};
+const GUESS_ACTIONS = {
+    start: 'start',
+    quit: 'quit',
+    help: 'help',
+    开始: 'start',
+    放弃: 'quit',
+    帮助: 'help',
+};
+const DICE_ACTIONS = {
+    start: 'start',
+    continue: 'continue',
+    quit: 'quit',
+    help: 'help',
+    开始: 'start',
+    继续: 'continue',
+    放弃: 'quit',
+    帮助: 'help',
+};
+function lookup(map, raw) {
+    const t = raw.trim();
+    if (!t)
+        return 'help';
+    return map[t] ?? map[t.toLowerCase()] ?? t.toLowerCase();
+}
+export function normalizeTttAction(raw) {
+    return lookup(TTT_ACTIONS, raw);
+}
+export function normalizeAdvAction(raw) {
+    return lookup(ADV_ACTIONS, raw);
+}
+export function normalizeRpsAction(raw) {
+    return lookup(RPS_ACTIONS, raw);
+}
+export function normalizeGuessAction(raw) {
+    return lookup(GUESS_ACTIONS, raw);
+}
+export function normalizeDiceAction(raw) {
+    return lookup(DICE_ACTIONS, raw);
+}
+const CHAIN_ACTIONS = {
+    start: 'start_pinyin',
+    start_pinyin: 'start_pinyin',
+    start_char: 'start_char',
+    continue: 'continue',
+    quit: 'quit',
+    help: 'help',
+    pinyin: 'start_pinyin',
+    char: 'start_char',
+    开始: 'start_pinyin',
+    同音: 'start_pinyin',
+    同字: 'start_char',
+    继续: 'continue',
+    放弃: 'quit',
+    帮助: 'help',
+};
+const RIDDLE_ACTIONS = {
+    start: 'start',
+    continue: 'continue',
+    quit: 'quit',
+    help: 'help',
+    char: 'char',
+    idiom: 'idiom',
+    开始: 'start',
+    继续: 'continue',
+    放弃: 'quit',
+    帮助: 'help',
+    字谜: 'char',
+    成语: 'idiom',
+};
+export function normalizeChainAction(raw) {
+    return lookup(CHAIN_ACTIONS, raw);
+}
+export function normalizeRiddleAction(raw) {
+    return lookup(RIDDLE_ACTIONS, raw);
+}
+//# sourceMappingURL=game-action-alias.js.map

package/lib/game-action-alias.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-action-alias.js","sourceRoot":"","sources":["../src/game-action-alias.ts"],"names":[],"mappings":"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"}

package/lib/game-hub-feature.d.ts

@@ -0,0 +1,58 @@
+import { Feature, type FeatureJSON, type Plugin, type PluginLike } from 'zhin.js';
+export interface GameHubContext {
+    plugin: Plugin;
+    message: import('zhin.js').Message<any>;
+}
+export interface GameMenuAction {
+    id: string;
+    label: string;
+    style?: 'primary' | 'danger' | 'secondary';
+    groupOnly?: boolean;
+    privateOnly?: boolean;
+}
+export interface RegisteredGame {
+    id: string;
+    title: string;
+    icon: string;
+    description: string;
+    commandPrefix: string;
+    quickStart?: string;
+    aliases?: string[];
+    menus: GameMenuAction[];
+    runAction: (actionId: string, ctx: GameHubContext) => Promise<string | undefined | void>;
+}
+export interface GameHubContextExtensions {
+    registerGame(game: RegisteredGame): () => void;
+}
+declare module 'zhin.js' {
+    namespace Plugin {
+        interface Extensions extends GameHubContextExtensions {
+        }
+        interface Contexts {
+            game: GameHubFeature;
+        }
+    }
+}
+export declare class GameHubFeature extends Feature<RegisteredGame> {
+    readonly name: "game";
+    readonly icon = "Gamepad2";
+    readonly desc = "\u6E38\u620F\u5927\u5385";
+    private readonly byId;
+    private hubDisposers;
+    register(game: RegisteredGame, pluginName: string): () => void;
+    getGame(id: string): RegisteredGame | undefined;
+    remove(item: RegisteredGame, pluginName?: string): boolean;
+    toJSON(pluginName?: string): FeatureJSON;
+    get extensions(): {
+        registerGame(game: RegisteredGame): () => void;
+    };
+    mounted(plugin: PluginLike): void;
+    dispose(): void;
+}
+/**
+ * 在 root 上注册 `game` 服务（幂等）。游戏插件初始化时调用一次即可。
+ */
+export declare function ensureGameHubService(plugin: Plugin): GameHubFeature;
+export declare function getRegisteredGames(): readonly RegisteredGame[];
+export declare function getRegisteredGame(id: string): RegisteredGame | undefined;
+//# sourceMappingURL=game-hub-feature.d.ts.map

package/lib/game-hub-feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-hub-feature.d.ts","sourceRoot":"","sources":["../src/game-hub-feature.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAEP,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,UAAU,EAChB,MAAM,SAAS,CAAC;AAGjB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC3C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;CAC1F;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,IAAI,CAAC;CAChD;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,MAAM,CAAC;QACf,UAAU,UAAW,SAAQ,wBAAwB;SAAG;QACxD,UAAU,QAAQ;YAChB,IAAI,EAAE,cAAc,CAAC;SACtB;KACF;CACF;AAID,qBAAa,cAAe,SAAQ,OAAO,CAAC,cAAc,CAAC;IACzD,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,IAAI,8BAAU;IAEvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqC;IAC1D,OAAO,CAAC,YAAY,CAAsB;IAE1C,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,IAAI;IAS9D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAItC,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO;IAKnE,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW;IAexC,IAAI,UAAU;2BAGS,cAAc,SApCqB,IAAI;MA6C7D;IAED,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOjC,OAAO,IAAI,IAAI;CAOhB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAenE;AAED,wBAAgB,kBAAkB,IAAI,SAAS,cAAc,EAAE,CAE9D;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAExE"}

package/lib/game-hub-feature.js

@@ -0,0 +1,89 @@
+import { Feature, getPlugin, } from 'zhin.js';
+import { mountGameHubUi, markGameHubUiMounted } from './game-hub-mount.js';
+let activeFeature = null;
+export class GameHubFeature extends Feature {
+    name = 'game';
+    icon = 'Gamepad2';
+    desc = '游戏大厅';
+    byId = new Map();
+    hubDisposers = [];
+    register(game, pluginName) {
+        const prev = this.byId.get(game.id);
+        if (prev) {
+            this.remove(prev);
+        }
+        this.byId.set(game.id, game);
+        return this.add(game, pluginName);
+    }
+    getGame(id) {
+        return this.byId.get(id);
+    }
+    remove(item, pluginName) {
+        this.byId.delete(item.id);
+        return super.remove(item, pluginName);
+    }
+    toJSON(pluginName) {
+        const list = pluginName ? this.getByPlugin(pluginName) : [...this.items];
+        return {
+            name: this.name,
+            icon: this.icon,
+            desc: this.desc,
+            count: list.length,
+            items: list.map((g) => ({
+                name: g.id,
+                desc: g.title,
+                usage: `${g.commandPrefix} ${g.quickStart ?? '开始'}`,
+            })),
+        };
+    }
+    get extensions() {
+        const feature = this;
+        return {
+            registerGame(game) {
+                const plugin = getPlugin();
+                ensureGameHubService(plugin);
+                const dispose = feature.register(game, plugin.name);
+                plugin.recordFeatureContribution(feature.name, game.id);
+                plugin.onDispose(dispose);
+                return dispose;
+            },
+        };
+    }
+    mounted(plugin) {
+        activeFeature = this;
+        const root = plugin;
+        this.hubDisposers = mountGameHubUi(root.root ?? root);
+        markGameHubUiMounted();
+    }
+    dispose() {
+        for (const d of this.hubDisposers)
+            d();
+        this.hubDisposers = [];
+        if (activeFeature === this) {
+            activeFeature = null;
+        }
+    }
+}
+/**
+ * 在 root 上注册 `game` 服务（幂等）。游戏插件初始化时调用一次即可。
+ */
+export function ensureGameHubService(plugin) {
+    const root = plugin.root;
+    if (root.contextIsReady('game')) {
+        return root.inject('game');
+    }
+    const feature = new GameHubFeature();
+    root.provide(feature);
+    activeFeature = feature;
+    if (root.started && feature.mounted) {
+        feature.mounted(root);
+    }
+    return root.inject('game');
+}
+export function getRegisteredGames() {
+    return activeFeature?.items ?? [];
+}
+export function getRegisteredGame(id) {
+    return activeFeature?.getGame(id);
+}
+//# sourceMappingURL=game-hub-feature.js.map

package/lib/game-hub-feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-hub-feature.js","sourceRoot":"","sources":["../src/game-hub-feature.ts"],"names":[],"mappings":"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"}

package/lib/game-hub-flow.d.ts

@@ -0,0 +1,9 @@
+import type { Message, Plugin } from 'zhin.js';
+import { buildMainHubMenu } from './game-hub-menu.js';
+export declare function openMainMenu(message: Message<any>): ReturnType<typeof buildMainHubMenu> | string;
+export declare function handleHubChoice(plugin: Plugin, message: Message<any>, scopeId: string, choiceId: string): Promise<boolean>;
+export declare function parseHubPayload(payload: string): {
+    scopeId: string;
+    choiceId: string;
+} | null;
+//# sourceMappingURL=game-hub-flow.d.ts.map

package/lib/game-hub-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-hub-flow.d.ts","sourceRoot":"","sources":["../src/game-hub-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAEL,gBAAgB,EAMjB,MAAM,oBAAoB,CAAC;AAkC5B,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,GAAG,MAAM,CAShG;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CA+ClB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI7F"}