feat: ideas for slay-the-backpack

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

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

src/samples/slay-the-spire-like/items.csv

@@ -0,0 +1,4 @@
+class,name,role,description
+战士,长刀,武器,普通的平砍攻击牌，锋利的效果x2
+战士,磨刀石,buff,相邻物品获得【锋利2】（攻击伤害+2），
+战士,盾牌,防具,普通的叠盾防御牌

src/samples/slay-the-spire-like/slay-the-backpack.md

@@ -0,0 +1,46 @@
+# slay the spire + backpack heroes
+
+玩家有4x6的背包
+
+装备占格子，提供同等数量的牌，并且给周围加buff，背包英雄style
+
+战斗时玩杀戮尖塔
+
+## Roguelike structure
+
+Zone based Point Crawl:
+- 分4个区域，每个区域有独立的随机遭遇池
+- 遭遇分为随机遭遇、战斗、服务
+  - 随机遭遇使用d6三阶段结构，共18遭遇
+  - 战斗遭遇分简单和困难，困难可以绕
+  - 服务遭遇分商店（恢复/卖装备/附魔）篝火（恢复/补充药水/下次战斗buff）npc（恢复/任务（任务=完成特定地点遭遇获得奖励））
+- 每区域12遭遇
+  - 战斗：非战斗=8：4
+  - 5小怪，2精英，1boss，1店1篝1npc1随机
+
+## 战斗
+
+典中典5手牌3费，每个格子1张牌，同一装备牌逻辑相同，但根据邻接吃到的牌buff不同
+
+3种牌（攻击/防御/穿透）攻击克穿透克防御克攻击
+
+受伤时伤口先占格子再扣血，牌少的角色受掉血影响大但血更厚
+
+没有能力牌/启动时间逻辑，所有背包物品开局生效
+
+部分物品带使用次数限制，药瓶喝完可以在篝火补
+
+## Buff / Debuff
+
+玩家buff主要按照“有默认功能的货币”考虑
+
+debuff暂时只考虑“条件回合覆盖”类debuff，有时可以当货币用
+
+敌人buff和debuff与玩家对称设计
+
+## 设计量
+
+~15 物品 每角色每池
+-10 小怪 5 精英 3 boss 每区域
+-8 遗物 每角色
+