121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
# 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()` 方法。
|
||
详见 [动画与状态更新同步](./animation-sync.md)。
|
||
|
||
## 工具
|
||
|
||
| 导出 | 说明 |
|
||
|---|---|
|
||
| `RNG` | 随机数生成器接口 |
|
||
| `createRNG(seed?)` | 创建种子 RNG |
|
||
| `Mulberry32RNG` | Mulberry32 算法实现 |
|