2026-04-04 13:20:34 +08:00
|
|
|
|
# API 参考
|
|
|
|
|
|
|
|
|
|
|
|
## 核心
|
|
|
|
|
|
|
|
|
|
|
|
| 导出 | 说明 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `IGameContext` | 游戏上下文基础接口 |
|
|
|
|
|
|
| `createGameContext(registry, initialState?)` | 创建游戏上下文实例 |
|
|
|
|
|
|
| `createGameCommandRegistry<TState>()` | 创建命令注册表，返回带 `.add()` 的对象 |
|
|
|
|
|
|
| `createGameModule(module)` | 辅助函数，标记一个对象为 GameModule |
|
|
|
|
|
|
| `GameHost<TState>` | 游戏生命周期管理类 |
|
|
|
|
|
|
| `createGameHost(module, options?)` | 从 GameModule 创建 GameHost |
|
|
|
|
|
|
| `GameHostStatus` | 类型: `'created' \| 'running' \| 'disposed'` |
|
|
|
|
|
|
|
|
|
|
|
|
## 棋子 (Parts)
|
|
|
|
|
|
|
|
|
|
|
|
| 导出 | 说明 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `Part<TMeta>` | 游戏棋子类型 |
|
|
|
|
|
|
| `PartTemplate<TMeta>` | 创建棋子的模板类型 |
|
|
|
|
|
|
| `PartPool<TMeta>` | 棋子池 |
|
|
|
|
|
|
| `createPart(template, id)` | 创建单个棋子 |
|
|
|
|
|
|
| `createParts(template, count, idPrefix)` | 批量创建相同棋子 |
|
|
|
|
|
|
| `createPartPool(template, count, idPrefix)` | 创建棋子池 |
|
|
|
|
|
|
| `mergePartPools(...pools)` | 合并多个棋子池 |
|
|
|
|
|
|
| `findPartById(parts, id)` | 按 ID 查找棋子 |
|
|
|
|
|
|
| `isCellOccupied(parts, regionId, position)` | 检查格子是否被占用 |
|
|
|
|
|
|
| `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?)` | 移动棋子到其他区域 |
|
|
|
|
|
|
| `moveToRegionAll(parts, sourceRegion?, targetRegion, positions?)` | 批量移动 |
|
|
|
|
|
|
| `removeFromRegion(part, region)` | 从区域移除棋子 |
|
|
|
|
|
|
|
|
|
|
|
|
## 命令 (Commands)
|
|
|
|
|
|
|
|
|
|
|
|
| 导出 | 说明 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `parseCommand(input)` | 解析命令字符串 |
|
|
|
|
|
|
| `parseCommandSchema(schema)` | 解析 Schema 字符串 |
|
|
|
|
|
|
| `validateCommand(cmd, schema)` | 验证命令 |
|
|
|
|
|
|
| `Command` / `CommandSchema` / `CommandResult` | 命令相关类型 |
|
|
|
|
|
|
| `PromptEvent` | 玩家输入提示事件 |
|
|
|
|
|
|
| `createRNG(seed?)` | 创建种子 RNG |
|
2026-04-04 15:27:37 +08:00
|
|
|
|
|
|
|
|
|
|
## MutableSignal
|
|
|
|
|
|
|
|
|
|
|
|
| 导出 | 说明 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `MutableSignal<T>` | 支持突变和动画中断的响应式信号 |
|
|
|
|
|
|
| `mutableSignal(initial?, options?)` | 创建 MutableSignal |
|
|
|
|
|
|
| `EntityCollection<T>` / `createEntityCollection()` | 实体集合辅助函数 |
|
|
|
|
|
|
|
|
|
|
|
|
### MutableSignal 成员
|
|
|
|
|
|
|
|
|
|
|
|
| 成员 | 说明 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `value: T` | 获取当前值（继承自 Signal） |
|
|
|
|
|
|
| `produce(fn: (draft: T) => void): void` | 同步不可变更新 |
|
2026-04-04 15:37:22 +08:00
|
|
|
|
| `addInterruption(promise: Promise<void>): void` | 添加中断，`produceAsync` 会等待它 |
|
2026-04-04 15:27:37 +08:00
|
|
|
|
| `clearInterruptions(): void` | 清除所有未完成的中断 |
|
|
|
|
|
|
| `produceAsync(fn: (draft: T) => void): Promise<void>` | 等待所有 interruption 完成后更新状态 |
|
2026-04-04 15:37:22 +08:00
|
|
|
|
|
|
|
|
|
|
### GameHost 上的中断方法
|
|
|
|
|
|
|
|
|
|
|
|
`GameHost` 直接代理了 `addInterruption` 和 `clearInterruptions`，供 UI 层使用，无需访问内部 `MutableSignal`。详见 [动画与状态更新同步](./animation-sync.md)。
|
