@@ -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 s chema 语法：
- `<param>` - 必需参数
- `[param]` - 可选参数
- `[param:type]` - 带类型验证的参数（如 `[count:number]` ）
S chema 语法：`<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 ) - 项目代码规范
hyper