@zhin.js/game-shared 1.0.0

package/lib/grid-keyboard.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 通用网格按钮键盘构建器
+ * 支持井字棋（3×3）、五子棋（15×15）、四子棋（7×6）等
+ */
+import { type SendContent } from 'zhin.js';
+export interface GridCell<T = unknown> {
+    /** 单元格状态（游戏自定义，如 0=空, 1=X, 2=O） */
+    state: T;
+    /** 按钮显示文本 */
+    label: string;
+    /** 是否禁用（已落子或终局） */
+    disabled: boolean;
+    /** 高亮（胜利连线等） */
+    highlight?: boolean;
+}
+export interface GridKeyboardOptions<T = unknown> {
+    /** 游戏前缀（如 'ttt', 'gomoku', 'c4'） */
+    gamePrefix: string;
+    /** 会话 ID */
+    sessionId: string;
+    /** 行数 */
+    rows: number;
+    /** 列数 */
+    cols: number;
+    /** 单元格数据，按行优先 [row * cols + col] */
+    cells: GridCell<T>[];
+    /** 状态行文本 */
+    statusLine: string;
+    /** 是否终局（全部按钮禁用） */
+    terminal?: boolean;
+    /** 省略 ASCII 文本棋盘（QQ 等平台） */
+    omitAsciiBoard?: boolean;
+    /** ASCII 棋盘渲染器（可选，省略则不渲染 ASCII） */
+    renderAscii?: (cells: GridCell<T>[], rows: number, cols: number, highlight?: number[]) => string;
+    /** 高亮的单元格索引（胜利连线等） */
+    highlight?: number[];
+    /** fallback 提示文本 */
+    fallbackHint?: string;
+}
+/**
+ * 构建 fallback 数字映射（仅可落子的格子）
+ */
+export declare function buildGridFallbackMap(gamePrefix: string, sessionId: string, cells: GridCell[]): Record<string, string>;
+/**
+ * 构建网格按钮键盘消息内容
+ */
+export declare function buildGridKeyboard<T>(options: GridKeyboardOptions<T>): SendContent;
+/**
+ * 解析网格 payload：`{prefix}:{sessionId}:{cellIndex}`
+ */
+export declare function parseGridPayload(payload: string, expectedPrefix?: string): {
+    prefix: string;
+    sessionId: string;
+    cell: number;
+} | null;
+/**
+ * 解析按钮 ID 格式：`c{cellIndex}`（QQ 等平台 action 可能只回传 button_id）
+ */
+export declare function parseCellButtonId(value: string): number | null;
+//# sourceMappingURL=grid-keyboard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grid-keyboard.d.ts","sourceRoot":"","sources":["../src/grid-keyboard.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,mCAAmC;IACnC,KAAK,EAAE,CAAC,CAAC;IACT,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS;IACT,IAAI,EAAE,MAAM,CAAC;IACb,SAAS;IACT,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACrB,YAAY;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mCAAmC;IACnC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IACjG,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EAAE,GAChB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,WAAW,CAkDjF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQ5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM9D"}

package/lib/grid-keyboard.js

