init: 2.B

2026-11-01 06:04:30 +08:00 · 2026-02-28 20:23:34 +08:00
commit 6bf32174d8
@@ -0,0 +1,424 @@
+# ObjectMoverBase API 文档
+
+本文档由 `DeepSeek R1` 模型生成并微调。
+
+---
+
+## 类描述
+
+游戏中可移动对象的基类控制器，提供面向方向、移动队列管理和动画协调的通用移动能力。继承自 EventEmitter3，用于实现图块、角色等元素的移动控制。
+
+```mermaid
+graph LR
+    ObjectMoverBase --> EventEmitter
+
+    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
+```
+
+---
+
+## 核心属性
+
+| 属性名       | 类型              | 说明                     |
+| ------------ | ----------------- | ------------------------ |
+| `moveSpeed`  | `number`          | 当前移动速度（毫秒/格）  |
+| `moveDir`    | `Dir2`            | 当前移动方向（八方向）   |
+| `moving`     | `boolean`         | 是否处于移动状态         |
+| `faceDir`    | `Dir2`            | 当前面朝方向（八方向）   |
+| `controller` | `IMoveController` | 当前移动控制实例（只读） |
+
+---
+
+## 事件说明
+
+| 事件名      | 参数          | 触发时机           |
+| ----------- | ------------- | ------------------ |
+| `stepEnd`   | `MoveStepDir` | 单步移动完成时     |
+| `moveEnd`   | -             | 整个移动队列完成时 |
+| `moveStart` | `MoveStep[]`  | 移动队列开始执行时 |
+
+---
+
+## 方法说明
+
+### `startMove`
+
+```typescript
+function startMove(): IMoveController | null;
+```
+
+**功能**  
+启动移动队列执行
+
+**返回值**  
+`IMoveController`：移动控制器实例（可追加指令）  
+`null`：队列为空或已在移动中时返回
+
+**示例**
+
+```typescript
+const controller = mover.startMove();
+if (controller) {
+    controller.push({ type: 'dir', value: 'right' });
+}
+```
+
+---
+
+### `insertMove`
+
+```typescript
+function insertMove(...move: MoveStep[]): void;
+```
+
+| 参数   | 类型         | 说明         |
+| ------ | ------------ | ------------ |
+| `move` | `MoveStep[]` | 移动指令序列 |
+
+**功能**  
+向队列末尾插入移动指令
+
+**示例**
+
+```typescript
+// 添加转向+加速指令
+mover.insertMove({ type: 'dir', value: 'left' }, { type: 'speed', value: 200 });
+```
+
+---
+
+### `clearMoveQueue`
+
+```typescript
+function clearMoveQueue(): void;
+```
+
+**功能**  
+清空所有待执行移动指令
+
+**注意**  
+不影响已开始的移动步骤
+
+---
+
+### `oneStep`
+
+```typescript
+function oneStep(step: Move2): void;
+```
+
+| 参数   | 类型    | 说明                              |
+| ------ | ------- | --------------------------------- |
+| `step` | `Move2` | 移动方向（支持八向/前后相对方向） |
+
+**功能**  
+添加单步方向移动指令
+
+**示例**
+
+```typescript
+// 添加面朝方向移动指令
+mover.oneStep('forward');
+```
+
+---
+
+### `moveAs`
+
+```typescript
+function moveAs(steps: MoveStep[]): void;
+```
+
+| 参数    | 类型         | 说明               |
+| ------- | ------------ | ------------------ |
+| `steps` | `MoveStep[]` | 结构化移动指令序列 |
+
+**功能**  
+批量加载复杂移动路径
+
+**示例**
+
+```typescript
+mover.moveAs([
+    { type: 'dir', value: 'up' }, // 向上移动
+    { type: 'speed', value: 150 }, // 修改速度为每 150ms 移动一格
+    { type: 'dir', value: 'rightup' } // 右上45度移动
+]);
+```
+
+---
+
+### `setFaceDir`
+
+```typescript
+function setFaceDir(dir: Dir2): void;
+```
+
+| 参数  | 类型   | 说明           |
+| ----- | ------ | -------------- |
+| `dir` | `Dir2` | 八方向面朝方向 |
+
+**限制**  
+仅在非移动状态生效
+
+**示例**
+
+```typescript
+// 设置角色面朝左上方
+mover.setFaceDir('leftup');
+```
+
+---
+
+### `setMoveDir`
+
+```typescript
+function setMoveDir(dir: Dir2): void;
+```
+
+| 参数  | 类型   | 说明         |
+| ----- | ------ | ------------ |
+| `dir` | `Dir2` | 基础移动方向 |
+
+**注意**  
+影响`forward/backward`指令的实际方向
+
+---
+
+## 抽象方法
+
+### `abstract onMoveStart`
+
+```typescript
+function onMoveStart(controller: IMoveController): Promise<void>;
+```
+
+**触发时机**  
+移动队列开始执行时
+
+---
+
+### `abstract onMoveEnd`
+
+```typescript
+function onMoveEnd(controller: IMoveController): Promise<void>;
+```
+
+**触发时机**  
+移动队列完成或被中断时
+
+---
+
+### `abstract onStepStart`
+
+```typescript
+function onStepStart(
+    step: MoveStepDir,
+    controller: IMoveController
+): Promise<number>;
+```
+
+| 参数         | 类型              | 说明         |
+| ------------ | ----------------- | ------------ |
+| `step`       | `MoveStepDir`     | 当前移动步骤 |
+| `controller` | `IMoveController` | 移动控制器   |
+
+**返回值**  
+`Promise<number>`：步骤执行标识码（用于后续传递）
+
+---
+
+### `abstract onStepEnd`
+
+```typescript
+function onStepEnd(
+    step: MoveStepDir,
+    code: number,
+    controller: IMoveController
+): Promise<void>;
+```
+
+| 参数         | 类型              | 说明                       |
+| ------------ | ----------------- | -------------------------- |
+| `code`       | `number`          | `onStepStart` 返回的标识码 |
+| `controller` | `IMoveController` | 移动控制器                 |
+
+---
+
+### `abstract onSetMoveSpeed`
+
+```typescript
+function onSetMoveSpeed(speed: number, controller: IMoveController): void;
+```
+
+| 参数         | 类型              | 说明           |
+| ------------ | ----------------- | -------------- |
+| `speed`      | `number`          | 新的移动速度值 |
+| `controller` | `IMoveController` | 移动控制器     |
+
+---
+
+## BlockMover
+
+`BlockMover` 是基于 `ObjectMoverBase` 的内置类，用于实现图块移动。
+
+```mermaid
+graph LR
+    BlockMover --> ObjectMoverBase
+    ObjectMoverBase --> EventEmitter
+
+    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
+```
+
+### 新增方法
+
+```typescript
+function bind(
+    x: number,
+    y: number,
+    floorId: FloorIds,
+    layer: FloorLayer,
+    dir: Dir = 'down'
+): boolean;
+```
+
+| 参数      | 类型         | 说明                 |
+| --------- | ------------ | -------------------- |
+| `x`       | `number`     | 图块 X 坐标          |
+| `y`       | `number`     | 图块 Y 坐标          |
+| `floorId` | `FloorIds`   | 所在楼层 ID          |
+| `layer`   | `FloorLayer` | 图层类型（bg/fg 等） |
+| `dir`     | `Dir`        | 初始方向             |
+
+**返回值**：绑定成功返回 `true`，若目标正在移动则返回 `false`
+
+**示例**
+
+```typescript
+if (blockMover.bind(5, 8, 'floor1', 'bg', 'up')) {
+    blockMover.insertMove({ type: 'dir', value: 'right' });
+}
+```
+
+---
+
+## HeroMover
+
+`HeroMover` 是基于 `ObjectMoverBase` 的内置类，用于实现勇士移动。
+
+```mermaid
+graph LR
+    HeroMover --> ObjectMoverBase
+    ObjectMoverBase --> EventEmitter
+
+    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
+```
+
+### 覆盖方法
+
+```ts
+function startMove(
+    ignoreTerrain: boolean = false,
+    noRoute: boolean = false,
+    inLockControl: boolean = false,
+    autoSave: boolean = false
+): IMoveController | null;
+```
+
+| 参数            | 说明                                     |
+| --------------- | ---------------------------------------- |
+| `ignoreTerrain` | 是否忽略地形，即是否穿墙                 |
+| `noRoute`       | 是否不计入录像                           |
+| `inLockControl` | 是否是在锁定控制中移动的，例如事件中移动 |
+| `autoSave`      | 在必要时刻是否自动存档                   |
+
+其余用法与基类相同。
+
+---
+
+## 使用示例
+
+### 勇士移动控制
+
+```typescript
+import { heroMoverCollection } from '@user/data-state';
+
+// 获取勇士移动控制器单例
+const heroMover = heroMoveCollection.mover;
+
+// 设置面朝方向为右侧
+heroMover.setFaceDir('right');
+
+// 添加移动指令：前进三步
+heroMover.insertMove(
+    { type: 'dir', value: 'forward' },
+    { type: 'dir', value: 'forward' },
+    { type: 'dir', value: 'forward' }
+);
+
+// 启动移动并获取控制器
+const controller = heroMover.startMove(
+    false, // 不允许穿墙
+    true, // 不计入录像
+    false, // 不在录像锁定中触发
+    false // 不进行自动存档
+);
+
+if (controller) {
+    // 动态追加移动指令
+    controller.push({ type: 'dir', value: 'leftup' });
+    // 监听移动完成事件
+    controller.onEnd.then(() => {
+        console.log('勇士移动完成');
+    });
+}
+```
+
+### 图块移动控制
+
+```typescript
+import { BlockMover } from '@user/data-state';
+
+// 创建图块移动器实例
+const blockMover = new BlockMover();
+
+// 绑定到(5,8)位置的背景图块
+if (blockMover.bind(5, 8, 'floor1', 'bg', 'up')) {
+    // 添加螺旋移动路径
+    blockMover.moveAs([
+        { type: 'dir', value: 'right' },
+        { type: 'dir', value: 'down' },
+        { type: 'dir', value: 'left' },
+        { type: 'dir', value: 'up' }
+    ]);
+
+    // 设置移动速度为200像素/秒
+    blockMover.insertMove({ type: 'speed', value: 200 });
+
+    // 启动移动
+    const ctrl = blockMover.startMove();
+}
+```
+
+---
+
+## 移动指令类型
+
+```typescript
+type MoveStep =
+    | { type: 'dir'; value: Move2 } // 方向指令
+    | { type: 'speed'; value: number }; // 速度指令
+```
+
+---
+
+## 注意事项
+
+1. **方向优先级**  
+   `forward/backward` 基于当前面朝方向计算，修改 faceDir 会影响实际移动方向
+
+2. **速度叠加规则**  
+   多个 speed 指令按队列顺序覆盖，最终生效最后一个速度值
+
+3. **移动中断处理**  
+   调用 controller.stop() 会立即中断移动并触发 moveEnd 事件