5.1 KiB
5.1 KiB
API 参考
核心
| 导出 | 说明 |
|---|---|
IGameContext |
游戏上下文基础接口 |
createGameContext(registry, initialState?) |
创建游戏上下文实例 |
createGameContextFromModule(module) |
从 GameModule 创建游戏上下文 |
createGameCommandRegistry<TState>() |
创建命令注册表 |
createGameModule(module) |
辅助函数，标记 GameModule |
GameHost<TState> |
游戏生命周期管理类 |
createGameHost(module, options?) |
从 GameModule 创建 GameHost |
GameHostStatus |
类型: 'created' | 'running' | 'disposed' |
GameModule |
游戏模块类型 |
棋子 (Parts)
| 导出 | 说明 |
|---|---|
Part<TMeta> |
游戏棋子类型 |
PartTemplate<TMeta> |
创建棋子的模板类型 |
PartPool<TMeta> |
棋子池类型 |
createPart(template, id) |
创建单个棋子 |
createParts(template, count, idPrefix) |
批量创建相同棋子 |
createPartsFromTable(items, getId, getCount?) |
从表格数据创建棋子 |
createPartPool(template, count, idPrefix) |
创建棋子池 |
mergePartPools(...pools) |
合并多个棋子池 |
findPartById(parts, id) |
按 ID 查找棋子 |
isCellOccupied(parts, regionId, position) |
检查格子是否被占用 |
getPartAtPosition(parts, regionId, position) |
获取格子上的棋子 |
isCellOccupiedByRegion(region, position) |
O(1) 检查格子占用 |
getPartAtPositionInRegion(region, parts, position) |
O(1) 获取棋子 |
flip(part) / flipTo(part, side) / roll(part, rng) |
翻面/随机面 |
区域 (Regions)
| 导出 | 说明 |
|---|---|
Region / RegionAxis |
区域类型 |
createRegion(id, axes) |
创建区域 |
applyAlign(region, parts) |
紧凑排列 |
shuffle(region, parts, rng) |
打乱位置 |
moveToRegion(part, sourceRegion?, targetRegion, position?) |
移动棋子到区域 |
命令 (Commands)
| 导出 | 说明 |
|---|---|
Command / CommandSchema / CommandResult |
命令相关类型 |
CommandParamSchema / CommandOptionSchema / CommandFlagSchema |
命令参数类型 |
parseCommand(input) |
解析命令字符串 |
parseCommandSchema(schema) |
解析 Schema 字符串 |
validateCommand(cmd, schema) |
验证命令 |
parseCommandWithSchema(input, schema) |
解析并应用 Schema |
applyCommandSchema(cmd, schema) |
应用 Schema 到命令 |
命令运行器
| 导出 | 说明 |
|---|---|
CommandRunner<TContext, TResult> |
命令运行器类型 |
CommandRunnerHandler<TContext, TResult> |
命令处理器类型 |
CommandRunnerContext<TContext> |
命令运行器上下文类型 |
CommandRunnerContextExport<TContext> |
导出的命令运行器上下文（含内部方法） |
CommandRegistry<TContext> |
命令注册表类型 |
PromptEvent / CommandRunnerEvents |
提示事件类型 |
PromptValidator<T> |
提示验证器类型 |
createCommandRegistry() |
创建命令注册表 |
registerCommand(registry, runner) |
注册命令运行器 |
unregisterCommand(registry, name) |
注销命令 |
hasCommand(registry, name) |
检查命令是否存在 |
getCommand(registry, name) |
获取命令 |
runCommand(registry, context, input) |
运行命令 |
runCommandParsed(registry, context, command) |
运行已解析命令 |
createCommandRunnerContext(registry, context) |
创建命令运行器上下文 |
Game Command Registry
游戏专用命令注册表（通过 createGameCommandRegistry 创建，类型为 CommandRegistry<IGameContext<TState>>）：
| 方法 | 说明 |
|---|---|
registry.register(schema, handler) |
注册命令并返回可调用命令对象 |
registry.register 接受命令 Schema（字符串或 CommandSchema 对象）和处理器函数，返回一个可调用函数。处理器函数签名为 (ctx, ...args) => Promise<TResult>。
在 GameModule 中使用 game.prompt() 等待玩家输入，验证函数中 throw 字符串会触发重新提示，返回非 null 值表示验证通过。子命令可以通过 await subCommand(game, ...args) 方式调用。
MutableSignal
| 导出 | 说明 |
|---|---|
MutableSignal<T> |
支持突变和动画中断的响应式信号 |
mutableSignal(initial?, options?) |
创建 MutableSignal |
EntityCollection<T> / createEntityCollection() |
实体集合辅助函数 |
MutableSignal 成员
| 成员 | 说明 |
|---|---|
value: T |
获取当前值 |
produce(fn: (draft: T) => void): void |
同步不可变更新 |
addInterruption(promise: Promise<void>): void |
添加中断 |
clearInterruptions(): void |
清除所有中断 |
produceAsync(fn: (draft: T) => void): Promise<void> |
等待中断完成后更新 |
GameHost 中断代理
GameHost 直接代理 addInterruption 和 clearInterruptions，供 UI 层使用。
IGameContext 提供 produce()、produceAsync() 和 addInterruption() 方法。
详见 动画与状态更新同步。
工具
| 导出 | 说明 |
|---|---|
RNG |
随机数生成器接口 |
createRNG(seed?) |
创建种子 RNG |
Mulberry32RNG |
Mulberry32 算法实现 |