docs: update docs

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) | 安装、构建脚本、测试命令 |
 

docs/api-reference.md

@@ -6,11 +6,13 @@
 |---|---|
 | `IGameContext` | 游戏上下文基础接口 |
 | `createGameContext(registry, initialState?)` | 创建游戏上下文实例 |
-| `createGameCommandRegistry<TState>()` | 创建命令注册表，返回带 `.add()` 的对象 |
+| `createGameContextFromModule(module)` | 从 GameModule 创建游戏上下文 |
-| `createGameModule(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?)` | 移动棋子到其他区域 |
+| `moveToRegion(part, sourceRegion?, targetRegion, position?)` | 移动棋子到区域 |
-| `moveToRegionAll(parts, sourceRegion?, targetRegion, positions?)` | 批量移动 |
-| `removeFromRegion(part, region)` | 从区域移除棋子 |
 
 ## 命令 (Commands)
 
 | 导出 | 说明 |
 |---|---|
+| `Command` / `CommandSchema` / `CommandResult` | 命令相关类型 |
+| `CommandParamSchema` / `CommandOptionSchema` / `CommandFlagSchema` | 命令参数类型 |
 | `parseCommand(input)` | 解析命令字符串 |
 | `parseCommandSchema(schema)` | 解析 Schema 字符串 |
 | `validateCommand(cmd, schema)` | 验证命令 |
-| `Command` / `CommandSchema` / `CommandResult` | 命令相关类型 |
+| `parseCommandWithSchema(input, schema)` | 解析并应用 Schema |
-| `PromptEvent` | 玩家输入提示事件 |
+| `applyCommandSchema(cmd, schema)` | 应用 Schema 到命令 |
-| `createRNG(seed?)` | 创建种子 RNG |
+
+### 命令运行器
+
+| 导出 | 说明 |
+|---|---|
+| `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` 会等待它 |
+| `addInterruption(promise: Promise<void>): void` | 添加中断 |
-| `clearInterruptions(): void` | 清除所有未完成的中断 |
+| `clearInterruptions(): void` | 清除所有中断 |
-| `produceAsync(fn: (draft: T) => void): Promise<void>` | 等待所有 interruption 完成后更新状态 |
+| `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 算法实现 |

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