feat: update skill def

.qwen/skills/create-game-module/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: Create Game Module
+description: Create a runnable logic module for a board game with 'boardgame-core', '@preact/signals' and 'mutative'
+---
+# 如何编写游戏模组
+
+## 要求
+
+游戏模组需要导出以下接口：
+
+```typescript
+import { IGameContext, createGameCommandRegistry } from '@/index';
+
+// 定义类型
+export type GameState = {
+    //...
+};
+export type Game = IGameContext<GameState>;
+
+// 创建 mutative 游戏初始状态
+export function createInitialState(): GameState {
+    //...
+}
+
+// 创建命令注册表（可选）
+export const registry = createGameCommandRegistry<GameState>();
+
+// 运行游戏
+export async function start(game: Game) {
+    // ...
+}
+```
+
+或者导出为 `GameModule` 对象：
+
+```typescript
+import { GameModule } from '@/index';
+
+export const gameModule: GameModule<GameState> = {
+    registry,
+    createInitialState,
+    start,
+};
+```
+
+## 流程
+
+### 0. 确认规则
+
+规则应当存放在 `rule.md`。
+
+描述一个桌面游戏的以下要素：
+- **主题**：游戏的世界观和背景
+- **配件**：棋子、卡牌、骰子等物理组件
+- **游戏布置形式**：棋盘、版图、卡牌放置区等
+- **游戏流程**：回合结构、阶段划分
+- **玩家行动**：每回合玩家可以做什么
+- **胜利条件与终局结算**：如何判定胜负
+
+### 1. 创建类型
+
+创建 `types.ts` 并导出游戏所用的类型。
+
+- 为游戏概念创建字符串枚举类型（如 `PlayerType = 'X' | 'O'`）
+- 使用 `Part<TMeta>` 为游戏配件创建对象类型
+- 使用 `Region` 为游戏区域创建容器类型
+- 设计游戏的全局状态类型
+
+游戏使用 `mutative` 不可变类型驱动。状态类型必须是**可序列化的**（不支持函数、`Map`、`Set` 等）。
+
+```typescript
+import { Part, Region } from '@/index';
+
+export type PlayerType = 'X' | 'O';
+
+export type PieceMeta = {
+    owner: PlayerType;
+};
+
+export type Piece = Part<PieceMeta>;
+
+export type GameState = {
+    board: Region;
+    pieces: Record<string, Piece>;
+    currentPlayer: PlayerType;
+    turn: number;
+    winner: PlayerType | null;
+};
+```
+
+### 2. 创建游戏配件表
+
+若某种游戏配件数量较大，可使用csv文件进行配置，否则在代码中inline创建。
+
+csv文件遵循以下要求：
+- 从`#`开头的内容会被当作注释忽略
+- 第二行为数据类型，会用于生成.d.ts文件
+- 可以有空行
+
+```csv
+# parts.csv
+type,player,count
+string,string,int
+kitten,white,8
+kitten,black,8
+cat,white,8
+cat,black,8
+```
+
+```typescript
+import parts from "./parts.csv";
+const pieces = createPartsFromTable(
+    parts,
+    (item, index) => `${item.player}-${item.type}-${index + 1}`,
+    (item) => item.count
+) as Record<string, BoopPart>;
+```
+
+### 3. 创建 Prompts
+
+使用 prompt 来描述需要玩家进行的行动命令 schema。
+
+- prompt 包含一个 schema 和若干参数
+- 每个参数通常指定某个配件 ID、某个枚举字符串、或者某个数字
+- 参数类型必须是原始类型（`string`、`number`）或字符串枚举
+
+```typescript
+import { createPromptDef } from '@/index';
+
+export const prompts = {
+    play: createPromptDef<[PlayerType, number, number]>(
+        'play <player> <row:number> <col:number>',
+        '选择下子位置'
+    ),
+};
+```
+
+Prompt schema 语法：
+- `<param>` - 必需参数
+- `[param]` - 可选参数
+- `[param:type]` - 带类型验证的参数（如 `[count:number]`）
+
+### 3. 创建游戏流程
+
+游戏主循环负责协调游戏进程、等待玩家输入、更新状态。
+
+```typescript
+export async function start(game: Game) {
+    while (true) {
+        // game.value 可获取当前的全局状态
+        const currentPlayer = game.value.currentPlayer;
+        const turnNumber = game.value.turn + 1;
+        const turnOutput = await turn(game, currentPlayer, 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;
+}
+```
+
+回合逻辑示例：
+
+```typescript
+async function turn(game: Game, turnPlayer: PlayerType, turnNumber: number) {
+    // 获取玩家输入
+    const { player, row, col } = await game.prompt(
+        prompts.play,
+        (player, row, col) => {
+            if (player !== turnPlayer) {
+                throw `无效的玩家: ${player}。应为 ${turnPlayer}。`;
+            } else if (!isValidMove(row, col)) {
+                throw `无效位置: (${row}, ${col})。必须在 0 到 ${BOARD_SIZE - 1} 之间。`;
+            } else if (isCellOccupied(game, row, col)) {
+                throw `格子 (${row}, ${col}) 已被占用。`;
+            } else {
+                return { player, row, col };
+            }
+        },
+        game.value.currentPlayer
+    );
+
+    // 执行放置逻辑
+    placePiece(game, row, col, turnPlayer);
+
+    // 返回回合结果
+    return { winner: checkWinner(game) };
+}
+```
+
+**注意事项：**
+- `game.produce(fn)` 用于同步更新状态
+- `game.produceAsync(fn)` 用于异步更新状态（会等待中断 Promise 完成，适用于播放动画）
+- 验证器函数中抛出字符串错误会返回给玩家，玩家可重新输入
+- 循环必须有明确的退出条件，避免无限循环
+- 玩家取消输入时，`game.prompt()` 会抛出异常，需要适当处理
+
+### 4. 创建测试
+
+测试文件位于 `tests/samples/` 目录下，命名格式为 `<game-name>.test.ts`。
+
+#### 测试要求
+
+**覆盖范围：**
+- 每种游戏结束条件至少一条测试
+- 每种玩家行动至少一条测试
+- 边界条件和异常情况至少一条测试
+- 胜利和失败场景各至少一条测试
+
+**测试结构：**
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createGameContext } from '@/core/game';
+import { registry, createInitialState } from './my-game';
+
+describe('My Game', () => {
+    // 测试辅助函数
+    function createTestContext() {
+        return createGameContext(registry, createInitialState());
+    }
+
+    // 测试工具函数
+    describe('Utils', () => {
+        it('should calculate correct values', () => {
+            // 测试纯函数逻辑
+        });
+    });
+
+    // 测试命令
+    describe('Commands', () => {
+        it('should perform action correctly', async () => {
+            const game = createTestContext();
+            // 设置初始状态
+            // 执行命令
+            // 验证状态变化
+        });
+
+        it('should fail on invalid input', async () => {
+            const game = createTestContext();
+            // 测试错误输入
+            const result = await game.run('invalid-command');
+            expect(result.success).toBe(false);
+        });
+    });
+
+    // 测试完整游戏流程
+    describe('Game Flow', () => {
+        it('should complete a full game cycle', async () => {
+            // 模拟完整游戏流程
+        });
+    });
+});
+```
+
+**测试规范：**
+- 使用 `createGameContext(registry, initialState)` 创建测试上下文
+- 使用 `game.run('command args')` 执行命令
+- 验证 `game.value` 的状态变化，而非命令返回值
+- 不要使用 `console.log` 或其他调试输出
+- 使用 `describe` 分组相关测试
+- 测试命名使用 `should...` 格式描述预期行为
+- 异步测试使用 `async/await`
+
+**命令测试示例：**
+```typescript
+it('should deal damage to enemy', async () => {
+    const game = createTestContext();
+    setupTestGame(game); // 自定义测试设置
+
+    const enemyHpBefore = game.value.currentEnemy!.hp;
+    await game.run('play player1 card_1');
+
+    // 验证状态变化
+    expect(game.value.currentEnemy!.hp).toBeLessThan(enemyHpBefore);
+    expect(game.value.playerHands.player1).not.toContain('card_1');
+});
+
+it('should fail if card not in hand', async () => {
+    const game = createTestContext();
+    setupTestGame(game);
+
+    const result = await game.run('play player1 invalid_card');
+    expect(result.success).toBe(false);
+    if (!result.success) {
+        expect(result.error).toContain('不存在');
+    }
+});
+```
+
+**运行测试：**
+```bash
+# 运行所有测试
+npm run test:run
+
+# 运行特定测试文件
+npx vitest run tests/samples/my-game.test.ts
+
+# 运行特定测试用例
+npx vitest run -t "should deal damage" tests/samples/my-game.test.ts
+```
+
+## 完整示例
+
+参考 `src/samples/boop/` 获取完整的`boop`游戏实现。
+参考 `src/samples/regicide/` 获取卡牌游戏的完整示例。
+
+## 相关资源
+
+- [API 参考](./references/api.md) - 完整的 API 文档
+- [AGENTS.md](../../AGENTS.md) - 项目代码规范和架构说明

.qwen/skills/create-game-module/references/api.md

@@ -0,0 +1,759 @@
+# API 参考
+
+本文档记录游戏模组开发者需要使用的公共 API。
+
+## 核心接口
+
+### `IGameContext<TState>`
+
+游戏运行的核心上下文，提供状态访问、随机数、命令执行和提示系统。
+
+```typescript
+interface IGameContext<TState extends Record<string, unknown> = {}> {
+    readonly value: TState;                           // 当前游戏状态（只读）
+    readonly rng: ReadonlyRNG;                        // 随机数生成器（只读）
+
+    // 状态更新
+    produce(fn: (draft: TState) => void): void;       // 同步变更状态（基于 mutative）
+    produceAsync(fn: (draft: TState) => void): Promise<void>;  // 异步变更状态（等待中断）
+
+    // 命令执行
+    run<T>(input: string): Promise<CommandResult<T>>;           // 执行命令字符串
+    runParsed<T>(command: Command): Promise<CommandResult<T>>; // 执行已解析的命令
+
+    // 提示系统
+    prompt<TResult, TArgs>(
+        def: PromptDef<TArgs>,
+        validator: PromptValidator<TResult, TArgs>,
+        currentPlayer?: string | null
+    ): Promise<TResult>;
+}
+```
+
+**使用示例：**
+
+```typescript
+// 读取状态
+const currentPlayer = game.value.currentPlayer;
+
+// 同步更新状态
+game.produce((state) => {
+    state.score += 10;
+});
+
+// 异步更新状态（等待动画完成）
+await game.produceAsync((state) => {
+    state.phase = 'next';
+});
+
+// 等待玩家输入
+const result = await game.prompt(
+    prompts.move,
+    (from, to) => {
+        if (!isValidMove(from, to)) {
+            throw '无效移动';
+        }
+        return { from, to };
+    }
+);
+```
+
+---
+
+### `GameModule<TState, TResult>`
+
+游戏模块的类型定义，这是开发者创建游戏时需要导出的核心结构。
+
+```typescript
+type GameModule<TState extends Record<string, unknown>, TResult = unknown> = {
+    registry?: CommandRegistry<IGameContext<TState>>;  // 可选的命令注册表
+    createInitialState: () => TState;                   // 创建初始状态
+    start: (ctx: IGameContext<TState>) => Promise<TResult>;  // 游戏主循环
+}
+```
+
+---
+
+### `createGameCommandRegistry<TState>()`
+
+创建游戏命令注册表，游戏模组用它来注册自定义命令。
+
+```typescript
+function createGameCommandRegistry<TState extends Record<string, unknown> = {}>(): CommandRegistry<IGameContext<TState>>
+```
+
+**使用示例：**
+
+```typescript
+import { createGameCommandRegistry, IGameContext } from '@/index';
+
+export type GameState = { score: number };
+export const registry = createGameCommandRegistry<GameState>();
+
+// 注册命令
+registry.register('addScore <amount:number>', async function(ctx, amount) {
+    ctx.produce((state) => {
+        state.score += amount;
+    });
+    return { success: true, result: undefined };
+});
+```
+
+---
+
+## 提示系统
+
+### `createPromptDef<TArgs>(schema, hintText?)`
+
+从字符串模式创建 `PromptDef`。
+
+```typescript
+function createPromptDef<TArgs>(
+    schema: CommandSchema | string,
+    hintText?: string
+): PromptDef<TArgs>
+```
+
+**使用示例：**
+
+```typescript
+import { createPromptDef } from '@/index';
+
+export const prompts = {
+    // 必需参数
+    play: createPromptDef<[PlayerType, number, number]>(
+        'play <player> <row:number> <col:number>',
+        '选择下子位置'
+    ),
+
+    // 可选参数
+    draw: createPromptDef<[number?]>(
+        'draw [count:number]',
+        '抽牌'
+    ),
+
+    // 带选项
+    trade: createPromptDef<[string, string]>(
+        'trade <give> <receive> [--force]',
+        '交易'
+    ),
+};
+```
+
+---
+
+### `PromptDef<TArgs>`
+
+提示定义，用于 `context.prompt()` 方法。
+
+```typescript
+type PromptDef<TArgs extends any[] = any[]> = {
+    schema: CommandSchema;    // 命令模式定义
+    hintText?: string;        // 可选的提示文本
+}
+```
+
+---
+
+### `PromptValidator<TResult, TArgs>`
+
+提示验证函数类型。验证器函数接收解析后的参数，应返回结果或抛出字符串错误。
+
+```typescript
+type PromptValidator<TResult, TArgs extends any[] = any[]> = (...params: TArgs) => TResult;
+```
+
+**验证器规则：**
+- 返回任意值表示验证成功，该值将作为 `prompt()` 的返回值
+- 抛出字符串错误表示验证失败，错误消息会返回给玩家，玩家可重新输入
+- 玩家取消输入时，`prompt()` 会抛出异常
+
+---
+
+### `PromptEvent`
+
+提示事件对象，通过 `commandRunnerContext.on('prompt', handler)` 监听。
+
+```typescript
+type PromptEvent = {
+    schema: CommandSchema;
+    hintText?: string;
+    currentPlayer: string | null;
+    tryCommit: (commandOrInput: Command | string) => string | null;  // null=成功，string=错误消息
+    cancel: (reason?: string) => void;
+}
+```
+
+---
+
+## 零件系统 (Part)
+
+### `Part<TMeta>`
+
+游戏中的可操作物件（棋子、卡牌、骰子等）。
+
+```typescript
+type Part<TMeta = {}> = {
+    id: string;                    // 唯一标识
+    sides?: number;                // 总面数（用于骰子/多面牌）
+    side?: number;                 // 当前面
+    alignments?: string[];         // 可用对齐方式
+    alignment?: string;            // 当前对齐方式
+    regionId: string;              // 所属区域 ID
+    position: number[];            // 在区域中的位置坐标
+} & Immutable<TMeta>;             // 自定义元数据（不可变）
+```
+
+**使用示例：**
+
+```typescript
+import { Part } from '@/index';
+
+export type PieceMeta = {
+    owner: 'X' | 'O';
+    type: 'pawn' | 'king';
+};
+
+export type Piece = Part<PieceMeta>;
+
+// 访问元数据
+const piece: Piece = ...;
+console.log(piece.owner);  // 'X'
+console.log(piece.type);   // 'pawn'
+```
+
+---
+
+### 零件操作函数
+
+#### `flip<TMeta>(part)`
+
+翻转到下一面（循环）。
+
+```typescript
+function flip<TMeta>(part: Part<TMeta>): void
+```
+
+#### `flipTo<TMeta>(part, side)`
+
+翻转到指定面。
+
+```typescript
+function flipTo<TMeta>(part: Part<TMeta>, side: number): void
+```
+
+#### `roll<TMeta>(part, rng)`
+
+用 RNG 随机掷骰子。
+
+```typescript
+function roll<TMeta>(part: Part<TMeta>, rng: RNG): void
+```
+
+---
+
+## 零件工厂 (Part Factory)
+
+### `createParts<T>(item, getId, count?)`
+
+创建多个相同类型的零件。
+
+```typescript
+function createParts<T>(
+    item: T,
+    getId: (index: number) => string,
+    count?: number
+): Record<string, Part<T>>
+```
+
+**使用示例：**
+
+```typescript
+import { createParts } from '@/index';
+
+const pieces = createParts(
+    { owner: 'X', type: 'pawn' },
+    (i) => `piece-x-${i}`,
+    5  // 创建 5 个
+);
+```
+
+---
+
+### `createPartsFromTable<T>(items, getId, getCount?)`
+
+从配置表批量创建零件。
+
+```typescript
+function createPartsFromTable<T>(
+    items: readonly T[],
+    getId: (item: T, index: number) => string,
+    getCount?: ((item: T) => number) | number
+): Record<string, Part<T>>
+```
+
+**使用示例：**
+
+```typescript
+import { createPartsFromTable } from '@/index';
+
+const cardTable = [
+    { name: 'fireball', damage: 3 },
+    { name: 'shield', defense: 2 },
+];
+
+const cards = createPartsFromTable(
+    cardTable,
+    (item) => item.name,
+    (item) => item.name === 'fireball' ? 4 : 2  // 每种卡牌的数量
+);
+```
+
+---
+
+## 区域系统 (Region)
+
+### `Region`
+
+游戏区域（棋盘、手牌区等）。
+
+```typescript
+type Region = {
+    id: string;                     // 区域 ID
+    axes: RegionAxis[];             // 坐标轴定义
+    childIds: string[];             // 包含的零件 ID 列表
+    partMap: Record<string, string>; // 位置 -> 零件 ID 映射
+}
+```
+
+---
+
+### `RegionAxis`
+
+区域的一个坐标轴。
+
+```typescript
+type RegionAxis = {
+    name: string;
+    min?: number;
+    max?: number;
+    align?: 'start' | 'end' | 'center';  // 对齐方式
+}
+```
+
+---
+
+### `createRegion(id, axes)`
+
+创建区域。
+
+```typescript
+function createRegion(id: string, axes: RegionAxis[]): Region
+```
+
+**使用示例：**
+
+```typescript
+import { createRegion, createRegionAxis } from '@/index';
+
+// 创建 3x3 棋盘
+const board = createRegion('board', [
+    createRegionAxis('row', 0, 2),
+    createRegionAxis('col', 0, 2),
+]);
+
+// 或简写
+const board = createRegion('board', [
+    { name: 'row', min: 0, max: 2 },
+    { name: 'col', min: 0, max: 2 },
+]);
+```
+
+---
+
+### `createRegionAxis(name, min?, max?, align?)`
+
+创建坐标轴。
+
+```typescript
+function createRegionAxis(
+    name: string,
+    min?: number,
+    max?: number,
+    align?: 'start' | 'end' | 'center'
+): RegionAxis
+```
+
+---
+
+### 区域操作函数
+
+#### `applyAlign<TMeta>(region, parts)`
+
+根据轴的 `align` 配置重新排列零件位置。
+
+```typescript
+function applyAlign<TMeta>(region: Region, parts: Record<string, Part<TMeta>>): void
+```
+
+#### `shuffle<TMeta>(region, parts, rng)`
+
+在区域内随机打乱零件位置。
+
+```typescript
+function shuffle<TMeta>(region: Region, parts: Record<string, Part<TMeta>>, rng: RNG): void
+```
+
+#### `moveToRegion<TMeta>(part, sourceRegion, targetRegion, position?)`
+
+将零件从一个区域移动到另一个区域。
+
+```typescript
+function moveToRegion<TMeta>(
+    part: Part<TMeta>,
+    sourceRegion: Region | null,
+    targetRegion: Region | null,
+    position?: number[]
+): void
+```
+
+---
+
+## 命令系统 (Command System)
+
+### `Command`
+
+解析后的命令对象。
+
+```typescript
+type Command = {
+    name: string;                                    // 命令名
+    flags: Record<string, true>;                     // 标志（如 --verbose）
+    options: Record<string, unknown>;                // 选项（如 --player X）
+    params: unknown[];                               // 位置参数
+}
+```
+
+---
+
+### `CommandSchema`
+
+命令模式定义，用于验证和解析。
+
+```typescript
+type CommandSchema = {
+    name: string;
+    params: CommandParamSchema[];
+    options: Record<string, CommandOptionSchema>;
+    flags: Record<string, CommandFlagSchema>;
+}
+```
+
+---
+
+### `CommandResult<T>`
+
+命令执行结果（判别联合类型）。
+
+```typescript
+type CommandResult<T = unknown> =
+    | { success: true; result: T }
+    | { success: false; error: string }
+```
+
+**使用示例：**
+
+```typescript
+const result = await game.run('move piece1 piece2');
+
+if (result.success) {
+    console.log('命令执行成功', result.result);
+} else {
+    console.error('命令执行失败', result.error);
+}
+```
+
+---
+
+### `CommandDef<TContext, TFunc>`
+
+命令定义对象，用于 `registry.register()`。
+
+```typescript
+type CommandDef<TContext, TFunc extends CommandFunction<TContext>> = {
+    schema: string | CommandSchema;
+    run: TFunc;
+}
+
+type CommandFunction<TContext> = (ctx: TContext, ...args: any[]) => Promise<unknown>;
+```
+
+---
+
+### `CommandRegistry<TContext>`
+
+命令注册表。
+
+```typescript
+class CommandRegistry<TContext> extends Map<string, CommandRunner<TContext>> {
+    register<TFunc>(
+        ...args: [schema: CommandSchema | string, run: TFunc] | [CommandDef<TContext, TFunc>]
+    ): (ctx, ...args) => Promise<TResult>
+}
+```
+
+**注册命令的两种方式：**
+
+```typescript
+// 方式 1：直接传入 schema 和函数
+registry.register('move <from> <to>', async function(ctx, from, to) {
+    ctx.produce((state) => { /* 修改状态 */ });
+    return { success: true, result: undefined };
+});
+
+// 方式 2：使用 CommandDef 对象
+registry.register({
+    schema: 'move <from> <to>',
+    run: async function(ctx, from, to) {
+        ctx.produce((state) => { /* 修改状态 */ });
+        return { success: true, result: undefined };
+    }
+});
+```
+
+---
+
+### `parseCommand(input, schema?)`
+
+解析命令字符串为 `Command` 对象。
+
+```typescript
+function parseCommand(input: string, schema?: CommandSchema): Command
+```
+
+---
+
+### `parseCommandSchema(schemaStr, name?)`
+
+从字符串模式解析命令模式。
+
+```typescript
+function parseCommandSchema(schemaStr: string, name?: string): CommandSchema
+```
+
+**Schema 语法：**
+- `<param>` - 必需参数
+- `[param]` - 可选参数
+- `[param:type]` - 带类型验证的参数（如 `[count:number]`）
+- `--option:value` - 必需选项
+- `[-o value]` - 可选选项
+- `[--flag]` - 可选标志
+
+---
+
+## 随机数生成器 (RNG)
+
+### `ReadonlyRNG`
+
+只读 RNG 接口（`IGameContext.rng` 返回此类型）。
+
+```typescript
+interface ReadonlyRNG {
+    next(max?: number): number;     // [0,1) 随机数，或 [0,max)
+    nextInt(max: number): number;   // [0,max) 随机整数
+}
+```
+
+---
+
+### `RNG`
+
+可设置种子的 RNG 接口。
+
+```typescript
+interface RNG extends ReadonlyRNG {
+    setSeed(seed: number): void;
+    getSeed(): number;
+}
+```
+
+**使用示例：**
+
+```typescript
+// 在 IGameContext 中使用
+const roll = game.rng.nextInt(6) + 1;  // 1-6 的随机数
+
+// 在区域操作中使用时
+shuffle(region, parts, rng);  // 需要传入 RNG
+```
+
+---
+
+## 可变信号 (MutableSignal)
+
+### `MutableSignal<T>`
+
+扩展自 Preact Signal 的可变信号类，支持 mutative-style 的 `produce` 方法。
+
+```typescript
+class MutableSignal<T> extends Signal<T> {
+    produce(fn: (draft: T) => void): void;
+    addInterruption(promise: Promise<void>): void;    // 添加中断 Promise（用于动画等待）
+    clearInterruptions(): void;                        // 清除所有中断
+    produceAsync(fn: (draft: T) => void): Promise<void>;  // 等待中断后更新状态
+}
+```
+
+---
+
+### `mutableSignal<T>(initial?, options?)`
+
+创建可变信号。
+
+```typescript
+function mutableSignal<T>(initial?: T, options?: SignalOptions<T>): MutableSignal<T>
+```
+
+---
+
+## 游戏主机 (GameHost)
+
+### `GameHost<TState, TResult>`
+
+游戏会话的生命周期管理器。
+
+```typescript
+class GameHost<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>;            // 当前提示文本
+
+    tryInput(input: string): string | null;                    // 尝试提交输入，返回错误信息或 null
+    tryAnswerPrompt<TArgs>(def: PromptDef<TArgs>, ...args: TArgs): void;  // 尝试回答提示
+    addInterruption(promise: Promise<void>): void;             // 注册中断 Promise（用于动画）
+    clearInterruptions(): void;                                // 清除所有中断
+    start(seed?: number): Promise<TResult>;                    // 启动游戏
+    dispose(): void;                                           // 销毁游戏
+    on(event: 'start' | 'dispose', listener: () => void): () => void;  // 注册事件监听
+}
+```
+
+---
+
+### `GameHostStatus`
+
+```typescript
+type GameHostStatus = 'created' | 'running' | 'disposed';
+```
+
+---
+
+### `createGameHost<TState>(gameModule)`
+
+从游戏模块创建 `GameHost` 实例。
+
+```typescript
+function createGameHost<TState extends Record<string, unknown>>(
+    gameModule: GameModule<TState>
+): GameHost<TState>
+```
+
+**使用示例：**
+
+```typescript
+import { createGameHost } from '@/index';
+import { gameModule } from './my-game';
+
+const host = createGameHost(gameModule);
+
+// 启动游戏
+const result = await host.start(42);  // 传入种子
+
+// 提交玩家输入
+const error = host.tryInput('play X 0 0');
+if (error) {
+    console.error('输入错误:', error);
+}
+
+// 监听事件
+host.on('start', () => console.log('游戏开始'));
+host.on('dispose', () => console.log('游戏结束'));
+
+// 销毁游戏
+host.dispose();
+```
+
+---
+
+## Preact Signals 重新导出
+
+```typescript
+export * from '@preact/signals-core';
+```
+
+开发者可直接使用 `@preact/signals-core` 的所有导出，包括：
+- `Signal<T>` - 基础信号类
+- `ReadonlySignal<T>` - 只读信号类型
+- `signal<T>(value)` - 创建信号
+- `computed<T>(fn)` - 创建计算信号
+- `effect(fn)` - 创建副作用
+- `batch(fn)` - 批量更新
+- `untracked(fn)` - 非追踪读取
+
+---
+
+## 测试辅助函数
+
+以下函数主要用于测试代码：
+
+### `createGameContext(options)`
+
+创建游戏上下文实例。
+
+```typescript
+function createGameContext<TState>(options: {
+    initialState: TState;
+    registry?: CommandRegistry<IGameContext<TState>>;
+    rng?: RNG;
+}): IGameContext<TState>
+```
+
+**使用示例：**
+
+```typescript
+import { createGameContext } from '@/core/game';
+import { createInitialState, registry } from './my-game';
+
+const ctx = createGameContext({
+    initialState: createInitialState(),
+    registry,
+});
+
+// 执行命令
+await ctx.run('move piece1 piece2');
+
+// 断言状态
+expect(ctx.value.score).toBe(10);
+```
+
+---
+
+### `createTestContext()`
+
+创建用于测试的游戏上下文（简化版）。
+
+```typescript
+function createTestContext<TState>(initialState: TState): IGameContext<TState>
+```
+
+---
+
+### `createTestRegion()`
+
+创建用于测试的区域。
+
+```typescript
+function createTestRegion(): Region
+```

src/core/part-factory.ts

@@ -7,12 +7,7 @@ export function createPartsFromTable<T>(items: readonly T[], getId: (item: T, in
     const count = getCount ? (typeof getCount === 'function' ? getCount(entry) : getCount) : 1;
     for (let i = 0; i < count; i++) {
       const id = getId(entry, i);
-      pool[id] = {
+      pool[id] = createPart(id, entry);
-        id,
-        regionId: '',
-        position: [],
-        ...entry as Immutable<T>
-      };
     }
   }
   return pool;
@@ -21,3 +16,12 @@ export function createPartsFromTable<T>(items: readonly T[], getId: (item: T, in
 export function createParts<T>(item: T, getId: (index: number) => string, count?: number){
   return createPartsFromTable([item], (_,index) => getId(index), count);
 }
+
+export function createPart<T>(id: string, entry: T): Part<T> {
+ return {
+     id,
+     regionId: '',
+     position: [],
+     ...entry as Immutable<T>
+ }   
+}

src/samples/boop/parts.csv.d.ts

@@ -0,0 +1,8 @@
+type PartsTable = readonly {
+    readonly type: string;
+    readonly player: string;
+    readonly count: number;
+}[];
+
+declare const data: PartsTable;
+export default data;

src/samples/regicide/commands/index.ts

@@ -0,0 +1,421 @@
+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";
+
+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];
+
+        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} 的手牌中`};
+        }
+
+        // 检查是否有当前敌人
+        if (!state.currentEnemy) {
+            return {success: false, error: '没有活跃的敌人'};
+        }
+
+        // 计算伤害（基础伤害为卡牌面值）
+        let damage = card.value;
+        let attackReduction = 0;
+
+        // 梅花双倍伤害
+        if (card.suit === 'clubs') {
+            damage *= 2;
+        }
+
+        // 黑桃降低敌人攻击力
+        if (card.suit === 'spades') {
+            attackReduction = card.value;
+        }
+
+        const enemyHpBefore = state.currentEnemy.hp;
+
+        await game.produce(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
+            }
+        };
+    }
+});
+
+/**
+ * 打出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];
+
+        if (!aceCard || !otherCard) {
+            return {success: false, error: '卡牌不存在'};
+        }
+
+        // 检查是否是A牌
+        if (aceCard.rank !== 'A') {
+            return {success: false, error: `第一张牌必须是A`};
+        }
+
+        const playerKey = player as PlayerType;
+        const playerHand = state.playerHands[playerKey];
+
+        // 检查两张牌都在手牌中
+        if (!playerHand.includes(aceCardId) || !playerHand.includes(otherCardId)) {
+            return {success: false, error: '卡牌不在手牌中'};
+        }
+
+        if (!state.currentEnemy) {
+            return {success: false, error: '没有活跃的敌人'};
+        }
+
+        // 计算两张牌的总伤害
+        let totalDamage = aceCard.value + otherCard.value;
+
+        // 如果另一张牌是梅花，双倍伤害
+        if (otherCard.suit === 'clubs') {
+            totalDamage *= 2;
+        }
+
+        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;
+
+            // 记录黑桃的攻击力降低
+            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} 让过`}};
+    }
+});
+
+/**
+ * 敌人反击 - 玩家必须弃掉点数和 >= 敌人攻击力的牌
+ */
+const enemyCounterattackCmd = registry.register({
+    schema: 'counterattack <player:string> <discardCards:string[]>',
+    run: async (game: RegicideGame, player: string, discardCards: string[]) => {
+        const state = game.value;
+
+        if (!state.currentEnemy) {
+            return {success: false, error: '没有活跃的敌人'};
+        }
+
+        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
+            }
+        };
+    }
+});
+
+/**
+ * 检查敌人是否被击败，如果击败则翻开下一个敌人
+ */
+const checkEnemyDefeatedCmd = registry.register({
+    schema: 'check-enemy',
+    run: async (game: RegicideGame) => {
+        const state = game.value;
+
+        if (!state.currentEnemy) {
+            return {success: false, error: '没有活跃的敌人'};
+        }
+
+        const defeated = state.currentEnemy.hp <= 0;
+
+        if (defeated) {
+            const defeatedEnemy = {...state.currentEnemy};
+
+            await game.produce(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 (!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
+            }
+        };
+    }
+});
+
+/**
+ * 检查玩家是否有可出的牌
+ */
+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];
+
+        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
+            }
+        };
+    }
+});
+
+/**
+ * 检查酒馆牌堆是否为空
+ */
+const checkTavernDeckCmd = registry.register({
+    schema: 'check-tavern-deck',
+    run: async (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
+            }
+        };
+    }
+});
+
+/**
+ * 下一个玩家回合
+ */
+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;
+        });
+
+        const players: PlayerType[] = ['player1', 'player2', 'player3', 'player4'];
+        const currentPlayer = players[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,
+};

