diff --git a/.qwen/skills/create-game-module/SKILL.md b/.qwen/skills/create-game-module/SKILL.md index 2940856..905607b 100644 --- a/.qwen/skills/create-game-module/SKILL.md +++ b/.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; -// 创建 mutative 游戏初始状态 -export function createInitialState(): GameState { - //... -} - -// 创建命令注册表(可选) -export const registry = createGameCommandRegistry(); - -// 运行游戏 -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 = { - registry, - createInitialState, - start, -}; +export const gameModule: GameModule = { registry, createInitialState, start }; ``` ## 流程 ### 0. 确认规则 -规则应当存放在 `rule.md`。 +在 `rule.md` 中描述:主题、配件、布置形式、游戏流程、玩家行动、胜利条件。 -描述一个桌面游戏的以下要素: -- **主题**:游戏的世界观和背景 -- **配件**:棋子、卡牌、骰子等物理组件 -- **游戏布置形式**:棋盘、版图、卡牌放置区等 -- **游戏流程**:回合结构、阶段划分 -- **玩家行动**:每回合玩家可以做什么 -- **胜利条件与终局结算**:如何判定胜负 +### 1. 创建类型 (`types.ts`) -### 1. 创建类型 - -创建 `types.ts` 并导出游戏所用的类型。 - -- 为游戏概念创建字符串枚举类型(如 `PlayerType = 'X' | 'O'`) -- 使用 `Part` 为游戏配件创建对象类型 -- 使用 `Region` 为游戏区域创建容器类型 -- 设计游戏的全局状态类型 - -游戏使用 `mutative` 不可变类型驱动。状态类型必须是**可序列化的**(不支持函数、`Map`、`Set` 等)。 +- 使用字符串枚举表示游戏概念(如 `PlayerType = 'X' | 'O'`) +- 使用 `Part` 表示配件(棋子、卡牌等) +- 使用 `Region` 表示区域(棋盘、牌堆等) +- 状态必须可序列化(不支持函数、`Map`、`Set`) ```typescript import { Part, Region } from '@/index'; -export type PlayerType = 'X' | 'O'; - -export type PieceMeta = { - owner: PlayerType; -}; - -export type Piece = Part; - +export type Piece = Part<{ owner: 'X' | 'O' }>; export type GameState = { board: Region; pieces: Record; - 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; +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 ', '选择下子位置' ), }; ``` -Prompt schema 语法: -- `` - 必需参数 -- `[param]` - 可选参数 -- `[param:type]` - 带类型验证的参数(如 `[count:number]`) +Schema 语法:`` 必需,`[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/` 目录下,命名格式为 `.test.ts`。 +位于 `tests/samples/.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) - 项目代码规范