143 lines
5.7 KiB
Markdown
143 lines
5.7 KiB
Markdown
# 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 } | { success: false, error: string }` |
|
||
|
||
### 注册与运行
|
||
|
||
| 导出 | 说明 |
|
||
|---|---|
|
||
| `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` 方法：
|
||
|
||
```ts
|
||
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()` | 清除所有未完成的中断 |
|
||
|
||
详见 [动画与状态更新同步](./animation-sync.md)。
|
||
|
||
## 工具
|
||
|
||
| 导出 | 说明 |
|
||
|---|---|
|
||
| `RNG` | 随机数生成器接口: `setSeed`、`getSeed`、`next`、`nextInt` |
|
||
| `createRNG(seed?)` / `Mulberry32RNG` | Mulberry32 算法 PRNG |
|