From a02403d2c78ca4f46e9bc3963e886c0a1a0b63b0 Mon Sep 17 00:00:00 2001 From: hypercross Date: Sat, 4 Apr 2026 22:19:36 +0800 Subject: [PATCH] docs: update docs --- README.md | 2 ++ docs/api-reference.md | 63 +++++++++++++++++++++++++++++---------- docs/parts-regions-rng.md | 39 ++++++++++++++++++++++-- 3 files changed, 87 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 52c61b2..b26b586 100644 --- a/README.md +++ b/README.md @@ -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) | 安装、构建脚本、测试命令 | diff --git a/docs/api-reference.md b/docs/api-reference.md index 998dbbd..c60a312 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -6,11 +6,13 @@ |---|---| | `IGameContext` | 游戏上下文基础接口 | | `createGameContext(registry, initialState?)` | 创建游戏上下文实例 | -| `createGameCommandRegistry()` | 创建命令注册表，返回带 `.add()` 的对象 | -| `createGameModule(module)` | 辅助函数，标记一个对象为 GameModule | +| `createGameContextFromModule(module)` | 从 GameModule 创建游戏上下文 | +| `createGameCommandRegistry()` | 创建命令注册表 | +| `createGameModule(module)` | 辅助函数，标记 GameModule | | `GameHost` | 游戏生命周期管理类 | | `createGameHost(module, options?)` | 从 GameModule 创建 GameHost | | `GameHostStatus` | 类型: `'created' \| 'running' \| 'disposed'` | +| `GameModule` | 游戏模块类型 | ## 棋子 (Parts) @@ -18,13 +20,17 @@ |---|---| | `Part` | 游戏棋子类型 | | `PartTemplate` | 创建棋子的模板类型 | -| `PartPool` | 棋子池 | +| `PartPool` | 棋子池类型 | | `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` | 命令运行器类型 | +| `CommandRunnerHandler` | 命令处理器 | +| `CommandRunnerContext` / `CommandRunnerContextExport` | 命令运行器上下文 | +| `CommandRegistry` | 命令注册表类型 | +| `PromptEvent` / `CommandRunnerEvents` | 提示事件类型 | +| `PromptValidator` | 提示验证器类型 | +| `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` | 添加中断，`produceAsync` 会等待它 | -| `clearInterruptions(): void` | 清除所有未完成的中断 | -| `produceAsync(fn: (draft: T) => void): Promise` | 等待所有 interruption 完成后更新状态 | +| `addInterruption(promise: Promise): void` | 添加中断 | +| `clearInterruptions(): void` | 清除所有中断 | +| `produceAsync(fn: (draft: T) => void): Promise` | 等待中断完成后更新 | -### GameHost 上的中断方法 +### GameHost 中断代理 -`GameHost` 直接代理了 `addInterruption` 和 `clearInterruptions`，供 UI 层使用，无需访问内部 `MutableSignal`。详见 [动画与状态更新同步](./animation-sync.md)。 +`GameHost` 直接代理 `addInterruption` 和 `clearInterruptions`，供 UI 层使用。 +详见 [动画与状态更新同步](./animation-sync.md)。 + +## 工具 + +| 导出 | 说明 | +|---|---| +| `RNG` | 随机数生成器接口 | +| `createRNG(seed?)` | 创建种子 RNG | +| `Mulberry32RNG` | Mulberry32 算法实现 | diff --git a/docs/parts-regions-rng.md b/docs/parts-regions-rng.md index 6d21594..1203eeb 100644 --- a/docs/parts-regions-rng.md +++ b/docs/parts-regions-rng.md @@ -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