@zhin.js/game-kit 2.0.1 → 2.0.2

package/src/deterministic-random.ts

@@ -0,0 +1,81 @@
+const UINT32_RANGE = 0x1_0000_0000;
+const ZERO_STATE_FALLBACK = 0x6d2b79f5;
+
+/**
+ * Serializable xorshift32 generator for replayable game simulations.
+ * Security-sensitive randomness must continue using secureRandomInt.
+ */
+export class DeterministicRandom {
+  #state: number;
+
+  private constructor(state: number) {
+    this.#state = normalizeState(state);
+  }
+
+  static fromSeed(seed: string | number): DeterministicRandom {
+    return new DeterministicRandom(
+      typeof seed === 'number' ? seed : hashSeed(seed),
+    );
+  }
+
+  static fromState(state: number): DeterministicRandom {
+    return new DeterministicRandom(state);
+  }
+
+  get state(): number {
+    return this.#state;
+  }
+
+  nextUint32(): number {
+    let value = this.#state;
+    value ^= value << 13;
+    value ^= value >>> 17;
+    value ^= value << 5;
+    this.#state = value >>> 0;
+    return this.#state;
+  }
+
+  int(maxExclusive: number): number {
+    if (!Number.isSafeInteger(maxExclusive)
+      || maxExclusive <= 0
+      || maxExclusive > UINT32_RANGE) {
+      throw new RangeError(
+        'maxExclusive must be an integer between 1 and 2^32',
+      );
+    }
+    const limit = Math.floor(UINT32_RANGE / maxExclusive) * maxExclusive;
+    let value: number;
+    do {
+      value = this.nextUint32();
+    } while (value >= limit);
+    return value % maxExclusive;
+  }
+
+  intInclusive(min: number, max: number): number {
+    if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max) || max < min) {
+      throw new RangeError('invalid inclusive random range');
+    }
+    return min + this.int(max - min + 1);
+  }
+
+  item<T>(items: readonly T[]): T {
+    if (items.length === 0) {
+      throw new RangeError('cannot choose from an empty array');
+    }
+    return items[this.int(items.length)] as T;
+  }
+}
+
+function normalizeState(state: number): number {
+  if (!Number.isFinite(state)) throw new RangeError('state must be finite');
+  return (state >>> 0) || ZERO_STATE_FALLBACK;
+}
+
+function hashSeed(seed: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}

package/src/game-events.ts

