build: include samples in prepare script

Replace subscribe with effect in assignSelector to ensure the
selector value is tracked and the callback is executed within
the reactive context.

package.json

@@ -18,7 +18,7 @@
   "scripts": {
     "build": "tsup",
     "build:samples": "tsup --config tsup.samples.config.ts",
-    "prepare": "npm run build",
+    "prepare": "npm run build && npm run build:samples",
     "test": "vitest",
     "test:run": "vitest run",
     "typecheck": "tsc --noEmit"

src/core/game-client.ts

@@ -0,0 +1,118 @@
+import { createPromptContext, PromptDef } from "@/utils/command";
+import { computed, effect, signal } from "@preact/signals-core";
+import { createGameContext, IGameContext } from "./game";
+
+export enum ClientStatus {
+  Idle = "idle",
+  Running = "running",
+  Disposed = "disposed",
+}
+
+export type PromptInfo =
+  | {
+      hasPrompt: false;
+      player: string;
+    }
+  | {
+      hasPrompt: true;
+      player: string;
+      def: PromptDef<unknown[]>;
+      tryAnswer(...args: unknown[]): string | null;
+    };
+
+/**
+ * 1. create a client instance
+ * 2. setStatus("running")
+ * 3. select("selector", t => {}) for c# to capture game state
+ * 4. useClient("status" | "prompt") for c# to handle prompt / game status
+ */
+export abstract class BaseGameClient<
+  T extends Record<string, unknown> = Record<string, unknown>,
+  R = unknown,
+> {
+  protected _initialState: T;
+  protected _context: IGameContext<T>;
+  protected _prompts = createPromptContext();
+  protected _status = signal(ClientStatus.Idle);
+  protected _result = signal(null as null | R);
+  public get state() {
+    return this._context.value;
+  }
+  constructor(is: T) {
+    this._initialState = is;
+    this._context = createGameContext(this._prompts, is);
+  }
+
+  async setStatus(status: ClientStatus) {
+    this._status.value = status;
+    if (status === ClientStatus.Disposed) {
+      this._prompts.reset();
+    } else if (status === ClientStatus.Running) {
+      this._prompts.reset();
+      this._context._state.value = this._initialState;
+      this._result.value = null;
+      this._result.value = await this.start(this._context);
+      this.setStatus(ClientStatus.Idle);
+    }
+  }
+
+  abstract start(ctx: IGameContext<T>): Promise<R>;
+
+  assignSelector<S>(selector: (t: T) => S, callback: (s: S) => void) {
+    const selected = computed(() => selector(this._context.value));
+    return effect(() => {
+      callback(selected.value);
+    });
+  }
+
+  addInterruption() {
+    let resolve!: () => void;
+    const promise = new Promise<void>((resolver) => {
+      resolve = resolver;
+    });
+    this._context._state.addInterruption(promise);
+    return resolve;
+  }
+
+  selectPrompt(callback: (prompt: PromptInfo) => void) {
+    return this._prompts.handleCall.use(async (ctx, next) => {
+      function tryAnswer(...args: any[]) {
+        try {
+          const res = ctx.validator(...args);
+          ctx.resolve(res);
+          return null;
+        } catch (reason) {
+          if (typeof reason === "string") {
+            return reason;
+          }
+          throw reason;
+        }
+      }
+
+      try {
+        callback({
+          hasPrompt: true,
+          player: ctx.player || "global",
+          def: ctx.def,
+          tryAnswer,
+        });
+        return await next();
+      } finally {
+        callback({
+          hasPrompt: false,
+          player: ctx.player || "global",
+        });
+      }
+    });
+  }
+  selectStatus(callback: (status: ClientStatus) => void) {
+    return effect(() => {
+      callback(this._status.value);
+    });
+  }
+  selectResult(callback: (status: R | null) => void) {
+    return effect(() => {
+      callback(this._result.value);
+    });
+  }
+}

src/core/game-host.ts

@@ -1,99 +1,39 @@
+import { createPromptContext } from "@/utils/command";
+import { PromptContext } from "@/utils/command/command-prompt";
 import { ReadonlySignal, Signal } from "@preact/signals-core";
-import { CommandSchema, CommandRegistry, PromptEvent } from "@/utils/command";
-import {
-  createGameCommandRegistry,
-  createGameContext,
-  IGameContext,
-  PromptDef,
-} from "./game";
+import { createGameContext, IGameContext } from "./game";
 
 export type GameHostStatus = "created" | "running" | "disposed";
 
 export class GameHost<
   TState extends Record<string, unknown>,
   TResult = unknown,
+  TModule extends GameModule<TState, TResult> = GameModule<TState, TResult>,
 > {
   readonly state: ReadonlySignal<TState>;
   readonly status: ReadonlySignal<GameHostStatus>;
-  readonly activePromptSchema: ReadonlySignal<CommandSchema | null>;
-  readonly activePromptPlayer: ReadonlySignal<string | null>;
-  readonly activePromptHint: ReadonlySignal<string | null>;
+  readonly prompts: PromptContext;
 
   private _context: IGameContext<TState>;
   private _start: (ctx: IGameContext<TState>) => Promise<TResult>;
   private _status: Signal<GameHostStatus>;
-  private _activePromptSchema: Signal<CommandSchema | null>;
-  private _activePromptPlayer: Signal<string | null>;
-  private _activePromptHint: Signal<string | null>;
   private _createInitialState: () => TState;
   private _eventListeners: Map<"start" | "dispose", Set<() => void>>;
   private _isDisposed = false;
 
-  constructor(
-    registry: CommandRegistry<IGameContext<TState>>,
-    createInitialState: () => TState,
-    start: (ctx: IGameContext<TState>) => Promise<TResult>,
-  ) {
+  constructor(public readonly gameModule: TModule) {
+    const { createInitialState, start } = gameModule;
     this._createInitialState = createInitialState;
     this._eventListeners = new Map();
 
+    this.prompts = createPromptContext();
     const initialState = createInitialState();
-    this._context = createGameContext(registry, initialState);
+    this._context = createGameContext(this.prompts, initialState);
     this._start = start;
     this.state = this._context._state;
 
     this._status = new Signal<GameHostStatus>("created");
     this.status = this._status;
-
-    this._activePromptSchema = new Signal<CommandSchema | null>(null);
-    this.activePromptSchema = this._activePromptSchema;
-
-    this._activePromptPlayer = new Signal<string | null>(null);
-    this.activePromptPlayer = this._activePromptPlayer;
-
-    this._activePromptHint = new Signal<string | null>(null);
-    this.activePromptHint = this._activePromptHint;
-
-    this._setupPromptTracking();
-  }
-
-  private _setupPromptTracking() {
-    let currentPromptEvent: PromptEvent | null = null;
-
-    this._context._commands.on("prompt", (e) => {
-      currentPromptEvent = e as PromptEvent;
-      this._activePromptSchema.value = currentPromptEvent.schema;
-      this._activePromptPlayer.value = currentPromptEvent.currentPlayer;
-      this._activePromptHint.value = currentPromptEvent.hintText || null;
-    });
-
-    this._context._commands.on("promptEnd", () => {
-      currentPromptEvent = null;
-      this._activePromptSchema.value = null;
-      this._activePromptPlayer.value = null;
-      this._activePromptHint.value = null;
-    });
-
-    // Initial state
-    this._activePromptSchema.value = null;
-    this._activePromptPlayer.value = null;
-    this._activePromptHint.value = null;
-  }
-
-  tryInput(input: string): string | null {
-    if (this._isDisposed) {
-      return "GameHost is disposed";
-    }
-    return this._context._commands._tryCommit(input);
-  }
-
-  tryAnswerPrompt<TArgs extends any[]>(def: PromptDef<TArgs>, ...args: TArgs) {
-    return this._context._commands._tryCommit({
-      name: def.schema.name,
-      params: args,
-      options: {},
-      flags: {},
-    });
   }
 
   /**
@@ -117,7 +57,7 @@ export class GameHost<
       throw new Error("GameHost is disposed");
     }
 
-    this._context._commands._cancel();
+    this.prompts.reset();
 
     const initialState = this._createInitialState();
     this._context._state.value = initialState as any;
@@ -138,7 +78,7 @@ export class GameHost<
     }
 
     this._isDisposed = true;
-    this._context._commands._cancel();
+    this.prompts.reset();
     this._status.value = "disposed";
 
     // Emit dispose event BEFORE clearing listeners
@@ -168,21 +108,17 @@ export class GameHost<
 }
 
 export type GameModule<
-  TState extends Record<string, unknown>,
+  TState extends Record<string, unknown> = Record<string, unknown>,
   TResult = unknown,
 > = {
-  registry?: CommandRegistry<IGameContext<TState>>;
   createInitialState: () => TState;
   start: (ctx: IGameContext<TState>) => Promise<TResult>;
 };
 
 export function createGameHost<
-  TState extends Record<string, unknown>,
+  TState extends Record<string, unknown> = Record<string, unknown>,
   TResult = unknown,
->(gameModule: GameModule<TState, TResult>): GameHost<TState, TResult> {
-  return new GameHost(
-    gameModule.registry || createGameCommandRegistry(),
-    gameModule.createInitialState,
-    gameModule.start,
-  );
+  TModule extends GameModule<TState, TResult> = GameModule<TState, TResult>,
+>(gameModule: TModule): GameHost<TState, TResult, TModule> {
+  return new GameHost(gameModule);
 }

src/core/game.ts

@@ -1,40 +1,29 @@
 import { MutableSignal, mutableSignal } from "@/utils/mutable-signal";
-import {
-  Command,
-  CommandRegistry,
-  CommandResult,
-  CommandRunnerContextExport,
-  CommandSchema,
-  createCommandRegistry,
-  createCommandRunnerContext,
-  parseCommandSchema,
-} from "@/utils/command";
+import { CommandSchema, parseCommandSchema, PromptDef } from "@/utils/command";
 import { PromptValidator } from "@/utils/command/command-runner";
 import { Mulberry32RNG, ReadonlyRNG, RNG } from "@/utils/rng";
+import { PromptContext } from "@/utils/command/command-prompt";
 
 export interface IGameContext<TState extends Record<string, unknown> = {}> {
   get value(): TState;
   get rng(): ReadonlyRNG;
   produce(fn: (draft: TState) => undefined): void;
   produceAsync(fn: (draft: TState) => undefined): Promise<void>;
-  run<T>(input: string): Promise<CommandResult<T>>;
-  runParsed<T>(command: Command): Promise<CommandResult<T>>;
   prompt: <TResult, TArgs extends any[] = any[]>(
     def: PromptDef<TArgs>,
     validator: PromptValidator<TResult, TArgs>,
-    currentPlayer?: string | null,
+    player?: string,
   ) => Promise<TResult>;
 
   // test only
   _state: MutableSignal<TState>;
-  _commands: CommandRunnerContextExport<IGameContext<TState>>;
   _rng: RNG;
 }
 export type IGameContextExport<TState extends Record<string, unknown> = {}> =
   Omit<IGameContext<TState>, "_state" | "_commands" | "_rng">;
 
 export function createGameContext<TState extends Record<string, unknown> = {}>(
-  commandRegistry: CommandRegistry<IGameContext<TState>>,
+  promptContext: PromptContext,
   initialState?: TState | (() => TState),
 ): IGameContext<TState> {
   const stateValue =
@@ -42,7 +31,7 @@ export function createGameContext<TState extends Record<string, unknown> = {}>(
       ? initialState()
       : (initialState ?? ({} as TState));
   const state = mutableSignal(stateValue);
-  let commands: CommandRunnerContextExport<IGameContext<TState>> = null as any;
+  const { prompt } = promptContext;
 
   const context: IGameContext<TState> = {
     get value(): TState {
@@ -57,38 +46,15 @@ export function createGameContext<TState extends Record<string, unknown> = {}>(
     produceAsync(fn: (draft: TState) => undefined) {
       return state.produceAsync(fn);
     },
-    run<T>(input: string) {
-      return commands.run<T>(input);
-    },
-    runParsed<T>(command: Command) {
-      return commands.runParsed<T>(command);
-    },
-    prompt(def, validator, currentPlayer) {
-      return commands.prompt(
-        def.schema,
-        validator,
-        def.hintText,
-        currentPlayer,
-      );
-    },
+    prompt,
 
     _state: state,
-    _commands: commands,
     _rng: new Mulberry32RNG(),
   };
 
-  context._commands = commands = createCommandRunnerContext(
-    commandRegistry,
-    context,
-  );
-
   return context;
 }
 
-export type PromptDef<TArgs extends any[] = any[]> = {
-  schema: CommandSchema;
-  hintText?: string;
-};
 export function createPromptDef<TArgs extends any[] = any[]>(
   schema: CommandSchema | string,
   hintText?: string,
@@ -96,9 +62,3 @@ export function createPromptDef<TArgs extends any[] = any[]>(
   schema = typeof schema === "string" ? parseCommandSchema(schema) : schema;
   return { schema, hintText };
 }
-
-export function createGameCommandRegistry<
-  TState extends Record<string, unknown> = {},
->() {
-  return createCommandRegistry<IGameContext<TState>>();
-}

src/index.ts

@@ -5,7 +5,7 @@
 
 // Core types
 export type { IGameContext } from "./core/game";
-export { createGameCommandRegistry, createPromptDef } from "./core/game";
+export { createPromptDef } from "./core/game";
 
 export type { GameHost, GameHostStatus, GameModule } from "./core/game-host";
 export { createGameHost } from "./core/game-host";
@@ -24,6 +24,8 @@ export {
   moveToRegion,
 } from "./core/region";
 
+export * from "./core/game-client";
+
 // Utils
 export type {
   Command,
@@ -71,4 +73,6 @@ export { createRNG, Mulberry32RNG } from "./utils/rng";
 export type { MiddlewareChain } from "./utils/middleware";
 export { createMiddlewareChain } from "./utils/middleware";
 
+export * from "./utils/spawner";
+
 export * from "@preact/signals-core";

src/samples/boop/commands/index.ts

@@ -1,101 +1,31 @@
-import {BoopGame} from "@/samples/boop/types-extensions";
-import {PlayerType} from "@/samples/boop/types";
-import {turn} from "@/samples/boop/commands/turn";
-import {createGameCommandRegistry} from "@/core/game";
-
-export const registry = createGameCommandRegistry<BoopGame['value']>();
-
-/**
- * 放置棋子到棋盘
- */
-const placeCmd = registry.register({
-    schema: 'place <row:number> <col:number> <player> <type>',
-    run: async (game, row, col, player, type) => {
-        const {place} = await import('./place');
-        return place(game, row, col, player, type);
-    }
-});
-
-/**
- * 执行boop - 推动周围棋子
- */
-const boopCmd = registry.register({
-    schema: 'boop <row:number> <col:number> <type>',
-    run: async (game, row, col, type) => {
-        const {boop} = await import('./boop');
-        return boop(game, row, col, type);
-    }
-});
-
-/**
- * 检查是否有玩家获胜(三个猫连线)
- */
-const checkWinCmd = registry.register({
-    schema: 'check-win',
-    run: async (game) => {
-        const {checkWin} = await import('./win');
-        return checkWin(game);
-    }
-});
-
-/**
- * 检查并执行小猫升级(三个小猫连线变成猫)
- */
-const checkGraduatesCmd = registry.register({
-    schema: 'check-graduates',
-    run: async (game) => {
-        const {checkGraduates} = await import('./graduate');
-        return checkGraduates(game);
-    }
-});
-
-/**
- * 检查并执行 8-piece 规则
- */
-const checkFullBoardCmd = registry.register({
-    schema: 'check-full-board <player:string>',
-    run: async (game, player) => {
-        const {checkFullBoard} = await import('./full-board');
-        return checkFullBoard(game, player);
-    }
-});
-
-/**
- * 处理一个回合
- */
-const turnCmd = registry.register({
-    schema: 'turn <player:string>',
-    run: async (game, player) => {
-        const {turn} = await import('./turn');
-        return turn(game, player);
-    }
-});
+import { BoopGame } from "@/samples/boop/types-extensions";
+import { PlayerType } from "@/samples/boop/types";
+import { turn } from "@/samples/boop/commands/turn";
+import { boop } from "./boop";
+import { checkFullBoard } from "./full-board";
+import { checkGraduates } from "./graduate";
+import { place } from "./place";
+import { checkWin } from "./win";
 
 /**
  * 启动游戏主循环
  */
 export async function start(game: BoopGame) {
-    while (true) {
-        const currentPlayer = game.value.currentPlayer;
-        const turnOutput = await turn(game, currentPlayer);
+  while (true) {
+    const currentPlayer = game.value.currentPlayer;
+    const turnOutput = await turn(game, currentPlayer);
 
-        await game.produceAsync(state => {
-            state.winner = turnOutput.winner;
-            if (!state.winner) {
-                state.currentPlayer = state.currentPlayer === 'white' ? 'black' : 'white';
-            }
-        });
-        if (game.value.winner) break;
-    }
+    await game.produceAsync((state) => {
+      state.winner = turnOutput.winner;
+      if (!state.winner) {
+        state.currentPlayer =
+          state.currentPlayer === "white" ? "black" : "white";
+      }
+    });
+    if (game.value.winner) break;
+  }
 
-    return game.value;
+  return game.value;
 }
 
-export {
-    placeCmd as place,
-    boopCmd as boop,
-    checkWinCmd as checkWin,
-    checkGraduatesCmd as checkGraduates,
-    checkFullBoardCmd as checkFullBoard,
-    turnCmd as turn
-};
+export { place, boop, checkWin, checkGraduates, checkFullBoard, turn };

src/samples/boop/index.ts

@@ -1,49 +1,41 @@
 // Types
 export type {
-    PlayerType,
-    PieceType,
-    WinnerType,
-    RegionType,
-    BoopPartMeta,
-    BoopPart
-} from './types';
+  PlayerType,
+  PieceType,
+  WinnerType,
+  RegionType,
+  BoopPartMeta,
+  BoopPart,
+} from "./types";
 
-export type {BoopGame} from './types-extensions';
+export type { BoopGame } from "./types-extensions";
 
 // Constants
-export {
-    BOARD_SIZE,
-    MAX_PIECES_PER_PLAYER,
-    WIN_LENGTH
-} from './constants';
+export { BOARD_SIZE, MAX_PIECES_PER_PLAYER, WIN_LENGTH } from "./constants";
 
 // State
-export {
-    createInitialState,
-    type BoopState
-} from './state';
+export { createInitialState, type BoopState } from "./state";
 
 // Prompts
-export {prompts} from './prompts';
+export { prompts } from "./prompts";
 
 // Commands
 export {
-    registry,
-    start,
-    place as placeCmd,
-    boop as boopCmd,
-    checkWin as checkWinCmd,
-    checkGraduates as checkGraduatesCmd,
-    checkFullBoard as checkFullBoardCmd,
-    turn as turnCmd
-} from './commands';
+  start,
+  place as placeCmd,
+  boop as boopCmd,
+  checkWin as checkWinCmd,
+  checkGraduates as checkGraduatesCmd,
+  checkFullBoard as checkFullBoardCmd,
+  turn as turnCmd,
+} from "./commands";
 
 // Utils
 export {
-    getLineCandidates,
-    isInBounds,
-    isCellOccupied,
-    getNeighborPositions,
-    findPartInRegion,
-    findPartAtPosition
-} from './utils';
+  getLineCandidates,
+  isInBounds,
+  isCellOccupied,
+  getNeighborPositions,
+  findPartInRegion,
+  findPartAtPosition,
+} from "./utils";

src/samples/onitama/commands.ts

@@ -1,379 +1,409 @@
 import {
-    OnitamaGame,
-    OnitamaState,
-    PlayerType,
-    prompts,
-    initializeCards
+  OnitamaGame,
+  OnitamaState,
+  PlayerType,
+  prompts,
+  initializeCards,
 } from "./types";