@@ -0,0 +1,82 @@
+/**
+ * 通用网格按钮键盘构建器
+ * 支持井字棋（3×3）、五子棋（15×15）、四子棋（7×6）等
+ */
+import { segment } from 'zhin.js';
+/**
+ * 构建 fallback 数字映射（仅可落子的格子）
+ */
+export function buildGridFallbackMap(gamePrefix, sessionId, cells) {
+    const map = {};
+    let n = 1;
+    for (let i = 0; i < cells.length; i++) {
+        if (!cells[i].disabled) {
+            map[String(n)] = `${gamePrefix}:${sessionId}:${i}`;
+            n++;
+        }
+    }
+    return map;
+}
+/**
+ * 构建网格按钮键盘消息内容
+ */
+export function buildGridKeyboard(options) {
+    const { gamePrefix, sessionId, rows, cols, cells, statusLine, terminal, omitAsciiBoard, renderAscii, highlight, fallbackHint, } = options;
+    const buttonRows = [];
+    for (let r = 0; r < rows; r++) {
+        const row = [];
+        for (let c = 0; c < cols; c++) {
+            const i = r * cols + c;
+            const cell = cells[i];
+            row.push(segment.button({
+                id: `c${i}`,
+                label: cell.label,
+                payload: `${gamePrefix}:${sessionId}:${i}`,
+                disabled: terminal || cell.disabled,
+                style: cell.highlight ? 'primary' : 'secondary',
+            }));
+        }
+        buttonRows.push(row);
+    }
+    const fallback = buildGridFallbackMap(gamePrefix, sessionId, cells);
+    const textLines = [statusLine];
+    if (!omitAsciiBoard && renderAscii) {
+        textLines.push('', renderAscii(cells, rows, cols, highlight));
+    }
+    return [
+        segment.text(textLines.join('\n')),
+        segment.keyboard(buttonRows, {
+            fallback: fallbackHint
+                ? { hint: fallbackHint, map: fallback }
+                : undefined,
+        }).toElement(),
+    ];
+}
+/**
+ * 解析网格 payload：`{prefix}:{sessionId}:{cellIndex}`
+ */
+export function parseGridPayload(payload, expectedPrefix) {
+    const m = /^([a-z0-9_]+):([^:]+):(\d+)$/i.exec(payload);
+    if (!m)
+        return null;
+    const prefix = m[1];
+    if (expectedPrefix && prefix !== expectedPrefix)
+        return null;
+    const cell = Number(m[3]);
+    if (!Number.isInteger(cell) || cell < 0)
+        return null;
+    return { prefix, sessionId: m[2], cell };
+}
+/**
+ * 解析按钮 ID 格式：`c{cellIndex}`（QQ 等平台 action 可能只回传 button_id）
+ */
+export function parseCellButtonId(value) {
+    const m = /^c(\d+)$/.exec(value);
+    if (!m)
+        return null;
+    const cell = Number(m[1]);
+    if (!Number.isInteger(cell) || cell < 0)
+        return null;
+    return cell;
+}
+//# sourceMappingURL=grid-keyboard.js.map

package/lib/grid-keyboard.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @zhin.js/game-shared - 通用游戏工具包
+ *
+ * 提供网格棋盘、会话管理、消息发送等通用抽象
+ */
+export * from './grid-keyboard.js';
+export * from './choice-keyboard.js';
+export * from './board-sender.js';
+export * from './game-session.js';
+export * from './game-hub-feature.js';
+export * from './game-hub-menu.js';
+export * from './game-hub-menu-context.js';
+export * from './game-hub-flow.js';
+export * from './game-hub-mount.js';
+export * from './game-middleware.js';
+export * from './game-action-alias.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

package/lib/index.js

@@ -0,0 +1,17 @@
+/**
+ * @zhin.js/game-shared - 通用游戏工具包
+ *
+ * 提供网格棋盘、会话管理、消息发送等通用抽象
+ */
+export * from './grid-keyboard.js';
+export * from './choice-keyboard.js';
+export * from './board-sender.js';
+export * from './game-session.js';
+export * from './game-hub-feature.js';
+export * from './game-hub-menu.js';
+export * from './game-hub-menu-context.js';
+export * from './game-hub-flow.js';
+export * from './game-hub-mount.js';
+export * from './game-middleware.js';
+export * from './game-action-alias.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@zhin.js/game-shared",
+  "version": "1.0.0",
+  "description": "Zhin.js 游戏插件通用工具包",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "zhin.js": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "zhin.js": "4.1.0"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/board-sender.ts

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

package/src/choice-keyboard.ts

