docs: update docs
This commit is contained in:
parent
e58690c9c6
commit
a02403d2c7
|
|
@ -42,6 +42,8 @@ const error = host.onInput('play X 1 2');
|
|||
|---|---|
|
||||
| [使用 GameHost](docs/game-host.md) | GameHost 生命周期、响应式状态、事件处理 |
|
||||
| [编写 GameModule](docs/game-module.md) | 定义状态、注册命令、prompt 系统、Part/Region 使用 |
|
||||
| [棋子、区域与 RNG](docs/parts-regions-rng.md) | Part 创建、池管理、区域操作、RNG 使用 |
|
||||
| [动画与状态同步](docs/animation-sync.md) | produceAsync 和中断机制 |
|
||||
| [API 参考](docs/api-reference.md) | 所有导出 API 的完整列表 |
|
||||
| [开发指南](docs/development.md) | 安装、构建脚本、测试命令 |
|
||||
|
||||
|
|
|
|||
|
|
@ -6,11 +6,13 @@
|
|||
|---|---|
|
||||
| `IGameContext` | 游戏上下文基础接口 |
|
||||
| `createGameContext(registry, initialState?)` | 创建游戏上下文实例 |
|
||||
| `createGameCommandRegistry<TState>()` | 创建命令注册表，返回带 `.add()` 的对象 |
|
||||
| `createGameModule(module)` | 辅助函数，标记一个对象为 GameModule |
|
||||
| `createGameContextFromModule(module)` | 从 GameModule 创建游戏上下文 |
|
||||
| `createGameCommandRegistry<TState>()` | 创建命令注册表 |
|
||||
| `createGameModule(module)` | 辅助函数，标记 GameModule |
|
||||
| `GameHost<TState>` | 游戏生命周期管理类 |
|
||||
| `createGameHost(module, options?)` | 从 GameModule 创建 GameHost |
|
||||
| `GameHostStatus` | 类型: `'created' \| 'running' \| 'disposed'` |
|
||||
| `GameModule` | 游戏模块类型 |
|
||||
|
||||
## 棋子 (Parts)
|
||||
|
||||
|
|
@ -18,13 +20,17 @@
|
|||
|---|---|
|
||||
| `Part<TMeta>` | 游戏棋子类型 |
|
||||
| `PartTemplate<TMeta>` | 创建棋子的模板类型 |
|
||||
| `PartPool<TMeta>` | 棋子池 |
|
||||
| `PartPool<TMeta>` | 棋子池类型 |
|
||||
| `createPart(template, id)` | 创建单个棋子 |
|
||||
| `createParts(template, count, idPrefix)` | 批量创建相同棋子 |
|
||||
| `createPartsFromTable(template, table, idField?)` | 从表格数据创建棋子 |
|
||||
| `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)
|
||||
|
|
@ -35,20 +41,38 @@
|
|||
| `createRegion(id, axes)` | 创建区域 |
|
||||
| `applyAlign(region, parts)` | 紧凑排列 |
|
||||
| `shuffle(region, parts, rng)` | 打乱位置 |
|
||||
| `moveToRegion(part, sourceRegion?, targetRegion, position?)` | 移动棋子到其他区域 |
|
||||
| `moveToRegionAll(parts, sourceRegion?, targetRegion, positions?)` | 批量移动 |
|
||||
| `removeFromRegion(part, region)` | 从区域移除棋子 |
|
||||
| `moveToRegion(part, sourceRegion?, targetRegion, position?)` | 移动棋子到区域 |
|
||||
|
||||
## 命令 (Commands)
|
||||
|
||||
| 导出 | 说明 |
|
||||
|---|---|
|
||||
| `Command` / `CommandSchema` / `CommandResult` | 命令相关类型 |
|
||||
| `CommandParamSchema` / `CommandOptionSchema` / `CommandFlagSchema` | 命令参数类型 |
|
||||
| `parseCommand(input)` | 解析命令字符串 |
|
||||
| `parseCommandSchema(schema)` | 解析 Schema 字符串 |
|
||||
| `validateCommand(cmd, schema)` | 验证命令 |
|
||||
| `Command` / `CommandSchema` / `CommandResult` | 命令相关类型 |
|
||||
| `PromptEvent` | 玩家输入提示事件 |
|
||||
| `createRNG(seed?)` | 创建种子 RNG |
|
||||
| `parseCommandWithSchema(input, schema)` | 解析并应用 Schema |
|
||||
| `applyCommandSchema(cmd, schema)` | 应用 Schema 到命令 |
|
||||
|
||||
### 命令运行器
|
||||
|
||||
| 导出 | 说明 |
|
||||
|---|---|
|
||||
| `CommandRunner<TContext, TResult>` | 命令运行器类型 |
|
||||
| `CommandRunnerHandler` | 命令处理器 |
|
||||
| `CommandRunnerContext` / `CommandRunnerContextExport` | 命令运行器上下文 |
|
||||
| `CommandRegistry` | 命令注册表类型 |
|
||||
| `PromptEvent` / `CommandRunnerEvents` | 提示事件类型 |
|
||||
| `PromptValidator<T>` | 提示验证器类型 |
|
||||
| `createCommandRegistry()` | 创建命令注册表 |
|
||||
| `registerCommand(registry, name, handler)` | 注册命令 |
|
||||
| `unregisterCommand(registry, name)` | 注销命令 |
|
||||
| `hasCommand(registry, name)` | 检查命令是否存在 |
|
||||
| `getCommand(registry, name)` | 获取命令 |
|
||||
| `runCommand(ctx, input)` | 运行命令 |
|
||||
| `runCommandParsed(ctx, cmd)` | 运行已解析命令 |
|
||||
| `createCommandRunnerContext(registry, ctx)` | 创建命令运行器上下文 |
|
||||
|
||||
## MutableSignal
|
||||
|
||||
|
|
@ -62,12 +86,21 @@
|
|||
|
||||
| 成员 | 说明 |
|
||||
|---|---|
|
||||
| `value: T` | 获取当前值（继承自 Signal） |
|
||||
| `value: T` | 获取当前值 |
|
||||
| `produce(fn: (draft: T) => void): void` | 同步不可变更新 |
|
||||
| `addInterruption(promise: Promise<void>): void` | 添加中断，`produceAsync` 会等待它 |
|
||||
| `clearInterruptions(): void` | 清除所有未完成的中断 |
|
||||
| `produceAsync(fn: (draft: T) => void): Promise<void>` | 等待所有 interruption 完成后更新状态 |
|
||||
| `addInterruption(promise: Promise<void>): void` | 添加中断 |
|
||||
| `clearInterruptions(): void` | 清除所有中断 |
|
||||
| `produceAsync(fn: (draft: T) => void): Promise<void>` | 等待中断完成后更新 |
|
||||
|
||||
### GameHost 上的中断方法
|
||||
### GameHost 中断代理
|
||||
|
||||
`GameHost` 直接代理了 `addInterruption` 和 `clearInterruptions`，供 UI 层使用，无需访问内部 `MutableSignal`。详见 [动画与状态更新同步](./animation-sync.md)。
|
||||
`GameHost` 直接代理 `addInterruption` 和 `clearInterruptions`，供 UI 层使用。
|
||||
详见 [动画与状态更新同步](./animation-sync.md)。
|
||||
|
||||
## 工具
|
||||
|
||||
| 导出 | 说明 |
|
||||
|---|---|
|
||||
| `RNG` | 随机数生成器接口 |
|
||||
| `createRNG(seed?)` | 创建种子 RNG |
|
||||
| `Mulberry32RNG` | Mulberry32 算法实现 |
|
||||
|
|
|
|||
|
|
@ -36,17 +36,52 @@ pool.return(piece); // 放回
|
|||
pool.remaining(); // 剩余数量
|
||||
```
|
||||
|
||||
## 从表格数据创建 Part
|
||||
|
||||
```ts
|
||||
const parts = createPartsFromTable(
|
||||
{ regionId: 'board', owner: 'white' },
|
||||
[
|
||||
{ id: 'p1', position: [0, 0] },
|
||||
{ id: 'p2', position: [1, 1] },
|
||||
],
|
||||
'id'
|
||||
);
|
||||
```
|
||||
|
||||
## 查询棋子
|
||||
|
||||
```ts
|
||||
// O(n) 遍历查找
|
||||
findPartById(state.parts, 'piece-1');
|
||||
getPartAtPosition(state.parts, 'board', [1, 1]);
|
||||
isCellOccupied(state.parts, 'board', [1, 1]);
|
||||
|
||||
// O(1) 使用 Region.partMap 查找
|
||||
getPartAtPositionInRegion(board, state.parts, [1, 1]);
|
||||
isCellOccupiedByRegion(board, [1, 1]);
|
||||
```
|
||||
|
||||
## 区域操作
|
||||
|
||||
```ts
|
||||
import { applyAlign, shuffle, moveToRegion, isCellOccupied } from 'boardgame-core';
|
||||
import { applyAlign, shuffle, moveToRegion } from 'boardgame-core';
|
||||
|
||||
isCellOccupied(state.parts, 'board', [1, 1]);
|
||||
applyAlign(handRegion, state.parts); // 紧凑排列
|
||||
shuffle(deckRegion, state.parts, rng); // 打乱
|
||||
moveToRegion(piece, sourceRegion, targetRegion, [0, 0]);
|
||||
```
|
||||
|
||||
## 翻面与掷骰
|
||||
|
||||
```ts
|
||||
import { flip, flipTo, roll } from 'boardgame-core';
|
||||
|
||||
flip(piece); // 翻到下一面
|
||||
flipTo(piece, 2); // 翻到指定面
|
||||
roll(piece, rng); // 随机面
|
||||
```
|
||||
|
||||
## RNG
|
||||
|
||||
```ts
|
||||
|
|
|
|||
Loading…
Reference in New Issue