@zhin.js/game-kit 1.0.1

package/src/game-hub-feature.ts

@@ -0,0 +1,151 @@
+import { Feature, getPlugin, type FeatureJSON, type Plugin, type PluginLike, type DatabaseFeature } from '@zhin.js/core';
+import { mountGameHubUi, markGameHubUiMounted } from './game-hub-mount.js';
+import { registerGameRecordModels, initGameRecordDatabase } from './game-records.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/core' {
+  namespace Plugin {
+    interface Extensions extends GameHubContextExtensions {}
+    interface Contexts {
+      game: GameHubFeature;
+    }
+  }
+}
+
+let activeFeature: GameHubFeature | null = null;
+
+export class GameHubFeature extends Feature<RegisteredGame> {
+  readonly name = 'game' as const;
+  readonly icon = 'Gamepad2';
+  readonly desc = '游戏';
+
+  private readonly byId = new Map<string, RegisteredGame>();
+  private hubDisposers: (() => void)[] = [];
+
+  register(game: RegisteredGame, pluginName: string): () => void {
+    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: string): RegisteredGame | undefined {
+    return this.byId.get(id);
+  }
+
+  override remove(item: RegisteredGame, pluginName?: string): boolean {
+    this.byId.delete(item.id);
+    return super.remove(item, pluginName);
+  }
+
+  toJSON(pluginName?: string): FeatureJSON {
+    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: RegisteredGame) {
+        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: PluginLike): void {
+    activeFeature = this;
+    const root = plugin as Plugin;
+    const host = root.root ?? root;
+    registerGameRecordModels(host);
+    if (host.contextIsReady('database')) {
+      initGameRecordDatabase(host.inject('database') as DatabaseFeature);
+    } else {
+      host.useContext('database', (dbFeature: DatabaseFeature) => {
+        initGameRecordDatabase(dbFeature);
+      });
+    }
+    this.hubDisposers = mountGameHubUi(host);
+    markGameHubUiMounted();
+  }
+
+  dispose(): void {
+    for (const d of this.hubDisposers) d();
+    this.hubDisposers = [];
+    if (activeFeature === this) {
+      activeFeature = null;
+    }
+  }
+}
+
+/**
+ * 在 root 上注册 `game` 服务（幂等）。游戏插件初始化时调用一次即可。
+ */
+export function ensureGameHubService(plugin: Plugin): GameHubFeature {
+  const root = plugin.root;
+  if (root.contextIsReady('game')) {
+    return root.inject('game') as GameHubFeature;
+  }
+
+  const feature = new GameHubFeature();
+  root.provide(feature);
+  activeFeature = feature;
+
+  if (root.started && feature.mounted) {
+    feature.mounted(root);
+  }
+
+  return root.inject('game') as GameHubFeature;
+}
+
+export function getRegisteredGames(): readonly RegisteredGame[] {
+  return activeFeature?.items ?? [];
+}
+
+export function getRegisteredGame(id: string): RegisteredGame | undefined {
+  return activeFeature?.getGame(id);
+}

package/src/game-hub-flow.ts