@@ -0,0 +1,103 @@
+/**
+ * 选项式交互键盘（文字冒险、问答、剧情分支等）
+ */
+import { segment, 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 function buildChoiceFallbackMap(
+  gamePrefix: string,
+  sessionId: string,
+  choices: ChoiceOption[],
+): Record<string, string> {
+  const map: Record<string, string> = {};
+  let n = 1;
+  for (const choice of choices) {
+    if (!choice.disabled) {
+      map[String(n)] = `${gamePrefix}:${sessionId}:${choice.id}`;
+      n++;
+    }
+  }
+  return map;
+}
+
+function chunkChoices<T>(items: T[], size: number): T[][] {
+  if (size <= 0 || items.length <= size) return [items];
+  const rows: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    rows.push(items.slice(i, i + size));
+  }
+  return rows;
+}
+
+/**
+ * 构建选项键盘消息：正文 + 一行或多行按钮
+ */
+export function buildChoiceKeyboard(options: ChoiceKeyboardOptions): SendContent {
+  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: string,
+  expectedPrefix?: string,
+): { prefix: string; sessionId: string; choiceId: string } | null {
+  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]! };
+}

package/src/game-action-alias.ts

@@ -0,0 +1,129 @@
+const TTT_ACTIONS: Record<string, string> = {
+  bot: 'bot',
+  join: 'join',
+  leave: 'leave',
+  quit: 'quit',
+  spectate: 'spectate',
+  help: 'help',
+  人机: 'bot',
+  排队: 'join',
+  加入: 'join',
+  离开: 'leave',
+  认输: 'quit',
+  观战: 'spectate',
+  帮助: 'help',
+};
+
+const ADV_ACTIONS: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  map: 'map',
+  achievements: 'achievements',
+  achievement: 'achievements',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  继续: 'continue',
+  地图: 'map',
+  成就: 'achievements',
+  放弃: 'quit',
+  退出: 'quit',
+  帮助: 'help',
+};
+
+const RPS_ACTIONS: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  继续: 'continue',
+  放弃: 'quit',
+  帮助: 'help',
+};
+
+const GUESS_ACTIONS: Record<string, string> = {
+  start: 'start',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  放弃: 'quit',
+  帮助: 'help',
+};
+
+const DICE_ACTIONS: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  继续: 'continue',
+  放弃: 'quit',
+  帮助: 'help',
+};
+
+function lookup(map: Record<string, string>, raw: string): string {
+  const t = raw.trim();
+  if (!t) return 'help';
+  return map[t] ?? map[t.toLowerCase()] ?? t.toLowerCase();
+}
+
+export function normalizeTttAction(raw: string): string {
+  return lookup(TTT_ACTIONS, raw);
+}
+
+export function normalizeAdvAction(raw: string): string {
+  return lookup(ADV_ACTIONS, raw);
+}
+
+export function normalizeRpsAction(raw: string): string {
+  return lookup(RPS_ACTIONS, raw);
+}
+
+export function normalizeGuessAction(raw: string): string {
+  return lookup(GUESS_ACTIONS, raw);
+}
+
+export function normalizeDiceAction(raw: string): string {
+  return lookup(DICE_ACTIONS, raw);
+}
+
+const CHAIN_ACTIONS: Record<string, string> = {
+  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: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  quit: 'quit',
+  help: 'help',
+  char: 'char',
+  idiom: 'idiom',
+  开始: 'start',
+  继续: 'continue',
+  放弃: 'quit',
+  帮助: 'help',
+  字谜: 'char',
+  成语: 'idiom',
+};
+
+export function normalizeChainAction(raw: string): string {
+  return lookup(CHAIN_ACTIONS, raw);
+}
+
+export function normalizeRiddleAction(raw: string): string {
+  return lookup(RIDDLE_ACTIONS, raw);
+}

package/src/game-hub-feature.ts

@@ -0,0 +1,147 @@
+import {
+  Feature,
+  getPlugin,
+  type FeatureJSON,
+  type Plugin,
+  type PluginLike,
+} from 'zhin.js';
+import { mountGameHubUi, markGameHubUiMounted } from './game-hub-mount.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;
+    }
+  }
+}
+
+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;
+    this.hubDisposers = mountGameHubUi(root.root ?? root);
+    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);
+}