boardgame-core/docs/api-reference.md

API 参考

核心

导出	说明
GameHost<TState>	游戏生命周期管理类
createGameHost(module)	从 GameModule 创建 GameHost
GameHostStatus	类型: 'created' | 'running' | 'disposed'
GameModule	游戏模块类型，包含 registry 和 createInitialState
createGameModule(module)	辅助函数，标记 GameModule
createGameCommandRegistry<TState>()	创建游戏命令注册表

GameHost

成员	说明
context: IGameContext<TState>	游戏上下文，含状态和命令运行能力
status: Signal<GameHostStatus>	当前状态
activePromptSchema: Signal<CommandSchema | null>	当前等待的 prompt schema
activePromptPlayer: Signal<string | null>	当前等待的玩家
setup(setupCommand: string)	启动游戏，运行 setup 命令
onInput(input: string)	提交玩家输入到当前 prompt
addInterruption(promise) / clearInterruptions()	动画中断控制
on(event, listener)	监听 setup / dispose 事件
dispose()	销毁游戏实例

IGameContext

成员	说明
value: TState	当前游戏状态
produce(fn)	同步更新状态
produceAsync(fn)	等待动画中断后更新状态
run(input) / runParsed(command)	运行命令
prompt(schema, validator, currentPlayer?)	等待玩家输入
addInterruption(promise)	注册动画中断

棋子与区域

Part

导出	说明
Part<TMeta>	棋子类型，含 id、regionId、position、side 等
PartTemplate<TMeta> / PartPool<TMeta>	棋子模板和棋子池类型
createPart(template, id)	创建单个棋子
createParts(template, count, idPrefix)	批量创建棋子
createPartPool(template, count, idPrefix)	创建棋子池，支持 draw() / return() / remaining()
mergePartPools(...pools)	合并棋子池
createPartsFromTable(items, getId, getCount?)	从表格数据创建棋子
findPartById(parts, id)	按 ID 查找
getPartAtPosition(parts, regionId, position)	获取位置上的棋子
isCellOccupied(parts, regionId, position)	检查格子占用
flip(part) / flipTo(part, side) / roll(part, rng)	翻面/掷骰

Region

导出	说明
Region / RegionAxis	区域类型
createRegion(id, axes)	创建区域
applyAlign(region, parts)	按 axis 配置紧凑排列棋子
shuffle(region, parts, rng)	打乱区域内棋子位置
moveToRegion(part, source?, target, position?)	移动棋子到区域
isCellOccupiedByRegion(region, position)	O(1) 检查格子占用（使用 region.partMap）
getPartAtPositionInRegion(region, parts, position)	O(1) 获取棋子（使用 region.partMap）

命令系统

基础类型

导出	说明
Command	解析后的命令对象，含 name、params、options、flags
CommandSchema	命令 schema 定义
CommandResult<T>	命令执行结果: `{ success: true, result: T }

注册与运行

导出	说明
CommandRegistry<TContext>	命令注册表，继承自 Map<string, CommandRunner>，含 register(schema, handler) 快捷方法
CommandRunner<TContext, TResult>	命令运行器，含 schema 和 run
CommandRunnerContext<TContext>	命令运行器上下文，提供 run、prompt、on、off
PromptEvent	prompt 事件，含 schema、currentPlayer、tryCommit、cancel
PromptValidator<T>	prompt 验证器: (command) => T，throw 字符串表示验证失败
createCommandRegistry()	创建命令注册表
registerCommand(registry, runner)	注册命令
unregisterCommand(registry, name) / hasCommand(registry, name) / getCommand(registry, name)	命令管理
runCommand(registry, context, input)	解析并运行命令

命令解析

导出	说明
parseCommand(input)	解析命令字符串为 Command 对象
parseCommandSchema(schemaStr)	解析 schema 字符串为 CommandSchema
validateCommand(command, schema)	验证命令是否符合 schema
parseCommandWithSchema(input, schemaStr)	解析并验证命令
applyCommandSchema(command, schema)	应用 schema 到命令，含类型转换

Game Command Registry

通过 createGameCommandRegistry() 创建的注册表有快捷 register 方法：

const moveCmd = registry.register('move <from> <to>', async (ctx, from, to) => {
    ctx.produce(state => { /* ... */ });
});

// 作为子命令调用
await moveCmd(ctx, 'A1', 'A2');

处理器签名: (ctx, ...args) => Promise<TResult>。 game.prompt() 等待玩家输入，验证器 throw 字符串触发重新提示，返回非 null 值表示通过。

MutableSignal

导出	说明
MutableSignal<T>	支持突变和动画中断的响应式信号，继承 Preact Signal
mutableSignal(initial?, options?)	创建 MutableSignal
EntityCollection<T> / createEntityCollection()	实体集合辅助函数，管理 MutableSignal 字典

成员	说明
value: T	获取/设置当前值
produce(fn)	同步不可变更新（使用 mutative）
produceAsync(fn)	等待所有 interruption 完成后更新状态
addInterruption(promise)	注册中断，下一个 produceAsync 会等待
clearInterruptions()	清除所有未完成的中断

详见 动画与状态更新同步。

工具

导出	说明
RNG	随机数生成器接口: setSeed、getSeed、next、nextInt
createRNG(seed?) / Mulberry32RNG	Mulberry32 算法 PRNG