@@ -0,0 +1,114 @@
+import type { Message, Plugin } from '@zhin.js/core';
+import { parseChoicePayload } from './choice-keyboard.js';
+import {
+  buildGameHubMenu,
+  buildMainHubMenu,
+  formatHubEmptyMessage,
+  HUB_PREFIX,
+  hubActionChoiceId,
+  hubGameChoiceId,
+  parseHubChoiceId,
+} from './game-hub-menu.js';
+import { getRegisteredGame, getRegisteredGames } from './game-hub-feature.js';
+import {
+  createHubScope,
+  getHubContext,
+  rememberHubMenu,
+  type HubMenuChoice,
+} from './game-hub-menu-context.js';
+
+function mainMenuChoices(): HubMenuChoice[] {
+  return getRegisteredGames().map((g) => ({
+    id: hubGameChoiceId(g.id),
+    label: `${g.icon} ${g.title}`,
+  }));
+}
+
+function gameMenuChoices(gameId: string, channelType: string): HubMenuChoice[] {
+  const game = getRegisteredGame(gameId);
+  if (!game) return [];
+  const isGroup = channelType !== 'private';
+  const menus = game.menus.filter((m) => {
+    if (m.groupOnly && !isGroup) return false;
+    if (m.privateOnly && isGroup) return false;
+    return true;
+  });
+  return [
+    ...menus.map((m) => ({
+      id: hubActionChoiceId(game.id, m.id),
+      label: m.label,
+    })),
+    { id: 'back', label: '↩️ 返回大厅' },
+  ];
+}
+
+export function openMainMenu(message: Message<any>): ReturnType<typeof buildMainHubMenu> | string {
+  const games = getRegisteredGames();
+  if (!games.length) {
+    return formatHubEmptyMessage();
+  }
+  const scopeId = createHubScope(message);
+  const choices = mainMenuChoices();
+  rememberHubMenu(message, scopeId, choices);
+  return buildMainHubMenu(scopeId, games, message.$channel.type);
+}
+
+export async function handleHubChoice(
+  plugin: Plugin,
+  message: Message<any>,
+  scopeId: string,
+  choiceId: string,
+): Promise<boolean> {
+  const ctx = getHubContext(scopeId);
+  if (!ctx) {
+    await message.$reply?.('菜单已过期，请重新发送「游戏」。');
+    return true;
+  }
+  const ch = `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+  if (ctx.channelKey !== ch) {
+    await message.$reply?.('请在本频道使用游戏大厅。');
+    return true;
+  }
+
+  const parsed = parseHubChoiceId(choiceId);
+  if (!parsed) return false;
+
+  // 大厅导航（选游戏 / 返回）：同频道任何人都可点；具体开局由 runAction 用当前点击者 message
+  if (parsed.kind === 'back') {
+    const games = getRegisteredGames();
+    const choices = mainMenuChoices();
+    rememberHubMenu(message, scopeId, choices);
+    await message.$reply?.(buildMainHubMenu(scopeId, games, message.$channel.type));
+    return true;
+  }
+
+  if (parsed.kind === 'game') {
+    const game = getRegisteredGame(parsed.gameId);
+    if (!game) {
+      await message.$reply?.('该游戏未安装。');
+      return true;
+    }
+    const choices = gameMenuChoices(parsed.gameId, message.$channel.type);
+    rememberHubMenu(message, scopeId, choices);
+    await message.$reply?.(
+      buildGameHubMenu(scopeId, game, message.$channel.type),
+    );
+    return true;
+  }
+
+  const game = getRegisteredGame(parsed.gameId);
+  if (!game) {
+    await message.$reply?.('该游戏未安装。');
+    return true;
+  }
+
+  const result = await game.runAction(parsed.actionId, { plugin, message });
+  if (typeof result === 'string') await message.$reply?.(result);
+  return true;
+}
+
+export function parseHubPayload(payload: string): { scopeId: string; choiceId: string } | null {
+  const parsed = parseChoicePayload(payload, HUB_PREFIX);
+  if (!parsed) return null;
+  return { scopeId: parsed.sessionId, choiceId: parsed.choiceId };
+}

package/src/game-hub-menu-context.ts

@@ -0,0 +1,94 @@
+import type { Message } from '@zhin.js/core';
+import { channelKey } from './board-sender.js';
+import { generateCompactId } from './random.js';
+
+export interface HubMenuContext {
+  channelKey: string;
+  /** 打开菜单的用户（仅记录，大厅导航不限制点击者） */
+  openerId: string;
+  message: Message<any>;
+  expiresAt: number;
+}
+
+export interface HubMenuChoice {
+  id: string;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface LastHubMenu {
+  scopeId: string;
+  choices: HubMenuChoice[];
+  expiresAt: number;
+}
+
+const TTL_MS = 60 * 60 * 1000;
+const contexts = new Map<string, HubMenuContext>();
+const lastMenus = new Map<string, LastHubMenu>();
+
+/** 大厅 fallback 按频道共享，任意成员可回复数字或点按钮 */
+function hubMenuKey(message: Message<any>): string {
+  return channelKey(message);
+}
+
+export function createHubScope(message: Message<any>): string {
+  const scopeId = generateCompactId('h');
+  contexts.set(scopeId, {
+    channelKey: channelKey(message),
+    openerId: message.$sender.id,
+    message,
+    expiresAt: Date.now() + TTL_MS,
+  });
+  pruneExpired();
+  return scopeId;
+}
+
+export function rememberHubMenu(
+  message: Message<any>,
+  scopeId: string,
+  choices: HubMenuChoice[],
+): void {
+  lastMenus.set(hubMenuKey(message), {
+    scopeId,
+    choices,
+    expiresAt: Date.now() + TTL_MS,
+  });
+  pruneExpired();
+}
+
+export function getLastHubMenu(message: Message<any>): LastHubMenu | null {
+  pruneExpired();
+  const key = hubMenuKey(message);
+  const last = lastMenus.get(key);
+  if (!last || last.expiresAt < Date.now()) {
+    lastMenus.delete(key);
+    return null;
+  }
+  return last;
+}
+
+export function getHubContext(scopeId: string): HubMenuContext | null {
+  pruneExpired();
+  const ctx = contexts.get(scopeId);
+  if (!ctx || ctx.expiresAt < Date.now()) {
+    contexts.delete(scopeId);
+    return null;
+  }
+  return ctx;
+}
+
+function pruneExpired(): void {
+  const now = Date.now();
+  for (const [id, ctx] of contexts) {
+    if (ctx.expiresAt < now) contexts.delete(id);
+  }
+  for (const [key, menu] of lastMenus) {
+    if (menu.expiresAt < now) lastMenus.delete(key);
+  }
+}
+
+/** 测试专用：清空菜单上下文 */
+export function resetHubMenuContextForTests(): void {
+  contexts.clear();
+  lastMenus.clear();
+}

package/src/game-hub-menu.ts

@@ -0,0 +1,223 @@
+import { segment, type SendContent } from '@zhin.js/core';
+
+import { buildChoiceKeyboard } from './choice-keyboard.js';
+import { slashCommandPrefix } from './game-commands.js';
+import type { RegisteredGame } from './game-hub-feature.js';
+import {
+  formatHubOpenCommandLines,
+  formatSupplementaryCommandsHelp,
+  type CommandHelpSource,
+} from './command-help.js';
+import {
+  buildBotHelpHtml,
+  buildHubHelpHtml,
+  HELP_CARD_CANVAS,
+  HELP_CARD_WIDTH,
+} from './help-card.js';
+
+export const HUB_PREFIX = 'hub';
+
+export function hubGameChoiceId(gameId: string): string {
+  return `g_${gameId}`;
+}
+
+export function hubActionChoiceId(gameId: string, actionId: string): string {
+  return `a_${gameId}_${actionId}`;
+}
+
+export function parseHubChoiceId(
+  choiceId: string,
+):
+  | { kind: 'game'; gameId: string }
+  | { kind: 'action'; gameId: string; actionId: string }
+  | { kind: 'back' }
+  | null {
+  if (choiceId === 'back') return { kind: 'back' };
+  if (choiceId.startsWith('g_')) return { kind: 'game', gameId: choiceId.slice(2) };
+  if (choiceId.startsWith('a_')) {
+    const rest = choiceId.slice(2);
+    const sep = rest.indexOf('_');
+    if (sep <= 0) return null;
+    return {
+      kind: 'action',
+      gameId: rest.slice(0, sep),
+      actionId: rest.slice(sep + 1),
+    };
+  }
+  return null;
+}
+
+export function buildMainHubMenu(
+  scopeId: string,
+  games: readonly RegisteredGame[],
+  channelType: string,
+): SendContent {
+  const cmdHint = formatCommandPrefixHint(games);
+  const lines = [
+    '🎮 **游戏大厅**',
+    '',
+    cmdHint,
+    '',
+    '_同频道均可浏览；开局后仅对局玩家可操作棋盘。_',
+    '',
+  ];
+  for (const g of games) {
+    lines.push(`• ${g.icon} **${g.title}** — ${g.description}`);
+  }
+
+  return buildChoiceKeyboard({
+    gamePrefix: HUB_PREFIX,
+    sessionId: scopeId,
+    narrative: lines.join('\n'),
+    choices: games.map((g) => ({
+      id: hubGameChoiceId(g.id),
+      label: `${g.icon} ${g.title}`,
+      style: 'primary' as const,
+    })),
+    buttonsPerRow: 2,
+    fallbackHint: '回复数字进入对应游戏',
+    interactionProfile: 'menu',
+    channelType,
+  });
+}
+
+export function buildGameHubMenu(
+  scopeId: string,
+  game: RegisteredGame,
+  channelType: string,
+): SendContent {
+  const isGroup = channelType !== 'private';
+  const menus = game.menus.filter((m) => {
+    if (m.groupOnly && !isGroup) return false;
+    if (m.privateOnly && isGroup) return false;
+    return true;
+  });
+
+  return buildChoiceKeyboard({
+    gamePrefix: HUB_PREFIX,
+    sessionId: scopeId,
+    narrative: `${game.icon} **${game.title}**\n\n${game.description}\n\n请选择：`,
+    choices: [
+      ...menus.map((m) => ({
+        id: hubActionChoiceId(game.id, m.id),
+        label: m.label,
+        style: m.style,
+      })),
+      { id: 'back', label: '↩️ 返回大厅' },
+    ],
+    buttonsPerRow: 2,
+    fallbackHint: '回复数字选择操作',
+    interactionProfile: 'menu',
+    channelType,
+  });
+}
+
+/** 大厅主菜单：命令前缀提示 */
+export function formatCommandPrefixHint(games: readonly RegisteredGame[]): string {
+  if (!games.length) return '暂无可用游戏。';
+  const sample = games.slice(0, 5).map((g) => slashCommandPrefix(g.commandPrefix.replace(/^\//, '')));
+  const tail = games.length > sample.length ? '等' : '';
+  return `选择想玩的游戏（也可直接发送斜杠命令，如「${sample.join('」「')}」${tail}）：`;
+}
+
+/** 游戏大厅帮助文案（随 registerGame 动态生成） */
+export function formatHubHelp(
+  games: readonly RegisteredGame[],
+  commands?: readonly CommandHelpSource[],
+): string {
+  const lines = [
+    '🎮 **游戏大厅**',
+    '',
+    ...formatHubOpenCommandLines(commands),
+  ];
+
+  if (!games.length) {
+    lines.push('', '当前暂无已注册游戏。', '请安装任意游戏插件（registerGame 会自动挂载大厅）。');
+    return lines.join('\n');
+  }
+
+  lines.push('', `当前已注册 **${games.length}** 款游戏：`, '');
+
+  for (const g of games) {
+    const quick = g.quickStart ?? '开始';
+    const alias = g.aliases?.length ? ` · ${g.aliases.join(' / ')}` : '';
+    lines.push(`• ${g.icon} **${g.title}**${alias}`);
+    lines.push(`  命令：\`${slashCommandPrefix(g.commandPrefix.replace(/^\//, ''))} ${quick}\` — ${g.description}`);
+  }
+
+  return lines.join('\n');
+}
+
+/** 顶层 /帮助：游戏大厅 + 已注册命令自动汇总 */
+export function formatBotHelp(
+  games: readonly RegisteredGame[],
+  options?: {
+    channelType?: string;
+    commands?: readonly CommandHelpSource[];
+  },
+): string {
+  const commands = options?.commands;
+  const sections = [formatHubHelp(games, commands)];
+
+  const other = commands?.length
+    ? formatSupplementaryCommandsHelp(commands, games)
+    : '';
+  if (other) {
+    sections.push('', '---', '', other);
+  }
+
+  if (options?.channelType === 'group') {
+    sections.push(
+      '',
+      '**QQ 群用法**',
+      '• 公域群需 **@ 机器人** 后发送命令，或直接 **点击消息按钮**',
+      '• 发送 `/游戏` 打开大厅，同群成员均可点击按钮',
+    );
+  }
+  return sections.join('\n');
+}
+
+/** 顶层 /帮助：HTML 卡片（QQ 等出站 policy 为 image 时渲染为 PNG；无 renderer 时回退文本） */
+export function buildBotHelpReply(
+  games: readonly RegisteredGame[],
+  options?: {
+    channelType?: string;
+    commands?: readonly CommandHelpSource[];
+  },
+): SendContent {
+  const text = formatBotHelp(games, options);
+  return segment.html({
+    html: buildBotHelpHtml({
+      games,
+      commands: options?.commands,
+      channelType: options?.channelType,
+    }),
+    text,
+    width: HELP_CARD_WIDTH,
+    backgroundColor: HELP_CARD_CANVAS,
+    fileName: 'bot-help.png',
+  });
+}
+
+/** /游戏 帮助：大厅专用卡片 */
+export function buildHubHelpReply(
+  games: readonly RegisteredGame[],
+  commands?: readonly CommandHelpSource[],
+): SendContent {
+  const text = formatHubHelp(games, commands);
+  return segment.html({
+    html: buildHubHelpHtml(games, commands),
+    text,
+    width: HELP_CARD_WIDTH,
+    backgroundColor: HELP_CARD_CANVAS,
+    fileName: 'game-hub-help.png',
+  });
+}
+
+/** 无游戏时的提示 */
+export function formatHubEmptyMessage(): string {
+  return [
+    '游戏大厅暂无可用游戏。',
+    '请安装任意游戏插件；首个游戏 registerGame 时会自动挂载大厅命令。',
+  ].join('');
+}