src/samples/regicide/constants.ts

@@ -0,0 +1,36 @@
+import {CardRank, SuitType} from "@/samples/regicide/types";
+
+// 敌人总数
+export const ENEMY_COUNT = 12;
+
+// 初始手牌数
+export const INITIAL_HAND_SIZE = 6;
+
+// 卡牌面值映射
+export const CARD_VALUES: Record<CardRank, number> = {
+    'A': 1,
+    '2': 2,
+    '3': 3,
+    '4': 4,
+    '5': 5,
+    '6': 6,
+    '7': 7,
+    '8': 8,
+    '9': 9,
+    '10': 10,
+    'J': 10,
+    'Q': 15,
+    'K': 20,
+};
+
+// 所有花色
+export const ALL_SUITS: SuitType[] = ['spades', 'hearts', 'diamonds', 'clubs'];
+
+// 所有牌面值（不含大小王）
+export const ALL_RANKS: CardRank[] = ['A', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'J', 'Q', 'K'];
+
+// 人头牌（J/Q/K）
+export const FACE_CARDS: CardRank[] = ['J', 'Q', 'K'];
+
+// 数字牌（A-10）
+export const NUMBER_CARDS: CardRank[] = ['A', '2', '3', '4', '5', '6', '7', '8', '9', '10'];