@@ -0,0 +1,75 @@
+export interface GameEventSession {
+  readonly id: string;
+  readonly channel_key: string;
+  readonly status: string;
+  readonly updated_at: number;
+  readonly adapter?: string;
+  readonly endpoint?: string;
+  readonly channel_type?: string;
+  readonly channel_id?: string;
+}
+
+export interface GameOutcome {
+  readonly userId: string;
+  readonly userName?: string;
+  readonly result: 'won' | 'lost' | 'draw' | 'aborted';
+  readonly score?: number;
+}
+
+export interface GameEventMap {
+  'game:start': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+  };
+  'game:end': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+    readonly previousStatus: string;
+    readonly outcomes: readonly GameOutcome[];
+  };
+  'turn:change': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+    readonly previousTurn: unknown;
+    readonly turn: unknown;
+  };
+  'session:timeout': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+    readonly idleMs: number;
+  };
+}
+
+export type GameEventName = keyof GameEventMap;
+export type GameEventListener<K extends GameEventName> = (
+  event: GameEventMap[K],
+) => void | Promise<void>;
+
+/**
+ * Small async pub/sub used by game modules. Listener failures are isolated so a
+ * notification adapter cannot roll back an already committed session update.
+ */
+export class GameEventBus {
+  readonly #listeners = new Map<GameEventName, Set<GameEventListener<GameEventName>>>();
+
+  on<K extends GameEventName>(name: K, listener: GameEventListener<K>): () => void {
+    const listeners = this.#listeners.get(name) ?? new Set();
+    listeners.add(listener as GameEventListener<GameEventName>);
+    this.#listeners.set(name, listeners);
+    return () => {
+      listeners.delete(listener as GameEventListener<GameEventName>);
+      if (listeners.size === 0) this.#listeners.delete(name);
+    };
+  }
+
+  async emit<K extends GameEventName>(name: K, event: GameEventMap[K]): Promise<void> {
+    const listeners = [...(this.#listeners.get(name) ?? [])];
+    await Promise.allSettled(listeners.map((listener) => listener(event)));
+  }
+
+  clear(): void {
+    this.#listeners.clear();
+  }
+}
+
+export const gameEvents = new GameEventBus();

package/src/game-interactive.ts

@@ -1,18 +1,4 @@
-import { getActionFromMessage, resolvePayloadFromText, type Message } from '@zhin.js/core';
-
-import { channelKey } from './board-sender.js';
-import { parseChoicePayload } from './choice-keyboard.js';
-
-export const GAME_RESTART_CHOICE_IDS = new Set([
-  'restart',
-  'restart_char',
-  'restart_idiom',
-  'restart_bot',
-]);
-
-export function isRestartChoice(choiceId: string): boolean {
-  return GAME_RESTART_CHOICE_IDS.has(choiceId) || choiceId.startsWith('restart_');
-}
+import { resolvePayloadFromText } from '@zhin.js/core';
 
 /** 从 QQ 指令预填 / 数字 fallback 解析游戏 payload */
 export function resolveGameTextPayload(
@@ -21,68 +7,3 @@ export function resolveGameTextPayload(
 ): string | undefined {
   return resolvePayloadFromText(raw, map);
 }
-
-export interface GameSessionRef {
-  id: string;
-  channel_key: string;
-}
-
-export interface ResolveGameChoiceOptions {
-  message: Message;
-  gamePrefix: string;
-  validChoiceIds: readonly string[];
-  getById: (sessionId: string) => Promise<GameSessionRef | null>;
-  getActiveForUser: (channel: string, userId: string) => Promise<GameSessionRef | null>;
-  getByBoardMessageId?: (messageId: string) => Promise<GameSessionRef | null>;
-}
-
-/**
- * 解析按钮/选项回调：优先 payload；终局「再来一局」允许已结束 session。
- */
-export async function resolveGameChoice(
-  opts: ResolveGameChoiceOptions,
-): Promise<{ sessionId: string; choiceId: string } | null> {
-  const action = getActionFromMessage(opts.message);
-  if (!action) return null;
-
-  const ch = channelKey(opts.message);
-  const userId = opts.message.$sender.id;
-
-  const fromPayload = parseChoicePayload(action.payload, opts.gamePrefix);
-  if (fromPayload && opts.validChoiceIds.includes(fromPayload.choiceId)) {
-    const session = await opts.getById(fromPayload.sessionId);
-    if (session?.channel_key === ch) {
-      return { sessionId: fromPayload.sessionId, choiceId: fromPayload.choiceId };
-    }
-  }
-
-  const choiceId = action.id || action.payload;
-  if (!choiceId || !opts.validChoiceIds.includes(choiceId)) return null;
-
-  if (isRestartChoice(choiceId)) {
-    if (fromPayload) {
-      const session = await opts.getById(fromPayload.sessionId);
-      if (session?.channel_key === ch) {
-        return { sessionId: fromPayload.sessionId, choiceId };
-      }
-    }
-    if (action.sourceMessageId && opts.getByBoardMessageId) {
-      const byBoard = await opts.getByBoardMessageId(action.sourceMessageId);
-      if (byBoard && byBoard.channel_key === ch) {
-        return { sessionId: byBoard.id, choiceId };
-      }
-    }
-    const active = await opts.getActiveForUser(ch, userId);
-    if (active) return { sessionId: active.id, choiceId };
-    return null;
-  }
-
-  const session =
-    (await opts.getActiveForUser(ch, userId))
-    ?? (action.sourceMessageId && opts.getByBoardMessageId
-      ? await opts.getByBoardMessageId(action.sourceMessageId)
-      : null);
-  if (!session || session.channel_key !== ch) return null;
-
-  return { sessionId: session.id, choiceId };
-}

package/src/game-records.ts

@@ -1,5 +1,4 @@
 import {
-  MessageCommand,
   type Database,
   type DatabaseFeature,
   type Models,
@@ -8,7 +7,6 @@ import {
 } from '@zhin.js/core';
 import { channelKey } from './board-sender.js';
 import type { GameMessageLike } from './command-message.js';
-import { getRegisteredGame, getRegisteredGames } from './game-hub-feature.js';
 import { createHostGameDb, type HostGameDbSource } from './memory-db.js';
 import { generateCompactId } from './random.js';
 
@@ -234,77 +232,6 @@ export async function getGameLeaderboard(
     .slice(0, limit);
 }
 
-function gameTitle(gameId: string): string {
-  const g = getRegisteredGame(gameId);
-  return g ? `${g.icon} ${g.title}` : gameId;
-}
-
-function formatUserStats(stats: UserGameStats[]): string {
-  if (!stats.length) return '暂无战绩记录，快去 `/游戏` 开一局吧！';
-  const lines = stats.map((s) => {
-    const title = gameTitle(s.gameId);
-    return `• ${title}：${s.wins} 胜 ${s.losses} 负${s.draws ? ` ${s.draws} 平` : ''}（${s.games} 局，得分 ${s.totalScore}）`;
-  });
-  return ['📊 **你的战绩**', '', ...lines].join('\n');
-}
-
-function formatLeaderboard(gameId: string, entries: LeaderboardEntry[]): string {
-  const title = gameTitle(gameId);
-  if (!entries.length) {
-    return `${title} 在本群暂无排行，发送 \`/游戏\` 开始第一局！`;
-  }
-  const lines = entries.map((e, i) =>
-    `${i + 1}. ${e.userName} — ${e.wins} 胜 / ${e.games} 局（得分 ${e.totalScore}）`,
-  );
-  return [`🏆 **${title} 本群排行**`, '', ...lines].join('\n');
-}
-
-export function mountGameRecordCommands(root: Plugin): () => void {
-  const disposers: (() => void)[] = [];
-
-  disposers.push(
-    root.addCommand(
-      new MessageCommand('/战绩')
-        .desc('查看本人在本群的游戏战绩')
-        .action(async (message) => {
-          const stats = await getUserGameStats(message.$sender.id, channelKey(message));
-          return formatUserStats(stats);
-        }),
-    ),
-    root.addCommand(
-      new MessageCommand('/排行')
-        .desc('查看本群某游戏排行榜')
-        .action(async (message, ...args) => {
-          const query = args.join(' ').trim();
-          const games = getRegisteredGames();
-          if (!games.length) return '暂无已注册游戏。';
-          const firstGame = games[0];
-          if (!firstGame) return '暂无已注册游戏。';
-          let gameId = firstGame.id;
-          if (query) {
-            const hit = games.find(
-              (g) => g.id === query
-                || g.title.includes(query)
-                || g.commandPrefix.includes(query)
-                || g.aliases?.some((a) => a.includes(query)),
-            );
-            if (!hit) {
-              const names = games.map((g) => g.title).join('、');
-              return `未找到游戏「${query}」。可选：${names}`;
-            }
-            gameId = hit.id;
-          }
-          const board = await getGameLeaderboard(gameId, channelKey(message));
-          return formatLeaderboard(gameId, board);
-        }),
-    ),
-  );
-
-  return () => {
-    for (const d of disposers) d();
-  };
-}
-
 /** 测试专用 */
 export function resetGameRecordsForTests(): void {
   legacyDb = null;

package/src/game-session.ts

@@ -1,93 +1,10 @@
-/**
- * 通用游戏会话接口
- * 定义回合制游戏的基础会话结构
- */
-import type { Message } from '@zhin.js/core';
 import { generateCompactId } from './random.js';
 
-/** 会话状态 */
-export type GameStatus = 'active' | 'won' | 'draw' | 'aborted';
-
-/** 通用游戏会话接口 */
-export interface GameSession {
-  /** 会话 ID */
-  id: string;
-  /** 适配器名称 */
-  adapter: string;
-  /** Endpoint 名称 */
-  endpoint: string;
-  /** 频道类型 */
-  channel_type: 'private' | 'group' | 'channel';
-  /** 频道 ID */
-  channel_id: string;
-  /** 频道唯一键 */
-  channel_key: string;
-  /** 棋盘消息 ID（用于编辑） */
-  board_message_id: string;
-  /** 当前状态 */
-  status: GameStatus;
-  /** 更新时间戳 */
-  updated_at: number;
-  /** 创建时间戳 */
-  created_at: number;
-}
-
-/** 回合制游戏会话（2 人对战） */
-export interface TurnBasedSession extends GameSession {
-  /** 玩家 1 ID */
-  player_1: string;
-  /** 玩家 2 ID */
-  player_2: string;
-  /** 玩家 1 显示名 */
-  player_1_name: string;
-  /** 玩家 2 显示名 */
-  player_2_name: string;
-  /** 当前回合（1 或 2） */
-  turn: 1 | 2;
-  /** 胜者（0=无，1=玩家1，2=玩家2） */
-  winner: 0 | 1 | 2;
-  /** 步数 */
-  move_count: number;
-}
-
 /** 生成会话 ID */
 export function generateSessionId(): string {
   return generateCompactId('s');
 }
 
-/** 获取当前回合玩家 ID */
-export function currentPlayerId(session: TurnBasedSession): string {
-  return session.turn === 1 ? session.player_1 : session.player_2;
-}
-
-/** 判断用户是否为本局玩家 */
-export function isPlayer(session: TurnBasedSession, userId: string): boolean {
-  return session.player_1 === userId || session.player_2 === userId;
-}
-
-/** 判断是否轮到该用户 */
-export function isPlayerTurn(session: TurnBasedSession, userId: string): boolean {
-  return currentPlayerId(session) === userId;
-}
-
-/** 获取玩家编号（1 或 2），非玩家返回 null */
-export function playerNumber(session: TurnBasedSession, userId: string): 1 | 2 | null {
-  if (session.player_1 === userId) return 1;
-  if (session.player_2 === userId) return 2;
-  return null;
-}
-
-/** 切换回合 */
-export function nextTurn(current: 1 | 2): 1 | 2 {
-  return current === 1 ? 2 : 1;
-}
-
-/** 从 Message 提取发送者显示名 */
-export function senderDisplayName(message: Message): string {
-  const name = message.$sender.name?.trim();
-  return name || message.$sender.id;
-}
-
 /** 比对出站 board_message_id 与平台回调 messageId（含 composite id） */
 export function boardMessageMatches(stored: string, messageId: string): boolean {
   if (!stored || !messageId) return false;

package/src/index.ts

@@ -8,19 +8,16 @@ 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 './base-session-service.js';
+export * from './versioned-session-service.js';
+export * from './deterministic-random.js';
+export * from './game-events.js';
+export * from './session-coordinator.js';
+export * from './define-game-plugin.js';
 export * from './game-action-alias.js';
-export * from './game-commands.js';
 export * from './game-interactive.js';
 export * from './interaction-profiles.js';
 export * from './game-records.js';
-export * from './game-onboarding.js';
-export * from './command-help.js';
 export * from './command-message.js';
 export * from './memory-db.js';
 export * from './send-content-text.js';

package/src/memory-db.ts

@@ -72,6 +72,18 @@ export function createInMemoryGameDb(tableNames: readonly string[]): InMemoryGam
   };
 }
 
+/**
+ * Typed boundary used by game tests and standalone embedders. The database
+ * implementation is deliberately structural so game packages keep their
+ * precise model types without each package recreating the same adapter.
+ */
+export function createMemoryGameServices<TDatabase, TServices>(
+  tableNames: readonly string[],
+  factory: (database: TDatabase) => TServices,
+): TServices {
+  return factory(createInMemoryGameDb(tableNames) as unknown as TDatabase);
+}
+
 /** Minimal DatabaseHost model surface (structural typing; no plugin-runtime dep). */
 export interface HostGameModelSource {
   select(): {

package/src/session-coordinator.ts

@@ -0,0 +1,74 @@
+export interface ActiveGameSession {
+  readonly id: string;
+  readonly channel_key: string;
+}
+
+export interface GameSessionProvider {
+  readonly gameId: string;
+  getActiveForUser(channelKey: string, userId: string): Promise<ActiveGameSession | null>;
+}
+
+export class GameSessionConflictError extends Error {
+  constructor(
+    readonly requestedGameId: string,
+    readonly activeGameId: string,
+    readonly sessionId: string,
+    readonly userId: string,
+  ) {
+    super(
+      `你在当前频道已有进行中的「${activeGameId}」对局，`
+      + `请先结束它，再开始「${requestedGameId}」。`,
+    );
+    this.name = 'GameSessionConflictError';
+  }
+}
+
+/**
+ * Cross-game active-session index. Registrations form per-game stacks so HMR
+ * can install a new generation before disposing the old one without a gap.
+ */
+export class GameSessionCoordinator {
+  readonly #providers = new Map<string, GameSessionProvider[]>();
+
+  register(provider: GameSessionProvider): () => void {
+    const providers = this.#providers.get(provider.gameId) ?? [];
+    providers.push(provider);
+    this.#providers.set(provider.gameId, providers);
+    return () => {
+      const current = this.#providers.get(provider.gameId);
+      if (!current) return;
+      const index = current.lastIndexOf(provider);
+      if (index >= 0) current.splice(index, 1);
+      if (current.length === 0) this.#providers.delete(provider.gameId);
+    };
+  }
+
+  async assertAvailable(
+    requestedGameId: string,
+    channelKey: string,
+    userIds: readonly string[],
+  ): Promise<void> {
+    for (const [gameId, registrations] of this.#providers) {
+      if (gameId === requestedGameId) continue;
+      const provider = registrations[registrations.length - 1];
+      if (!provider) continue;
+      for (const userId of new Set(userIds.filter(Boolean))) {
+        const active = await provider.getActiveForUser(channelKey, userId);
+        if (active) {
+          throw new GameSessionConflictError(
+            requestedGameId,
+            gameId,
+            active.id,
+            userId,
+          );
+        }
+      }
+    }
+  }
+
+  clear(): void {
+    this.#providers.clear();
+  }
+}
+
+export const gameSessionCoordinator = new GameSessionCoordinator();