-import {createGameCommandRegistry} from "@/core/game";
-import {moveToRegion} from "@/core/region";
-
-export const registry = createGameCommandRegistry<OnitamaState>();
+import { moveToRegion } from "@/core/region";
 
 /**
  * 检查位置是否在棋盘范围内
  */
 function isInBounds(x: number, y: number): boolean {
-    return x >= 0 && x < 5 && y >= 0 && y < 5;
+  return x >= 0 && x < 5 && y >= 0 && y < 5;
 }
 
 /**
  * 检查位置是否有棋子
  */
 function getPawnAtPosition(state: OnitamaState, x: number, y: number) {
-    const key = `${x},${y}`;
-    const pawnId = state.regions.board.partMap[key];
-    return pawnId ? state.pawns[pawnId] : null;
+  const key = `${x},${y}`;
+  const pawnId = state.regions.board.partMap[key];
+  return pawnId ? state.pawns[pawnId] : null;
 }
 
 /**
  * 检查玩家是否拥有某张卡牌
  */
-function playerHasCard(state: OnitamaState, player: PlayerType, cardName: string): boolean {
-    const cardList = player === 'red' ? state.redCards : state.blackCards;
-    return cardList.includes(cardName);
+function playerHasCard(
+  state: OnitamaState,
+  player: PlayerType,
+  cardName: string,
+): boolean {
+  const cardList = player === "red" ? state.redCards : state.blackCards;
+  return cardList.includes(cardName);
 }
 
 /**
  * 获取卡牌的移动候选项，根据玩家视角进行旋转
  * 黑方需要将卡牌旋转180度
  */
-export function getCardMoveCandidates(state: OnitamaState, cardName: string, player: PlayerType) {
-    const card = state.cards[cardName];
-    const candidates = card.moveCandidates;
+export function getCardMoveCandidates(
+  state: OnitamaState,
+  cardName: string,
+  player: PlayerType,
+) {
+  const card = state.cards[cardName];
+  const candidates = card.moveCandidates;
 
-    // 黑方需要将卡牌旋转180度
-    if (player === 'black') {
-        return candidates.map(m => ({ dx: -m.dx, dy: -m.dy }));
-    }
+  // 黑方需要将卡牌旋转180度
+  if (player === "black") {
+    return candidates.map((m) => ({ dx: -m.dx, dy: -m.dy }));
+  }
 
-    return candidates;
+  return candidates;
 }
 
 /**
  * 检查移动是否合法
  */
-export function isValidMove(state: OnitamaState, cardName: string, fromX: number, fromY: number, toX: number, toY: number, player: PlayerType): string | null {
-    // 检查玩家是否拥有该卡牌
-    if (!playerHasCard(state, player, cardName)) {
-        return `玩家 ${player} 不拥有卡牌 ${cardName}`;
-    }
+export function isValidMove(
+  state: OnitamaState,
+  cardName: string,
+  fromX: number,
+  fromY: number,
+  toX: number,
+  toY: number,
+  player: PlayerType,
+): string | null {
+  // 检查玩家是否拥有该卡牌
+  if (!playerHasCard(state, player, cardName)) {
+    return `玩家 ${player} 不拥有卡牌 ${cardName}`;
+  }
 
-    // 检查起始位置是否有玩家的棋子
-    const fromPawn = getPawnAtPosition(state, fromX, fromY);
-    if (!fromPawn) {
-        return `位置 (${fromX}, ${fromY}) 没有棋子`;
-    }
-    if (fromPawn.owner !== player) {
-        return `位置 (${fromX}, ${fromY}) 的棋子不属于玩家 ${player}`;
-    }
+  // 检查起始位置是否有玩家的棋子
+  const fromPawn = getPawnAtPosition(state, fromX, fromY);
+  if (!fromPawn) {
+    return `位置 (${fromX}, ${fromY}) 没有棋子`;
+  }
+  if (fromPawn.owner !== player) {
+    return `位置 (${fromX}, ${fromY}) 的棋子不属于玩家 ${player}`;
+  }
 
-    // 检查卡牌是否存在
-    const card = state.cards[cardName];
-    if (!card) {
-        return `卡牌 ${cardName} 不存在`;
-    }
+  // 检查卡牌是否存在
+  const card = state.cards[cardName];
+  if (!card) {
+    return `卡牌 ${cardName} 不存在`;
+  }
 
-    // 计算移动偏移量
-    const dx = toX - fromX;
-    const dy = toY - fromY;
+  // 计算移动偏移量
+  const dx = toX - fromX;
+  const dy = toY - fromY;
 
-    // 检查移动是否在卡牌的移动候选项中（黑方需要旋转180度）
-    const candidates = getCardMoveCandidates(state, cardName, player);
-    const isValid = candidates.some(m => m.dx === dx && m.dy === dy);
-    if (!isValid) {
-        return `卡牌 ${cardName} 不支持移动 (${dx}, ${dy})`;
-    }
+  // 检查移动是否在卡牌的移动候选项中（黑方需要旋转180度）
+  const candidates = getCardMoveCandidates(state, cardName, player);
+  const isValid = candidates.some((m) => m.dx === dx && m.dy === dy);
+  if (!isValid) {
+    return `卡牌 ${cardName} 不支持移动 (${dx}, ${dy})`;
+  }
 
-    // 检查目标位置是否在棋盘内
-    if (!isInBounds(toX, toY)) {
-        return `目标位置 (${toX}, ${toY}) 超出棋盘范围`;
-    }
+  // 检查目标位置是否在棋盘内
+  if (!isInBounds(toX, toY)) {
+    return `目标位置 (${toX}, ${toY}) 超出棋盘范围`;
+  }
 
-    // 检查目标位置是否有己方棋子
-    const toPawn = getPawnAtPosition(state, toX, toY);
-    if (toPawn && toPawn.owner === player) {
-        return `目标位置 (${toX}, ${toY}) 已有己方棋子`;
-    }
+  // 检查目标位置是否有己方棋子
+  const toPawn = getPawnAtPosition(state, toX, toY);
+  if (toPawn && toPawn.owner === player) {
+    return `目标位置 (${toX}, ${toY}) 已有己方棋子`;
+  }
 
-    return null;
+  return null;
 }
 
 /**
  * 执行移动
  */
-async function handleMove(game: OnitamaGame, player: PlayerType, cardName: string, fromX: number, fromY: number, toX: number, toY: number) {
-    const state = game.value;
-    
-    // 验证移动
-    const error = isValidMove(state, cardName, fromX, fromY, toX, toY, player);
-    if (error) {
-        throw new Error(error);
-    }
-    
-    const capturedPawnId = getPawnAtPosition(state, toX, toY)?.id || null;
-    
-    await game.produceAsync(state => {
-        const pawn = state.pawns[getPawnAtPosition(state, fromX, fromY)!.id];
-        
-        // 如果目标位置有敌方棋子，将其移除（吃掉）
-        if (capturedPawnId) {
-            const capturedPawn = state.pawns[capturedPawnId];
-            moveToRegion(capturedPawn, state.regions.board, null);
-        }
-        
-        // 移动棋子到目标位置
-        moveToRegion(pawn, state.regions.board, state.regions.board, [toX, toY]);
-    });
-    
-    // 交换卡牌
-    await handleSwapCard(game, player, cardName);
-    
-    return { 
-        from: { x: fromX, y: fromY }, 
-        to: { x: toX, y: toY }, 
-        card: cardName,
-        captured: capturedPawnId 
-    };
-}
+async function move(
+  game: OnitamaGame,
+  player: PlayerType,
+  cardName: string,
+  fromX: number,
+  fromY: number,
+  toX: number,
+  toY: number,
+) {
+  const state = game.value;
 
-const move = registry.register({
-    schema: 'move <player> <card:string> <fromX:number> <fromY:number> <toX:number> <toY:number>',
-    run: handleMove
-});
+  // 验证移动
+  const error = isValidMove(state, cardName, fromX, fromY, toX, toY, player);
+  if (error) {
+    throw new Error(error);
+  }
+
+  const capturedPawnId = getPawnAtPosition(state, toX, toY)?.id || null;
+
+  await game.produceAsync((state) => {
+    const pawn = state.pawns[getPawnAtPosition(state, fromX, fromY)!.id];
+
+    // 如果目标位置有敌方棋子，将其移除（吃掉）
+    if (capturedPawnId) {
+      const capturedPawn = state.pawns[capturedPawnId];
+      moveToRegion(capturedPawn, state.regions.board, null);
+    }
+
+    // 移动棋子到目标位置
+    moveToRegion(pawn, state.regions.board, state.regions.board, [toX, toY]);
+  });
+
+  // 交换卡牌
+  await swapCard(game, player, cardName);
+
+  return {
+    from: { x: fromX, y: fromY },
+    to: { x: toX, y: toY },
+    card: cardName,
+    captured: capturedPawnId,
+  };
+}
 
 /**
  * 交换卡牌：将使用的卡牌与备用卡牌交换
  */
-async function handleSwapCard(game: OnitamaGame, player: PlayerType, usedCard: string) {
-    await game.produceAsync(state => {
-        const spareCard = state.spareCard;
-        const usedCardData = state.cards[usedCard];
-        const spareCardData = state.cards[spareCard];
-        
-        // 从玩家手牌中移除使用的卡牌
-        if (player === 'red') {
-            state.redCards = state.redCards.filter(c => c !== usedCard);
-            state.redCards.push(spareCard);
-        } else {
-            state.blackCards = state.blackCards.filter(c => c !== usedCard);
-            state.blackCards.push(spareCard);
-        }
-        
-        // 更新卡牌区域
-        usedCardData.regionId = 'spare';
-        spareCardData.regionId = player;
-        
-        // 更新备用卡牌
-        state.spareCard = usedCard;
-    });
-}
+async function swapCard(
+  game: OnitamaGame,
+  player: PlayerType,
+  usedCard: string,
+) {
+  await game.produceAsync((state) => {
+    const spareCard = state.spareCard;
+    const usedCardData = state.cards[usedCard];
+    const spareCardData = state.cards[spareCard];
 
-const swapCard = registry.register({
-    schema: 'swap-card <player> <card:string>',
-    run: handleSwapCard
-});
+    // 从玩家手牌中移除使用的卡牌
+    if (player === "red") {
+      state.redCards = state.redCards.filter((c) => c !== usedCard);
+      state.redCards.push(spareCard);
+    } else {
+      state.blackCards = state.blackCards.filter((c) => c !== usedCard);
+      state.blackCards.push(spareCard);
+    }
+
+    // 更新卡牌区域
+    usedCardData.regionId = "spare";
+    spareCardData.regionId = player;
+
+    // 更新备用卡牌
+    state.spareCard = usedCard;
+  });
+}
 
 /**
  * 检查占领胜利条件：玩家的师父棋子到达对手的初始位置
  * 红色师父需要到达 (2, 4) - 黑色师父的初始位置
  * 黑色师父需要到达 (2, 0) - 红色师父的初始位置
  */
-async function handleCheckConquestWin(game: OnitamaGame): Promise<PlayerType | null> {
-    const state = game.value;
+async function checkConquestWin(game: OnitamaGame): Promise<PlayerType | null> {
+  const state = game.value;
 
-    // 红色师父到达 (2, 4)（黑色师父的初始位置）
-    const redMaster = state.pawns['red-master'];
-    if (redMaster && redMaster.regionId === 'board' && redMaster.position[0] === 2 && redMaster.position[1] === 4) {
-        return 'red';
-    }
+  // 红色师父到达 (2, 4)（黑色师父的初始位置）
+  const redMaster = state.pawns["red-master"];
+  if (
+    redMaster &&
+    redMaster.regionId === "board" &&
+    redMaster.position[0] === 2 &&
+    redMaster.position[1] === 4
+  ) {
+    return "red";
+  }
 
-    // 黑色师父到达 (2, 0)（红色师父的初始位置）
-    const blackMaster = state.pawns['black-master'];
-    if (blackMaster && blackMaster.regionId === 'board' && blackMaster.position[0] === 2 && blackMaster.position[1] === 0) {
-        return 'black';
-    }
+  // 黑色师父到达 (2, 0)（红色师父的初始位置）
+  const blackMaster = state.pawns["black-master"];
+  if (
+    blackMaster &&
+    blackMaster.regionId === "board" &&
+    blackMaster.position[0] === 2 &&
+    blackMaster.position[1] === 0
+  ) {
+    return "black";
+  }
 
-    return null;
+  return null;
 }
 
-const checkConquestWin = registry.register({
-    schema: 'check-conquest-win',
-    run: handleCheckConquestWin
-});
-
 /**
  * 检查吃掉胜利条件：对手的师父棋子被吃掉（不在棋盘上）
  */
-async function handleCheckCaptureWin(game: OnitamaGame): Promise<PlayerType | null> {
-    const state = game.value;
-    
-    // 红色师父不在棋盘上，黑色获胜
-    const redMaster = state.pawns['red-master'];
-    if (!redMaster || redMaster.regionId !== 'board') {
-        return 'black';
-    }
-    
-    // 黑色师父不在棋盘上，红色获胜
-    const blackMaster = state.pawns['black-master'];
-    if (!blackMaster || blackMaster.regionId !== 'board') {
-        return 'red';
-    }
-    
-    return null;
-}
+async function checkCaptureWin(game: OnitamaGame): Promise<PlayerType | null> {
+  const state = game.value;
 
-const checkCaptureWin = registry.register({
-    schema: 'check-capture-win',
-    run: handleCheckCaptureWin
-});
+  // 红色师父不在棋盘上，黑色获胜
+  const redMaster = state.pawns["red-master"];
+  if (!redMaster || redMaster.regionId !== "board") {
+    return "black";
+  }
+
+  // 黑色师父不在棋盘上，红色获胜
+  const blackMaster = state.pawns["black-master"];
+  if (!blackMaster || blackMaster.regionId !== "board") {
+    return "red";
+  }
+
+  return null;
+}
 
 /**
  * 综合胜利检测
  */
-async function handleCheckWin(game: OnitamaGame): Promise<PlayerType | null> {
-    const conquestWinner = await handleCheckConquestWin(game);
-    if (conquestWinner) {
-        return conquestWinner;
-    }
-    
-    const captureWinner = await handleCheckCaptureWin(game);
-    if (captureWinner) {
-        return captureWinner;
-    }
-    
-    return null;
-}
+async function checkWin(game: OnitamaGame): Promise<PlayerType | null> {
+  const conquestWinner = await checkConquestWin(game);
+  if (conquestWinner) {
+    return conquestWinner;
+  }
 
-const checkWin = registry.register({
-    schema: 'check-win',
-    run: handleCheckWin
-});
+  const captureWinner = await checkCaptureWin(game);
+  if (captureWinner) {
+    return captureWinner;
+  }
+
+  return null;
+}
 
 /**
  * 获取玩家可用的移动
  */
-export function getAvailableMoves(state: OnitamaState, player: PlayerType): Array<{card: string, fromX: number, fromY: number, toX: number, toY: number}> {
-    const moves: Array<{card: string, fromX: number, fromY: number, toX: number, toY: number}> = [];
+export function getAvailableMoves(
+  state: OnitamaState,
+  player: PlayerType,
+): Array<{
+  card: string;
+  fromX: number;
+  fromY: number;
+  toX: number;
+  toY: number;
+}> {
+  const moves: Array<{
+    card: string;
+    fromX: number;
+    fromY: number;
+    toX: number;
+    toY: number;
+  }> = [];
 
-    // 获取玩家的所有卡牌
-    const cardNames = player === 'red' ? state.redCards : state.blackCards;
+  // 获取玩家的所有卡牌
+  const cardNames = player === "red" ? state.redCards : state.blackCards;
 
-    // 获取玩家的所有棋子
-    const playerPawns = Object.values(state.pawns).filter(p => p.owner === player && p.regionId === 'board');
+  // 获取玩家的所有棋子
+  const playerPawns = Object.values(state.pawns).filter(
+    (p) => p.owner === player && p.regionId === "board",
+  );
 
-    // 对于每张卡牌
-    for (const cardName of cardNames) {
-        // 获取旋转后的移动候选项（黑方需要旋转180度）
-        const candidates = getCardMoveCandidates(state, cardName, player);
+  // 对于每张卡牌
+  for (const cardName of cardNames) {
+    // 获取旋转后的移动候选项（黑方需要旋转180度）
+    const candidates = getCardMoveCandidates(state, cardName, player);
 
-        // 对于每个棋子
-        for (const pawn of playerPawns) {
-            const [fromX, fromY] = pawn.position;
+    // 对于每个棋子
+    for (const pawn of playerPawns) {
+      const [fromX, fromY] = pawn.position;
 
-            // 对于卡牌的每个移动
-            for (const move of candidates) {
-                const toX = fromX + move.dx;
-                const toY = fromY + move.dy;
+      // 对于卡牌的每个移动
+      for (const move of candidates) {
+        const toX = fromX + move.dx;
+        const toY = fromY + move.dy;
 
-                // 检查移动是否合法
-                if (isInBounds(toX, toY)) {
-                    const targetPawn = getPawnAtPosition(state, toX, toY);
-                    // 目标位置为空或有敌方棋子
-                    if (!targetPawn || targetPawn.owner !== player) {
-                        moves.push({ card: cardName, fromX, fromY, toX, toY });
-                    }
-                }
-            }
+        // 检查移动是否合法
+        if (isInBounds(toX, toY)) {
+          const targetPawn = getPawnAtPosition(state, toX, toY);
+          // 目标位置为空或有敌方棋子
+          if (!targetPawn || targetPawn.owner !== player) {
+            moves.push({ card: cardName, fromX, fromY, toX, toY });
+          }
         }
+      }
     }
+  }
 
-    return moves;
+  return moves;
 }
 
 /**
  * 处理回合
  */
-async function handleTurn(game: OnitamaGame, turnPlayer: PlayerType) {
-    const state = game.value;
-    const availableMoves = getAvailableMoves(state, turnPlayer);
-    
-    let moveOutput;
-    
-    if (availableMoves.length === 0) {
-        // 没有可用移动，玩家必须交换一张卡牌
-        const cardToSwap = await game.prompt(
-            prompts.move,
-            (player, card, _fromX, _fromY, _toX, _toY) => {
-                if (player !== turnPlayer) {
-                    throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
-                }
-                if (!playerHasCard(state, player, card)) {
-                    throw `Player ${player} does not have card ${card}.`;
-                }
-                return card;
-            },
-            turnPlayer
-        );
-        
-        await swapCard(game, turnPlayer, cardToSwap);
-        moveOutput = { swappedCard: cardToSwap, noMoves: true };
-    } else {
-        // 有可用移动，提示玩家选择
-        moveOutput = await game.prompt(
-            prompts.move,
-            (player, card, fromX, fromY, toX, toY) => {
-                if (player !== turnPlayer) {
-                    throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
-                }
-                
-                const error = isValidMove(state, card, fromX, fromY, toX, toY, player);
-                if (error) {
-                    throw error;
-                }
-                
-                return { player, card, fromX, fromY, toX, toY };
-            },
-            turnPlayer
-        );
-        
-        await move(game, moveOutput.player, moveOutput.card, moveOutput.fromX, moveOutput.fromY, moveOutput.toX, moveOutput.toY);
-    }
-    
-    // 检查胜利
-    const winner = await checkWin(game);
-    
-    await game.produceAsync(state => {
-        state.winner = winner;
-        if (!winner) {
-            state.currentPlayer = state.currentPlayer === 'red' ? 'black' : 'red';
-            state.turn++;
-        }
-    });
-    
-    return { winner, move: moveOutput };
-}
+async function turn(game: OnitamaGame, turnPlayer: PlayerType) {
+  const state = game.value;
+  const availableMoves = getAvailableMoves(state, turnPlayer);
 
-const turn = registry.register({
-    schema: 'turn <player>',
-    run: handleTurn
-});
+  let moveOutput;
+
+  if (availableMoves.length === 0) {
+    // 没有可用移动，玩家必须交换一张卡牌
+    const cardToSwap = await game.prompt(
+      prompts.move,
+      (player, card, _fromX, _fromY, _toX, _toY) => {
+        if (player !== turnPlayer) {
+          throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
+        }
+        if (!playerHasCard(state, player, card)) {
+          throw `Player ${player} does not have card ${card}.`;
+        }
+        return card;
+      },
+      turnPlayer,
+    );
+
+    await swapCard(game, turnPlayer, cardToSwap);
+    moveOutput = { swappedCard: cardToSwap, noMoves: true };
+  } else {
+    // 有可用移动，提示玩家选择
+    moveOutput = await game.prompt(
+      prompts.move,
+      (player, card, fromX, fromY, toX, toY) => {
+        if (player !== turnPlayer) {
+          throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
+        }
+
+        const error = isValidMove(state, card, fromX, fromY, toX, toY, player);
+        if (error) {
+          throw error;
+        }
+
+        return { player, card, fromX, fromY, toX, toY };
+      },
+      turnPlayer,
+    );
+
+    await move(
+      game,
+      moveOutput.player,
+      moveOutput.card,
+      moveOutput.fromX,
+      moveOutput.fromY,
+      moveOutput.toX,
+      moveOutput.toY,
+    );
+  }
+
+  // 检查胜利
+  const winner = await checkWin(game);
+
+  await game.produceAsync((state) => {
+    state.winner = winner;
+    if (!winner) {
+      state.currentPlayer = state.currentPlayer === "red" ? "black" : "red";
+      state.turn++;
+    }
+  });
+
+  return { winner, move: moveOutput };
+}
 
 /**
  * 开始游戏主循环
  */
 export async function start(game: OnitamaGame) {
-    // Initialize cards with RNG at game start
-    initializeCards(game);
+  // Initialize cards with RNG at game start
+  initializeCards(game);
 
-    while (true) {
-        const currentPlayer = game.value.currentPlayer;
-        const turnOutput = await turn(game, currentPlayer);
+  while (true) {
+    const currentPlayer = game.value.currentPlayer;
+    const turnOutput = await turn(game, currentPlayer);
 
-        if (turnOutput.winner) {
-            break;
-        }
+    if (turnOutput.winner) {
+      break;
     }
+  }
 
-    return game.value;
+  return game.value;
 }

src/samples/regicide/commands/index.ts

@@ -1,421 +1,417 @@
-import {IGameContext} from "@/core/game";
-import {RegicideState} from "@/samples/regicide/state";
-import {createGameCommandRegistry} from "@/core/game";
-import {PlayerType, RegicideCard} from "@/samples/regicide/types";
-import {CARD_VALUES, FACE_CARDS} from "@/samples/regicide/constants";
-import {isEnemyDefeated} from "@/samples/regicide/utils";
+import { IGameContext } from "@/core/game";
+import { RegicideState } from "@/samples/regicide/state";
+import { PlayerType, RegicideCard } from "@/samples/regicide/types";
+import { CARD_VALUES, FACE_CARDS } from "@/samples/regicide/constants";
+import { isEnemyDefeated } from "@/samples/regicide/utils";
 
 export type RegicideGame = IGameContext<RegicideState>;
 
-export const registry = createGameCommandRegistry<RegicideState>();
-
 /**
  * 打出一张牌（对当前敌人造成伤害）
  */
-const playCmd = registry.register({
-    schema: 'play <player:string> <cardId:string>',
-    run: async (game: RegicideGame, player: string, cardId: string) => {
-        const state = game.value;
-        const card = state.cards[cardId];
+async function playCmd(game: RegicideGame, player: string, cardId: string) {
+  const state = game.value;
+  const card = state.cards[cardId];
 
-        if (!card) {
-            return {success: false, error: `卡牌 ${cardId} 不存在`};
-        }
+  if (!card) {
+    return { success: false, error: `卡牌 ${cardId} 不存在` };
+  }
 
-        // 检查卡牌是否在玩家手牌中
-        const playerKey = player as PlayerType;
-        const playerHand = state.playerHands[playerKey];
-        if (!playerHand || !playerHand.includes(cardId)) {
-            return {success: false, error: `卡牌 ${cardId} 不在玩家 ${player} 的手牌中`};
-        }
+  // 检查卡牌是否在玩家手牌中
+  const playerKey = player as PlayerType;
+  const playerHand = state.playerHands[playerKey];
+  if (!playerHand || !playerHand.includes(cardId)) {
+    return {
+      success: false,
+      error: `卡牌 ${cardId} 不在玩家 ${player} 的手牌中`,
+    };
+  }
 
-        // 检查是否有当前敌人
-        if (!state.currentEnemy) {
-            return {success: false, error: '没有活跃的敌人'};
-        }
+  // 检查是否有当前敌人
+  if (!state.currentEnemy) {
+    return { success: false, error: "没有活跃的敌人" };
+  }
 
-        // 计算伤害（基础伤害为卡牌面值）
-        let damage = card.value;
-        let attackReduction = 0;
+  // 计算伤害（基础伤害为卡牌面值）
+  let damage = card.value;
+  let attackReduction = 0;
 
-        // 梅花双倍伤害
-        if (card.suit === 'clubs') {
-            damage *= 2;
-        }
+  // 梅花双倍伤害
+  if (card.suit === "clubs") {
+    damage *= 2;
+  }
 
-        // 黑桃降低敌人攻击力
-        if (card.suit === 'spades') {
-            attackReduction = card.value;
-        }
+  // 黑桃降低敌人攻击力
+  if (card.suit === "spades") {
+    attackReduction = card.value;
+  }
 
-        const enemyHpBefore = state.currentEnemy.hp;
+  const enemyHpBefore = state.currentEnemy.hp;
 
-        await game.produce(state => {
-            // 对敌人造成伤害
-            state.currentEnemy!.hp -= damage;
+  await game.produceAsync((state) => {
+    // 对敌人造成伤害
+    state.currentEnemy!.hp -= damage;
 
-            // 记录黑桃的攻击力降低
-            if (attackReduction > 0) {
-                state.currentEnemy!.value = Math.max(0, state.currentEnemy!.value - attackReduction);
-            }
-
-            // 从手牌移除卡牌
-            const hand = state.playerHands[playerKey];
-            const cardIndex = hand.indexOf(cardId);
-            if (cardIndex !== -1) {
-                hand.splice(cardIndex, 1);
-            }
-
-            // 将卡牌移到弃牌堆
-            state.cards[cardId].regionId = 'discardPile';
-
-            // 红心能力：将弃牌堆洗回酒馆牌堆
-            if (card.suit === 'hearts') {
-                const discardIds = state.regions.discardPile.childIds.filter(id => id !== state.currentEnemy!.id);
-                if (discardIds.length > 0) {
-                    // 将弃牌堆（除当前敌人外）移回酒馆牌堆
-                    for (const discardId of discardIds) {
-                        state.cards[discardId].regionId = 'tavernDeck';
-                    }
-                    state.regions.tavernDeck.childIds.push(...discardIds);
-                    state.regions.discardPile.childIds = [state.currentEnemy!.id];
-                }
-            }
-
-            // 方块能力：从酒馆牌堆抓牌
-            if (card.suit === 'diamonds') {
-                const tavernDeckCount = state.regions.tavernDeck.childIds.length;
-                if (tavernDeckCount > 0) {
-                    const drawCardId = state.regions.tavernDeck.childIds.shift()!;
-                    state.cards[drawCardId].regionId = `hand_${player}`;
-                    hand.push(drawCardId);
-                }
-            }
-        });
-
-        // 检查敌人是否被击败
-        const enemyDefeated = isEnemyDefeated(game.value.currentEnemy);
-
-        return {
-            success: true,
-            result: {
-                damage,
-                attackReduction,
-                enemyHpBefore,
-                enemyHpAfter: game.value.currentEnemy!.hp,
-                enemyDefeated,
-                suitAbility: card.suit
-            }
-        };
+    // 记录黑桃的攻击力降低
+    if (attackReduction > 0) {
+      state.currentEnemy!.value = Math.max(
+        0,
+        state.currentEnemy!.value - attackReduction,
+      );
     }
-});
+
+    // 从手牌移除卡牌
+    const hand = state.playerHands[playerKey];
+    const cardIndex = hand.indexOf(cardId);
+    if (cardIndex !== -1) {
+      hand.splice(cardIndex, 1);
+    }
+
+    // 将卡牌移到弃牌堆
+    state.cards[cardId].regionId = "discardPile";
+
+    // 红心能力：将弃牌堆洗回酒馆牌堆
+    if (card.suit === "hearts") {
+      const discardIds = state.regions.discardPile.childIds.filter(
+        (id) => id !== state.currentEnemy!.id,
+      );
+      if (discardIds.length > 0) {
+        // 将弃牌堆（除当前敌人外）移回酒馆牌堆
+        for (const discardId of discardIds) {
+          state.cards[discardId].regionId = "tavernDeck";
+        }
+        state.regions.tavernDeck.childIds.push(...discardIds);
+        state.regions.discardPile.childIds = [state.currentEnemy!.id];
+      }
+    }
+
+    // 方块能力：从酒馆牌堆抓牌
+    if (card.suit === "diamonds") {
+      const tavernDeckCount = state.regions.tavernDeck.childIds.length;
+      if (tavernDeckCount > 0) {
+        const drawCardId = state.regions.tavernDeck.childIds.shift()!;
+        state.cards[drawCardId].regionId = `hand_${player}`;
+        hand.push(drawCardId);
+      }
+    }
+  });
+
+  // 检查敌人是否被击败
+  const enemyDefeated = isEnemyDefeated(game.value.currentEnemy);
+
+  return {
+    success: true,
+    result: {
+      damage,
+      attackReduction,
+      enemyHpBefore,
+      enemyHpAfter: game.value.currentEnemy!.hp,
+      enemyDefeated,
+      suitAbility: card.suit,
+    },
+  };
+}
 
 /**
  * 打出A配合另一张牌
  */
-const playWithACmd = registry.register({
-    schema: 'play-with-a <player:string> <aceCardId:string> <otherCardId:string>',
-    run: async (game: RegicideGame, player: string, aceCardId: string, otherCardId: string) => {
-        const state = game.value;
-        const aceCard = state.cards[aceCardId];
-        const otherCard = state.cards[otherCardId];
+async function playWithACmd(
+  game: RegicideGame,
+  player: string,
+  aceCardId: string,
+  otherCardId: string,
+) {
+  const state = game.value;
+  const aceCard = state.cards[aceCardId];
+  const otherCard = state.cards[otherCardId];
 
-        if (!aceCard || !otherCard) {
-            return {success: false, error: '卡牌不存在'};
-        }
+  if (!aceCard || !otherCard) {
+    return { success: false, error: "卡牌不存在" };
+  }
 
-        // 检查是否是A牌
-        if (aceCard.rank !== 'A') {
-            return {success: false, error: `第一张牌必须是A`};
-        }
+  // 检查是否是A牌
+  if (aceCard.rank !== "A") {
+    return { success: false, error: `第一张牌必须是A` };
+  }
 
-        const playerKey = player as PlayerType;
-        const playerHand = state.playerHands[playerKey];
+  const playerKey = player as PlayerType;
+  const playerHand = state.playerHands[playerKey];
 
-        // 检查两张牌都在手牌中
-        if (!playerHand.includes(aceCardId) || !playerHand.includes(otherCardId)) {
-            return {success: false, error: '卡牌不在手牌中'};
-        }
+  // 检查两张牌都在手牌中
+  if (!playerHand.includes(aceCardId) || !playerHand.includes(otherCardId)) {
+    return { success: false, error: "卡牌不在手牌中" };
+  }
 
-        if (!state.currentEnemy) {
-            return {success: false, error: '没有活跃的敌人'};
-        }
+  if (!state.currentEnemy) {
+    return { success: false, error: "没有活跃的敌人" };
+  }
 
-        // 计算两张牌的总伤害
-        let totalDamage = aceCard.value + otherCard.value;
+  // 计算两张牌的总伤害
+  let totalDamage = aceCard.value + otherCard.value;
 
-        // 如果另一张牌是梅花，双倍伤害
-        if (otherCard.suit === 'clubs') {
-            totalDamage *= 2;
-        }
+  // 如果另一张牌是梅花，双倍伤害
+  if (otherCard.suit === "clubs") {
+    totalDamage *= 2;
+  }
 
-        let attackReduction = 0;
-        if (aceCard.suit === 'spades') {
-            attackReduction += aceCard.value;
-        }
-        if (otherCard.suit === 'spades') {
-            attackReduction += otherCard.value;
-        }
+  let attackReduction = 0;
+  if (aceCard.suit === "spades") {
+    attackReduction += aceCard.value;
+  }
+  if (otherCard.suit === "spades") {
+    attackReduction += otherCard.value;
+  }
 
-        await game.produce(state => {
-            // 对敌人造成伤害
-            state.currentEnemy!.hp -= totalDamage;
+  await game.produceAsync((state) => {
+    // 对敌人造成伤害
+    state.currentEnemy!.hp -= totalDamage;
 
-            // 记录黑桃的攻击力降低
-            if (attackReduction > 0) {
-                state.currentEnemy!.value = Math.max(0, state.currentEnemy!.value - attackReduction);
-            }
-
-            // 从手牌移除两张牌
-            const hand = state.playerHands[playerKey];
-            const aceIndex = hand.indexOf(aceCardId);
-            const otherIndex = hand.indexOf(otherCardId);
-            if (aceIndex !== -1) hand.splice(aceIndex, 1);
-            if (otherIndex !== -1) hand.splice(otherIndex, 1);
-
-            // 将卡牌移到弃牌堆
-            state.cards[aceCardId].regionId = 'discardPile';
-            state.cards[otherCardId].regionId = 'discardPile';
-        });
-
-        const enemyDefeated = isEnemyDefeated(state.currentEnemy);
-
-        return {
-            success: true,
-            result: {
-                damage: totalDamage,
-                attackReduction,
-                enemyHp: state.currentEnemy!.hp,
-                enemyDefeated
-            }
-        };
+    // 记录黑桃的攻击力降低
+    if (attackReduction > 0) {
+      state.currentEnemy!.value = Math.max(
+        0,
+        state.currentEnemy!.value - attackReduction,
+      );
     }
-});
+
+    // 从手牌移除两张牌
+    const hand = state.playerHands[playerKey];
+    const aceIndex = hand.indexOf(aceCardId);
+    const otherIndex = hand.indexOf(otherCardId);
+    if (aceIndex !== -1) hand.splice(aceIndex, 1);
+    if (otherIndex !== -1) hand.splice(otherIndex, 1);
+
+    // 将卡牌移到弃牌堆
+    state.cards[aceCardId].regionId = "discardPile";
+    state.cards[otherCardId].regionId = "discardPile";
+  });
+
+  const enemyDefeated = isEnemyDefeated(state.currentEnemy);
+
+  return {
+    success: true,
+    result: {
+      damage: totalDamage,
+      attackReduction,
+      enemyHp: state.currentEnemy!.hp,
+      enemyDefeated,
+    },
+  };
+}
 
 /**
  * 让过（不出牌）
  */
-const passCmd = registry.register({
-    schema: 'pass <player:string>',
-    run: async (game: RegicideGame, player: string) => {
-        // 即使让过，也会受到敌人反击（在回合结束时处理）
-        return {success: true, result: {message: `${player} 让过`}};
-    }
-});
+async function passCmd(game: RegicideGame, player: string) {
+  // 即使让过，也会受到敌人反击（在回合结束时处理）
+  return { success: true, result: { message: `${player} 让过` } };
+}
 
 /**
  * 敌人反击 - 玩家必须弃掉点数和 >= 敌人攻击力的牌
  */
-const enemyCounterattackCmd = registry.register({
-    schema: 'counterattack <player:string> <discardCards:string[]>',
-    run: async (game: RegicideGame, player: string, discardCards: string[]) => {
-        const state = game.value;
+async function enemyCounterattackCmd(
+  game: RegicideGame,
+  player: string,
+  discardCards: string[],
+) {
+  const state = game.value;
 
-        if (!state.currentEnemy) {
-            return {success: false, error: '没有活跃的敌人'};
-        }
+  if (!state.currentEnemy) {
+    return { success: false, error: "没有活跃的敌人" };
+  }
 
-        const playerKey = player as PlayerType;
-        const playerHand = state.playerHands[playerKey];
+  const playerKey = player as PlayerType;
+  const playerHand = state.playerHands[playerKey];
 
-        // 检查要弃的牌都在手牌中
-        for (const cardId of discardCards) {
-            if (!playerHand.includes(cardId)) {
-                return {success: false, error: `卡牌 ${cardId} 不在手牌中`};
-            }
-        }
-
-        // 计算弃牌的点数和
-        let totalValue = 0;
-        for (const cardId of discardCards) {
-            const card = state.cards[cardId];
-            if (card) {
-                totalValue += card.value;
-            }
-        }
-
-        const enemyAttack = state.currentEnemy.value;
-
-        // 检查点数和是否 >= 敌人攻击力
-        if (totalValue < enemyAttack) {
-            return {
-                success: false,
-                error: `弃牌点数和 (${totalValue}) 小于敌人攻击力 (${enemyAttack})，游戏失败`
-            };
-        }
-
-        // 执行弃牌
-        await game.produce(state => {
-            const hand = state.playerHands[playerKey];
-            for (const cardId of discardCards) {
-                const index = hand.indexOf(cardId);
-                if (index !== -1) {
-                    hand.splice(index, 1);
-                }
-                state.cards[cardId].regionId = 'discardPile';
-            }
-        });
-
-        return {
-            success: true,
-            result: {
-                discardedCards: discardCards,
-                totalValue,
-                enemyAttack
-            }
-        };
+  // 检查要弃的牌都在手牌中
+  for (const cardId of discardCards) {
+    if (!playerHand.includes(cardId)) {
+      return { success: false, error: `卡牌 ${cardId} 不在手牌中` };
     }
-});
+  }
+
+  // 计算弃牌的点数和
+  let totalValue = 0;
+  for (const cardId of discardCards) {
+    const card = state.cards[cardId];
+    if (card) {
+      totalValue += card.value;
+    }
+  }
+
+  const enemyAttack = state.currentEnemy.value;
+
+  // 检查点数和是否 >= 敌人攻击力
+  if (totalValue < enemyAttack) {
+    return {
+      success: false,
+      error: `弃牌点数和 (${totalValue}) 小于敌人攻击力 (${enemyAttack})，游戏失败`,
+    };
+  }
+
+  // 执行弃牌
+  await game.produceAsync((state) => {
+    const hand = state.playerHands[playerKey];
+    for (const cardId of discardCards) {
+      const index = hand.indexOf(cardId);
+      if (index !== -1) {
+        hand.splice(index, 1);
+      }
+      state.cards[cardId].regionId = "discardPile";
+    }
+  });
+
+  return {
+    success: true,
+    result: {
+      discardedCards: discardCards,
+      totalValue,
+      enemyAttack,
+    },
+  };
+}
 
 /**
  * 检查敌人是否被击败，如果击败则翻开下一个敌人
  */
-const checkEnemyDefeatedCmd = registry.register({
-    schema: 'check-enemy',
-    run: async (game: RegicideGame) => {
-        const state = game.value;
+async function checkEnemyDefeatedCmd(game: RegicideGame) {
+  const state = game.value;
 
-        if (!state.currentEnemy) {
-            return {success: false, error: '没有活跃的敌人'};
-        }
+  if (!state.currentEnemy) {
+    return { success: false as const, error: "没有活跃的敌人" };
+  }
 
-        const defeated = state.currentEnemy.hp <= 0;
+  const defeated = state.currentEnemy.hp <= 0;
 
-        if (defeated) {
-            const defeatedEnemy = {...state.currentEnemy};
+  if (defeated) {
+    const defeatedEnemy = { ...state.currentEnemy };
 
-            await game.produce(state => {
-                // 将当前敌人移到弃牌堆
-                state.regions.discardPile.childIds.push(state.currentEnemy!.id);
+    await game.produceAsync((state) => {
+      // 将当前敌人移到弃牌堆
+      state.regions.discardPile.childIds.push(state.currentEnemy!.id);
 
-                // 翻开下一个敌人
-                if (state.enemyDeck.length > 0) {
-                    const nextEnemy = state.enemyDeck.shift()!;
-                    state.currentEnemy = nextEnemy;
-                } else {
-                    // 没有更多敌人了
-                    state.currentEnemy = null;
-                }
-            });
+      // 翻开下一个敌人
+      if (state.enemyDeck.length > 0) {
+        const nextEnemy = state.enemyDeck.shift()!;
+        state.currentEnemy = nextEnemy;
+      } else {
+        // 没有更多敌人了
+        state.currentEnemy = null;
+      }
+    });
 
-            // 检查是否胜利（没有更多敌人）
-            if (!game.value.currentEnemy) {
-                await game.produce(state => {
-                    state.phase = 'victory';
-                    state.winner = true;
-                });
-            }
-
-            return {
-                success: true,
-                result: {
-                    defeated: true,
-                    defeatedEnemy,
-                    nextEnemy: game.value.currentEnemy,
-                    enemiesRemaining: game.value.enemyDeck.length
-                }
-            };
-        }
-
-        return {
-            success: true,
-            result: {
-                defeated: false,
-                currentEnemy: {...state.currentEnemy},
-                enemiesRemaining: state.enemyDeck.length
-            }
-        };
+    // 检查是否胜利（没有更多敌人）
+    if (!game.value.currentEnemy) {
+      await game.produceAsync((state) => {
+        state.phase = "victory";
+        state.winner = true;
+      });
     }
-});
+
+    return {
+      success: true as const,
+      result: {
+        defeated: true,
+        defeatedEnemy,
+        nextEnemy: game.value.currentEnemy,
+        enemiesRemaining: game.value.enemyDeck.length,
+      },
+    };
+  }
+
+  return {
+    success: true,
+    result: {
+      defeated: false,
+      currentEnemy: { ...state.currentEnemy },
+      enemiesRemaining: state.enemyDeck.length,
+    },
+  };
+}
 
 /**
  * 检查玩家是否有可出的牌
  */
-const checkCanPlayCmd = registry.register({
-    schema: 'check-can-play <player:string>',
-    run: async (game: RegicideGame, player: string) => {
-        const state = game.value;
-        const playerKey = player as PlayerType;
-        const playerHand = state.playerHands[playerKey];
+async function checkCanPlayCmd(game: RegicideGame, player: string) {
+  const state = game.value;
+  const playerKey = player as PlayerType;
+  const playerHand = state.playerHands[playerKey];
 
-        const canPlay = playerHand.length > 0;
-        const canPlayWithA = playerHand.some(cardId => {
-            const card = state.cards[cardId];
-            return card && card.rank === 'A' && playerHand.length > 1;
-        });
+  const canPlay = playerHand.length > 0;
+  const canPlayWithA = playerHand.some((cardId) => {
+    const card = state.cards[cardId];
+    return card && card.rank === "A" && playerHand.length > 1;
+  });
 
-        return {
-            success: true,
-            result: {
-                canPlay,
-                canPlayWithA,
-                handSize: playerHand.length
-            }
-        };
-    }
-});
+  return {
+    success: true,
+    result: {
+      canPlay,
+      canPlayWithA,
+      handSize: playerHand.length,
+    },
+  };
+}
 
 /**
  * 检查酒馆牌堆是否为空
  */
-const checkTavernDeckCmd = registry.register({
-    schema: 'check-tavern-deck',
-    run: async (game: RegicideGame) => {
-        const state = game.value;
-        const isEmpty = state.regions.tavernDeck.childIds.length === 0;
+async function checkTavernDeckCmd(game: RegicideGame) {
+  const state = game.value;
+  const isEmpty = state.regions.tavernDeck.childIds.length === 0;
 
-        // 如果酒馆牌堆为空且所有玩家手牌也为空，则游戏失败
-        if (isEmpty) {
-            const allHandsEmpty = Object.values(state.playerHands).every(hand => hand.length === 0);
-            if (allHandsEmpty) {
-                await game.produce(state => {
-                    state.phase = 'defeat';
-                    state.winner = false;
-                });
-            }
-        }
-
-        return {
-            success: true,
-            result: {
-                isEmpty,
-                cardsRemaining: state.regions.tavernDeck.childIds.length
-            }
-        };
+  // 如果酒馆牌堆为空且所有玩家手牌也为空，则游戏失败
+  if (isEmpty) {
+    const allHandsEmpty = Object.values(state.playerHands).every(
+      (hand) => hand.length === 0,
+    );
+    if (allHandsEmpty) {
+      await game.produceAsync((state) => {
+        state.phase = "defeat";
+        state.winner = false;
+      });
     }
-});
+  }
+
+  return {
+    success: true,
+    result: {
+      isEmpty,
+      cardsRemaining: state.regions.tavernDeck.childIds.length,
+    },
+  };
+}
 
 /**
  * 下一个玩家回合
  */
-const nextTurnCmd = registry.register({
-    schema: 'next-turn',
-    run: async (game: RegicideGame) => {
-        const state = game.value;
-        await game.produce(state => {
-            state.currentPlayerIndex = (state.currentPlayerIndex + 1) % state.playerCount;
-        });
+async function nextTurnCmd(game: RegicideGame) {
+  const state = game.value;
+  await game.produce((state) => {
+    state.currentPlayerIndex =
+      (state.currentPlayerIndex + 1) % state.playerCount;
+  });
 
-        const players: PlayerType[] = ['player1', 'player2', 'player3', 'player4'];
-        const currentPlayer = players[game.value.currentPlayerIndex];
+  const players: PlayerType[] = ["player1", "player2", "player3", "player4"];
+  const currentPlayer = players[game.value.currentPlayerIndex];
 
-        return {
-            success: true,
-            result: {
-                currentPlayer,
-                currentPlayerIndex: game.value.currentPlayerIndex
-            }
-        };
-    }
-});
+  return {
+    success: true,
+    result: {
+      currentPlayer,
+      currentPlayerIndex: game.value.currentPlayerIndex,
+    },
+  };
+}
 
 export {
-    playCmd as play,
-    playWithACmd as playWithA,
-    passCmd as pass,
-    enemyCounterattackCmd as enemyCounterattack,
-    checkEnemyDefeatedCmd as checkEnemy,
-    checkCanPlayCmd as checkCanPlay,
-    checkTavernDeckCmd as checkTavernDeck,
-    nextTurnCmd as nextTurn,
+  playCmd as play,
+  playWithACmd as playWithA,
+  passCmd as pass,
+  enemyCounterattackCmd as enemyCounterattack,
+  checkEnemyDefeatedCmd as checkEnemy,
+  checkCanPlayCmd as checkCanPlay,
+  checkTavernDeckCmd as checkTavernDeck,
+  nextTurnCmd as nextTurn,
 };

src/samples/regicide/game.ts

@@ -1,8 +1,15 @@
-import {IGameContext} from "@/core/game";
-import {RegicideState} from "@/samples/regicide/state";
-import {buildEnemyDeck, buildTavernDeck, createAllCards, getPlayerHandRegionId} from "@/samples/regicide/utils";
-import {INITIAL_HAND_SIZE} from "@/samples/regicide/constants";
-import {Enemy, PlayerType, RegicideCard} from "@/samples/regicide/types";
+import { IGameContext } from "@/core/game";
+import { RegicideState } from "@/samples/regicide/state";
+import {
+  buildEnemyDeck,
+  buildTavernDeck,
+  createAllCards,
+  getPlayerHandRegionId,
+} from "@/samples/regicide/utils";
+import { INITIAL_HAND_SIZE } from "@/samples/regicide/constants";
+import { Enemy, PlayerType, RegicideCard } from "@/samples/regicide/types";
+import { checkEnemy, nextTurn, pass, playWithA } from "./commands";
+import { enemyCounterattackCmd, playCmd } from ".";
 
 export type RegicideGame = IGameContext<RegicideState>;
 
@@ -12,228 +19,255 @@ export type RegicideGame = IGameContext<RegicideState>;
  * @param playerCount 玩家数量（1-4）
  * @param seed 随机种子（可选）
  */
-export async function setupGame(game: RegicideGame, playerCount: number, seed?: number) {
-    if (playerCount < 1 || playerCount > 4) {
-        throw new Error('玩家数量必须为 1-4 人');
+export async function setupGame(
+  game: RegicideGame,
+  playerCount: number,
+  seed?: number,
+) {
+  if (playerCount < 1 || playerCount > 4) {
+    throw new Error("玩家数量必须为 1-4 人");
+  }
+
+  if (seed) {
+    // RNG seeding handled by game context
+  }
+
+  // 创建所有卡牌
+  const allCards = createAllCards();
+
+  // 构建敌人牌堆（J/Q/K）
+  const enemyDeck = buildEnemyDeck(game._rng);
+
+  // 构建酒馆牌堆（A-10）
+  const tavernDeck = buildTavernDeck(game._rng);
+
+  // 初始化游戏状态
+  await game.produceAsync((state) => {
+    state.cards = allCards;
+    state.playerCount = playerCount;
+    state.currentPlayerIndex = 0;
+    state.enemyDeck = enemyDeck;
+
+    // 设置酒馆牌堆区域
+    for (const card of tavernDeck) {
+      card.regionId = "tavernDeck";
+      state.regions.tavernDeck.childIds.push(card.id);
     }
 
-    if (seed) {
-        // RNG seeding handled by game context
+    // 设置敌人牌堆区域（只存储ID，敌人是独立对象）
+    state.regions.enemyDeck.childIds = enemyDeck.map((e) => e.id);
+
+    // 给每个玩家发牌
+    const players: PlayerType[] = ["player1", "player2", "player3", "player4"];
+    for (let i = 0; i < playerCount; i++) {
+      const player = players[i];
+      const regionId = getPlayerHandRegionId(player);
+
+      for (let j = 0; j < INITIAL_HAND_SIZE; j++) {
+        if (tavernDeck.length === 0) break;
+        const card = tavernDeck.shift()!;
+        card.regionId = regionId;
+        state.playerHands[player].push(card.id);
+        const region = state.regions[regionId as keyof typeof state.regions];
+        region.childIds.push(card.id);
+      }
     }
 
-    // 创建所有卡牌
-    const allCards = createAllCards();
-
-    // 构建敌人牌堆（J/Q/K）
-    const enemyDeck = buildEnemyDeck(game._rng);
-
-    // 构建酒馆牌堆（A-10）
-    const tavernDeck = buildTavernDeck(game._rng);
-
-    // 初始化游戏状态
-    await game.produceAsync(state => {
-        state.cards = allCards;
-        state.playerCount = playerCount;
-        state.currentPlayerIndex = 0;
-        state.enemyDeck = enemyDeck;
-
-        // 设置酒馆牌堆区域
-        for (const card of tavernDeck) {
-            card.regionId = 'tavernDeck';
-            state.regions.tavernDeck.childIds.push(card.id);
-        }
-
-        // 设置敌人牌堆区域（只存储ID，敌人是独立对象）
-        state.regions.enemyDeck.childIds = enemyDeck.map(e => e.id);
-
-        // 给每个玩家发牌
-        const players: PlayerType[] = ['player1', 'player2', 'player3', 'player4'];
-        for (let i = 0; i < playerCount; i++) {
-            const player = players[i];
-            const regionId = getPlayerHandRegionId(player);
-
-            for (let j = 0; j < INITIAL_HAND_SIZE; j++) {
-                if (tavernDeck.length === 0) break;
-                const card = tavernDeck.shift()!;
-                card.regionId = regionId;
-                state.playerHands[player].push(card.id);
-                const region = state.regions[regionId as keyof typeof state.regions];
-                region.childIds.push(card.id);
-            }
-        }
-
-        // 翻开第一个敌人
-        if (enemyDeck.length > 0) {
-            const firstEnemy = enemyDeck.shift()!;
-            state.currentEnemy = firstEnemy;
-        }
-    });
+    // 翻开第一个敌人
+    if (enemyDeck.length > 0) {
+      const firstEnemy = enemyDeck.shift()!;
+      state.currentEnemy = firstEnemy;
+    }
+  });
 }
 
 /**
  * 启动游戏主循环
  */
 export async function start(game: RegicideGame) {
-    const state = game.value;
+  const state = game.value;
 
-    // 检查游戏是否已设置
-    if (!state.currentEnemy) {
-        throw new Error('请先调用 setupGame 初始化游戏');
+  // 检查游戏是否已设置
+  if (!state.currentEnemy) {
+    throw new Error("请先调用 setupGame 初始化游戏");
+  }
+
+  const players: PlayerType[] = ["player1", "player2", "player3", "player4"];
+
+  // 主游戏循环
+  while (state.phase === "playing") {
+    const currentPlayerIndex = state.currentPlayerIndex;
+    const currentPlayer = players[currentPlayerIndex];
+
+    // 检查当前玩家是否有手牌
+    const currentHand = state.playerHands[currentPlayer];
+    if (currentHand.length === 0) {
+      // 玩家没有手牌，跳过回合
+      await game.produceAsync((state) => {
+        state.currentPlayerIndex =
+          (state.currentPlayerIndex + 1) % state.playerCount;
+      });
+      continue;
     }
 
-    const players: PlayerType[] = ['player1', 'player2', 'player3', 'player4'];
+    // 等待玩家输入（出牌或让过）
+    // 这里需要外部通过 prompt 系统获取输入
+    // 实际使用时由 UI 或测试代码提供输入
 
-    // 主游戏循环
-    while (state.phase === 'playing') {
-        const currentPlayerIndex = state.currentPlayerIndex;
-        const currentPlayer = players[currentPlayerIndex];
+    // 循环会在外部调用 play/pass 命令后继续
+    // 当 phase 变为 'victory' 或 'defeat' 时退出
+    break;
+  }
 
-        // 检查当前玩家是否有手牌
-        const currentHand = state.playerHands[currentPlayer];
-        if (currentHand.length === 0) {
-            // 玩家没有手牌，跳过回合
-            await game.produceAsync(state => {
-                state.currentPlayerIndex = (state.currentPlayerIndex + 1) % state.playerCount;
-            });
-            continue;
-        }
-
-        // 等待玩家输入（出牌或让过）
-        // 这里需要外部通过 prompt 系统获取输入
-        // 实际使用时由 UI 或测试代码提供输入
-
-        // 循环会在外部调用 play/pass 命令后继续
-        // 当 phase 变为 'victory' 或 'defeat' 时退出
-        break;
-    }
-
-    return game.value;
+  return game.value;
 }
 
 /**
  * 处理完整的玩家回合
  */
-export async function playTurn(game: RegicideGame, player: PlayerType, action: 'play' | 'pass', cardId?: string, secondCardId?: string) {
-    const state = game.value;
+export async function playTurn(
+  game: RegicideGame,
+  player: PlayerType,
+  action: "play" | "pass",
+  cardId?: string,
+  secondCardId?: string,
+) {
+  const state = game.value;
 
-    if (state.phase !== 'playing') {
-        return {success: false, error: '游戏已结束'};
-    }
+  if (state.phase !== "playing") {
+    return { success: false, error: "游戏已结束" };
+  }
 
-    if (!state.currentEnemy) {
-        return {success: false, error: '没有活跃的敌人'};
-    }
+  if (!state.currentEnemy) {
+    return { success: false, error: "没有活跃的敌人" };
+  }
 
-    let playResult: any;
+  let playResult: any;
 
-    // 执行玩家动作
-    if (action === 'play' && cardId) {
-        // 检查是否是A配合另一张牌
-        const card = state.cards[cardId];
-        if (card.rank === 'A' && secondCardId) {
-            playResult = await game.run(`play-with-a ${player} ${cardId} ${secondCardId}`);
-        } else {
-            playResult = await game.run(`play ${player} ${cardId}`);
-        }
+  // 执行玩家动作
+  if (action === "play" && cardId) {
+    // 检查是否是A配合另一张牌
+    const card = state.cards[cardId];
+    if (card.rank === "A" && secondCardId) {
+      playResult = await playWithA(game, player, cardId, secondCardId);
     } else {
-        // 让过
-        playResult = await game.run(`pass ${player}`);
+      playResult = await playCmd(game, player, cardId);
     }
+  } else {
+    // 让过
+    playResult = await pass(game, player);
+  }
 
-    if (!playResult.success) {
-        return playResult;
-    }
+  if (!playResult.success) {
+    return playResult;
+  }
 
-    // 检查敌人是否被击败
-    const checkResult = await game.run<{defeated: boolean; currentEnemy?: any; nextEnemy?: any; defeatedEnemy?: any; enemiesRemaining?: number}>('check-enemy');
-    if (!checkResult.success) {
-        return checkResult;
-    }
-
-    // 如果敌人未被击败，处理反击
-    if (!checkResult.result.defeated) {
-        // 反击逻辑需要玩家选择弃牌，这里返回状态让外部处理
-        return {
-            success: true,
-            result: {
-                playResult: playResult.result,
-                enemyDefeated: false,
-                needsDiscard: true,
-                enemyAttack: state.currentEnemy.value,
-                playerHand: state.playerHands[player]
-            }
-        };
-    }
-
-    // 敌人被击败，检查是否还有更多敌人
-    if (state.enemyDeck.length === 0 && state.currentEnemy && state.currentEnemy.hp <= 0) {
-        await game.produceAsync(state => {
-            state.phase = 'victory';
-            state.winner = true;
-        });
-        return {
-            success: true,
-            result: {
-                playResult: playResult.result,
-                enemyDefeated: true,
-                gameWon: true
-            }
-        };
-    }
-
-    // 切换到下一个玩家
-    await game.run('next-turn');
+  // 检查敌人是否被击败
+  const checkResult = await checkEnemy(game);
+  if (!checkResult.success) {
+    return checkResult;
+  }
 
+  // 如果敌人未被击败，处理反击
+  if (!checkResult.result.defeated) {
+    // 反击逻辑需要玩家选择弃牌，这里返回状态让外部处理
     return {
-        success: true,
-        result: {
-            playResult: playResult.result,
-            enemyDefeated: true,
-            nextEnemy: state.currentEnemy
-        }
+      success: true,
+      result: {
+        playResult: playResult.result,
+        enemyDefeated: false,
+        needsDiscard: true,
+        enemyAttack: state.currentEnemy.value,
+        playerHand: state.playerHands[player],
+      },
     };
+  }
+
+  // 敌人被击败，检查是否还有更多敌人
+  if (
+    state.enemyDeck.length === 0 &&
+    state.currentEnemy &&
+    state.currentEnemy.hp <= 0
+  ) {
+    await game.produceAsync((state) => {
+      state.phase = "victory";
+      state.winner = true;
+    });
+    return {
+      success: true,
+      result: {
+        playResult: playResult.result,
+        enemyDefeated: true,
+        gameWon: true,
+      },
+    };
+  }
+
+  // 切换到下一个玩家
+  await nextTurn(game);
+
+  return {
+    success: true,
+    result: {
+      playResult: playResult.result,
+      enemyDefeated: true,
+      nextEnemy: state.currentEnemy,
+    },
+  };
 }
 
 /**
  * 处理反击阶段的弃牌
  */
-export async function handleCounterattack(game: RegicideGame, player: PlayerType, discardCardIds: string[]) {
-    const result = await game.run(`counterattack ${player} ${JSON.stringify(discardCardIds)}`);
-
-    if (!result.success) {
-        // 弃牌失败（点数和不足），游戏失败
-        await game.produceAsync(state => {
-            state.phase = 'defeat';
-            state.winner = false;
-        });
-        return result;
-    }
-
-    // 弃牌成功，切换到下一个玩家
-    await game.run('next-turn');
-
+export async function handleCounterattack(
+  game: RegicideGame,
+  player: PlayerType,
+  discardCardIds: string[],
+) {
+  const result = await enemyCounterattackCmd(game, player, discardCardIds);
+  if (!result.success) {
+    // 弃牌失败（点数和不足），游戏失败
+    await game.produceAsync((state) => {
+      state.phase = "defeat";
+      state.winner = false;
+    });
     return result;
+  }
+
+  // 弃牌成功，切换到下一个玩家
+  await nextTurn(game);
+
+  return result;
 }
 
 /**
  * 获取当前游戏状态摘要
  */
 export function getGameStatus(game: RegicideGame) {
-    const state = game.value;
+  const state = game.value;
 
-    return {
-        phase: state.phase,
-        currentPlayer: ['player1', 'player2', 'player3', 'player4'][state.currentPlayerIndex],
-        currentEnemy: state.currentEnemy ? {
-            ...state.currentEnemy,
-            hpPercent: Math.round((state.currentEnemy.hp / state.currentEnemy.maxHp) * 100)
-        } : null,
-        enemiesRemaining: state.enemyDeck.length,
-        tavernDeckCount: state.regions.tavernDeck.childIds.length,
-        discardPileCount: state.regions.discardPile.childIds.length,
-        playerHands: Object.fromEntries(
-            Object.entries(state.playerHands).map(([player, hand]) => [player, hand.length])
-        ),
-        winner: state.winner
-    };
+  return {
+    phase: state.phase,
+    currentPlayer: ["player1", "player2", "player3", "player4"][
+      state.currentPlayerIndex
+    ],
+    currentEnemy: state.currentEnemy
+      ? {
+          ...state.currentEnemy,
+          hpPercent: Math.round(
+            (state.currentEnemy.hp / state.currentEnemy.maxHp) * 100,
+          ),
+        }
+      : null,
+    enemiesRemaining: state.enemyDeck.length,
+    tavernDeckCount: state.regions.tavernDeck.childIds.length,
+    discardPileCount: state.regions.discardPile.childIds.length,
+    playerHands: Object.fromEntries(
+      Object.entries(state.playerHands).map(([player, hand]) => [
+        player,
+        hand.length,
+      ]),
+    ),
+    winner: state.winner,
+  };
 }

src/samples/regicide/index.ts

@@ -1,67 +1,63 @@
 // Types
 export type {
-    SuitType,
-    CardRank,
-    PlayerType,
-    RegionType,
-    RegicideCardMeta,
-    RegicideCard,
-    Enemy,
-    GamePhase
-} from './types';
+  SuitType,
+  CardRank,
+  PlayerType,
+  RegionType,
+  RegicideCardMeta,
+  RegicideCard,
+  Enemy,
+  GamePhase,
+} from "./types";
 
 // Constants
 export {
-    ENEMY_COUNT,
-    INITIAL_HAND_SIZE,
-    CARD_VALUES,
-    ALL_SUITS,
-    ALL_RANKS,
-    FACE_CARDS,
-    NUMBER_CARDS
-} from './constants';
+  ENEMY_COUNT,
+  INITIAL_HAND_SIZE,
+  CARD_VALUES,
+  ALL_SUITS,
+  ALL_RANKS,
+  FACE_CARDS,
+  NUMBER_CARDS,
+} from "./constants";
 
 // State
-export {
-    createInitialState,
-    type RegicideState
-} from './state';
+export { createInitialState, type RegicideState } from "./state";
 
 // Prompts
-export {prompts} from './prompts';
+export { prompts } from "./prompts";
 
 // Commands
 export {
-    registry,
-    play as playCmd,
-    playWithA as playWithACmd,
-    pass as passCmd,
-    enemyCounterattack as enemyCounterattackCmd,
-    checkEnemy as checkEnemyCmd,
-    checkCanPlay as checkCanPlayCmd,
-    checkTavernDeck as checkTavernDeckCmd,
-    nextTurn as nextTurnCmd,
-} from './commands';
+  play as playCmd,
+  playWithA as playWithACmd,
+  pass as passCmd,
+  enemyCounterattack as enemyCounterattackCmd,
+  checkEnemy as checkEnemyCmd,
+  checkCanPlay as checkCanPlayCmd,
+  checkTavernDeck as checkTavernDeckCmd,
+  nextTurn as nextTurnCmd,
+} from "./commands";
 
 // Game
 export {
-    setupGame,
-    start,
-    playTurn,
-    handleCounterattack,
-    getGameStatus,
-    type RegicideGame
-} from './game';
+  setupGame,
+  start,
+  playTurn,
+  handleCounterattack,
+  getGameStatus,
+  type RegicideGame,
+} from "./game";
 
 // Utils
 export {
-    getCardValue,
-    createCard,
-    createEnemy,
-    createAllCards,
-    buildEnemyDeck,
-    buildTavernDeck,
-    drawFromDeck,
-    isEnemyDefeated,
-    getPlayerHandRegionId
-} from './utils';
+  getCardValue,
+  createCard,
+  createEnemy,
+  createAllCards,
+  buildEnemyDeck,
+  buildTavernDeck,
+  drawFromDeck,
+  isEnemyDefeated,
+  getPlayerHandRegionId,
+} from "./utils";

src/samples/slay-the-spire-like/data/desert/cardEffect.csv

@@ -1,5 +1,5 @@
 # type CardEffectTrigger = 'onPlay' | 'onDraw' | 'onDiscard'
-# type CardEffectTarget = 'user' | 'eachTarget' | 'eachEnemy' | 'randomEnemy' | 'player'
+# type CardEffectTarget = 'source' | 'eachTarget' | 'eachEnemy' | 'randomEnemy' | 'player'
 # type CardEffectList = [effect: @effect; stacks: number][]
 
 id,card,trigger,target,effects
@@ -9,28 +9,28 @@ greataxe,greataxe,onPlay,eachTarget,[attack;5]
 spear,spear,onPlay,eachTarget,[attack;2];[attack;2];[attack;2]
 dagger,dagger,onPlay,eachTarget,[attack;3];[attack;3]
 dart,dart,onPlay,eachTarget,[attack;1]
-dart-draw,dart,onPlay,user,[draw;1]
+dart-draw,dart,onPlay,source,[draw;1]
 crossbow,crossbow,onPlay,eachTarget,[attack;6]
-crossbow-combo,crossbow,onPlay,user,[crossbow;0]
-shield,shield,onPlay,user,[defend;3]
-hat,hat,onPlay,user,[defend;8]
-cape,cape,onPlay,user,[defend;2];[defendNext;2]
-bracer,bracer,onPlay,user,[defend;1];[draw;1]
-greatshield,greatshield,onPlay,user,[defend;5]
-chainmail,chainmail,onPlay,user,[damageReduce;3]
-bandage,bandage,onPlay,user,[removeWound;1]
-poisonPotion,poisonPotion,onPlay,user,[attackBuff;2]
-fortifyPotion,fortifyPotion,onPlay,user,[defendBuff;2]
-vitalityPotion,vitalityPotion,onPlay,user,[gainEnergy;1]
-focusPotion,focusPotion,onPlay,user,[draw;2]
-healingPotion,healingPotion,onPlay,user,[removeWound;3]
-waterBag,waterBag,onPlay,user,[energyNext;1];[drawNext;2]
-rope,rope,onPlay,user,[defendBuffUntilPlay;2]
-belt,belt,onPlay,user,[drawChoice;1]
-torch,torch,onPlay,user,[burnForEnergy;1]
-whetstone,whetstone,onPlay,user,[attackBuffUntilPlay;3]
-blacksmithHammer,blacksmithHammer,onPlay,user,[transformRandom;1]
-venom,venom,onDiscard,user,[attack;3]
-curse,curse,onDraw,user,[curse;1]
-static,static,onDraw,user,[static;1]
-vultureEye,vultureEye,onDraw,user,[expose;3]
+crossbow-combo,crossbow,onPlay,source,[crossbow;0]
+shield,shield,onPlay,source,[defend;3]
+hat,hat,onPlay,source,[defend;8]
+cape,cape,onPlay,source,[defend;2];[defendNext;2]
+bracer,bracer,onPlay,source,[defend;1];[draw;1]
+greatshield,greatshield,onPlay,source,[defend;5]
+chainmail,chainmail,onPlay,source,[damageReduce;3]
+bandage,bandage,onPlay,source,[removeWound;1]
+poisonPotion,poisonPotion,onPlay,source,[attackBuff;2]
+fortifyPotion,fortifyPotion,onPlay,source,[defendBuff;2]
+vitalityPotion,vitalityPotion,onPlay,source,[gainEnergy;1]
+focusPotion,focusPotion,onPlay,source,[draw;2]
+healingPotion,healingPotion,onPlay,source,[removeWound;3]
+waterBag,waterBag,onPlay,source,[energyNext;1];[drawNext;2]
+rope,rope,onPlay,source,[defendBuffUntilPlay;2]
+belt,belt,onPlay,source,[drawChoice;1]
+torch,torch,onPlay,source,[burnForEnergy;1]
+whetstone,whetstone,onPlay,source,[attackBuffUntilPlay;3]
+blacksmithHammer,blacksmithHammer,onPlay,source,[transformRandom;1]
+venom,venom,onDiscard,source,[attack;3]
+curse,curse,onDraw,source,[curse;1]
+static,static,onDraw,source,[static;1]
+vultureEye,vultureEye,onDraw,source,[expose;3]

src/samples/slay-the-spire-like/data/desert/cardEffect.csv.d.ts

@@ -2,7 +2,7 @@ import type { Card } from './card.csv';
 import type { Effect } from './effect.csv';
 
 export type CardEffectTrigger = 'onPlay' | 'onDraw' | 'onDiscard';
-export type CardEffectTarget = 'user' | 'eachTarget' | 'eachEnemy' | 'randomEnemy' | 'player';
+export type CardEffectTarget = 'source' | 'eachTarget' | 'eachEnemy' | 'randomEnemy' | 'player';
 export type CardEffectList = [effect: Effect, stacks: number][];
 
 type CardEffectTable = readonly {

src/samples/slay-the-spire-like/data/desert/intent.csv

@@ -6,50 +6,50 @@
 # initBuffs: initial buffs for this intent (applied when intent becomes active)
 # effects: effects executed when this intent is active
 
-# type IntentEffectTarget = 'user' | 'eachEnemy' | 'randomEnemy' | 'player'
+# type IntentEffectTarget = 'source' | 'eachEnemy' | 'randomEnemy' | 'player'
 # type IntentEffect = [IntentEffectTarget;@effect;number]
 # type IntentEffectList = IntentEffect[]
 
 id,enemy,initialIntent,nextIntents,brokenIntent,effects
 string,@enemy,boolean,@intent[],@intent[],IntentEffectList
-仙人掌怪-boost,仙人掌怪,true,仙人掌怪-boost;仙人掌怪-defend,,[user;spike;1];[user;defend;4]
-仙人掌怪-defend,仙人掌怪,false,仙人掌怪-attack,,[user;defend;8]
+仙人掌怪-boost,仙人掌怪,true,仙人掌怪-boost;仙人掌怪-defend,,[source;spike;1];[source;defend;4]
+仙人掌怪-defend,仙人掌怪,false,仙人掌怪-attack,,[source;defend;8]
 仙人掌怪-attack,仙人掌怪,false,仙人掌怪-boost,,[player;attack;5]
 蛇-poison,蛇,true,蛇-attack;蛇-attack,,[player;venom;1];[player;attack;4]
 蛇-attack,蛇,false,蛇-poison;蛇-boost,,[player;attack;6]
-蛇-boost,蛇,false,蛇-poison;蛇-attack,,[user;defend;3];[player;venom;1]
+蛇-boost,蛇,false,蛇-poison;蛇-attack,,[source;defend;3];[player;venom;1]
 木乃伊-attack,木乃伊,true,木乃伊-defend;木乃伊-curse,,[player;attack;6]
-木乃伊-defend,木乃伊,false,木乃伊-attack,,[user;defend;6]
+木乃伊-defend,木乃伊,false,木乃伊-attack,,[source;defend;6]
 木乃伊-curse,木乃伊,false,木乃伊-defend;木乃伊-attack,木乃伊-attack,[player;curse;1]
-枪手-aim,枪手,true,枪手-attack,,[user;aim;2]
+枪手-aim,枪手,true,枪手-attack,,[source;aim;2]
 枪手-attack,枪手,false,枪手-aim;枪手-defend,枪手-aim,[player;attack;8]
-枪手-defend,枪手,false,枪手-aim,枪手-aim,[user;defend;5]
-风卷草-boost,风卷草,true,风卷草-defend;风卷草-defend;风卷草-boost,,[user;roll;5];[user;defend;4]
-风卷草-defend,风卷草,false,风卷草-boost;风卷草-attack,,[user;defend;8]
+枪手-defend,枪手,false,枪手-aim,枪手-aim,[source;defend;5]
+风卷草-boost,风卷草,true,风卷草-defend;风卷草-defend;风卷草-boost,,[source;roll;5];[source;defend;4]
+风卷草-defend,风卷草,false,风卷草-boost;风卷草-attack,,[source;defend;8]
 风卷草-attack,风卷草,false,风卷草-boost,,[player;rollDamage;0]
 秃鹫-attack,秃鹫,true,秃鹫-defend;秃鹫-defend,,[player;attack;6];[player;vultureEye;1]
-秃鹫-defend,秃鹫,false,秃鹫-attack;秃鹫-attack,,[user;defend;5]
-沙蝎-boost,沙蝎,true,沙蝎-attack;沙蝎-attack,,[user;tailSting;2]
+秃鹫-defend,秃鹫,false,秃鹫-attack;秃鹫-attack,,[source;defend;5]
+沙蝎-boost,沙蝎,true,沙蝎-attack;沙蝎-attack,,[source;tailSting;2]
 沙蝎-attack,沙蝎,false,沙蝎-boost;沙蝎-attack,,[player;attack;6]
-幼沙虫-defend,幼沙虫,true,幼沙虫-defend;幼沙虫-boost,,[user;defend;6]
-幼沙虫-boost,幼沙虫,false,幼沙虫-attack;幼沙虫-defend,,[user;energyDrain;1];[user;defend;4]
+幼沙虫-defend,幼沙虫,true,幼沙虫-defend;幼沙虫-boost,,[source;defend;6]
+幼沙虫-boost,幼沙虫,false,幼沙虫-attack;幼沙虫-defend,,[source;energyDrain;1];[source;defend;4]
 幼沙虫-attack,幼沙虫,false,幼沙虫-defend;幼沙虫-defend,,[player;attack;5]
 蜥蜴-attack,蜥蜴,true,蜥蜴-defend;蜥蜴-molt,,[player;attack;5]
-蜥蜴-defend,蜥蜴,false,蜥蜴-attack;蜥蜴-attack,,[user;defend;6]
-蜥蜴-molt,蜥蜴,false,蜥蜴-defend;蜥蜴-attack,,[user;molt;3]
+蜥蜴-defend,蜥蜴,false,蜥蜴-attack;蜥蜴-attack,,[source;defend;6]
+蜥蜴-molt,蜥蜴,false,蜥蜴-defend;蜥蜴-attack,,[source;molt;3]
 沙匪-attack,沙匪,true,沙匪-attack;沙匪-heavyAttack,,[player;attack;6]
 沙匪-heavyAttack,沙匪,false,沙匪-attack;沙匪-attack;沙匪-debuff,,[player;attack;10]
 沙匪-debuff,沙匪,false,沙匪-attack;沙匪-attack,,[player;discard;1]
-风暴之灵-storm,风暴之灵,true,风暴之灵-attack;风暴之灵-storm,,[user;storm;2];[user;defend;3]
+风暴之灵-storm,风暴之灵,true,风暴之灵-attack;风暴之灵-storm,,[source;storm;2];[source;defend;3]
 风暴之灵-attack,风暴之灵,false,风暴之灵-storm;风暴之灵-defend,,[player;attack;8];[player;static;1]
-风暴之灵-defend,风暴之灵,false,风暴之灵-storm;风暴之灵-attack,,[user;defend;8]
-骑马枪手-charge,骑马枪手,true,骑马枪手-attack,,[user;charge;2]
+风暴之灵-defend,风暴之灵,false,风暴之灵-storm;风暴之灵-attack,,[source;defend;8]
+骑马枪手-charge,骑马枪手,true,骑马枪手-attack,,[source;charge;2]
 骑马枪手-attack,骑马枪手,false,骑马枪手-charge;骑马枪手-defend,骑马枪手-charge,[player;attack;6]
-骑马枪手-defend,骑马枪手,false,骑马枪手-charge;骑马枪手-attack,骑马枪手-charge,[user;defend;5]
-沙虫王-summon,沙虫王,true,沙虫王-attack;沙虫王-defend,,[user;summonSandwormLarva;18]
+骑马枪手-defend,骑马枪手,false,骑马枪手-charge;骑马枪手-attack,骑马枪手-charge,[source;defend;5]
+沙虫王-summon,沙虫王,true,沙虫王-attack;沙虫王-defend,,[source;summonSandwormLarva;18]
 沙虫王-attack,沙虫王,false,沙虫王-summon;沙虫王-defend,,[player;attack;9]
-沙虫王-defend,沙虫王,false,沙虫王-attack;沙虫王-summon,,[user;defend;6]
-沙漠守卫-summon,沙漠守卫,true,沙漠守卫-attack;沙漠守卫-defend,,[user;summonMummy;14]
+沙虫王-defend,沙虫王,false,沙虫王-attack;沙虫王-summon,,[source;defend;6]
+沙漠守卫-summon,沙漠守卫,true,沙漠守卫-attack;沙漠守卫-defend,,[source;summonMummy;14]
 沙漠守卫-attack,沙漠守卫,false,沙漠守卫-defend;沙漠守卫-summon,,[player;attack;8]
-沙漠守卫-defend,沙漠守卫,false,沙漠守卫-attack;沙漠守卫-revive,,[user;defend;8]
-沙漠守卫-revive,沙漠守卫,false,沙漠守卫-attack;沙漠守卫-summon,,[user;reviveMummy;1]
+沙漠守卫-defend,沙漠守卫,false,沙漠守卫-attack;沙漠守卫-revive,,[source;defend;8]
+沙漠守卫-revive,沙漠守卫,false,沙漠守卫-attack;沙漠守卫-summon,,[source;reviveMummy;1]

src/samples/slay-the-spire-like/data/desert/intent.csv.d.ts

@@ -1,7 +1,7 @@
 import type { Enemy } from './enemy.csv';
 import type { Effect } from './effect.csv';
 
-export type IntentEffectTarget = 'user' | 'eachEnemy' | 'randomEnemy' | 'player';
+export type IntentEffectTarget = 'source' | 'eachEnemy' | 'randomEnemy' | 'player';
 export type IntentEffect = [IntentEffectTarget, Effect, number];
 export type IntentEffectList = IntentEffect[];
 

src/samples/slay-the-spire-like/data/desert/triggers/card-events.ts

@@ -30,9 +30,9 @@ export function addCardEventTriggers(triggers: Triggers, run: IRunContext) {
       for (let i = 0; i < storm; i++) {
         await triggers.onEffectApplied.execute(ctx.game, {
           effect: findEffect("static"),
-          entityKey: "player",
+          entityId: "player",
           stacks: 1,
-          sourceEntityKey: ctx.enemyId,
+          sourceEntityId: ctx.enemyId,
         });
       }
     }
@@ -52,7 +52,7 @@ export function addCardEventTriggers(triggers: Triggers, run: IRunContext) {
         await triggers.onCardPlayed.execute(ctx.game, {
           cardId: id,
           targetId: ctx.targetId,
-          sourceEntityKey: "player",
+          sourceEntityId: "player",
         });
       }
     }
@@ -113,17 +113,17 @@ export function addCardEventTriggers(triggers: Triggers, run: IRunContext) {
     await next();
 
     const dealt = ctx.amount - (ctx.prevented ?? 0);
-    if (dealt <= 0 || !ctx.sourceEntityKey) return;
+    if (dealt <= 0 || !ctx.sourceEntityId) return;
 
-    const attacker = getCombatEntity(ctx.game.value, ctx.sourceEntityKey);
+    const attacker = getCombatEntity(ctx.game.value, ctx.sourceEntityId);
     if (!attacker || !("enemy" in attacker) || attacker.enemy.id !== "秃鹫")
       return;
 
     await triggers.onEffectApplied.execute(ctx.game, {
       effect: findEffect("vultureEye"),
-      entityKey: "player",
+      entityId: "player",
       stacks: 1,
-      sourceEntityKey: ctx.sourceEntityKey,
+      sourceEntityId: ctx.sourceEntityId,
     });
   });
 }

src/samples/slay-the-spire-like/data/desert/triggers/damage.ts

@@ -22,7 +22,7 @@ export function addDamageTriggers(triggers: Triggers) {
 
   // block / damage prevention
   triggers.onDamage.use(async (ctx, next) => {
-    const entity = getCombatEntity(ctx.game.value, ctx.entityKey);
+    const entity = getCombatEntity(ctx.game.value, ctx.entityId);
     if (!entity) return;
 
     let preventable = ctx.amount - (ctx.prevented ?? 0);
@@ -42,7 +42,7 @@ export function addDamageTriggers(triggers: Triggers) {
       ctx.prevented = (ctx.prevented ?? 0) + blocked;
       preventable -= blocked;
       await ctx.game.produceAsync((draft) => {
-        const e = getCombatEntity(draft, ctx.entityKey);
+        const e = getCombatEntity(draft, ctx.entityId);
         if (e) addEntityEffect(e, findEffect("defend"), -blocked);
       });
     }
@@ -55,32 +55,13 @@ export function addDamageTriggers(triggers: Triggers) {
     await next();
   });
 
-  // spike: damage attacker
-  triggers.onDamage.use(async (ctx, next) => {
-    await next();
-
-    if (ctx.amount - (ctx.prevented ?? 0) <= 0) return;
-
-    const entity = getCombatEntity(ctx.game.value, ctx.entityKey);
-    if (!entity || !entity.isAlive) return;
-
-    const spike = entity.effects.spike?.stacks ?? 0;
-    if (spike > 0 && ctx.sourceEntityKey) {
-      await triggers.onDamage.execute(ctx.game, {
-        entityKey: ctx.sourceEntityKey,
-        amount: spike,
-        sourceEntityKey: ctx.entityKey,
-      });
-    }
-  });
-
   // energyDrain: player loses energy when enemy takes damage
   triggers.onDamage.use(async (ctx, next) => {
-    const entity = getCombatEntity(ctx.game.value, ctx.entityKey);
+    const entity = getCombatEntity(ctx.game.value, ctx.entityId);
     if (!entity) return;
 
     const energyDrain = entity.effects.energyDrain?.stacks ?? 0;
-    if (energyDrain > 0 && ctx.entityKey !== "player") {
+    if (energyDrain > 0 && ctx.entityId !== "player") {
       const dealt = Math.min(
         Math.max(0, entity.hp),
         ctx.amount - (ctx.prevented ?? 0),
@@ -97,7 +78,7 @@ export function addDamageTriggers(triggers: Triggers) {
 
   // molt: enemy flees if molt >= maxHp
   triggers.onDamage.use(async (ctx, next) => {
-    const entity = getCombatEntity(ctx.game.value, ctx.entityKey);
+    const entity = getCombatEntity(ctx.game.value, ctx.entityId);
     if (!entity || !entity.isAlive) {
       await next();
       return;
@@ -106,7 +87,7 @@ export function addDamageTriggers(triggers: Triggers) {
     const molt = entity.effects.molt?.stacks ?? 0;
     if (molt >= entity.maxHp) {
       await ctx.game.produceAsync((draft) => {
-        const e = draft.enemies.find((en) => en.id === ctx.entityKey);
+        const e = draft.enemies.find((en) => en.id === ctx.entityId);
         if (e) {
           e.isAlive = false;
           e.hp = 0;
@@ -124,7 +105,7 @@ export function addDamageTriggers(triggers: Triggers) {
 
   // aim: double damage, lose aim on damage
   triggers.onDamage.use(async (ctx, next) => {
-    if (ctx.sourceEntityKey === "player") {
+    if (ctx.sourceEntityId === "player") {
       const player = ctx.game.value.player;
       const aim = player.effects.aim?.stacks ?? 0;
       if (aim > 0) {
@@ -136,7 +117,7 @@ export function addDamageTriggers(triggers: Triggers) {
 
   // roll: consume 10 roll per 10 damage
   triggers.onDamage.use(async (ctx, next) => {
-    if (ctx.sourceEntityKey === "player") {
+    if (ctx.sourceEntityId === "player") {
       const player = ctx.game.value.player;
       const roll = player.effects.roll?.stacks ?? 0;
       if (roll >= 10) {
@@ -152,8 +133,8 @@ export function addDamageTriggers(triggers: Triggers) {
 
   // tailSting: bonus damage on attack
   triggers.onDamage.use(async (ctx, next) => {
-    if (ctx.sourceEntityKey && ctx.sourceEntityKey !== "player") {
-      const attacker = getCombatEntity(ctx.game.value, ctx.sourceEntityKey);
+    if (ctx.sourceEntityId && ctx.sourceEntityId !== "player") {
+      const attacker = getCombatEntity(ctx.game.value, ctx.sourceEntityId);
       if (attacker) {
         const tailSting = attacker.effects.tailSting?.stacks ?? 0;
         if (tailSting > 0) {
@@ -166,7 +147,7 @@ export function addDamageTriggers(triggers: Triggers) {
 
   // charge: double damage dealt/received, consume equal charge
   triggers.onDamage.use(async (ctx, next) => {
-    const entity = getCombatEntity(ctx.game.value, ctx.entityKey);
+    const entity = getCombatEntity(ctx.game.value, ctx.entityId);
     if (entity) {
       const charge = entity.effects.charge?.stacks ?? 0;
       if (charge > 0) {
@@ -178,20 +159,20 @@ export function addDamageTriggers(triggers: Triggers) {
         ctx.amount += dealt;
         if (consumed > 0) {
           await ctx.game.produceAsync((draft) => {
-            const e = getCombatEntity(draft, ctx.entityKey);
+            const e = getCombatEntity(draft, ctx.entityId);
             if (e) addEntityEffect(e, findEffect("charge"), -consumed);
           });
         }
       }
     }
 
-    if (ctx.sourceEntityKey) {
-      const attacker = getCombatEntity(ctx.game.value, ctx.sourceEntityKey);
+    if (ctx.sourceEntityId) {
+      const attacker = getCombatEntity(ctx.game.value, ctx.sourceEntityId);
       if (attacker) {
         const charge = attacker.effects.charge?.stacks ?? 0;
         if (charge > 0) {
           const baseAmount = ctx.amount;
-          const targetEntity = getCombatEntity(ctx.game.value, ctx.entityKey);
+          const targetEntity = getCombatEntity(ctx.game.value, ctx.entityId);
           const dealt = Math.min(
             Math.max(0, targetEntity?.hp ?? 0),
             baseAmount - (ctx.prevented ?? 0),
@@ -200,7 +181,7 @@ export function addDamageTriggers(triggers: Triggers) {
           ctx.amount += dealt;
           if (consumed > 0) {
             await ctx.game.produceAsync((draft) => {
-              const a = getCombatEntity(draft, ctx.sourceEntityKey!);
+              const a = getCombatEntity(draft, ctx.sourceEntityId!);
               if (a) addEntityEffect(a, findEffect("charge"), -consumed);
             });
           }

src/samples/slay-the-spire-like/data/desert/triggers/effect.ts

@@ -1,13 +0,0 @@
-import { IRunContext } from "@/samples/slay-the-spire-like/system/combat/types";
-import { Triggers } from "@/samples/slay-the-spire-like/system/combat/triggers";
-import { addInstantEffectTriggers } from "./instant";
-import { addDamageTriggers } from "./damage";
-import { addTurnStartTriggers } from "./turn-start";
-import { addCardEventTriggers } from "./card-events";
-
-export function addDesertTriggers(triggers: Triggers, run: IRunContext) {
-  addInstantEffectTriggers(triggers);
-  addDamageTriggers(triggers);
-  addTurnStartTriggers(triggers);
-  addCardEventTriggers(triggers, run);
-}

src/samples/slay-the-spire-like/data/desert/triggers/index.ts

@@ -1 +1,15 @@
-export { addDesertTriggers as addTriggers } from './effect';
+import { addInstantEffectTriggers } from "./instant";
+import { addDamageTriggers } from "./damage";
+import { addTurnStartTriggers } from "./turn-start";
+import { addCardEventTriggers } from "./card-events";
+import {
+  IRunContext,
+  Triggers,
+} from "@/samples/slay-the-spire-like/system/combat";
+
+export function addTriggers(triggers: Triggers, run: IRunContext) {
+  addInstantEffectTriggers(triggers);
+  addDamageTriggers(triggers);
+  addTurnStartTriggers(triggers);
+  addCardEventTriggers(triggers, run);
+}

src/samples/slay-the-spire-like/data/desert/triggers/instant.ts

@@ -1,5 +1,8 @@
 import { Triggers } from "@/samples/slay-the-spire-like/system/combat/triggers";
-import { addEntityEffect } from "@/samples/slay-the-spire-like/system/combat/effects";
+import {
+  addEntityEffect,
+  getCombatEntity,
+} from "@/samples/slay-the-spire-like/system/combat/effects";
 import { moveToRegion } from "@/core/region";
 import { CombatGameContext } from "@/samples/slay-the-spire-like/system/combat/types";
 import { GameCard } from "@/samples/slay-the-spire-like/system/deck";
@@ -93,13 +96,20 @@ export function addInstantEffectTriggers(triggers: Triggers) {
   triggers.onEffectApplied.use(async (ctx, next) => {
     if (ctx.effect.id === "attack") {
       await triggers.onDamage.execute(ctx.game, {
-        entityKey: ctx.entityKey,
+        entityId: ctx.entityId,
         amount: ctx.stacks,
-        sourceEntityKey:
-          (ctx.sourceEntityKey ?? ctx.entityKey === "player")
-            ? undefined
-            : "player",
+        sourceEntityId: ctx.sourceEntityId,
       });
+
+      const entity = getCombatEntity(ctx.game.value, ctx.entityId);
+      const spike = entity?.effects.spike?.stacks ?? 0;
+      if (spike > 0 && ctx.sourceEntityId) {
+        await triggers.onDamage.execute(ctx.game, {
+          entityId: ctx.sourceEntityId,
+          amount: spike,
+          sourceEntityId: ctx.entityId,
+        });
+      }
     } else if (ctx.effect.id === "draw") {
       await triggers.onDraw.execute(ctx.game, { count: ctx.stacks });
     } else if (ctx.effect.id === "gainEnergy") {

src/samples/slay-the-spire-like/data/desert/triggers/turn-start.ts

@@ -19,7 +19,7 @@ export function addTurnStartTriggers(triggers: Triggers) {
 
   // discard: random discard at turn start
   triggers.onTurnStart.use(async (ctx, next) => {
-    if (ctx.entityKey !== "player") {
+    if (ctx.entityId !== "player") {
       await next();
       return;
     }
@@ -56,7 +56,7 @@ export function addTurnStartTriggers(triggers: Triggers) {
 
   // energyNext: gain energy next turn
   triggers.onTurnStart.use(async (ctx, next) => {
-    if (ctx.entityKey !== "player") {
+    if (ctx.entityId !== "player") {
       await next();
       return;
     }
@@ -74,7 +74,7 @@ export function addTurnStartTriggers(triggers: Triggers) {
 
   // drawNext: draw extra cards next turn
   triggers.onTurnStart.use(async (ctx, next) => {
-    if (ctx.entityKey !== "player") {
+    if (ctx.entityId !== "player") {
       await next();
       return;
     }

src/samples/slay-the-spire-like/data/types.ts

@@ -2,16 +2,17 @@ import { LoadResult as YarnDialogues } from "yarn-spinner-loader";
 import { Triggers } from "../system/combat/triggers";
 
 import type * as desert from "./desert";
+import { IRunContext } from "../system/combat";
 
 export type ContentModule = {
-  getCards: () => desert.Card[];
-  getEffects: () => desert.Effect[];
-  getEncounters: () => desert.Encounter[];
-  getEnemies: () => desert.Enemy[];
-  getIntents: () => desert.Intent[];
-  getItems: () => desert.Item[];
-  getStartingItems: () => desert.Item[];
+  readonly getCards: () => readonly desert.Card[];
+  readonly getEffects: () => readonly desert.Effect[];
+  readonly getEncounters: () => readonly desert.Encounter[];
+  readonly getEnemies: () => readonly desert.Enemy[];
+  readonly getIntents: () => readonly desert.Intent[];
+  readonly getItems: () => readonly desert.Item[];
+  readonly getStartingItems: () => readonly desert.Item[];
 
-  dialogues: YarnDialogues;
-  addTriggers: (triggers: Triggers) => void;
+  readonly dialogues: YarnDialogues;
+  readonly addTriggers: (triggers: Triggers, run: IRunContext) => void;
 };

src/samples/slay-the-spire-like/system/combat/effects.ts

@@ -112,7 +112,7 @@ export function* getEffectTargets(
     for (const enemy of getAliveEnemies(game.value)) {
       yield enemy;
     }
-  } else if (target === "user") {
+  } else if (target === "source") {
     const entity = getCombatEntity(game.value, sourceEntityKey);
     if (entity) yield entity;
   } else if (target === "player") {

src/samples/slay-the-spire-like/system/combat/triggers.ts

@@ -19,33 +19,33 @@ import { EffectData } from "@/samples/slay-the-spire-like/system/types";
 
 type TriggerTypes = {
   onCombatStart: {};
-  onTurnStart: { entityKey: "player" | string };
-  onTurnEnd: { entityKey: "player" | string };
+  onTurnStart: { entityId: "player" | string };
+  onTurnEnd: { entityId: "player" | string };
   onShuffle: {};
   onCardPlayed: {
     cardId: string;
     targetId?: string;
-    sourceEntityKey?: "player" | string;
+    sourceEntityId?: "player" | string;
   };
-  onCardDiscarded: { cardId: string; sourceEntityKey?: "player" | string };
-  onCardDrawn: { cardId: string; sourceEntityKey?: "player" | string };
+  onCardDiscarded: { cardId: string; sourceEntityId?: "player" | string };
+  onCardDrawn: { cardId: string; sourceEntityId?: "player" | string };
   onDraw: { count: number };
   onEffectApplied: {
     effect: EffectData;
-    entityKey: "player" | string;
+    entityId: "player" | string;
     stacks: number;
     cardId?: string;
-    sourceEntityKey?: "player" | string;
+    sourceEntityId?: "player" | string;
     targetId?: string;
   };
-  onHpChange: { entityKey: "player" | string; amount: number };
+  onHpChange: { entityId: "player" | string; amount: number };
   onDamage: {
-    entityKey: "player" | string;
+    entityId: "player" | string;
     amount: number;
     prevented?: number;
-    sourceEntityKey?: "player" | string;
+    sourceEntityId?: "player" | string;
   };
-  onEnemyIntent: { enemyId: string; sourceEntityKey?: "player" | string };
+  onEnemyIntent: { enemyId: string; sourceEntityId?: "player" | string };
   onIntentUpdate: { enemyId: string };
 };
 
@@ -57,13 +57,13 @@ export function createTriggers(run: IRunContext) {
     }),
     onTurnStart: createTrigger("onTurnStart", async (ctx) => {
       await ctx.game.produceAsync((draft) => {
-        const entity = getCombatEntity(draft, ctx.entityKey);
+        const entity = getCombatEntity(draft, ctx.entityId);
         if (entity) onEntityEffectUpkeep(entity);
         if (entity === draft.player) onPlayerItemEffectUpkeep(draft.player);
       });
     }),
     onTurnEnd: createTrigger("onTurnEnd", async (ctx) => {
-      if (ctx.entityKey !== "player") return;
+      if (ctx.entityId !== "player") return;
       const { regions } = ctx.game.value.player.deck;
       for (const cardId of Object.values(regions.hand.childIds)) {
         await triggers.onCardDiscarded.execute(ctx.game, { cardId });
@@ -97,7 +97,7 @@ export function createTriggers(run: IRunContext) {
       });
       const { cards, regions } = ctx.game.value.player.deck;
       const card = cards[ctx.cardId];
-      const source = ctx.sourceEntityKey ?? "player";
+      const source = ctx.sourceEntityId ?? "player";
       for (const { trigger, target, effects } of card.cardData.effects) {
         if (trigger !== "onPlay") continue;
         for (const [effect, stacks] of effects)
@@ -109,10 +109,10 @@ export function createTriggers(run: IRunContext) {
           ))
             await triggers.onEffectApplied.execute(ctx.game, {
               effect,
-              entityKey: entity.id,
+              entityId: entity.id,
               stacks,
               cardId: ctx.cardId,
-              sourceEntityKey: source,
+              sourceEntityId: source,
               targetId: ctx.targetId,
             });
       }
@@ -125,7 +125,7 @@ export function createTriggers(run: IRunContext) {
       });
       const { cards, regions } = ctx.game.value.player.deck;
       const card = cards[ctx.cardId];
-      const source = ctx.sourceEntityKey ?? "player";
+      const source = ctx.sourceEntityId ?? "player";
       for (const { trigger, target, effects } of card.cardData.effects) {
         if (trigger !== "onDiscard") continue;
         for (const [effect, stacks] of effects)
@@ -137,10 +137,10 @@ export function createTriggers(run: IRunContext) {
           ))
             await triggers.onEffectApplied.execute(ctx.game, {
               effect,
-              entityKey: entity.id,
+              entityId: entity.id,
               stacks,
               cardId: ctx.cardId,
-              sourceEntityKey: source,
+              sourceEntityId: source,
             });
       }
     }),
@@ -151,7 +151,7 @@ export function createTriggers(run: IRunContext) {
       });
       const { cards, regions } = ctx.game.value.player.deck;
       const card = cards[ctx.cardId];
-      const source = ctx.sourceEntityKey ?? "player";
+      const source = ctx.sourceEntityId ?? "player";
       for (const { trigger, target, effects } of card.cardData.effects) {
         if (trigger !== "onDraw") continue;
         for (const [effect, stacks] of effects)
@@ -163,10 +163,10 @@ export function createTriggers(run: IRunContext) {
           ))
             await triggers.onEffectApplied.execute(ctx.game, {
               effect,
-              entityKey: entity.id,
+              entityId: entity.id,
               stacks,
               cardId: ctx.cardId,
-              sourceEntityKey: source,
+              sourceEntityId: source,
             });
       }
     }),
@@ -204,18 +204,18 @@ export function createTriggers(run: IRunContext) {
 
       await ctx.game.produceAsync((draft) => {
         const entity =
-          ctx.entityKey === "player"
+          ctx.entityId === "player"
             ? draft.player
-            : draft.enemies.find((e) => e.id === ctx.entityKey);
+            : draft.enemies.find((e) => e.id === ctx.entityId);
         if (entity) addEntityEffect(entity, ctx.effect, ctx.stacks);
       });
     }),
     onHpChange: createTrigger("onHpChange", async (ctx) => {
       await ctx.game.produceAsync((draft) => {
         const entity =
-          ctx.entityKey === "player"
+          ctx.entityId === "player"
             ? draft.player
-            : draft.enemies.find((e) => e.id === ctx.entityKey);
+            : draft.enemies.find((e) => e.id === ctx.entityId);
         if (!entity) return;
         entity.hp += ctx.amount;
         entity.isAlive = entity.hp > 0;
@@ -229,9 +229,9 @@ export function createTriggers(run: IRunContext) {
     }),
     onDamage: createTrigger("onDamage", async (ctx) => {
       const entity =
-        ctx.entityKey === "player"
+        ctx.entityId === "player"
           ? ctx.game.value.player
-          : ctx.game.value.enemies.find((e) => e.id === ctx.entityKey);
+          : ctx.game.value.enemies.find((e) => e.id === ctx.entityId);
       if (!entity || !entity.isAlive) return;
       const dealt = Math.min(
         Math.max(0, entity.hp),
@@ -241,7 +241,7 @@ export function createTriggers(run: IRunContext) {
         onEntityPostureDamage(entity, dealt);
       });
       await triggers.onHpChange.execute(ctx.game, {
-        entityKey: ctx.entityKey,
+        entityId: ctx.entityId,
         amount: -dealt,
       });
     }),
@@ -252,7 +252,7 @@ export function createTriggers(run: IRunContext) {
       const intent = enemy.currentIntent;
       if (!intent) return;
 
-      const source = ctx.sourceEntityKey ?? enemy.id;
+      const source = ctx.sourceEntityId ?? enemy.id;
       for (const [target, effect, stacks] of intent.effects) {
         for (const entity of getEffectTargets(
           target,
@@ -262,9 +262,9 @@ export function createTriggers(run: IRunContext) {
         ))
           await triggers.onEffectApplied.execute(ctx.game, {
             effect,
-            entityKey: entity.id,
+            entityId: entity.id,
             stacks,
-            sourceEntityKey: source,
+            sourceEntityId: source,
           });
       }
     }),
@@ -287,18 +287,13 @@ export function createTriggers(run: IRunContext) {
   return triggers;
 }
 export type Triggers = ReturnType<typeof createTriggers>;
-export function createStartWith(
-  build: (triggers: Triggers, run: IRunContext) => void,
-  run: IRunContext,
-) {
-  const triggers = createTriggers(run);
-  build(triggers, run);
+export function createStart(triggers: Triggers, run: IRunContext) {
   return async function (game: CombatGameContext) {
     await triggers.onCombatStart.execute(game, {});
 
     try {
       while (true) {
-        await triggers.onTurnStart.execute(game, { entityKey: "player" });
+        await triggers.onTurnStart.execute(game, { entityId: "player" });
         while (true) {
           const action = await promptMainAction(game, run);
           if (action.action === "end-turn") break;
@@ -306,17 +301,17 @@ export function createStartWith(
             await triggers.onCardPlayed.execute(game, action);
           }
         }
-        await triggers.onTurnEnd.execute(game, { entityKey: "player" });
+        await triggers.onTurnEnd.execute(game, { entityId: "player" });
 
         for (const enemy of getAliveEnemies(game.value)) {
-          await triggers.onTurnStart.execute(game, { entityKey: enemy.id });
+          await triggers.onTurnStart.execute(game, { entityId: enemy.id });
         }
         for (const enemy of getAliveEnemies(game.value)) {
           await triggers.onEnemyIntent.execute(game, { enemyId: enemy.id });
           await triggers.onIntentUpdate.execute(game, { enemyId: enemy.id });
         }
         for (const enemy of getAliveEnemies(game.value)) {
-          await triggers.onTurnEnd.execute(game, { entityKey: enemy.id });
+          await triggers.onTurnEnd.execute(game, { entityId: enemy.id });
         }
       }
     } catch (e) {

src/samples/slay-the-spire-like/system/types.ts

@@ -21,3 +21,5 @@ export {
   CardEffectTarget,
   IntentEffectTarget,
 } from "../data/desert";
+
+export { ContentModule } from "../data";

src/samples/tic-tac-toe.ts

@@ -1,10 +1,8 @@
 import { Part } from "@/core/part";
-import { createRegion } from "@/core/region";
-import {
-  createGameCommandRegistry,
-  createPromptDef,
-  IGameContext,
-} from "@/core/game";
+import { createRegion, Region } from "@/core/region";
+import { createPromptDef, IGameContext } from "@/core/game";
+import { BaseGameClient } from "@/core/game-client";
+import { createMiddlewareChain } from "@/utils/middleware";
 
 const BOARD_SIZE = 3;
 const MAX_TURNS = BOARD_SIZE * BOARD_SIZE;
@@ -69,7 +67,6 @@ export function createInitialState() {
 }
 export type TicTacToeState = ReturnType<typeof createInitialState>;
 export type TicTacToeGame = IGameContext<TicTacToeState>;
-export const registry = createGameCommandRegistry<TicTacToeState>();
 export const prompts = {
   play: createPromptDef<[PlayerType, number, number]>(
     "play <player> <row:number> <col:number>",
@@ -82,7 +79,7 @@ export async function start(game: TicTacToeGame) {
     const turnNumber = game.value.turn + 1;
     const turnOutput = await turn(game, currentPlayer, turnNumber);
 
-    game.produce((state) => {
+    await game.produceAsync((state) => {
       state.winner = turnOutput.winner;
       if (!state.winner) {
         state.currentPlayer = state.currentPlayer === "X" ? "O" : "X";
@@ -95,34 +92,35 @@ export async function start(game: TicTacToeGame) {
   return game.value;
 }
 
-const turn = registry.register({
-  schema: "turn <player> <turnNumber:number>",
-  async run(game: TicTacToeGame, turnPlayer: PlayerType, turnNumber: number) {
-    const { player, row, col } = await game.prompt(
-      prompts.play,
-      (player, row, col) => {
-        if (player !== turnPlayer) {
-          throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
-        } else if (!isValidMove(row, col)) {
-          throw `Invalid position: (${row}, ${col}). Must be between 0 and ${BOARD_SIZE - 1}.`;
-        } else if (isCellOccupied(game, row, col)) {
-          throw `Cell (${row}, ${col}) is already occupied.`;
-        } else {
-          return { player, row, col };
-        }
-      },
-      game.value.currentPlayer,
-    );
+async function turn(
+  game: TicTacToeGame,
+  turnPlayer: PlayerType,
+  turnNumber: number,
+) {
+  const { player, row, col } = await game.prompt(
+    prompts.play,
+    (player, row, col) => {
+      if (player !== turnPlayer) {
+        throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
+      } else if (!isValidMove(row, col)) {
+        throw `Invalid position: (${row}, ${col}). Must be between 0 and ${BOARD_SIZE - 1}.`;
+      } else if (isCellOccupied(game, row, col)) {
+        throw `Cell (${row}, ${col}) is already occupied.`;
+      } else {
+        return { player, row, col };
+      }
+    },
+    game.value.currentPlayer,
+  );
 
-    placePiece(game, row, col, turnPlayer);
+  await placePiece(game, row, col, turnPlayer);
 
-    const winner = checkWinner(game);
-    if (winner) return { winner };
-    if (turnNumber >= MAX_TURNS) return { winner: "draw" as WinnerType };
+  const winner = checkWinner(game);
+  if (winner) return { winner };
+  if (turnNumber >= MAX_TURNS) return { winner: "draw" as WinnerType };
 
-    return { winner: null };
-  },
-});
+  return { winner: null };
+}
 
 function isValidMove(row: number, col: number): boolean {
   return (
@@ -167,7 +165,7 @@ export function checkWinner(host: TicTacToeGame): WinnerType {
   return null;
 }
 
-export function placePiece(
+export async function placePiece(
   host: TicTacToeGame,
   row: number,
   col: number,
@@ -181,9 +179,52 @@ export function placePiece(
     player,
     id: `piece-${player}-${moveNumber}`,
   };
-  host.produce((state) => {
+  await host.produceAsync((state) => {
     state.parts[piece.id] = piece;
     board.childIds.push(piece.id);
     board.partMap[`${row},${col}`] = piece.id;
   });
 }
+
+export class Client extends BaseGameClient<TicTacToeState> {
+  private onTurn = createMiddlewareChain(
+    async (ctx: { player: PlayerType; turn: number }) => {
+      return await turn(this._context, ctx.player, ctx.turn);
+    },
+  );
+
+  constructor() {
+    super(createInitialState());
+  }
+
+  async start(game: IGameContext<TicTacToeState>): Promise<TicTacToeState> {
+    while (true) {
+      const currentPlayer = game.value.currentPlayer;
+      const turnNumber = game.value.turn + 1;
+      const turnOutput = await this.onTurn.execute({
+        player: currentPlayer,
+        turn: turnNumber,
+      });
+
+      await game.produceAsync((state) => {
+        state.winner = turnOutput.winner;
+        if (!state.winner) {
+          state.currentPlayer = state.currentPlayer === "X" ? "O" : "X";
+          state.turn = turnNumber;
+        }
+      });
+      if (game.value.winner) break;
+    }
+
+    return game.value;
+  }
+  selectPart(id: string, callback: (t: TicTacToePart) => void): () => void {
+    return this.assignSelector((state) => state.parts[id], callback);
+  }
+  selectTurn(callback: (turns: number) => void): () => void {
+    return this.assignSelector((s) => s.turn, callback);
+  }
+  selectCurrentPlayer(callback: (player: PlayerType) => void) {
+    return this.assignSelector((s) => s.currentPlayer, callback);
+  }
+}

src/utils/command/command-prompt.ts

@@ -0,0 +1,105 @@
+import { createMiddlewareChain } from "../middleware";
+import { PromptValidator } from "./command-runner";
+import { CommandSchema } from "./types";
+
+export interface PromptDef<TArgs extends any[]> {
+  schema: CommandSchema;
+  hintText?: string;
+}
+
+export interface PromptCall<TArgs extends any[] = unknown[], TRes = unknown> {
+  def: PromptDef<TArgs>;
+  player?: string;
+  validator: PromptValidator<TRes, TArgs>;
+
+  resolve(res: TRes): void;
+  reject(reason: string): void;
+  promise: Promise<TRes>;
+}
+
+export type PromptTryResult =
+  | {
+      ok: false;
+      reason: string;
+    }
+  | {
+      ok: true;
+    };
+
+export type PromptContext = ReturnType<typeof createPromptContext>;
+export function createPromptContext() {
+  const map = new Map<string, PromptCall>();
+  const handleCall = createMiddlewareChain(async (call: PromptCall) => {
+    const key = call.player ?? "global";
+    const existing = map.get(key);
+    if (existing) {
+      existing.reject("Prompt overriden");
+    }
+
+    map.set(key, call);
+    try {
+      return await call.promise;
+    } finally {
+      if (map.get(key) === call) map.delete(key);
+    }
+  });
+
+  function tryCommit<TArgs extends any[]>(
+    def: PromptDef<TArgs>,
+    player: string,
+    ...args: TArgs
+  ): PromptTryResult {
+    const call = map.get(player);
+    if (!call) return { ok: false, reason: "No Prompt" };
+
+    try {
+      const res = call.validator(...args);
+      call.resolve(res);
+      return { ok: true };
+    } catch (reason) {
+      if (typeof reason === "string") return { ok: false, reason };
+      throw reason;
+    }
+  }
+
+  function cancel(player: string, reason = "Prompt Cancelled") {
+    map.get(player)?.reject(reason);
+  }
+
+  async function prompt<TArgs extends any[], TRes>(
+    def: PromptDef<TArgs>,
+    validator: PromptValidator<TRes, TArgs>,
+    player?: string,
+  ) {
+    let resolve: (res: TRes) => void;
+    let reject: (reason: string) => void;
+    const promise = new Promise<TRes>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    const call = {
+      def,
+      player,
+      validator,
+      resolve: resolve!,
+      reject: reject!,
+      promise,
+    } as PromptCall<unknown[], unknown>;
+    return (await handleCall.execute(call)) as TRes;
+  }
+
+  function reset() {
+    for (const call of map.values()) {
+      call.reject("Prompt Reset");
+    }
+    map.clear();
+  }
+
+  return {
+    prompt,
+    tryCommit,
+    cancel,
+    handleCall,
+    reset,
+  };
+}

src/utils/command/index.ts

@@ -1,22 +1,41 @@
-export { parseCommand } from './command-parse';
-export { parseCommandSchema } from './schema-parse';
-export { validateCommand, parseCommandWithSchema, applyCommandSchema } from './command-validate';
+export { parseCommand } from "./command-parse";
+export { parseCommandSchema } from "./schema-parse";
 export {
-    createCommandRegistry,
-    registerCommand,
-    unregisterCommand,
-    hasCommand,
-    getCommand,
-    runCommand,
-    runCommandParsed,
-    createCommandRunnerContext,
-} from './command-registry';
+  validateCommand,
+  parseCommandWithSchema,
+  applyCommandSchema,
+} from "./command-validate";
+export {
+  createCommandRegistry,
+  registerCommand,
+  unregisterCommand,
+  hasCommand,
+  getCommand,
+  runCommand,
+  runCommandParsed,
+  createCommandRunnerContext,
+} from "./command-registry";
 export type {
-    Command,
-    CommandParamSchema,
-    CommandOptionSchema,
-    CommandFlagSchema,
-    CommandSchema,
-} from './types';
-export type { CommandRunner, CommandDef, CommandResult, CommandRunnerHandler, CommandRunnerContext, PromptEvent, CommandRunnerEvents } from './command-runner';
-export type { CommandRegistry, CommandRunnerContextExport } from './command-registry';
+  Command,
+  CommandParamSchema,
+  CommandOptionSchema,
+  CommandFlagSchema,
+  CommandSchema,
+} from "./types";
+export type {
+  CommandRunner,
+  CommandDef,
+  CommandResult,
+  CommandRunnerHandler,
+  CommandRunnerContext,
+  PromptEvent,
+  CommandRunnerEvents,
+} from "./command-runner";
+export type {
+  CommandRegistry,
+  CommandRunnerContextExport,
+} from "./command-registry";
+
+export type { PromptDef, PromptTryResult, PromptCall } from "./command-prompt";
+
+export { createPromptContext } from "./command-prompt";

src/utils/middleware.ts

@@ -1,28 +1,38 @@
 type Middleware<TContext, TReturn> = (
   context: TContext,
-  next: () => Promise<TReturn>
+  next: () => Promise<TReturn>,
 ) => Promise<TReturn>;
 
 export type MiddlewareChain<TContext, TReturn> = {
-  use: (middleware: Middleware<TContext, TReturn>) => void;
+  use: (middleware: Middleware<TContext, TReturn>) => () => void;
   execute: (context: TContext) => Promise<TReturn>;
 };
 
-export function createMiddlewareChain<TContext extends object, TReturn=TContext>(
-  fallback?: (context: TContext) => Promise<TReturn>
+export function createMiddlewareChain<
+  TContext extends object,
+  TReturn = TContext,
+>(
+  fallback?: (context: TContext) => Promise<TReturn>,
 ): MiddlewareChain<TContext, TReturn> {
   const middlewares: Middleware<TContext, TReturn>[] = [];
 
   return {
     use(middleware: Middleware<TContext, TReturn>) {
       middlewares.push(middleware);
+
+      return function () {
+        const index = middlewares.indexOf(middleware);
+        if (index !== -1) {
+          middlewares.splice(index, 1);
+        }
+      };
     },
     async execute(context: TContext) {
       let index = 0;
 
       async function dispatch(ctx: TContext): Promise<TReturn> {
         if (index >= middlewares.length) {
-          return fallback ? fallback(ctx) : ctx as unknown as TReturn;
+          return fallback ? fallback(ctx) : (ctx as unknown as TReturn);
         }
         const current = middlewares[index++];
         return current(ctx, () => dispatch(ctx));

src/utils/mutable-signal.ts

@@ -1,7 +1,14 @@
 import { Signal, SignalOptions } from "@preact/signals-core";
 import { create } from "mutative";
 
-export class MutableSignal<T> extends Signal<T> {
+export interface MutableSignal<T> extends Signal<T> {
+  produce(fn: (draft: T) => undefined): void;
+  addInterruption(promise: Promise<void>): void;
+  clearInterruptions(): void;
+  produceAsync(fn: (draft: T) => undefined): Promise<void>;
+}
+
+class MutableSignalImpl<T> extends Signal<T> {
   private _interruptions: Promise<void>[] = [];
 
   public constructor(t?: T, options?: SignalOptions<T>) {
@@ -41,5 +48,5 @@ export function mutableSignal<T>(
   initial?: T,
   options?: SignalOptions<T>,
 ): MutableSignal<T> {
-  return new MutableSignal<T>(initial, options);
+  return new MutableSignalImpl<T>(initial, options);
 }

src/utils/spawner.ts

@@ -0,0 +1,39 @@
+import { effect } from "@preact/signals-core";
+
+export type SpawnerFunction = (id: string) => () => void;
+
+export function createSpawner(spawner: SpawnerFunction) {
+  const entries = new Map<string, () => void>();
+
+  function update(set: Set<string>) {
+    for (const key of set) {
+      if (!entries.has(key)) {
+        entries.set(key, spawner(key));
+      }
+    }
+
+    for (const [key, entry] of entries) {
+      if (!set.has(key)) {
+        entry();
+        entries.delete(key);
+      }
+    }
+  }
+
+  return update;
+}
+
+export function spawnerEffect(
+  iterable: () => Iterable<string>,
+  spawner: SpawnerFunction,
+) {
+  const update = createSpawner(spawner);
+
+  return effect(() => {
+    const set = new Set<string>();
+    for (const each of iterable()) {
+      set.add(each);
+    }
+    update(set);
+  });
+}

tests/samples/slay-the-spire-like/combat/triggers.test.ts

@@ -205,9 +205,9 @@ describe("desert triggers", () => {
 
       await triggers.onEffectApplied.execute(ctx, {
         effect: attackEffect,
-        entityKey: "player",
+        entityId: "player",
         stacks: 5,
-        sourceEntityKey: "enemy-0",
+        sourceEntityId: "enemy-0",
       });
 
       expect(ctx.value.player.hp).toBe(25);
@@ -223,7 +223,7 @@ describe("desert triggers", () => {
 
       await triggers.onEffectApplied.execute(ctx, {
         effect: drawEffect,
-        entityKey: "player",
+        entityId: "player",
         stacks: 2,
       });
 
@@ -239,7 +239,7 @@ describe("desert triggers", () => {
       const initialEnergy = ctx.value.player.energy;
       await triggers.onEffectApplied.execute(ctx, {
         effect: gainEnergyEffect,
-        entityKey: "player",
+        entityId: "player",
         stacks: 2,
       });
 
@@ -261,7 +261,7 @@ describe("desert triggers", () => {
 
       await triggers.onEffectApplied.execute(ctx, {
         effect: removeWoundEffect,
-        entityKey: "player",
+        entityId: "player",
         stacks: 2,
       });
 
@@ -286,9 +286,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "player",
+        entityId: "player",
         amount: 8,
-        sourceEntityKey: "enemy-0",
+        sourceEntityId: "enemy-0",
       });
 
       expect(ctx.value.player.hp).toBe(27);
@@ -312,9 +312,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "player",
+        entityId: "player",
         amount: 8,
-        sourceEntityKey: "enemy-0",
+        sourceEntityId: "enemy-0",
       });
 
       expect(ctx.value.player.hp).toBe(25);
@@ -334,9 +334,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "player",
+        entityId: "player",
         amount: 5,
-        sourceEntityKey: "enemy-0",
+        sourceEntityId: "enemy-0",
       });
 
       expect(ctx.value.player.hp).toBe(23);
@@ -352,16 +352,18 @@ describe("desert triggers", () => {
       );
       const triggers = getTriggers();
       const spikeEffect = createEffect("spike", "permanent");
+      const attackEffect = createEffect("attack", "instant");
 
       ctx._state.produce((draft) => {
         const enemy = draft.enemies[0];
         enemy.effects.spike = { data: spikeEffect, stacks: 3 };
       });
 
-      await triggers.onDamage.execute(ctx, {
-        entityKey: "仙人掌怪-0",
-        amount: 5,
-        sourceEntityKey: "player",
+      await triggers.onEffectApplied.execute(ctx, {
+        effect: attackEffect,
+        entityId: "仙人掌怪-0",
+        stacks: 5,
+        sourceEntityId: "player",
       });
 
       expect(ctx.value.player.hp).toBe(27);
@@ -402,9 +404,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "幼沙虫-0",
+        entityId: "幼沙虫-0",
         amount: 5,
-        sourceEntityKey: "player",
+        sourceEntityId: "player",
       });
 
       expect(ctx.value.player.energy).toBe(2);
@@ -429,9 +431,9 @@ describe("desert triggers", () => {
       let threw = false;
       try {
         await triggers.onDamage.execute(ctx, {
-          entityKey: "蜥蜴-0",
+          entityId: "蜥蜴-0",
           amount: 1,
-          sourceEntityKey: "player",
+          sourceEntityId: "player",
         });
       } catch (e) {
         threw = true;
@@ -457,7 +459,7 @@ describe("desert triggers", () => {
         draft.player.effects.discard = { data: discardEffect, stacks: 1 };
       });
 
-      await triggers.onTurnStart.execute(ctx, { entityKey: "player" });
+      await triggers.onTurnStart.execute(ctx, { entityId: "player" });
 
       expect(ctx.value.player.deck.regions.hand.childIds.length).toBe(2);
       expect(ctx.value.player.deck.regions.discardPile.childIds.length).toBe(1);
@@ -474,7 +476,7 @@ describe("desert triggers", () => {
         draft.player.effects.defendNext = { data: defendNextEffect, stacks: 5 };
       });
 
-      await triggers.onTurnStart.execute(ctx, { entityKey: "player" });
+      await triggers.onTurnStart.execute(ctx, { entityId: "player" });
 
       expect(ctx.value.player.effects.defend?.stacks).toBe(5);
       expect(ctx.value.player.effects.defendNext).toBeUndefined();
@@ -489,7 +491,7 @@ describe("desert triggers", () => {
         draft.player.effects.energyNext = { data: energyNextEffect, stacks: 2 };
       });
 
-      await triggers.onTurnStart.execute(ctx, { entityKey: "player" });
+      await triggers.onTurnStart.execute(ctx, { entityId: "player" });
 
       expect(ctx.value.player.energy).toBe(5);
       expect(ctx.value.player.effects.energyNext).toBeUndefined();
@@ -508,7 +510,7 @@ describe("desert triggers", () => {
         draft.player.effects.drawNext = { data: drawNextEffect, stacks: 2 };
       });
 
-      await triggers.onTurnStart.execute(ctx, { entityKey: "player" });
+      await triggers.onTurnStart.execute(ctx, { entityId: "player" });
 
       expect(ctx.value.player.deck.regions.hand.childIds.length).toBe(2);
       expect(ctx.value.player.effects.drawNext).toBeUndefined();
@@ -530,9 +532,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "仙人掌怪-0",
+        entityId: "仙人掌怪-0",
         amount: 5,
-        sourceEntityKey: "player",
+        sourceEntityId: "player",
       });
 
       expect(ctx.value.enemies[0].hp).toBe(2);
@@ -552,9 +554,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "仙人掌怪-0",
+        entityId: "仙人掌怪-0",
         amount: 5,
-        sourceEntityKey: "player",
+        sourceEntityId: "player",
       });
 
       expect(ctx.value.enemies[0].hp).toBe(74);
@@ -576,9 +578,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "player",
+        entityId: "player",
         amount: 5,
-        sourceEntityKey: "沙蝎-0",
+        sourceEntityId: "沙蝎-0",
       });
 
       expect(ctx.value.player.hp).toBe(23);
@@ -599,9 +601,9 @@ describe("desert triggers", () => {
       });
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "player",
+        entityId: "player",
         amount: 5,
-        sourceEntityKey: "骑马枪手-0",
+        sourceEntityId: "骑马枪手-0",
       });
 
       expect(ctx.value.player.hp).toBe(20);
@@ -623,10 +625,10 @@ describe("desert triggers", () => {
 
       await triggers.onEffectApplied.execute(ctx, {
         effect: crossbowEffect,
-        entityKey: "player",
+        entityId: "player",
         stacks: 0,
         cardId: "crossbow-1",
-        sourceEntityKey: "player",
+        sourceEntityId: "player",
         targetId: "仙人掌怪-0",
       });
 
@@ -647,7 +649,7 @@ describe("desert triggers", () => {
 
       await triggers.onCardDiscarded.execute(ctx, {
         cardId: "fatigue-1",
-        sourceEntityKey: "player",
+        sourceEntityId: "player",
       });
 
       expect(ctx.value.enemies[0].hp).toBe(40);
@@ -664,9 +666,9 @@ describe("desert triggers", () => {
       const triggers = getTriggers();
 
       await triggers.onDamage.execute(ctx, {
-        entityKey: "player",
+        entityId: "player",
         amount: 5,
-        sourceEntityKey: "秃鹫-0",
+        sourceEntityId: "秃鹫-0",
       });
 
       const vultureEyeCards = Object.values(ctx.value.player.deck.cards).filter(

tests/utils/command-prompt.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect } from "vitest";
+import { createPromptContext } from "@/utils/command/command-prompt";
+import type { CommandSchema } from "@/utils/command/types";
+
+const mockSchema: CommandSchema = {
+  name: "test",
+  params: [{ name: "value", required: true, variadic: false }],
+  options: {},
+  flags: {},
+};
+
+describe("createPromptContext", () => {
+  describe("prompt", () => {
+    it("should store prompt and return promise", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise = ctx.prompt({ schema: mockSchema }, validator);
+      await new Promise((r) => setTimeout(r, 0));
+
+      const result = ctx.tryCommit("global", "hello");
+      expect(result).toEqual({ ok: true });
+      await expect(promise).resolves.toBe("hello");
+    });
+
+    it("should associate prompt with specific player", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise = ctx.prompt({ schema: mockSchema }, validator, "player1");
+      await new Promise((r) => setTimeout(r, 0));
+
+      const result = ctx.tryCommit("player1", "hello");
+      expect(result).toEqual({ ok: true });
+      await expect(promise).resolves.toBe("hello");
+    });
+
+    it("should cancel existing prompt when new prompt starts for same player", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise1 = ctx.prompt({ schema: mockSchema }, validator, "player1");
+      await new Promise((r) => setTimeout(r, 0));
+
+      const promise2 = ctx.prompt({ schema: mockSchema }, validator, "player1");
+
+      // Resolve promise2 first, then both will settle
+      ctx.tryCommit("player1", "test");
+      const [result1, result2] = await Promise.allSettled([promise1, promise2]);
+
+      expect(result1.status).toBe("rejected");
+      expect((result1 as PromiseRejectedResult).reason).toBe(
+        "Prompt overriden",
+      );
+      expect(result2.status).toBe("fulfilled");
+    });
+
+    it("should allow different players to have independent prompts", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise1 = ctx.prompt({ schema: mockSchema }, validator, "player1");
+      const promise2 = ctx.prompt({ schema: mockSchema }, validator, "player2");
+      await new Promise((r) => setTimeout(r, 0));
+
+      ctx.tryCommit("player1", "hello");
+      ctx.tryCommit("player2", "world");
+
+      await expect(promise1).resolves.toBe("hello");
+      await expect(promise2).resolves.toBe("world");
+    });
+  });
+
+  describe("tryCommit", () => {
+    it("should return ok:true when prompt exists and validation passes", () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value.toUpperCase();
+
+      ctx.prompt({ schema: mockSchema }, validator, "player1");
+      const result = ctx.tryCommit("player1", "hello");
+
+      expect(result).toEqual({ ok: true });
+    });
+
+    it("should return ok:false with reason when no prompt exists", () => {
+      const ctx = createPromptContext();
+      const result = ctx.tryCommit("nonexistent", "hello");
+
+      expect(result).toEqual({ ok: false, reason: "No Prompt" });
+    });
+
+    it("should return ok:false when validator throws string", () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => {
+        if (value.length < 3) throw "Value too short";
+        return value;
+      };
+
+      ctx.prompt({ schema: mockSchema }, validator, "player1");
+      const result = ctx.tryCommit("player1", "ab");
+
+      expect(result).toEqual({ ok: false, reason: "Value too short" });
+    });
+
+    it("should throw when validator throws non-string error", () => {
+      const ctx = createPromptContext();
+      const validator = () => {
+        throw new Error("unexpected");
+      };
+
+      ctx.prompt({ schema: mockSchema }, validator, "player1");
+      expect(() => ctx.tryCommit("player1", "test")).toThrow("unexpected");
+    });
+
+    it("should pass validator return value to promise resolver", async () => {
+      const ctx = createPromptContext();
+      const validator = (a: number, b: number) => a + b;
+
+      const promise = ctx.prompt({ schema: mockSchema }, validator, "player1");
+      await new Promise((r) => setTimeout(r, 0));
+
+      ctx.tryCommit("player1", 2, 3);
+      await expect(promise).resolves.toBe(5);
+    });
+  });
+
+  describe("cancel", () => {
+    it("should reject promise with default message", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise = ctx.prompt({ schema: mockSchema }, validator, "player1");
+      await new Promise((r) => setTimeout(r, 0));
+
+      ctx.cancel("player1");
+
+      const result = await Promise.allSettled([promise]);
+      expect(result[0].status).toBe("rejected");
+      expect((result[0] as PromiseRejectedResult).reason).toBe(
+        "Prompt Cancelled",
+      );
+    });
+
+    it("should reject promise with custom reason", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise = ctx.prompt({ schema: mockSchema }, validator, "player1");
+      await new Promise((r) => setTimeout(r, 0));
+
+      ctx.cancel("player1", "Custom cancel reason");
+
+      const result = await Promise.allSettled([promise]);
+      expect(result[0].status).toBe("rejected");
+      expect((result[0] as PromiseRejectedResult).reason).toBe(
+        "Custom cancel reason",
+      );
+    });
+
+    it("should do nothing when no prompt exists for player", () => {
+      const ctx = createPromptContext();
+      ctx.cancel("nonexistent");
+    });
+
+    it("should only cancel prompt for specific player", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise1 = ctx.prompt({ schema: mockSchema }, validator, "player1");
+      const promise2 = ctx.prompt({ schema: mockSchema }, validator, "player2");
+      await new Promise((r) => setTimeout(r, 0));
+
+      ctx.cancel("player1");
+      ctx.tryCommit("player2", "test");
+
+      const [result1, result2] = await Promise.allSettled([promise1, promise2]);
+      expect(result1.status).toBe("rejected");
+      expect((result1 as PromiseRejectedResult).reason).toBe(
+        "Prompt Cancelled",
+      );
+
+      expect(result2.status).toBe("fulfilled");
+    });
+  });
+
+  describe("handleCall", () => {
+    it("should be a middleware chain that can be extended", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      let middlewareCalled = false;
+      ctx.handleCall.use(async (call, next) => {
+        middlewareCalled = true;
+        return next();
+      });
+
+      const promise = ctx.prompt({ schema: mockSchema }, validator);
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(middlewareCalled).toBe(true);
+      ctx.tryCommit("global", "test");
+      await expect(promise).resolves.toBe("test");
+    });
+
+    it("should remove prompt from map after resolution", async () => {
+      const ctx = createPromptContext();
+      const validator = (value: string) => value;
+
+      const promise = ctx.prompt({ schema: mockSchema }, validator);
+      await new Promise((r) => setTimeout(r, 0));
+
+      ctx.tryCommit("global", "test");
+      await promise;
+
+      const result = ctx.tryCommit("global", "another");
+      expect(result).toEqual({ ok: false, reason: "No Prompt" });
+    });
+  });
+});

tests/utils/command.test.ts

@@ -1,174 +1,176 @@
-import { describe, it, expect } from 'vitest';
-import { parseCommand, type Command } from '@/utils/command';
+import { describe, it, expect } from "vitest";
+import { parseCommand, type Command } from "@/utils/command";
 
-describe('parseCommand', () => {
-    it('should parse empty string', () => {
-        const result = parseCommand('');
-        expect(result).toEqual({
-            name: '',
-            flags: {},
-            options: {},
-            params: []
-        });
+describe("parseCommand", () => {
+  it("should parse empty string", () => {
+    const result = parseCommand("");
+    expect(result).toEqual({
+      name: "",
+      flags: {},
+      options: {},
+      params: [],
     });
+  });
 
-    it('should parse command name only', () => {
-        const result = parseCommand('move');
-        expect(result).toEqual({
-            name: 'move',
-            flags: {},
-            options: {},
-            params: []
-        });
+  it("should parse command name only", () => {
+    const result = parseCommand("move");
+    expect(result).toEqual({
+      name: "move",
+      flags: {},
+      options: {},
+      params: [],
     });
+  });
 
-    it('should parse command with params', () => {
-        const result = parseCommand('move meeple1 region1');
-        expect(result).toEqual({
-            name: 'move',
-            flags: {},
-            options: {},
-            params: ['meeple1', 'region1']
-        });
+  it("should parse command with params", () => {
+    const result = parseCommand("move meeple1 region1");
+    expect(result).toEqual({
+      name: "move",
+      flags: {},
+      options: {},
+      params: ["meeple1", "region1"],
     });
+  });
 
-    it('should parse command with long flags', () => {
-        const result = parseCommand('move meeple1 --force --quiet');
-        expect(result).toEqual({
-            name: 'move',
-            flags: { force: true, quiet: true },
-            options: {},
-            params: ['meeple1']
-        });
+  it("should parse command with long flags", () => {
+    const result = parseCommand("move meeple1 --force --quiet");
+    expect(result).toEqual({
+      name: "move",
+      flags: { force: true, quiet: true },
+      options: {},
+      params: ["meeple1"],
     });
+  });
 
-    it('should parse command with short flags', () => {
-        const result = parseCommand('move meeple1 -f -q');
-        expect(result).toEqual({
-            name: 'move',
-            flags: { f: true, q: true },
-            options: {},
-            params: ['meeple1']
-        });
+  it("should parse command with short flags", () => {
+    const result = parseCommand("move meeple1 -f -q");
+    expect(result).toEqual({
+      name: "move",
+      flags: { f: true, q: true },
+      options: {},
+      params: ["meeple1"],
     });
+  });
 
-    it('should parse command with long options', () => {
-        const result = parseCommand('move meeple1 --x 10 --y 20');
-        expect(result).toEqual({
-            name: 'move',
-            flags: {},
-            options: { x: '10', y: '20' },
-            params: ['meeple1']
-        });
+  it("should parse command with long options", () => {
+    const result = parseCommand("move meeple1 --x 10 --y 20");
+    expect(result).toEqual({
+      name: "move",
+      flags: {},
+      options: { x: "10", y: "20" },
+      params: ["meeple1"],
     });
+  });
 
-    it('should parse command with short options', () => {
-        const result = parseCommand('move meeple1 -x 10 -y 20');
-        expect(result).toEqual({
-            name: 'move',
-            flags: {},
-            options: { x: '10', y: '20' },
-            params: ['meeple1']
-        });
+  it("should parse command with short options", () => {
+    const result = parseCommand("move meeple1 -x 10 -y 20");
+    expect(result).toEqual({
+      name: "move",
+      flags: {},
+      options: { x: "10", y: "20" },
+      params: ["meeple1"],
     });
+  });
 
-    it('should parse command with mixed flags和选项', () => {
-        const result = parseCommand('move meeple1 region1 --force -x 10 -q');
-        expect(result).toEqual({
-            name: 'move',
-            flags: { force: true, q: true },
-            options: { x: '10' },
-            params: ['meeple1', 'region1']
-        });
+  it("should parse command with mixed flags和选项", () => {
+    const result = parseCommand("move meeple1 region1 --force -x 10 -q");
+    expect(result).toEqual({
+      name: "move",
+      flags: { force: true, q: true },
+      options: { x: "10" },
+      params: ["meeple1", "region1"],
     });
+  });
 
-    it('should handle extra whitespace', () => {
-        const result = parseCommand('  move   meeple1   --force  ');
-        expect(result).toEqual({
-            name: 'move',
-            flags: { force: true },
-            options: {},
-            params: ['meeple1']
-        });
+  it("should handle extra whitespace", () => {
+    const result = parseCommand("  move   meeple1   --force  ");
+    expect(result).toEqual({
+      name: "move",
+      flags: { force: true },
+      options: {},
+      params: ["meeple1"],
     });
+  });
 
-    it('should parse complex command', () => {
-        const result = parseCommand('place meeple1 board --x 5 --y 3 --rotate 90 --force');
-        expect(result).toEqual({
-            name: 'place',
-            flags: { force: true },
-            options: { x: '5', y: '3', rotate: '90' },
-            params: ['meeple1', 'board']
-        });
+  it("should parse complex command", () => {
+    const result = parseCommand(
+      "place meeple1 board --x 5 --y 3 --rotate 90 --force",
+    );
+    expect(result).toEqual({
+      name: "place",
+      flags: { force: true },
+      options: { x: "5", y: "3", rotate: "90" },
+      params: ["meeple1", "board"],
     });
+  });
 
-    it('should treat negative number as option value', () => {
-        const result = parseCommand('set --value -10');
-        expect(result).toEqual({
-            name: 'set',
-            flags: {},
-            options: { value: '-10' },
-            params: []
-        });
+  it("should treat negative number as option value", () => {
+    const result = parseCommand("set --value -10");
+    expect(result).toEqual({
+      name: "set",
+      flags: {},
+      options: { value: "-10" },
+      params: [],
     });
+  });
 
-    it('should parse quoted string with double quotes', () => {
-        const result = parseCommand('place tile "large castle" --x 5');
-        expect(result).toEqual({
-            name: 'place',
-            flags: {},
-            options: { x: '5' },
-            params: ['tile', 'large castle']
-        });
+  it("should parse quoted string with double quotes", () => {
+    const result = parseCommand('place tile "large castle" --x 5');
+    expect(result).toEqual({
+      name: "place",
+      flags: {},
+      options: { x: "5" },
+      params: ["tile", "large castle"],
     });
+  });
 
-    it('should parse quoted string with single quotes', () => {
-        const result = parseCommand("place tile 'large castle' --x 5");
-        expect(result).toEqual({
-            name: 'place',
-            flags: {},
-            options: { x: '5' },
-            params: ['tile', 'large castle']
-        });
+  it("should parse quoted string with single quotes", () => {
+    const result = parseCommand("place tile 'large castle' --x 5");
+    expect(result).toEqual({
+      name: "place",
+      flags: {},
+      options: { x: "5" },
+      params: ["tile", "large castle"],
     });
+  });
 
-    it('should handle escaped quotes', () => {
-        const result = parseCommand('say "hello \\"world\\""');
-        expect(result).toEqual({
-            name: 'say',
-            flags: {},
-            options: {},
-            params: ['hello "world"']
-        });
+  it("should handle escaped quotes", () => {
+    const result = parseCommand('say "hello \\"world\\""');
+    expect(result).toEqual({
+      name: "say",
+      flags: {},
+      options: {},
+      params: ['hello "world"'],
     });
+  });
 
-    it('should handle escaped backslash', () => {
-        const result = parseCommand('set path "C:\\\\Users"');
-        expect(result).toEqual({
-            name: 'set',
-            flags: {},
-            options: {},
-            params: ['path', 'C:\\Users']
-        });
+  it("should handle escaped backslash", () => {
+    const result = parseCommand('set path "C:\\\\Users"');
+    expect(result).toEqual({
+      name: "set",
+      flags: {},
+      options: {},
+      params: ["path", "C:\\Users"],
     });
+  });
 
-    it('should handle mixed quotes', () => {
-        const result = parseCommand('cmd "hello world" \'foo bar\' --flag');
-        expect(result).toEqual({
-            name: 'cmd',
-            flags: { flag: true },
-            options: {},
-            params: ['hello world', 'foo bar']
-        });
+  it("should handle mixed quotes", () => {
+    const result = parseCommand("cmd \"hello world\" 'foo bar' --flag");
+    expect(result).toEqual({
+      name: "cmd",
+      flags: { flag: true },
+      options: {},
+      params: ["hello world", "foo bar"],
     });
+  });
 
-    it('should handle quote in middle of argument', () => {
-        const result = parseCommand('cmd "hello\'s world"');
-        expect(result).toEqual({
-            name: 'cmd',
-            flags: {},
-            options: {},
-            params: ["hello's world"]
-        });
+  it("should handle quote in middle of argument", () => {
+    const result = parseCommand('cmd "hello\'s world"');
+    expect(result).toEqual({
+      name: "cmd",
+      flags: {},
+      options: {},
+      params: ["hello's world"],
     });
+  });
 });