src/samples/regicide/game.ts

@@ -0,0 +1,239 @@
+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";
+
+export type RegicideGame = IGameContext<RegicideState>;
+
+/**
+ * 初始化游戏设置
+ * @param game 游戏上下文
+ * @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 人');
+    }
+
+    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);
+        }
+
+        // 设置敌人牌堆区域（只存储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;
+        }
+    });
+}
+
+/**
+ * 启动游戏主循环
+ */
+export async function start(game: RegicideGame) {
+    const state = game.value;
+
+    // 检查游戏是否已设置
+    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;
+        }
+
+        // 等待玩家输入（出牌或让过）
+        // 这里需要外部通过 prompt 系统获取输入
+        // 实际使用时由 UI 或测试代码提供输入
+
+        // 循环会在外部调用 play/pass 命令后继续
+        // 当 phase 变为 'victory' 或 'defeat' 时退出
+        break;
+    }
+
+    return 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.currentEnemy) {
+        return {success: false, error: '没有活跃的敌人'};
+    }
+
+    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}`);
+        }
+    } else {
+        // 让过
+        playResult = await game.run(`pass ${player}`);
+    }
+
+    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');
+
+    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');
+
+    return result;
+}
+
+/**
+ * 获取当前游戏状态摘要
+ */
+export function getGameStatus(game: RegicideGame) {
+    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
+    };
+}

src/samples/regicide/index.ts

@@ -0,0 +1,67 @@
+// Types
+export type {
+    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';
+
+// State
+export {
+    createInitialState,
+    type RegicideState
+} from './state';
+
+// 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';
+
+// Game
+export {
+    setupGame,
+    start,
+    playTurn,
+    handleCounterattack,
+    getGameStatus,
+    type RegicideGame
+} from './game';
+
+// Utils
+export {
+    getCardValue,
+    createCard,
+    createEnemy,
+    createAllCards,
+    buildEnemyDeck,
+    buildTavernDeck,
+    drawFromDeck,
+    isEnemyDefeated,
+    getPlayerHandRegionId
+} from './utils';

src/samples/regicide/prompts.ts

@@ -0,0 +1,20 @@
+import {createPromptDef} from "@/core/game";
+
+export const prompts = {
+    playCard: createPromptDef<[string, string]>(
+        'play <player:string> <cardId:string>',
+        '选择要打出的卡牌'
+    ),
+    playWithA: createPromptDef<[string, string, string]>(
+        'play-with-a <player:string> <aceCardId:string> <otherCardId:string>',
+        '打出A配合另一张牌'
+    ),
+    pass: createPromptDef<[string]>(
+        'pass <player:string>',
+        '让过不出牌'
+    ),
+    discard: createPromptDef<[string, string[]]>(
+        'counterattack <player:string> <discardCards:string[]>',
+        '选择要弃掉的卡牌以应对敌人反击'
+    ),
+};

src/samples/regicide/rules.md

@@ -0,0 +1,78 @@
+# Regicide (弑君游戏)
+
+## 游戏概述
+
+**Regicide** 是一个合作式奇幻主题卡牌游戏，使用标准扑克牌进行游戏。
+
+- **玩家人数：** 1-4 人（合作）
+- **年龄：** 10+
+- **游戏时间：** 约30分钟
+
+## 游戏目标
+
+玩家们协作对抗，使用手牌击败12个强大的敌人（每个等级3个敌人）。如果成功击败所有12个敌人则获胜；如果任何敌人的生命值归零前未能击败它，或者牌库耗尽时仍有敌人存活，则游戏失败。
+
+## 游戏配件
+
+- **标准扑克牌：** 52张（不包含大小王）
+
+## 卡牌说明
+
+### 数字牌（A-10）
+- 面值等于牌面数字
+- 每张牌有独特的花色能力
+
+### 人头牌（J、Q、K）
+- **J（侍卫）：** 面值 10
+- **Q（皇后）：** 面值 15
+- **K（国王）：** 面值 20
+
+### 花色能力
+- **黑桃（Spades）：** 降低敌人的攻击力
+- **红心（Hearts）：** 将弃牌堆的牌洗回酒馆牌堆
+- **方块（Diamonds）：** 从酒馆牌堆抓牌
+- **梅花（Clubs）：** 造成双倍伤害
+
+## 游戏设置
+
+0. 将所有的J/Q/K从牌堆移出，将4张K洗混后放在最下，4张Q洗混后放在中间，4张J洗混后放在最上形成敌人牌堆
+1. 将剩余的扑克牌洗匀形成酒馆牌堆，每位玩家抽取 6 张手牌
+2. 翻开一张敌人牌
+3. 决定起始玩家（单人模式下自动为当前玩家）
+
+## 游戏流程
+
+从起始玩家开始，轮流进行以下操作：
+
+### 玩家回合
+在你的回合，你可以：
+1. **打出一张牌：** 选择一张手牌打出，对其目标敌人造成伤害或触发效果
+2. **打出一张A和另一张牌：** A可以配合任何其他牌一起打出
+3. **让过（Pass）：** 不出牌，结束回合
+
+### 出牌流程
+1. 打出的牌对当前敌人造成伤害
+2. 触发牌的花色能力
+3. 如果敌人的生命值降至0或以下，该敌人被击败，放置到弃牌堆
+4. 如果当前敌人被击败，翻开下一张敌人牌，否则受到敌人反击，必须弃掉点数和大于等于敌人攻击力的手牌
+
+即使玩家让过，也会受到敌人的反击。
+
+### 限制
+- 玩家之间不能交流或暗示关于手牌的信息
+- 每个回合只能打出一张牌（除了A配合其他牌的情况）
+
+## 敌人机制
+
+### 敌人属性
+- **生命值：** 敌人需要承受的伤害量，为卡牌面值的两倍
+- **攻击力：** 敌人的面值即敌人的攻击力
+
+## 胜利与失败条件
+
+### 胜利条件
+- 击败所有12个敌人
+
+### 失败条件
+- 任何玩家在敌人反击后无法弃掉点数和达到敌人攻击力以上的牌
+- 任何玩家无法出牌

src/samples/regicide/state.ts

@@ -0,0 +1,38 @@
+import {createRegion, Region} from "@/core/region";
+import {Enemy, GamePhase, PlayerType, RegionType} from "@/samples/regicide/types";
+import {RegicideCard} from "@/samples/regicide/types";
+import {INITIAL_HAND_SIZE} from "@/samples/regicide/constants";
+
+export function createInitialState() {
+    const regions: Record<RegionType, Region> = {
+        enemyDeck: createRegion('enemyDeck', []),
+        tavernDeck: createRegion('tavernDeck', []),
+        discardPile: createRegion('discardPile', []),
+        currentEnemy: createRegion('currentEnemy', []),
+        hand_player1: createRegion('hand_player1', []),
+        hand_player2: createRegion('hand_player2', []),
+        hand_player3: createRegion('hand_player3', []),
+        hand_player4: createRegion('hand_player4', []),
+    };
+
+    const playerHands: Record<PlayerType, string[]> = {
+        player1: [],
+        player2: [],
+        player3: [],
+        player4: [],
+    };
+
+    return {
+        regions,
+        cards: {} as Record<string, RegicideCard>,
+        playerHands,
+        currentPlayerIndex: 0,
+        playerCount: 1,
+        currentEnemy: null as Enemy | null,
+        enemyDeck: [] as Enemy[],
+        phase: 'playing' as GamePhase,
+        winner: null as boolean | null,
+    };
+}
+
+export type RegicideState = ReturnType<typeof createInitialState>;

src/samples/regicide/types.ts

@@ -0,0 +1,44 @@
+import {Part} from "@/core/part";
+
+// 花色类型
+export type SuitType = 'spades' | 'hearts' | 'diamonds' | 'clubs';
+
+// 牌面值
+export type CardRank = 'A' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | 'J' | 'Q' | 'K';
+
+// 玩家类型（1-4人合作）
+export type PlayerType = 'player1' | 'player2' | 'player3' | 'player4';
+
+// 区域类型
+export type RegionType =
+    | 'enemyDeck'    // 敌人牌堆
+    | 'tavernDeck'   // 酒馆牌堆
+    | 'discardPile'  // 弃牌堆
+    | 'currentEnemy' // 当前敌人
+    | 'hand_player1'
+    | 'hand_player2'
+    | 'hand_player3'
+    | 'hand_player4';
+
+// 卡牌元数据
+export type RegicideCardMeta = {
+    suit: SuitType;
+    rank: CardRank;
+    value: number;  // 卡牌面值
+};
+
+// 卡牌部件类型
+export type RegicideCard = Part<RegicideCardMeta>;
+
+// 敌人类型
+export type Enemy = {
+    id: string;
+    rank: CardRank;
+    suit: SuitType;
+    value: number;      // 敌人面值（即攻击力）
+    hp: number;         // 当前生命值
+    maxHp: number;      // 最大生命值（面值的2倍）
+};
+
+// 游戏阶段
+export type GamePhase = 'playing' | 'victory' | 'defeat';

src/samples/regicide/utils.ts

@@ -0,0 +1,132 @@
+import {ALL_RANKS, ALL_SUITS, CARD_VALUES, ENEMY_COUNT, FACE_CARDS} from "@/samples/regicide/constants";
+import {CardRank, Enemy, RegicideCard, SuitType} from "@/samples/regicide/types";
+import {RNG} from "@/utils/rng";
+
+/**
+ * 获取卡牌面值
+ */
+export function getCardValue(rank: CardRank): number {
+    return CARD_VALUES[rank];
+}
+
+/**
+ * 创建卡牌部件
+ */
+export function createCard(id: string, suit: SuitType, rank: CardRank): RegicideCard {
+    return {
+        id,
+        regionId: '',
+        position: [],
+        suit,
+        rank,
+        value: getCardValue(rank),
+    };
+}
+
+/**
+ * 创建敌人
+ */
+export function createEnemy(id: string, rank: CardRank, suit: SuitType): Enemy {
+    const value = getCardValue(rank);
+    return {
+        id,
+        rank,
+        suit,
+        value,
+        hp: value * 2,
+        maxHp: value * 2,
+    };
+}
+
+/**
+ * 生成完整卡牌列表（52张，不含大小王）
+ */
+export function createAllCards(): Record<string, RegicideCard> {
+    const cards: Record<string, RegicideCard> = {};
+
+    for (const suit of ALL_SUITS) {
+        for (const rank of ALL_RANKS) {
+            const id = `${suit}_${rank}`;
+            cards[id] = createCard(id, suit, rank);
+        }
+    }
+
+    return cards;
+}
+
+/**
+ * 构建敌人牌堆（J/Q/K 共12张）
+ * 规则：4张K在最下，4张Q在中间，4张J在最上
+ */
+export function buildEnemyDeck(rng: RNG): Enemy[] {
+    const enemies: Enemy[] = [];
+    let idCounter = 0;
+
+    // 创建所有J/Q/K敌人
+    for (const rank of FACE_CARDS) {
+        for (const suit of ALL_SUITS) {
+            const id = `enemy_${idCounter++}`;
+            enemies.push(createEnemy(id, rank, suit));
+        }
+    }
+
+    // 分离J、Q、K
+    const jEnemies = enemies.filter(e => e.rank === 'J');
+    const qEnemies = enemies.filter(e => e.rank === 'Q');
+    const kEnemies = enemies.filter(e => e.rank === 'K');
+
+    // 分别洗牌
+    shuffleArray(jEnemies, rng);
+    shuffleArray(qEnemies, rng);
+    shuffleArray(kEnemies, rng);
+
+    // J在最上（先遇到），Q在中间，K在最下
+    return [...jEnemies, ...qEnemies, ...kEnemies];
+}
+
+/**
+ * 构建酒馆牌堆（移除J/Q/K后的剩余牌）
+ */
+export function buildTavernDeck(rng: RNG): RegicideCard[] {
+    const allCards = createAllCards();
+    const numberCards = Object.values(allCards).filter(card => !FACE_CARDS.includes(card.rank));
+
+    shuffleArray(numberCards, rng);
+
+    return numberCards;
+}
+
+/**
+ * 洗牌辅助函数
+ */
+function shuffleArray<T>(array: T[], rng: RNG): void {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = rng.nextInt(i + 1);
+        [array[i], array[j]] = [array[j], array[i]];
+    }
+}
+
+/**
+ * 从牌堆抽牌
+ */
+export function drawFromDeck(
+    deck: RegicideCard[],
+    count: number
+): RegicideCard[] {
+    const drawn = deck.splice(0, count);
+    return drawn;
+}
+
+/**
+ * 检查敌人是否被击败
+ */
+export function isEnemyDefeated(enemy: Enemy | null): boolean {
+    return enemy !== null && enemy.hp <= 0;
+}
+
+/**
+ * 获取当前玩家手牌区域ID
+ */
+export function getPlayerHandRegionId(playerId: string): string {
+    return `hand_${playerId}`;
+}

tests/samples/regicide.test.ts

@@ -0,0 +1,353 @@
+import {createGameContext} from '@/core/game';
+import {registry} from '@/samples/regicide/commands';
+import {createInitialState} from '@/samples/regicide/state';
+import {
+    buildEnemyDeck,
+    buildTavernDeck,
+    createAllCards,
+    createCard,
+    createEnemy,
+    getCardValue,
+    isEnemyDefeated
+} from '@/samples/regicide/utils';
+import {Mulberry32RNG} from '@/utils/rng';
+import {CARD_VALUES, ENEMY_COUNT, FACE_CARDS, INITIAL_HAND_SIZE} from '@/samples/regicide/constants';
+import {PlayerType} from '@/samples/regicide/types';
+
+describe('Regicide - Utils', () => {
+    describe('getCardValue', () => {
+        it('should return correct value for number cards', () => {
+            expect(getCardValue('A')).toBe(1);
+            expect(getCardValue('5')).toBe(5);
+            expect(getCardValue('10')).toBe(10);
+        });
+
+        it('should return correct value for face cards', () => {
+            expect(getCardValue('J')).toBe(10);
+            expect(getCardValue('Q')).toBe(15);
+            expect(getCardValue('K')).toBe(20);
+        });
+    });
+
+    describe('createCard', () => {
+        it('should create a card with correct properties', () => {
+            const card = createCard('spades_A', 'spades', 'A');
+            expect(card.id).toBe('spades_A');
+            expect(card.suit).toBe('spades');
+            expect(card.rank).toBe('A');
+            expect(card.value).toBe(1);
+        });
+    });
+
+    describe('createEnemy', () => {
+        it('should create an enemy with correct HP', () => {
+            const enemy = createEnemy('enemy_0', 'J', 'spades');
+            expect(enemy.rank).toBe('J');
+            expect(enemy.value).toBe(10);
+            expect(enemy.hp).toBe(20);
+            expect(enemy.maxHp).toBe(20);
+        });
+
+        it('should create enemy with different values for different ranks', () => {
+            const jEnemy = createEnemy('enemy_0', 'J', 'spades');
+            const qEnemy = createEnemy('enemy_1', 'Q', 'hearts');
+            const kEnemy = createEnemy('enemy_2', 'K', 'diamonds');
+
+            expect(jEnemy.value).toBe(10);
+            expect(qEnemy.value).toBe(15);
+            expect(kEnemy.value).toBe(20);
+
+            expect(jEnemy.hp).toBe(20);
+            expect(qEnemy.hp).toBe(30);
+            expect(kEnemy.hp).toBe(40);
+        });
+    });
+
+    describe('createAllCards', () => {
+        it('should create 52 cards', () => {
+            const cards = createAllCards();
+            expect(Object.keys(cards).length).toBe(52);
+        });
+
+        it('should have all suits and ranks', () => {
+            const cards = createAllCards();
+            const suits = ['spades', 'hearts', 'diamonds', 'clubs'];
+            const ranks = ['A', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'J', 'Q', 'K'];
+
+            for (const suit of suits) {
+                for (const rank of ranks) {
+                    const id = `${suit}_${rank}`;
+                    expect(cards[id]).toBeDefined();
+                    expect(cards[id].suit).toBe(suit);
+                    expect(cards[id].rank).toBe(rank);
+                }
+            }
+        });
+    });
+
+    describe('buildEnemyDeck', () => {
+        it('should create 12 enemies (J/Q/K)', () => {
+            const rng = new Mulberry32RNG(12345);
+            const deck = buildEnemyDeck(rng);
+            expect(deck.length).toBe(12);
+        });
+
+        it('should have J at top, Q in middle, K at bottom', () => {
+            const rng = new Mulberry32RNG(12345);
+            const deck = buildEnemyDeck(rng);
+
+            for (let i = 0; i < 4; i++) {
+                expect(deck[i].rank).toBe('J');
+            }
+
+            for (let i = 4; i < 8; i++) {
+                expect(deck[i].rank).toBe('Q');
+            }
+
+            for (let i = 8; i < 12; i++) {
+                expect(deck[i].rank).toBe('K');
+            }
+        });
+    });
+
+    describe('buildTavernDeck', () => {
+        it('should create 40 cards (A-10)', () => {
+            const rng = new Mulberry32RNG(12345);
+            const deck = buildTavernDeck(rng);
+            expect(deck.length).toBe(40);
+        });
+
+        it('should not contain face cards', () => {
+            const rng = new Mulberry32RNG(12345);
+            const deck = buildTavernDeck(rng);
+
+            for (const card of deck) {
+                expect(FACE_CARDS.includes(card.rank)).toBe(false);
+            }
+        });
+    });
+
+    describe('isEnemyDefeated', () => {
+        it('should return true when enemy HP <= 0', () => {
+            const enemy = createEnemy('enemy_0', 'J', 'spades');
+            expect(isEnemyDefeated(enemy)).toBe(false);
+
+            enemy.hp = 0;
+            expect(isEnemyDefeated(enemy)).toBe(true);
+
+            enemy.hp = -5;
+            expect(isEnemyDefeated(enemy)).toBe(true);
+        });
+
+        it('should return false for null enemy', () => {
+            expect(isEnemyDefeated(null)).toBe(false);
+        });
+    });
+});
+
+describe('Regicide - Commands', () => {
+    function createTestContext() {
+        const initialState = createInitialState();
+        return createGameContext(registry, initialState);
+    }
+
+    function setupTestGame(game: ReturnType<typeof createTestContext>) {
+        const cards = createAllCards();
+        const rng = new Mulberry32RNG(12345);
+        const enemyDeck = buildEnemyDeck(rng);
+        const tavernDeck = buildTavernDeck(rng);
+
+        game.produce(state => {
+            state.cards = cards;
+            state.playerCount = 2;
+            state.currentPlayerIndex = 0;
+            state.enemyDeck = [...enemyDeck];
+            state.currentEnemy = {...enemyDeck[0]};
+
+            for (const card of tavernDeck) {
+                state.regions.tavernDeck.childIds.push(card.id);
+            }
+
+            for (let i = 0; i < 6; i++) {
+                const card1 = tavernDeck[i];
+                const card2 = tavernDeck[i + 6];
+                card1.regionId = 'hand_player1';
+                card2.regionId = 'hand_player2';
+                state.playerHands.player1.push(card1.id);
+                state.playerHands.player2.push(card2.id);
+                state.regions.hand_player1.childIds.push(card1.id);
+                state.regions.hand_player2.childIds.push(card2.id);
+            }
+        });
+    }
+
+    describe('play command', () => {
+        it('should deal damage to current enemy', async () => {
+            const game = createTestContext();
+            setupTestGame(game);
+
+            const enemyHpBefore = game.value.currentEnemy!.hp;
+            const cardId = game.value.playerHands.player1[0];
+            const card = game.value.cards[cardId];
+
+            const result = await game.run(`play player1 ${cardId}`);
+
+            expect(game.value.currentEnemy!.hp).toBe(enemyHpBefore - card.value);
+        });
+
+        it('should double damage for clubs suit', async () => {
+            const game = createTestContext();
+            setupTestGame(game);
+
+            game.produce(state => {
+                state.cards['clubs_5'] = createCard('clubs_5', 'clubs', '5');
+                state.playerHands.player1.push('clubs_5');
+                state.regions.hand_player1.childIds.push('clubs_5');
+            });
+
+            const clubsCardId = 'clubs_5';
+            const enemyHpBefore = game.value.currentEnemy!.hp;
+            const card = game.value.cards[clubsCardId];
+
+            await game.run(`play player1 ${clubsCardId}`);
+
+            expect(game.value.currentEnemy!.hp).toBe(enemyHpBefore - card.value * 2);
+        });
+    });
+
+    describe('pass command', () => {
+        it('should allow player to pass', async () => {
+            const game = createTestContext();
+            setupTestGame(game);
+
+            const result = await game.run('pass player1');
+
+            expect(result.success).toBe(true);
+        });
+    });
+
+    describe('check-enemy command', () => {
+        it('should detect defeated enemy and reveal next', async () => {
+            const game = createTestContext();
+            setupTestGame(game);
+
+            const firstEnemy = game.value.currentEnemy!;
+            game.produce(state => {
+                state.currentEnemy!.hp = 0;
+            });
+
+            await game.run('check-enemy');
+
+            expect(game.value.regions.discardPile.childIds).toContain(firstEnemy.id);
+            expect(game.value.currentEnemy).not.toBe(firstEnemy);
+        });
+
+        it('should not defeat enemy if HP > 0', async () => {
+            const game = createTestContext();
+            setupTestGame(game);
+
+            const currentEnemyId = game.value.currentEnemy!.id;
+
+            await game.run('check-enemy');
+
+            expect(game.value.currentEnemy!.id).toBe(currentEnemyId);
+        });
+    });
+
+    describe('next-turn command', () => {
+        it('should switch to next player', async () => {
+            const game = createTestContext();
+            setupTestGame(game);
+
+            expect(game.value.currentPlayerIndex).toBe(0);
+
+            await game.run('next-turn');
+
+            expect(game.value.currentPlayerIndex).toBe(1);
+        });
+
+        it('should wrap around to first player', async () => {
+            const game = createTestContext();
+            setupTestGame(game);
+
+            game.produce(state => {
+                state.currentPlayerIndex = 1;
+            });
+
+            await game.run('next-turn');
+
+            expect(game.value.currentPlayerIndex).toBe(0);
+        });
+    });
+});
+
+describe('Regicide - Game Flow', () => {
+    function createTestContext() {
+        const initialState = createInitialState();
+        return createGameContext(registry, initialState);
+    }
+
+    it('should complete a full turn cycle', async () => {
+        const game = createTestContext();
+
+        const cards = createAllCards();
+        const rng = new Mulberry32RNG(12345);
+        const enemyDeck = buildEnemyDeck(rng);
+        const tavernDeck = buildTavernDeck(rng);
+
+        game.produce(state => {
+            state.cards = cards;
+            state.playerCount = 1;
+            state.currentPlayerIndex = 0;
+            state.enemyDeck = [...enemyDeck.slice(1)];
+            state.currentEnemy = {...enemyDeck[0]};
+
+            for (const card of tavernDeck) {
+                state.regions.tavernDeck.childIds.push(card.id);
+            }
+
+            for (let i = 0; i < 6; i++) {
+                const card = tavernDeck[i];
+                card.regionId = 'hand_player1';
+                state.playerHands.player1.push(card.id);
+                state.regions.hand_player1.childIds.push(card.id);
+            }
+        });
+
+        const cardId = game.value.playerHands.player1[0];
+        const card = game.value.cards[cardId];
+        const enemyHpBefore = game.value.currentEnemy!.hp;
+
+        await game.run(`play player1 ${cardId}`);
+
+        expect(game.value.currentEnemy!.hp).toBeLessThan(enemyHpBefore);
+    });
+
+    it('should win game when all enemies defeated', async () => {
+        const game = createTestContext();
+
+        const cards = createAllCards();
+        const rng = new Mulberry32RNG(12345);
+        const tavernDeck = buildTavernDeck(rng);
+
+        game.produce(state => {
+            state.cards = cards;
+            state.playerCount = 1;
+            state.currentPlayerIndex = 0;
+            state.enemyDeck = [];
+            state.currentEnemy = null;
+
+            for (const card of tavernDeck) {
+                state.regions.tavernDeck.childIds.push(card.id);
+            }
+        });
+
+        game.produce(state => {
+            state.phase = 'victory';
+            state.winner = true;
+        });
+
+        expect(game.value.phase).toBe('victory');
+        expect(game.value.winner).toBe(true);
+    });
+});