mirror of
https://github.com/motajs/template.git
synced 2026-05-25 13:41:11 +08:00
feat: 动态图层
This commit is contained in:
parent
4c48b63e7e
commit
fbdd609001
7
dev.md
7
dev.md
@ -57,13 +57,15 @@
|
||||
|
||||
### 注释规范
|
||||
|
||||
- 常用属性成员、方法、接口、类型必须添加 `jsDoc` 注释。
|
||||
- 公共方法、接口必须在**源头处**（多数情况下为 `interface`）添加 `jsDoc` 注释；其他常用成员、方法、类型也必须添加注释（含义极为明确或极少使用的可例外，但建议全部添加）。
|
||||
- 继承或 `implements` 而来的 API（方法、成员等），若注释说明无需变更，则**不应重复添加** `jsDoc` 注释。
|
||||
- 不对构造器添加注释。若构造器使用了属性声明语法（`constructor(public prop: T)`）且成员需要说明，可仅对该成员添加参数注释，不写构造器描述。**在这种情况下**建议避免在构造器中使用属性声明语法，将成员单独声明并在构造器中赋值。此条建议**并非**要求不使用构造器的属性声明语法，而是仅在这一情况下不建议使用，常规情况下推荐使用此语法来缩短代码长度并提高可读性。
|
||||
- 长文件可使用 `#region` / `#endregion` 分段以支持折叠。
|
||||
- TODO 使用 `// TODO:` 或 `// todo:` 格式。
|
||||
- 单行注释的 `//` 与注释内容之间留一个空格；不允许出现非 jsDoc 的多行注释，如需多行注释，使用多个单行注释代替。
|
||||
- 注释合理换行：考虑中文字符较宽，建议每 40–60 个字符在标点符号后换行，不允许在句中换行；参数注释换行后保持对齐。
|
||||
- 单行注释结尾不加句号；较长的多行注释结尾可加句号。
|
||||
- 一般不建议给接口、类型别名或类本身写注释（不好看），特殊情况除外。
|
||||
- 一般不建议给接口（`inteface` 本身）、类型别名或类本身写注释（不好看），特殊情况除外。
|
||||
|
||||
### 类型规范
|
||||
|
||||
@ -77,6 +79,7 @@
|
||||
|
||||
### 其他要求
|
||||
|
||||
- 不使用字符串作为键或特殊标识符（如枚举值、事件名、状态名等），应使用枚举代替。仅当明确表示字符串本身（如字符串类型的 id 别名、文件路径等）时方可使用字符串字面量。
|
||||
- 严格遵循 `eslint` 配置，不允许出现 eslint 报错。
|
||||
- 尽量不使用 `?.` 运算符，仅推荐在以下两种场景中使用：
|
||||
- 副作用函数调用，如 `this.obj?.func()` 或 `this.obj.func?.()`
|
||||
|
||||
595
docs/dev/map/dynamic-tile-move.md
Normal file
595
docs/dev/map/dynamic-tile-move.md
Normal file
@ -0,0 +1,595 @@
|
||||
# 动态图块移动系统
|
||||
|
||||
> 本文档为 [动态图块系统](./dynamic-tile.md) 的移动子系统设计文档，
|
||||
> 重点描述双方向模型、`IDynamicMover` 计划式移动接口及执行流程。
|
||||
> 本文档中新增的类型与接口同样需要添加至 `@user/data-base/src/map/types.ts`。
|
||||
|
||||
---
|
||||
|
||||
# 背景与动机
|
||||
|
||||
`IDynamicLayer.moveDynamicStep` / `moveDynamicWith` 是命令式简单接口，适用于
|
||||
一次性的简单移动，但对以下场景力不从心：
|
||||
|
||||
- **后退移动**：角色面朝上、向下移动时，朝向不变但位移反向，
|
||||
单一 `FaceDirection` 参数无法同时描述朝向和移动方向；
|
||||
- **连续路径中途动态追加步骤**：命令式接口执行后无法继续追加；
|
||||
- **移动速度切换**：路径中途需要变速，命令式接口不支持；
|
||||
- **复杂动画编排**：需要按序执行多段计划时，纯 `Promise` 链表达不够直观。
|
||||
|
||||
因此引入以图块为粒度绑定的 `IDynamicMover`，采用**先建计划、再执行**的设计理念，
|
||||
参考 `@motajs/animate/types.ts` 的链式计划构建模式，
|
||||
以及 `@user/data-state/legacy/move.ts` 中 `ObjectMoverBase` 的双方向与队列设计。
|
||||
|
||||
---
|
||||
|
||||
# 实现思路
|
||||
|
||||
## 1. 双方向模型
|
||||
|
||||
每个动态图块维护两个方向字段：
|
||||
|
||||
| 字段 | 含义 | 影响 |
|
||||
| --------------- | ---------------------------- | --------------------------------------- |
|
||||
| `faceDirection` | **朝向**，视觉上「面朝哪里」 | 通过 `IRoleFaceBinder` 决定渲染图块数字 |
|
||||
| `moveDirection` | **移动方向**，「向哪边走」 | 结合 `getFaceMovement` 计算位移 |
|
||||
|
||||
两者分离后可以表达：
|
||||
|
||||
- **后退**：`moveDirection = Up`，执行 `backward()` 步，
|
||||
`moveDirection = Down`，`faceDirection = Down`，位移向下，朝向同步翻转。
|
||||
- **横向移动不转身**：使用 `stepFace(move, face)` 单独指定朝向，
|
||||
`moveDirection` 与 `faceDirection` 独立设置。
|
||||
|
||||
绝对方向步骤（传入 `FaceDirection`）默认将两者同时更新；
|
||||
`forward()` 沿当前 `moveDirection` 移动并对齐 `faceDirection`；
|
||||
`backward()` 将 `moveDirection` 取反并同步 `faceDirection`。
|
||||
|
||||
## 2. 方向步语义
|
||||
|
||||
绝对方向步（`IDynamicMoveStepDir` / `IDynamicMoveStepDirFace`）直接传入 `FaceDirection`：
|
||||
|
||||
- `step(dir, count?: number)`：追加 `count`（默认 1）个绝对方向步，`moveDirection` 和 `faceDirection` 均更新为 `dir`；
|
||||
- `stepFace(move, face, count?: number)`：追加 `count`（默认 1）个绝对方向步，`moveDirection` 更新为 `move`，
|
||||
`faceDirection` 更新为 `face`——用于移动方向与朝向不一致的场景（如斜切移动保持正向）。
|
||||
|
||||
相对方向步（`IDynamicMoveStepSpecial`）通过独立方法构建：
|
||||
|
||||
- `forward(count?)`：沿当前 `tile.moveDirection` 移动，`moveDirection` 不变，
|
||||
`faceDirection` 对齐为 `moveDirection`；
|
||||
- `backward(count?)`：沿 `opposite(tile.moveDirection)` 移动，`moveDirection` 取反，
|
||||
`faceDirection` 同步更新为新的 `moveDirection`，自动使用逆向动画。
|
||||
|
||||
## 3. DynamicMoveStep 类型
|
||||
|
||||
步骤类型通过 `const enum` 区分，避免字符串比较。
|
||||
前进/后退方向用独立的 `DynamicSpecialStep` 枚举表示；
|
||||
动画播放方向用独立的 `DynamicAnimDirection` 枚举表示，两者互不依赖：
|
||||
|
||||
```ts
|
||||
const enum DynamicMoveStepType {
|
||||
/** 绝对方向步，同步更新 moveDirection 和 faceDirection */
|
||||
Dir,
|
||||
/** 绝对方向步，单独指定 faceDirection */
|
||||
DirFace,
|
||||
/** 速度步 */
|
||||
Speed,
|
||||
/** 纯转向步，不产生位移 */
|
||||
Face,
|
||||
/** 特殊步（前进或后退） */
|
||||
Special,
|
||||
/** 动画方向步，不影响 moveDirection/faceDirection */
|
||||
AnimDir
|
||||
}
|
||||
|
||||
/** 特殊步方向：前进或后退 */
|
||||
const enum DynamicSpecialStep {
|
||||
Forward,
|
||||
Backward
|
||||
}
|
||||
|
||||
/** 动画播放方向：正向或逆向 */
|
||||
const enum DynamicAnimDirection {
|
||||
Forward,
|
||||
Backward
|
||||
}
|
||||
|
||||
/** 绝对方向步：move 方向既是移动方向也是朝向 */
|
||||
interface IDynamicMoveStepDir {
|
||||
type: DynamicMoveStepType.Dir;
|
||||
move: FaceDirection;
|
||||
}
|
||||
|
||||
/** 绝对方向步：move 是移动方向，face 是显式指定的朝向 */
|
||||
interface IDynamicMoveStepDirFace {
|
||||
type: DynamicMoveStepType.DirFace;
|
||||
move: FaceDirection;
|
||||
face: FaceDirection;
|
||||
}
|
||||
|
||||
/** 速度步：修改后续移动的每格耗时（单位 ms，越小越快） */
|
||||
interface IDynamicMoveStepSpeed {
|
||||
type: DynamicMoveStepType.Speed;
|
||||
value: number;
|
||||
}
|
||||
|
||||
/** 转向步：仅更新 faceDirection，不产生位移，等待渲染动画完成 */
|
||||
interface IDynamicMoveStepFace {
|
||||
type: DynamicMoveStepType.Face;
|
||||
value: FaceDirection;
|
||||
}
|
||||
|
||||
/** 特殊步：前进（Forward）或后退（Backward）。`forward(n)`/`backward(n)` 构建时 n>1 会 push n 个相同步骤 */
|
||||
interface IDynamicMoveStepSpecial {
|
||||
type: DynamicMoveStepType.Special;
|
||||
direction: DynamicSpecialStep;
|
||||
}
|
||||
|
||||
/** 动画方向步：指定后续步骤动画正向播放（Forward）还是逆向播放（Backward） */
|
||||
interface IDynamicMoveAnimDir {
|
||||
type: DynamicMoveStepType.AnimDir;
|
||||
dir: DynamicAnimDirection;
|
||||
}
|
||||
|
||||
type DynamicMoveStep =
|
||||
| IDynamicMoveStepDir
|
||||
| IDynamicMoveStepDirFace
|
||||
| IDynamicMoveStepSpeed
|
||||
| IDynamicMoveStepFace
|
||||
| IDynamicMoveStepSpecial
|
||||
| IDynamicMoveAnimDir;
|
||||
```
|
||||
|
||||
## 4. IMoverController 接口
|
||||
|
||||
`IDynamicMover.start()` 返回 `IMoverController`，用于控制进行中的移动。
|
||||
|
||||
```ts
|
||||
interface IMoverController {
|
||||
/** 本次移动是否已全部完成 */
|
||||
readonly done: boolean;
|
||||
/** 当本次移动全部步骤完成时兑现 */
|
||||
readonly onEnd: Promise<void>;
|
||||
/**
|
||||
* 向当前队列末尾追加步骤（仅在移动进行中有效，完成后追加无效）
|
||||
*/
|
||||
push(...steps: DynamicMoveStep[]): void;
|
||||
/**
|
||||
* 停止移动，等待当前步骤完成后停止，返回的 Promise 在停止后兑现
|
||||
*/
|
||||
stop(): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
## 5. IDynamicMover 接口
|
||||
|
||||
每个 `IDynamicTile` 持有一个**绑定**的 `IDynamicMover` 实例（`tile.mover`），
|
||||
无需单独创建或管理生命周期。
|
||||
|
||||
### 5.1 状态读取
|
||||
|
||||
```ts
|
||||
// 以下状态属性来自 IObjectMover<IDynamicTile>，IDynamicMover 全部继承
|
||||
interface IObjectMover<T extends IObjectMovable> {
|
||||
/** 是否正在移动 */
|
||||
readonly moving: boolean;
|
||||
/** 当前朝向（与 tile.faceDirection 同步） */
|
||||
readonly faceDirection: FaceDirection;
|
||||
/** 当前移动方向（与 tile.moveDirection 同步） */
|
||||
readonly moveDirection: FaceDirection;
|
||||
/** 所属的可移动对象 */
|
||||
readonly tile: T;
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 计划构建（链式）
|
||||
|
||||
所有构建方法均返回 `this`，支持链式调用。
|
||||
计划在调用 `start()` 前不执行，仅追加到内部队列。
|
||||
|
||||
```ts
|
||||
interface IDynamicMover {
|
||||
// ...
|
||||
/** 追加 count（默认 1）个绝对方向步，同步更新 moveDirection 和 faceDirection */
|
||||
step(dir: FaceDirection, count?: number): this;
|
||||
/** 追加 count（默认 1）个绝对方向步，单独指定 faceDirection（用于移动方向与朝向不一致的场景） */
|
||||
stepFace(move: FaceDirection, face: FaceDirection, count?: number): this;
|
||||
/** 追加前进步，沿当前 moveDirection 移动，faceDirection 对齐为 moveDirection */
|
||||
forward(count?: number): this;
|
||||
/** 追加后退步，moveDirection 取反，faceDirection 同步更新，自动使用逆向动画 */
|
||||
backward(count?: number): this;
|
||||
/** 追加一个速度步，改变后续移动的每格耗时（ms） */
|
||||
speed(value: number): this;
|
||||
/** 追加一个纯转向步，仅更新 faceDirection，不产生位移 */
|
||||
face(dir: FaceDirection): this;
|
||||
/** 追加一个动画方向步，控制后续步骤的动画播放方向（Forward 正向 / Backward 逆向） */
|
||||
animDir(dir: DynamicAnimDirection): this;
|
||||
/** 清空尚未执行的计划队列 */
|
||||
clear(): this;
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**用法示例**：
|
||||
|
||||
```ts
|
||||
// 先向下走 2 步，切换为半速，再向右走 1 步
|
||||
tile.mover
|
||||
.step(FaceDirection.Down, 2)
|
||||
.speed(200)
|
||||
.step(FaceDirection.Right)
|
||||
.start();
|
||||
|
||||
// 后退 3 步（moveDirection/faceDirection 翻转，逆向动画）
|
||||
tile.mover.backward(3).start();
|
||||
|
||||
// 向右移动但保持朝下（如横向滑步）
|
||||
tile.mover.stepFace(FaceDirection.Right, FaceDirection.Down, 2).start();
|
||||
```
|
||||
|
||||
### 5.3 执行控制
|
||||
|
||||
```ts
|
||||
interface IDynamicMover {
|
||||
// ...
|
||||
/**
|
||||
* 开始执行计划队列，返回控制对象。
|
||||
* 若已在移动则返回 null（不中断当前移动）。
|
||||
*/
|
||||
start(): IMoverController | null;
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 移动执行流程
|
||||
|
||||
每次 `start()` 启动后，执行器按以下总流程处理队列：
|
||||
|
||||
触发 `onMoveStart` → 循环每步：[
|
||||
`abstract onStepStart(step, tile, mover)` 执行并返回 `code: number`（子类计算本步场景）→
|
||||
触发 `IObjectMoverHooks.onStepStart(code, step, tile, mover)` 钩子（渲染预处理，此时 `tile.x/y` 为**移动前坐标**）→
|
||||
等待所有 Promise →
|
||||
`abstract onStepEnd(code, step, tile, mover)` 执行**逻辑效果**（子类根据 code 决定如何执行）→
|
||||
触发 `IObjectMoverHooks.onStepEnd(code, step, tile, mover)` 钩子（此时 `tile.x/y` 为**移动后坐标**）
|
||||
] → 触发 `onMoveEnd`。
|
||||
|
||||
### 6.1 绝对方向步（`DynamicMoveStepType.Dir`）
|
||||
|
||||
**onStepStart 阶段**（`tile.x/y` 为原始坐标）：
|
||||
|
||||
1. `abstract onStepStart(step, tile, mover)` 执行，子类计算本步 `code`（正常移动、碰墙等）并返回 `Promise<number>`。
|
||||
2. 父类拿到 `code`，触发 `IObjectMoverHooks.onStepStart(code, step, tile, mover)` 钩子——渲染端在此阶段播放移动动画，
|
||||
可由 `step.move` 与当前 `tile.x/y` 推算目标位置。
|
||||
3. `await Promise.all(promises)`——等待全部动画完成。
|
||||
|
||||
**onStepEnd 阶段**（逻辑效果）：
|
||||
|
||||
1. `abstract onStepEnd(code, step, tile, mover)` 执行——子类依据 `code` 决定本步实际效果：
|
||||
更新 `tile.moveDirection = step.move`。
|
||||
2. 计算 `{dx, dy} = getFaceMovement(step.move)`，**立即**更新 `tile.x += dx`、`tile.y += dy`。
|
||||
3. 同步更新 `posMap`。
|
||||
4. 执行转向逻辑（见 [dynamic-tile.md §8](./dynamic-tile.md#8-转向逻辑)），
|
||||
更新 `tile.faceDirection` 与 `tile.num`。
|
||||
5. 子类返回后，父类触发 `IObjectMoverHooks.onStepEnd(code, step, tile, mover)` 钩子，此时 `tile.x/y` 已为新坐标。
|
||||
|
||||
### 6.1.1 含显式朝向的绝对方向步（`DynamicMoveStepType.DirFace`）
|
||||
|
||||
与 `Dir` 步骤相同，但步骤 5 改为直接将 `tile.faceDirection` 设为 `step.face`，
|
||||
并通过 `getFaceOf(tile.num, step.face)` 更新 `tile.num`，不经过 `degradeFace` 降级。
|
||||
|
||||
### 6.2 速度步（`DynamicMoveStepType.Speed`）
|
||||
|
||||
更新内部速度状态，立即生效，无位移，无需等待。
|
||||
|
||||
### 6.3 纯转向步（`DynamicMoveStepType.Face`）
|
||||
|
||||
经由 `onStepStart` 触发钩子（`tile.x/y` 不变，`step.type === DynamicMoveStepType.Face` 供渲染端区分）；
|
||||
等待渲染端动画完成后，`onStepEnd` 阶段执行转向逻辑，更新 `faceDirection` 与 `tile.num`，
|
||||
触发 `onStepEnd` 钩子。
|
||||
|
||||
### 6.4 特殊步（`DynamicMoveStepType.Special`）
|
||||
|
||||
**语义说明**：`forward`/`backward` 以**上一步的移动方向**（即当前 `tile.moveDirection`）为基准；
|
||||
若无上一步，则回退到当前 `faceDirection`；若图块无朝向绑定，则抛出错误。
|
||||
|
||||
**Forward**（`DynamicSpecialStep.Forward`）：
|
||||
|
||||
1. `actualDir = tile.moveDirection`（不改变 moveDirection）；
|
||||
2. 执行与 `Dir` 步骤相同的位移流程；
|
||||
3. 步骤 2：跳过（`moveDirection` 保持不变）；
|
||||
4. 步骤 5：执行转向逻辑，以 `actualDir` 更新 `tile.faceDirection` 与 `tile.num`。
|
||||
|
||||
**Backward**（`DynamicSpecialStep.Backward`）：
|
||||
|
||||
1. `actualDir = opposite(tile.moveDirection)`；
|
||||
2. 在执行前临时将逆向动画标志设为开启（步骤完成后恢复）；
|
||||
3. 执行与 `Dir` 步骤相同的位移流程；
|
||||
4. 步骤 2：`tile.moveDirection = actualDir`；
|
||||
5. 步骤 5：执行转向逻辑，以 `actualDir` 更新 `tile.faceDirection` 与 `tile.num`。
|
||||
|
||||
### 6.5 动画方向步（`DynamicMoveStepType.AnimDir`）
|
||||
|
||||
指定后续步骤动画是**正向播放**（`DynamicAnimDirection.Forward`）还是**逆向播放**（`DynamicAnimDirection.Backward`），
|
||||
与图块朝向无关（朝向始终由 `faceDirection` 决定）。
|
||||
修改 mover 内部的 `currentAnimDir` 状态。
|
||||
渲染端在 `onStepStart` 收到 `AnimDir` 步骤时读取并更新本地动画方向状态，后续步骤的 `onStepStart` 触发时依据此状态决定播放方向。
|
||||
`onStepEnd` 阶段无逻辑操作，立即完成，不影响坐标与方向。
|
||||
|
||||
## 7. onStepStart / onStepEnd 钩子返回值
|
||||
|
||||
`IObjectMoverHooks.onStepStart` 与 `onStepEnd` 均为可选钩子（`?`），返回类型为 `Promise<void>`，
|
||||
执行器始终通过 `Promise.all` 等待所有订阅方完成后再继续。
|
||||
|
||||
关键时序：`onStepStart` 所有 Promise 兑现后，才执行逻辑效果（abstract onStepEnd）；
|
||||
`onStepEnd` 全部兑现后，才进入下一步。
|
||||
多个订阅方通过 `Promise.all` 并行等待，与 `forEachHook` 返回所有值的设计天然契合——
|
||||
`const promises = forEachHook(hook => hook.onStepStart?.(code, step, tile, mover));`
|
||||
`await Promise.all(promises);`
|
||||
|
||||
## 8. 与 IDynamicLayer / IDynamicTile 接口的关系
|
||||
|
||||
`IDynamicLayer` 和 `IDynamicTile` **仅保留 `step(dir)` 单步便捷接口**
|
||||
（等价于 `tile.mover.step(dir).start()`），不再提供 `moveDynamicWith` / `moveWith` 等批量接口。
|
||||
复杂移动能力（`forward`/`backward`/`animDir` 等）通过 `tile.mover` 访问。
|
||||
|
||||
**渲染端订阅移动事件的流程**：
|
||||
|
||||
1. 订阅 `IDynamicLayer.onCreateDynamicTile`；
|
||||
2. 创建图块时获取 `tile.mover` 引用，直接向其添加钩子；
|
||||
3. 移动事件从 `tile.mover` 触发，无需经过 `IDynamicLayer` 转发。
|
||||
|
||||
为此，`IDynamicMover` 扩展为可订阅对象，
|
||||
实现 `IHookable<IObjectMoverHooks<IDynamicTile>>`（见接口定义汇总）。
|
||||
|
||||
---
|
||||
|
||||
# 涉及文件
|
||||
|
||||
## 需要修改的文件
|
||||
|
||||
### `@user/data-base/src/map/types.ts`
|
||||
|
||||
修改现有接口（移动相关新增类型已移至 `move/types.ts`）：
|
||||
|
||||
- [ ] `IDynamicTile` 新增 `readonly mover: IDynamicMover`
|
||||
- [ ] `IDynamicTile` 已有 `readonly faceDirection: FaceDirection` 与
|
||||
`readonly moveDirection: FaceDirection`（已在主文档确认）
|
||||
- [ ] `IObjectMovable` 接口（`x`、`y`、`moveDirection`、`faceDirection` 只读属性 +
|
||||
`setPos`/`setMoveDirection`/`setFaceDirection`，定义在 `dynamic-tile.md`）
|
||||
- [ ] `IDynamicLayer` / `IDynamicTile` 仅保留 `step(dir)` 便捷接口，
|
||||
移除 `moveDynamicWith` / `moveDynamicStep` / `moveWith` / `moveStep`
|
||||
（主文档接口汇总需同步更新）
|
||||
|
||||
#### `@user/data-base/src/map/types.ts`
|
||||
|
||||
- [ ] `DynamicMoveStepType` `const enum`：
|
||||
含 `Dir`/`DirFace`/`Speed`/`Face`/`Special`/`AnimDir` 六个成员
|
||||
- [ ] `DynamicSpecialStep` `const enum`：含 `Forward`/`Backward` 两个成员
|
||||
- [ ] `DynamicAnimDirection` `const enum`：含 `Forward`/`Backward` 两个成员
|
||||
- [ ] `IDynamicMoveStepDir` 接口（`type: DynamicMoveStepType.Dir`，`move: FaceDirection`）
|
||||
- [ ] `IDynamicMoveStepDirFace` 接口（`type: DynamicMoveStepType.DirFace`，`move`/`face: FaceDirection`）
|
||||
- [ ] `IDynamicMoveStepSpeed` 接口（`type: DynamicMoveStepType.Speed`）
|
||||
- [ ] `IDynamicMoveStepFace` 接口（`type: DynamicMoveStepType.Face`）
|
||||
- [ ] `IDynamicMoveStepSpecial` 接口（`type: Special`，`direction: DynamicSpecialStep`；无 `count` 字段，`forward(n)`/`backward(n)` 改为 push n 个步骤对象）
|
||||
- [ ] `IDynamicMoveAnimDir` 接口（`type: DynamicMoveStepType.AnimDir`，`dir: DynamicAnimDirection`）
|
||||
- [ ] `DynamicMoveStep` 联合类型（含以上六种步骤）
|
||||
- [ ] `IMoverController` 接口
|
||||
- [ ] `IObjectMoverHooks<T extends IObjectMovable>` 接口（含 `onMoveStart`/`onMoveEnd`/`onStepStart`/`onStepEnd`；
|
||||
`onStepStart`/`onStepEnd` 参数顺序为 `(code, step, tile, mover)`，按使用频率排列）
|
||||
- [ ] `IObjectMover<T extends IObjectMovable>` 接口（含 `faceDirection`/`moveDirection` 只读属性及全部计划构建方法；`step`/`stepFace` 含 `count?` 参数）
|
||||
- [ ] `IDynamicMover extends IObjectMover<IDynamicTile>`（无额外成员，继承基类全部能力；`IDynamicMoverHooks` 已移除，直接使用 `IObjectMoverHooks<IDynamicTile>`）
|
||||
|
||||
#### `@user/data-base/src/map/mover.ts`
|
||||
|
||||
- [ ] `abstract class ObjectMover<T extends IObjectMovable>` 抽象基类：
|
||||
- 实现 `IObjectMover<T>`，在此提供全部**计划构建方法**（`step`/`stepFace`/`forward`/
|
||||
`backward`/`speed`/`face`/`animDir`/`clear`/`start`）及队列执行调度逻辑；
|
||||
- 含四个**抽象方法**，子类必须实现，组成移动核心控制流：
|
||||
- `abstract onMoveStart(tile, mover): Promise<void>`: 整次移动开始时调用
|
||||
- `abstract onMoveEnd(tile, mover): Promise<void>`: 整次移动结束时调用
|
||||
- `abstract onStepStart(step, tile, mover): Promise<number>`: 单步逻辑执行前调用，
|
||||
子类计算并**返回** `code`；父类将 `code` 传给 `IObjectMoverHooks.onStepStart` 钩子后等待
|
||||
- `abstract onStepEnd(code, step, tile, mover): Promise<void>`: 单步钩子等待完成后调用，子类依据 `code` 执行本步实际逻辑效果
|
||||
- [ ] `class DynamicMover extends ObjectMover<IDynamicTile> implements IDynamicMover`：
|
||||
持有 `tile: IDynamicTile` 引用，维护 `moveQueue`、`moving`、
|
||||
`faceDirection`、`moveDirection` 状态；实现四个抽象方法（含 posMap 更新、转向逻辑等）
|
||||
- [ ] `DynamicTile` 类新增 `readonly mover: DynamicMover`，
|
||||
在构造时以 `this` 为参数创建
|
||||
|
||||
---
|
||||
|
||||
# 接口定义汇总
|
||||
|
||||
```ts
|
||||
const enum DynamicMoveStepType {
|
||||
Dir,
|
||||
DirFace,
|
||||
Speed,
|
||||
Face,
|
||||
Special,
|
||||
AnimDir
|
||||
}
|
||||
|
||||
const enum DynamicSpecialStep {
|
||||
Forward,
|
||||
Backward
|
||||
}
|
||||
|
||||
const enum DynamicAnimDirection {
|
||||
Forward,
|
||||
Backward
|
||||
}
|
||||
|
||||
interface IDynamicMoveStepDir {
|
||||
type: DynamicMoveStepType.Dir;
|
||||
move: FaceDirection;
|
||||
}
|
||||
|
||||
interface IDynamicMoveStepDirFace {
|
||||
type: DynamicMoveStepType.DirFace;
|
||||
move: FaceDirection;
|
||||
face: FaceDirection;
|
||||
}
|
||||
|
||||
interface IDynamicMoveStepSpeed {
|
||||
type: DynamicMoveStepType.Speed;
|
||||
value: number;
|
||||
}
|
||||
|
||||
interface IDynamicMoveStepFace {
|
||||
type: DynamicMoveStepType.Face;
|
||||
value: FaceDirection;
|
||||
}
|
||||
|
||||
/** forward(n)/backward(n) 构建时 n>1 会 push n 个相同步骤，步骤对象本身不携带 count */
|
||||
interface IDynamicMoveStepSpecial {
|
||||
type: DynamicMoveStepType.Special;
|
||||
direction: DynamicSpecialStep;
|
||||
}
|
||||
|
||||
interface IDynamicMoveAnimDir {
|
||||
type: DynamicMoveStepType.AnimDir;
|
||||
dir: DynamicAnimDirection;
|
||||
}
|
||||
|
||||
type DynamicMoveStep =
|
||||
| IDynamicMoveStepDir
|
||||
| IDynamicMoveStepDirFace
|
||||
| IDynamicMoveStepSpeed
|
||||
| IDynamicMoveStepFace
|
||||
| IDynamicMoveStepSpecial
|
||||
| IDynamicMoveAnimDir;
|
||||
|
||||
interface IMoverController {
|
||||
readonly done: boolean;
|
||||
readonly onEnd: Promise<void>;
|
||||
push(...steps: DynamicMoveStep[]): void;
|
||||
stop(): Promise<void>;
|
||||
}
|
||||
|
||||
interface IObjectMoverHooks<T extends IObjectMovable> extends IHookBase {
|
||||
onMoveStart(mover: IObjectMover<T>, tile: T): Promise<void>;
|
||||
onMoveEnd(mover: IObjectMover<T>, tile: T): Promise<void>;
|
||||
/** 触发时 tile.x/y 为移动前坐标，适合渲染端在此播放动画 */
|
||||
onStepStart?(
|
||||
code: number,
|
||||
step: DynamicMoveStep,
|
||||
tile: T,
|
||||
mover: IObjectMover<T>
|
||||
): Promise<void>;
|
||||
/** 触发时 tile.x/y 已更新为移动后坐标 */
|
||||
onStepEnd?(
|
||||
code: number,
|
||||
step: DynamicMoveStep,
|
||||
tile: T,
|
||||
mover: IObjectMover<T>
|
||||
): Promise<void>;
|
||||
}
|
||||
|
||||
interface IObjectMover<T extends IObjectMovable> extends IHookable<
|
||||
IObjectMoverHooks<T>
|
||||
> {
|
||||
readonly moving: boolean;
|
||||
readonly tile: T;
|
||||
readonly faceDirection: FaceDirection;
|
||||
readonly moveDirection: FaceDirection;
|
||||
|
||||
step(dir: FaceDirection, count?: number): this;
|
||||
stepFace(move: FaceDirection, face: FaceDirection, count?: number): this;
|
||||
forward(count?: number): this;
|
||||
backward(count?: number): this;
|
||||
speed(value: number): this;
|
||||
face(dir: FaceDirection): this;
|
||||
animDir(dir: DynamicAnimDirection): this;
|
||||
clear(): this;
|
||||
start(): IMoverController | null;
|
||||
}
|
||||
|
||||
// 这里的 onStepStart 不再接受 code 作为参数，因为这应当是其返回值 `Promise<number>`，
|
||||
// 具体来说，这四个方法是整个移动的核心方法而非钩子，它应当提供接口让子类实现，
|
||||
// 子类应当真正执行移动效果，并进行一定的控制。显然子类是没办法知道 onStepStart 中的信息的，
|
||||
// 所以才提供了一个 code，用于子类向 ObjectMover 提供信息，然后父类再传递给子类，
|
||||
// 从而子类了解到 onStepStart 中的信息，再进一步决定这一步真正应该如何执行。
|
||||
// 而对于钩子，实际上是在子类的 onStepStart 执行完毕后进行的，所以是知道 code 的，所以才是参数。
|
||||
// 你应该好好想一想这之间的关系。
|
||||
// 以及子类是要求必须实现的，所以不应该会有返回 `void` 的场景，四个方法都应该返回 `Promise<void>`。
|
||||
// 总的来说，父类是一个“系统级”的流程控制器，它通过这四个接口来实现真正的移动控制，
|
||||
// 就像 legacy ObjectMoverBase 中的 startMove 一样。
|
||||
abstract class ObjectMover<
|
||||
T extends IObjectMovable
|
||||
> implements IObjectMover<T> {
|
||||
abstract onMoveStart(tile: T, mover: IObjectMover<T>): Promise<void>;
|
||||
abstract onMoveEnd(tile: T, mover: IObjectMover<T>): Promise<void>;
|
||||
/** 子类计算并返回本步 code；父类取得 code 后再触发 IObjectMoverHooks.onStepStart 钩子 */
|
||||
abstract onStepStart(
|
||||
step: DynamicMoveStep,
|
||||
tile: T,
|
||||
mover: IObjectMover<T>
|
||||
): Promise<number>;
|
||||
/** 子类依据 code 执行本步实际逻辑效果；父类在此之后触发 IObjectMoverHooks.onStepEnd 钩子 */
|
||||
abstract onStepEnd(
|
||||
code: number,
|
||||
step: DynamicMoveStep,
|
||||
tile: T,
|
||||
mover: IObjectMover<T>
|
||||
): Promise<void>;
|
||||
// 计划构建方法（step/stepFace/forward/backward/speed/face/animDir/clear/start）在此实现
|
||||
}
|
||||
|
||||
// faceDirection/moveDirection 已提升至 IObjectMover，IDynamicMover 无需额外声明
|
||||
// IDynamicMoverHooks 已移除，直接使用 IObjectMoverHooks<IDynamicTile>
|
||||
interface IDynamicMover extends IObjectMover<IDynamicTile> {
|
||||
// 继承自 IObjectMover：moving, faceDirection, moveDirection, tile, 全部计划构建方法及钩子
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 问题
|
||||
|
||||
1. **`backward()` 的移动方向基准** ✅ 已确定
|
||||
|
||||
`backward()` 以 `opposite(tile.moveDirection)` 作为移动方向（基于 `moveDirection` 取反，非 `faceDirection`）。
|
||||
`moveDirection` 更新为反向，`faceDirection` 通过转向逻辑跟随同步更新。
|
||||
|
||||
2. **`forward()` 是否更新 faceDirection** ✅ 已确定
|
||||
|
||||
`forward()` 沿当前 `moveDirection` 移动，`moveDirection` 不变，
|
||||
`faceDirection` 通过转向逻辑对齐为 `moveDirection`。
|
||||
|
||||
3. **转向步触发钩子方式** ✅ 已确定
|
||||
|
||||
统一经由 `onStepStart(code, step, tile, mover)` 钩子处理，在步骤逻辑执行前触发。
|
||||
渲染端通过 `step.type === DynamicMoveStepType.Face` 区分纯转向步与位移步；
|
||||
`onStepStart` 触发时 `tile.x/y` 为原始坐标，渲染端可直接读取，无需反推。
|
||||
转向逻辑（`faceDirection`/`num` 更新）在 `onStepEnd` 阶段执行。
|
||||
|
||||
4. **`animDir` 与渲染钩子集成** ✅ 已确定
|
||||
|
||||
`onStepStart` 统一接收所有步骤，`IDynamicMoveAnimDir` 步骤本身即为信息载体。
|
||||
渲染端在 `onStepStart` 收到 `AnimDir` 步骤时更新本地动画方向状态；
|
||||
后续方向步的 `onStepStart` 触发时，渲染端依据本地状态决定动画播放方向。
|
||||
|
||||
5. **玩家移动与图块移动的复用** ✅ 已确定
|
||||
|
||||
玩家（勇士）移动逻辑与 `IDynamicMover` 高度一致，共同抽象为
|
||||
`IObjectMover<T extends IObjectMovable>`（参考 legacy `ObjectMoverBase`，适配新 API）；
|
||||
核心抽象类为 `abstract class ObjectMover<T>`，含四个抽象方法组成控制流：
|
||||
- **计划构建方法**（`step`/`stepFace`/`forward`/`backward`/
|
||||
`speed`/`face`/`animDir`/`clear`/`start`）全部在 `ObjectMover` 基类实现，子类无需重复声明。
|
||||
- **移动流程钩子**（`IObjectMoverHooks<T>`，实现 `IHookable<IObjectMoverHooks<T>>`）：
|
||||
- `onMoveStart(mover, tile)`：整次移动队列开始时触发；
|
||||
- `onMoveEnd(mover, tile)`：整次移动队列结束时触发；
|
||||
- `onStepStart(code, step, tile, mover)`：单步开始前触发（`tile.x/y` 为移动前坐标）；
|
||||
- `onStepEnd(code, step, tile, mover)`：单步完成后触发（`tile.x/y` 已更新）；
|
||||
其中 `code: number` 标识移动场景（如碰墙、遇敌、循环地图等），由具体实现层设置。
|
||||
- **四个抽象方法**（`onMoveStart`/`onMoveEnd`/`onStepStart`/`onStepEnd`）：子类（`DynamicMover`/`HeroMover`）
|
||||
通过实现这四个方法完全控制移动行为，执行流程由 `ObjectMover` 基类统一调度。
|
||||
关键：`onStepStart` 返回 `Promise<number>`（code），父类将此 code 传给钩子后再调用 `onStepEnd(code, ...)`，
|
||||
子类在 `onStepEnd` 中依据 code 执行实际状态变更。四个方法均返回 `Promise`，无 `void` 选项。
|
||||
- **泛型参数** `T extends IObjectMovable`：`IObjectMovable` 是可移动对象的最小接口
|
||||
（`x`、`y`、`moveDirection`、`faceDirection` 只读属性 +
|
||||
`setPos`/`setMoveDirection`/`setFaceDirection` 方法），定义在 `dynamic-tile.md`；
|
||||
`IDynamicTile extends IObjectMovable`，玩家侧使用 `IHeroMovable extends IObjectMovable`。
|
||||
- **`IDynamicMover extends IObjectMover<IDynamicTile>`**：
|
||||
无额外成员，直接继承基类全部能力（含 `faceDirection`/`moveDirection` 及 `IObjectMoverHooks`）。
|
||||
407
docs/dev/map/dynamic-tile.md
Normal file
407
docs/dev/map/dynamic-tile.md
Normal file
@ -0,0 +1,407 @@
|
||||
# 需求综述
|
||||
|
||||
当前地图系统仅支持静态图块（通过 `IMapLayer` / `Uint32Array` 存储），
|
||||
无法支持可移动的动态图块（例如 NPC、推箱子、可交互物件等）。
|
||||
动态图块的核心特点：
|
||||
|
||||
1. **允许重叠**——同一格点可同时存在多个动态图块；
|
||||
2. **整数坐标**——始终处于格点整数坐标，不出现小数，便于渲染优化与交互；
|
||||
3. **异步移动**——移动接口返回 `Promise`，配合渲染动画；
|
||||
4. **朝向转向**——部分图块移动时需同步更新朝向（如四方向 NPC 行走图）。
|
||||
|
||||
---
|
||||
|
||||
# 实现思路
|
||||
|
||||
## 1. 动态图块标识方案
|
||||
|
||||
**采用引用标识**：`createDynamicTile` 与 `transferToDynamic` 均返回
|
||||
`IDynamicTile` 对象引用，调用方持有该引用作为后续操作（移动、删除、
|
||||
设置朝向等）的唯一凭证。无需维护任何 ID，无唯一性管理负担。
|
||||
|
||||
调用方可将返回的 `IDynamicTile` 引用存储在自己的数据结构中，
|
||||
`tile.x`、`tile.y`、`tile.num`、`tile.direction` 等字段始终反映图块的
|
||||
最新状态——内部实现类持有可变字段，接口以 `readonly` 暴露给外部，
|
||||
保证外部不能直接修改，内部可通过类实例更新。
|
||||
|
||||
## 2. 坐标表示
|
||||
|
||||
使用独立的 `x: number, y: number` 参数，与现有 `IMapLayer` 接口风格
|
||||
（如 `setBlock(block, x, y)`、`getBlock(x, y)`）保持一致，不引入 `ITileLocator`。
|
||||
|
||||
## 3. 方向表示
|
||||
|
||||
移动方向与转向方向统一使用 `FaceDirection` 枚举：
|
||||
|
||||
- 语义明确，与已有 `IRoleFaceBinder`（朝向绑定）直接对接；
|
||||
- 已有工具函数 `getFaceMovement(dir)` 可将其转换为坐标偏移，无需重复实现；
|
||||
- 多步路径（`moveDynamicWith` 的 `steps` 参数）使用 `FaceDirection[]`。
|
||||
|
||||
`IDirectionDescriptor` 更偏向纯数学计算（用于范围迭代等），
|
||||
语义上不适合表达「图块朝向某方向移动」的含义。
|
||||
|
||||
**已确定**：移动方向（`moveDirection`）与朝向（`faceDirection`）分离为两个独立字段。
|
||||
后退等相对移动必须依赖两者分离才能正确表达（例如面朝上、向下后退时，`faceDirection`
|
||||
保持 `Up`，`moveDirection` 更新为 `Down`）。
|
||||
|
||||
移动系统另立文档独立设计，包含双方向模型、`IDynamicMover` 抽象、
|
||||
计划式移动接口及执行流程等完整方案，见
|
||||
[动态图块移动系统](./dynamic-tile-move.md)。
|
||||
|
||||
`moveDynamicStep` / `moveDynamicWith` 保留为命令式便捷接口，适用于单次简单移动；
|
||||
复杂路径和计划式移动统一使用 `IDynamicMover`。
|
||||
|
||||
## 4. 动态图块数据模型与图层归属
|
||||
|
||||
动态图块按**所属静态图层**组织层级关系：每个 `IMapLayer` 持有一个
|
||||
`IDynamicLayer`，动态图块的渲染深度即为其所属 `IMapLayer` 的 `zIndex`，
|
||||
与静态图块一致。因此 `IDynamicLayer` 接口挂载在 `IMapLayer` 上，
|
||||
而不是 `ILayerState` 上（见第 5 节）。
|
||||
|
||||
每个动态图块存储以下信息：
|
||||
|
||||
```ts
|
||||
/** 可移动对象的最小公共接口，供 `IObjectMover` 泛型约束使用 */
|
||||
interface IObjectMovable {
|
||||
readonly x: number;
|
||||
readonly y: number;
|
||||
readonly moveDirection: FaceDirection;
|
||||
readonly faceDirection: FaceDirection;
|
||||
setPos(x: number, y: number): void;
|
||||
setMoveDirection(dir: FaceDirection): void;
|
||||
setFaceDirection(dir: FaceDirection): void;
|
||||
}
|
||||
|
||||
interface IDynamicTile extends IObjectMovable {
|
||||
readonly num: number; // 图块数字（决定渲染图像）
|
||||
readonly layer: IDynamicLayer; // 所属动态图层
|
||||
readonly mover: IDynamicMover; // 绑定的移动器（计划式移动）
|
||||
/** 删除此图块，转发至 layer.deleteDynamic */
|
||||
delete(): void;
|
||||
/** 还原为静态图块，转发至 layer.transferToStatic */
|
||||
toStatic(): void;
|
||||
/** 还原为静态图块，如果当前位置有东西则不转换，转发只 layer.transferToStaticIfSafe */
|
||||
toStaticIfSafe(): boolean;
|
||||
/**
|
||||
* 单步便捷移动接口，等价于 `mover.step(dir, count); return mover.start();`。
|
||||
* 适用于简单移动场景，复杂路径通过 `tile.mover` 访问。
|
||||
*/
|
||||
step(dir: FaceDirection, count?: number): IMoverController | null;
|
||||
}
|
||||
```
|
||||
|
||||
`x`、`y`、`moveDirection`、`faceDirection` 及 `setPos`/`setMoveDirection`/`setFaceDirection`
|
||||
均由 `IObjectMovable` 提供，`IDynamicTile` 不再重复声明。
|
||||
`IObjectMover<T extends IObjectMovable>` 以此接口为泛型约束，
|
||||
使图块和玩家 mover 共享核心执行逻辑；具体渲染效果通过 `IObjectMoverHooks` 的 `onStepStart`/`onStepEnd` 钩子实现。
|
||||
|
||||
`DynamicLayer` 内部维护两个结构：
|
||||
|
||||
- `tileSet: Set<IDynamicTile>` — 所有图块的集合，用于迭代与归属判断；
|
||||
- `posMap: Map<number, Map<number, Set<IDynamicTile>>>` — 按坐标索引
|
||||
（外层 key = y，内层 key = x，value = 该格点所有图块对象集合），
|
||||
图块移动时同步更新，支持越界坐标（见第 4.1 节）。
|
||||
|
||||
调用方持有 `IDynamicTile` 对象引用即可完成所有操作，
|
||||
`posMap` 仅供按坐标查询（`getDynamicTilesAt`）使用，
|
||||
因使用频率低，嵌套 `Map` 的开销完全可以接受。
|
||||
|
||||
`IDynamicTile` 上的 `moveStep`/`moveWith`/`delete`/`setDirection`/`setPos`/`toStatic`
|
||||
均为便捷转发方法，内部直接调用 `tile.layer` 对应接口，不修改任何内部状态。
|
||||
调用方可直接通过 `tile.xxx()` 操作，无需额外持有 `IDynamicLayer` 引用。
|
||||
|
||||
### 4.1 越界移动
|
||||
|
||||
动态图块的坐标不受楼层 `width`/`height` 约束，允许出现负值或超出地图范围的坐标。
|
||||
这满足了如「图块飞出屏幕」「过场动画」等临时越界需求。
|
||||
`DynamicLayer` 无需感知楼层尺寸，`resizeLayer` 也无需通知 `DynamicLayer`。
|
||||
|
||||
## 5. IDynamicLayer 挂载在 IMapLayer 上
|
||||
|
||||
动态图块的存储结构与 `IMapLayer`（Uint32Array）本质不同，独立封装为 `IDynamicLayer`。
|
||||
`IMapLayer` 新增 `readonly dynamicLayer: IDynamicLayer` 属性，
|
||||
调用方通过具体的图层对象操作该层的动态图块，z 层级天然与静态图块一致。
|
||||
|
||||
`IDynamicLayer` 实现 `IHookable<IDynamicLayerHooks>` 以支持渲染端订阅变更事件。
|
||||
`IRoleFaceBinder` 通过 `setFaceBinder(binder)` 方法注入（见第 8 节），
|
||||
不在构造时传入，使多楼层共用同一个 `binder` 实例更灵活。
|
||||
|
||||
`transferToDynamic(x, y)` 不需要 `layer` 参数，
|
||||
因为它隶属于某个具体的 `IDynamicLayer`，直接从同级 `IMapLayer` 读写图块即可，
|
||||
并返回创建的 `IDynamicTile` 引用。
|
||||
|
||||
## 6. 移动函数的坐标来源
|
||||
|
||||
`moveDynamicStep(direction, tile)` 与 `moveDynamicWith(steps, tile)` 均不接受
|
||||
`ox, oy` 参数，改为直接接受 `IDynamicTile` 引用。当前坐标直接读取 `tile.x`、
|
||||
`tile.y`，无需调用方额外传入。
|
||||
|
||||
内部行为：
|
||||
|
||||
- 直接读取 `tile.x`、`tile.y` 作为出发点；
|
||||
- **立即**将图块逻辑坐标更新为目标位置（单步 `(tile.x+dx, tile.y+dy)`）；
|
||||
- 同步更新 `posMap`；
|
||||
- 触发 `onMoveTile` 钩子，收集所有钩子返回的 `Promise<void> | void`；
|
||||
- `await Promise.all(promises)`——
|
||||
等待所有渲染动画完成后，本步才算兑现，再进入下一步。
|
||||
|
||||
详细多步路径与计划式移动的执行流程见
|
||||
[动态图块移动系统](./dynamic-tile-move.md)。
|
||||
|
||||
## 7. transferToDynamic 与 transferToStatic
|
||||
|
||||
`transferToDynamic(x, y)` 不需要额外的 `layer` 参数。
|
||||
`DynamicLayer` 在构造时持有对所属 `MapLayer` 的引用，
|
||||
直接调用 `mapLayer.getBlock(x, y)` 读取图块数字，再调用 `mapLayer.setBlock(0, x, y)` 清除，
|
||||
最后创建对应的动态图块并返回其引用。
|
||||
若该位置图块为 0（空白），则发出 logger 警告并仍然创建 `num = 0` 的动态图块。
|
||||
|
||||
新增 `transferToStaticIfSafe(tile)` 作为安全版本：仅当目标位置静态图块为 0（空白）时才执行还原，
|
||||
否则不转换并返回 `false`；转换成功返回 `true`。适用于不确定目标格是否已有图块的场景。
|
||||
|
||||
新增 `transferToStatic(tile)` 作为逆操作：将动态图块还原为静态图块。
|
||||
对于「只移动一次就固定」的图块（如推箱子放到指定位置后不再移动），
|
||||
及时转回静态存储可以降低存档体积、简化渲染订阅。执行流程：
|
||||
|
||||
1. 读取 `tile.x`、`tile.y`、`tile.num`；
|
||||
2. 若坐标不在所属 `MapLayer` 的合法范围内（即 `x < 0`、`y < 0`、
|
||||
`x >= width` 或 `y >= height`），发出 logger 警告并放弃操作；
|
||||
3. 若 `mapLayer.getBlock(tile.x, tile.y) !== 0`，在开发环境下发出 logger 警告
|
||||
（目标格点已有静态图块内容，将被覆盖）；
|
||||
调用 `mapLayer.setBlock(tile.num, tile.x, tile.y)` 写回静态图块；
|
||||
4. 从 `tileSet` 和 `posMap` 中移除该图块，触发 `onDeleteTile` 钩子。
|
||||
|
||||
## 8. 转向逻辑
|
||||
|
||||
`moveDynamicStep` / `moveDynamicWith` 在每一步移动时自动更新朝向（使用双方向模型，
|
||||
详见 [动态图块移动系统](./dynamic-tile-move.md)）：
|
||||
|
||||
1. 更新 `tile.moveDirection` 为本步实际移动方向；
|
||||
2. 通过外部注入的 `IRoleFaceBinder` 调用 `getFaceOf(tile.num, direction)` 查询
|
||||
该方向对应的图块数字；
|
||||
3. 若图块无朝向绑定（返回 `null`），则不修改 `num`，仅更新 `faceDirection`；
|
||||
4. 若有绑定，将 `tile.num` 与 `tile.faceDirection` 更新为查询结果。
|
||||
|
||||
`IRoleFaceBinder` 通过 `setFaceBinder(binder: IRoleFaceBinder): void` 方法注入，
|
||||
不在构造时传入；初始状态视为无朝向绑定（`getFaceOf` 始终返回 `null`）。
|
||||
若多个楼层共用同一个 `RoleFaceBinder` 实例，直接对各楼层各图层分别调用 `setFaceBinder` 即可。
|
||||
|
||||
对于八方向移动，转向查询逻辑扩展如下：
|
||||
|
||||
1. 更新 `tile.moveDirection` 为本步实际移动方向；
|
||||
2. 调用 `getFaceOf(tile.num, direction)` 查询；
|
||||
3. 若返回 `null` 且当前方向为斜向（八方向之一），
|
||||
调用 `degradeFace(direction)` 降级为四方向后再查询一次；
|
||||
4. 若仍返回 `null`，不修改 `num`，仅更新 `faceDirection`；
|
||||
5. 若查询到结果，将 `tile.num` 更新为结果图块数字，并更新 `faceDirection`。
|
||||
|
||||
手动设置朝向通过独立接口 `setDynamicDirection(tile, direction)` 完成，
|
||||
逻辑与上述步骤 1–5 相同，但不触发移动。
|
||||
|
||||
## 9. IDynamicLayerHooks 与 ILayerStateHooks
|
||||
|
||||
`IDynamicLayerHooks` 定义三个钩子：
|
||||
|
||||
- `onCreateTile(tile: IDynamicTile)`：图块被创建（含转换）时触发；
|
||||
- `onDeleteTile(tile: IDynamicTile)`：图块被删除时触发（传入删除前的快照）；
|
||||
- `onMoveTile(tile: IDynamicTile, fromX: number, fromY: number): Promise<void> | void`：
|
||||
图块移动一步时触发，`tile` 为更新后的状态，`fromX`/`fromY` 为移动前坐标。
|
||||
返回 `Promise<void>` 时，移动器将等待其兑现后再进行下一步（配合 `Promise.all` 并行等待所有订阅方）。
|
||||
|
||||
`ILayerStateHooks` 新增对应的三个转发钩子，额外携带 `layer: IMapLayer` 参数，
|
||||
与现有的 `onUpdateLayerArea`、`onResizeLayer` 等钩子风格一致：
|
||||
|
||||
- `onCreateDynamicTile(layer: IMapLayer, dynamicLayer: IDynamicLayer, tile: IDynamicTile)`
|
||||
- `onDeleteDynamicTile(layer: IMapLayer, dynamicLayer: IDynamicLayer, tile: IDynamicTile)`
|
||||
- `onMoveDynamicTile(layer: IMapLayer, dynamicLayer: IDynamicLayer, tile: IDynamicTile, fromX: number, fromY: number)`
|
||||
|
||||
`LayerState` 在为每个 `MapLayer` 注册 `StateMapLayerHook` 时，
|
||||
同步订阅该层 `dynamicLayer` 的三个钩子，将事件加上 `layer`、`dynamicLayer` 参数后转发至楼层钩子。
|
||||
|
||||
---
|
||||
|
||||
# 涉及文件
|
||||
|
||||
> 移动相关的接口（`DynamicMoveDir`、`IDynamicMoveStep`、`IMoverController`、`IDynamicMover`）
|
||||
> 设计详情见 [动态图块移动系统](./dynamic-tile-move.md)，
|
||||
> 同样需要添加至 `types.ts`。
|
||||
|
||||
## 需要引用的文件
|
||||
|
||||
- `@motajs/common`：`IHookable`, `IHookBase`, `Hookable`, `logger`
|
||||
- `@user/data-base/src/common`：`FaceDirection`, `IRoleFaceBinder`,
|
||||
`getFaceMovement`, `degradeFace`
|
||||
- `@user/data-base/src/map/types.ts`：`IMapLayer`, `IMapLayerHooks`,
|
||||
`ILayerState`, `ILayerStateHooks`
|
||||
|
||||
## 需要修改的文件
|
||||
|
||||
### `@user/data-base/src/map/types.ts`
|
||||
|
||||
- [ ] 新增 `IObjectMovable` 接口：
|
||||
含 `x`、`y`、`moveDirection`、`faceDirection` 四个只读属性及
|
||||
`setPos`/`setMoveDirection`/`setFaceDirection` 三个方法；
|
||||
供 `IObjectMover<T extends IObjectMovable>` 泛型约束使用
|
||||
- [ ] 新增 `IDynamicTile extends IObjectMovable` 接口：
|
||||
含 `num`、`layer`、`mover` 三个只读属性及 `delete`/`toStatic` 两个便捷方法；
|
||||
无 `id` 字段，坐标/方向成员由 `IObjectMovable` 提供
|
||||
- [ ] 新增移动相关类型（详见移动文档接口定义汇总，已移至 `move/types.ts`）：
|
||||
`DynamicMoveStepType`、`DynamicMoveStep`、`IMoverController`、
|
||||
`IObjectMoverHooks`、`IObjectMover`、`IDynamicMover`
|
||||
- [ ] 新增 `IDynamicLayerHooks extends IHookBase` 接口：
|
||||
含 `onCreateTile`、`onDeleteTile`、`onMoveTile` 三个钩子方法
|
||||
- [ ] 新增 `IDynamicLayer extends IHookable<IDynamicLayerHooks>` 接口：
|
||||
- [ ] `createDynamicTile(num, x, y): IDynamicTile`: 在指定位置创建动态图块，
|
||||
返回图块引用
|
||||
- [ ] `transferToDynamic(x, y): IDynamicTile`: 从所属静态图层读取并清除
|
||||
指定位置图块，创建对应动态图块并返回引用
|
||||
- [ ] `transferToStatic(tile: IDynamicTile)`: 将动态图块还原为静态图块；
|
||||
坐标越界则警告并放弃，否则写回静态图层并触发 `onDeleteTile`
|
||||
- [ ] `transferToStaticIfSafe(tile: IDynamicTile): boolean`: 仅当目标位置静态图块为 0
|
||||
时才还原，否则不转换；返回是否转换成功
|
||||
- [ ] `deleteDynamicTile(tile: IDynamicTile)`: 删除指定图块，不在此层则警告
|
||||
- [ ] `getDynamicTilesAt(x, y)`: 获取指定格点所有动态图块的可迭代对象
|
||||
- [ ] `moveDynamicWith` / `moveDynamicStep` 已由 `IDynamicMover` 权其责。
|
||||
`IDynamicLayer` 不再提供此两个方法，删除对应条目。
|
||||
- [ ] `setDynamicDirection(tile: IDynamicTile, direction)`: 手动设置朝向，
|
||||
同步更新 `direction` 与 `num`（若有朝向绑定）
|
||||
- [ ] `setDynamicPos(tile: IDynamicTile, x: number, y: number)`: 直接设置图块位置，
|
||||
同步更新 `posMap`，触发 `onMoveTile` 钩子，不更新朝向
|
||||
- [ ] `setFaceBinder(binder: IRoleFaceBinder)`: 注入朝向绑定器
|
||||
- [ ] 修改 `IMapLayer`：新增 `readonly dynamicLayer: IDynamicLayer`
|
||||
- [ ] 修改 `ILayerStateHooks`：新增 `onCreateDynamicTile`、`onDeleteDynamicTile`、
|
||||
`onMoveDynamicTile` 三个转发钩子，额外携带 `layer: IMapLayer` 与
|
||||
`dynamicLayer: IDynamicLayer` 两个参数
|
||||
|
||||
### `@user/data-base/src/map/dynamicLayer.ts`（新文件）
|
||||
|
||||
- [ ] 实现 `DynamicLayer extends Hookable<IDynamicLayerHooks>` 类，
|
||||
实现 `IDynamicLayer`
|
||||
- [ ] 实现内部类 `DynamicTile implements IDynamicTile`：
|
||||
持有 `layer: IDynamicLayer` 引用，`delete`/`toStatic` 转发至 `layer`；
|
||||
`step(dir, count?)` 封装为便捷方法
|
||||
- [ ] `DynamicTile` 构造时同步创建 `readonly mover: DynamicMover`，
|
||||
移动调度由 `move/dynamicMover.ts` 中的 `DynamicMover` 类实现
|
||||
- [ ] `private mapLayer: IMapLayer`：构造参数，所属静态图层引用，
|
||||
供 `transferToDynamic` / `transferToStatic` 读写使用
|
||||
- [ ] `private faceBinder: IRoleFaceBinder | null = null`：朝向绑定器，
|
||||
通过 `setFaceBinder` 注入
|
||||
- [ ] `private tileSet: Set<IDynamicTile>`：所有图块的集合，用于迭代与归属判断
|
||||
- [ ] `private posMap: Map<number, Map<number, Set<IDynamicTile>>>`：
|
||||
按坐标索引（外层 key = y，内层 key = x），支持越界坐标
|
||||
- [ ] 实现全部接口方法，移动时同步更新 `tileSet` 与 `posMap`
|
||||
|
||||
### `@user/data-base/src/map/mapLayer.ts`
|
||||
|
||||
- [ ] 新增 `readonly dynamicLayer: DynamicLayer`：构造时以 `this` 为参数创建
|
||||
|
||||
### `@user/data-base/src/map/layerState.ts`
|
||||
|
||||
- [ ] 修改 `StateMapLayerHook`（或 `addLayer` 中的订阅逻辑）：
|
||||
在为每个 `MapLayer` 注册钩子时，同时订阅其 `dynamicLayer` 的三个钩子，
|
||||
将事件加上 `layer`、`dynamicLayer` 参数后转发至楼层的 `ILayerStateHooks`
|
||||
|
||||
---
|
||||
|
||||
# 接口定义汇总
|
||||
|
||||
以下为本次新增与修改的完整接口签名，供实现时参考。
|
||||
|
||||
移动相关接口（`IObjectMoverHooks`、`IObjectMover`、`IDynamicMover`、`IMoverController`、`DynamicMoveStep` 等）
|
||||
详见 [dynamic-tile-move.md](./dynamic-tile-move.md) 接口定义汇总，此处不再重复。
|
||||
|
||||
## 新增接口
|
||||
|
||||
### IObjectMovable
|
||||
|
||||
```ts
|
||||
interface IObjectMovable {
|
||||
readonly x: number;
|
||||
readonly y: number;
|
||||
readonly moveDirection: FaceDirection;
|
||||
readonly faceDirection: FaceDirection;
|
||||
setPos(x: number, y: number): void;
|
||||
setMoveDirection(dir: FaceDirection): void;
|
||||
setFaceDirection(dir: FaceDirection): void;
|
||||
}
|
||||
```
|
||||
|
||||
### IDynamicTile
|
||||
|
||||
```ts
|
||||
interface IDynamicTile extends IObjectMovable {
|
||||
readonly num: number;
|
||||
readonly layer: IDynamicLayer;
|
||||
readonly mover: IDynamicMover;
|
||||
delete(): void;
|
||||
toStatic(): void;
|
||||
toStaticIfSafe(): boolean;
|
||||
/** 等价于 mover.step(dir, count); return mover.start(); */
|
||||
step(dir: FaceDirection, count?: number): IMoverController | null;
|
||||
}
|
||||
```
|
||||
|
||||
### IDynamicLayerHooks
|
||||
|
||||
```ts
|
||||
interface IDynamicLayerHooks extends IHookBase {
|
||||
onCreateTile(tile: IDynamicTile, layer: IDynamicLayer): void;
|
||||
onDeleteTile(tile: IDynamicTile, layer: IDynamicLayer): void;
|
||||
}
|
||||
```
|
||||
|
||||
### IDynamicLayer
|
||||
|
||||
```ts
|
||||
interface IDynamicLayer extends IHookable<IDynamicLayerHooks> {
|
||||
createDynamic(num: number, x: number, y: number): IDynamicTile;
|
||||
transferToDynamic(x: number, y: number): IDynamicTile;
|
||||
transferToStatic(tile: IDynamicTile): void;
|
||||
transferToStaticIfSafe(tile: IDynamicTile): boolean;
|
||||
deleteDynamic(tile: IDynamicTile): void;
|
||||
getDynamicTilesAt(x: number, y: number): Iterable<IDynamicTile>;
|
||||
setDynamicDirection(tile: IDynamicTile, direction: FaceDirection): void;
|
||||
setDynamicPos(tile: IDynamicTile, x: number, y: number): void;
|
||||
setFaceBinder(binder: IRoleFaceBinder): void;
|
||||
}
|
||||
```
|
||||
|
||||
## 修改接口
|
||||
|
||||
### IMapLayer（新增属性）
|
||||
|
||||
```ts
|
||||
interface IMapLayer {
|
||||
// ...现有成员...
|
||||
readonly dynamicLayer: IDynamicLayer;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 问题
|
||||
|
||||
1. **`ox, oy` 是否为必要参数？** ✅ 已确定
|
||||
|
||||
已确定移除。调用方持有 `IDynamicTile` 引用，坐标直接从 `tile.x`、`tile.y` 读取，
|
||||
`ox, oy` 为冗余参数，接口简化为 `moveDynamicStep(direction, tile)` 和
|
||||
`moveDynamicWith(steps, tile)`。
|
||||
|
||||
2. **`IRoleFaceBinder` 的注入方式** ✅ 已确定
|
||||
|
||||
已确定使用 `setFaceBinder(binder)` 方法注入，不在构造时传入。
|
||||
实际修改 `faceBinder` 的场景极少，接口保持简单。
|
||||
|
||||
3. **动态图块的存档支持** ⏸ 暂缓
|
||||
|
||||
动态图块状态（NPC 当前位置、推箱子位置等）属于游戏核心存档内容，
|
||||
长期来看必须纳入存档体系。但当前设计与旧引擎完全不同，
|
||||
存档格式需从头设计，建议在动态图块功能稳定后单独立项设计存档方案。
|
||||
**本次实现不涉及存档，`IDynamicLayer` 暂不实现 `ISaveableContent`。**
|
||||
|
||||
4. **`IDynamicLayer` 是否需要感知楼层尺寸** ✅ 已确定
|
||||
|
||||
已确定不感知。标识方案改为引用，`posMap` 同步改为
|
||||
`Map<number, Map<number, Set<IDynamicTile>>>` 嵌套结构（外层 key = y，内层 key = x），
|
||||
彻底去掉字符串键，天然支持越界坐标，`resizeLayer` 无需通知 `DynamicLayer`。
|
||||
`getDynamicTilesAt` 接口保留，使用频率低，嵌套 Map 开销完全可接受。
|
||||
@ -1,3 +1,4 @@
|
||||
export * from './face';
|
||||
export * from './mover';
|
||||
export * from './types';
|
||||
export * from './utils';
|
||||
|
||||
579
packages-user/data-base/src/common/mover.ts
Normal file
579
packages-user/data-base/src/common/mover.ts
Normal file
@ -0,0 +1,579 @@
|
||||
import {
|
||||
Hookable,
|
||||
HookController,
|
||||
IHookable,
|
||||
IHookBase,
|
||||
IHookController,
|
||||
ITileLocator
|
||||
} from '@motajs/common';
|
||||
import { FaceDirection } from './types';
|
||||
|
||||
//#region 对象移动
|
||||
|
||||
export const enum ObjectMoveStepType {
|
||||
/** 绝对方向步，同步更新移动方向与朝向 */
|
||||
Dir,
|
||||
/** 绝对方向步，显式指定朝向 */
|
||||
DirFace,
|
||||
/** 速度步 */
|
||||
Speed,
|
||||
/** 纯转向步 */
|
||||
Face,
|
||||
/** 特殊步，如前进或后退 */
|
||||
Special,
|
||||
/** 动画方向步 */
|
||||
AnimDir
|
||||
}
|
||||
|
||||
export const enum ObjectSpecialStep {
|
||||
/** 前进 */
|
||||
Forward,
|
||||
/** 后退 */
|
||||
Backward
|
||||
}
|
||||
|
||||
export const enum ObjectAnimDirection {
|
||||
/** 正向播放动画 */
|
||||
Forward,
|
||||
/** 反向播放动画 */
|
||||
Backward
|
||||
}
|
||||
|
||||
export interface IObjectMovable {
|
||||
/** 当前横坐标 */
|
||||
readonly x: number;
|
||||
/** 当前纵坐标 */
|
||||
readonly y: number;
|
||||
|
||||
/**
|
||||
* 设置对象位置
|
||||
* @param x 横坐标
|
||||
* @param y 纵坐标
|
||||
*/
|
||||
setPos(x: number, y: number): void;
|
||||
|
||||
/**
|
||||
* 获取当前朝向
|
||||
*/
|
||||
getCurrentFaceDirection(): FaceDirection;
|
||||
}
|
||||
|
||||
export interface IObjectMoveStepDir {
|
||||
/** 步骤类型 */
|
||||
type: ObjectMoveStepType.Dir;
|
||||
/** 本步移动方向 */
|
||||
move: FaceDirection;
|
||||
}
|
||||
|
||||
export interface IObjectMoveStepDirFace {
|
||||
/** 步骤类型 */
|
||||
type: ObjectMoveStepType.DirFace;
|
||||
/** 本步移动方向 */
|
||||
move: FaceDirection;
|
||||
/** 本步显式朝向 */
|
||||
face: FaceDirection;
|
||||
}
|
||||
|
||||
export interface IObjectMoveStepSpeed {
|
||||
/** 步骤类型 */
|
||||
type: ObjectMoveStepType.Speed;
|
||||
/** 后续移动的每格耗时，单位为 ms */
|
||||
value: number;
|
||||
}
|
||||
|
||||
export interface IObjectMoveStepFace {
|
||||
/** 步骤类型 */
|
||||
type: ObjectMoveStepType.Face;
|
||||
/** 要设置的朝向 */
|
||||
value: FaceDirection;
|
||||
}
|
||||
|
||||
export interface IObjectMoveStepSpecial {
|
||||
/** 步骤类型 */
|
||||
type: ObjectMoveStepType.Special;
|
||||
/** 特殊步方向 */
|
||||
direction: ObjectSpecialStep;
|
||||
}
|
||||
|
||||
export interface IObjectMoveAnimDir {
|
||||
/** 步骤类型 */
|
||||
type: ObjectMoveStepType.AnimDir;
|
||||
/** 动画播放方向 */
|
||||
dir: ObjectAnimDirection;
|
||||
}
|
||||
|
||||
export type ObjectMoveStep =
|
||||
| IObjectMoveStepDir
|
||||
| IObjectMoveStepDirFace
|
||||
| IObjectMoveStepSpeed
|
||||
| IObjectMoveStepFace
|
||||
| IObjectMoveStepSpecial
|
||||
| IObjectMoveAnimDir;
|
||||
|
||||
export interface IMoverController {
|
||||
/** 本次移动是否已经全部完成 */
|
||||
done: boolean;
|
||||
/** 当本次移动结束时兑现 */
|
||||
onEnd: Promise<void>;
|
||||
|
||||
/**
|
||||
* 向当前移动队列末尾追加步骤
|
||||
* @param steps 要追加的步骤列表
|
||||
*/
|
||||
push(...steps: ObjectMoveStep[]): void;
|
||||
|
||||
/**
|
||||
* 在当前步移动之后立刻插入指定步，顺序为参数传入的顺序
|
||||
* @param steps 要插入的步骤列表
|
||||
*/
|
||||
insert(...steps: ObjectMoveStep[]): void;
|
||||
|
||||
/**
|
||||
* 停止当前移动，在当前步骤完成后兑现
|
||||
*/
|
||||
stop(): Promise<void>;
|
||||
}
|
||||
|
||||
export interface IObjectMoverHooks<T extends IObjectMovable> extends IHookBase {
|
||||
/**
|
||||
* 当移动开始时触发
|
||||
* @param tile 移动器绑定的图块
|
||||
* @param mover 当前移动器
|
||||
*/
|
||||
onMoveStart?(tile: T, mover: IObjectMover<T>): Promise<void>;
|
||||
|
||||
/**
|
||||
* 当移动结束时触发
|
||||
* @param tile 移动器绑定的图块
|
||||
* @param mover 当前移动器
|
||||
*/
|
||||
onMoveEnd?(tile: T, mover: IObjectMover<T>): Promise<void>;
|
||||
|
||||
/**
|
||||
* 当单步移动开始前触发，此时对象坐标仍为移动前坐标
|
||||
* @param code 当前步移动代码
|
||||
* @param step 当前步骤
|
||||
* @param tile 移动器绑定的图块
|
||||
* @param mover 当前移动器
|
||||
*/
|
||||
onStepStart?(
|
||||
code: number,
|
||||
step: ObjectMoveStep,
|
||||
tile: T,
|
||||
mover: IObjectMover<T>
|
||||
): Promise<void>;
|
||||
|
||||
/**
|
||||
* 当单步移动结束后触发，此时对象坐标已更新为移动后坐标
|
||||
* @param code 当前步移动代码
|
||||
* @param step 当前步骤
|
||||
* @param tile 移动器绑定的图块
|
||||
* @param mover 当前移动器
|
||||
*/
|
||||
onStepEnd?(
|
||||
code: number,
|
||||
step: ObjectMoveStep,
|
||||
tile: T,
|
||||
mover: IObjectMover<T>
|
||||
): Promise<void>;
|
||||
}
|
||||
|
||||
export interface IObjectMover<T extends IObjectMovable> extends IHookable<
|
||||
IObjectMoverHooks<T>
|
||||
> {
|
||||
/** 当前是否正在移动 */
|
||||
readonly moving: boolean;
|
||||
/** 当前绑定的对象 */
|
||||
readonly tile: T;
|
||||
/** 当前朝向 */
|
||||
readonly faceDirection: FaceDirection;
|
||||
/** 当前移动方向 */
|
||||
readonly moveDirection: FaceDirection;
|
||||
/** 当前动画播放方向 */
|
||||
readonly currAnimDir: ObjectAnimDirection;
|
||||
/** 当前移动速度，单位毫秒 */
|
||||
readonly currentSpeed: number;
|
||||
|
||||
/**
|
||||
* 追加若干个绝对方向步，并同步更新移动方向与朝向
|
||||
* @param dir 移动方向
|
||||
* @param count 追加次数，默认 1
|
||||
*/
|
||||
step(dir: FaceDirection, count?: number): this;
|
||||
|
||||
/**
|
||||
* 追加若干个绝对方向步，移动方向与朝向分别指定
|
||||
* @param move 移动方向
|
||||
* @param face 朝向方向
|
||||
* @param count 追加次数，默认 1
|
||||
*/
|
||||
stepFace(move: FaceDirection, face: FaceDirection, count?: number): this;
|
||||
|
||||
/**
|
||||
* 追加若干个前进步，沿当前移动方向移动
|
||||
* @param count 追加次数，默认 1
|
||||
*/
|
||||
forward(count?: number): this;
|
||||
|
||||
/**
|
||||
* 追加若干个后退步，沿当前移动方向的反方向移动
|
||||
* @param count 追加次数，默认 1
|
||||
*/
|
||||
backward(count?: number): this;
|
||||
|
||||
/**
|
||||
* 设置后续移动速度
|
||||
* @param value 每格耗时，单位为 ms
|
||||
*/
|
||||
speed(value: number): this;
|
||||
|
||||
/**
|
||||
* 追加一个纯转向步骤
|
||||
* @param dir 目标朝向
|
||||
*/
|
||||
face(dir: FaceDirection): this;
|
||||
|
||||
/**
|
||||
* 设置后续步骤的动画播放方向
|
||||
* @param dir 动画播放方向
|
||||
*/
|
||||
animDir(dir: ObjectAnimDirection): this;
|
||||
|
||||
/**
|
||||
* 清空尚未执行的步骤队列
|
||||
*/
|
||||
clear(): this;
|
||||
|
||||
/**
|
||||
* 开始执行当前计划队列
|
||||
* @returns 若当前已在移动，则返回 `null`
|
||||
*/
|
||||
start(): Readonly<IMoverController> | null;
|
||||
}
|
||||
|
||||
//#endregion
|
||||
|
||||
//#region 移动基类
|
||||
|
||||
export abstract class ObjectMover<T extends IObjectMovable>
|
||||
extends Hookable<IObjectMoverHooks<T>>
|
||||
implements IObjectMover<T>
|
||||
{
|
||||
abstract readonly tile: T;
|
||||
|
||||
/** 尚未开始执行的移动步骤队列 */
|
||||
protected readonly moveQueue: Readonly<ObjectMoveStep>[] = [];
|
||||
|
||||
/** 当前是否正在移动 */
|
||||
moving: boolean = false;
|
||||
/** 当前朝向 */
|
||||
faceDirection: FaceDirection = FaceDirection.Unknown;
|
||||
/** 当前移动方向 */
|
||||
moveDirection: FaceDirection = FaceDirection.Unknown;
|
||||
/** 当前动画播放方向 */
|
||||
currAnimDir: ObjectAnimDirection = ObjectAnimDirection.Forward;
|
||||
/** 当前移动速度，单位毫秒 */
|
||||
currentSpeed: number = 100;
|
||||
|
||||
/** 是否调用了 `IMoverController.stop` 接口 */
|
||||
private shouldStop: boolean = false;
|
||||
|
||||
protected createController(
|
||||
hook: Partial<IObjectMoverHooks<T>>
|
||||
): IHookController<IObjectMoverHooks<T>> {
|
||||
return new HookController(this, hook);
|
||||
}
|
||||
|
||||
/**
|
||||
* 当移动开始时执行
|
||||
* @param tile 移动图块
|
||||
* @param controller 移动控制器
|
||||
*/
|
||||
protected abstract onMoveStart(
|
||||
tile: T,
|
||||
controller: Readonly<IMoverController>
|
||||
): Promise<void>;
|
||||
|
||||
/**
|
||||
* 当移动结束时触发
|
||||
* @param tile 移动图块
|
||||
* @param controller 移动控制器
|
||||
*/
|
||||
protected abstract onMoveEnd(
|
||||
tile: T,
|
||||
controller: Readonly<IMoverController>
|
||||
): Promise<void>;
|
||||
|
||||
/**
|
||||
* 当单步移动开始时触发，返回移动代码，此移动代码将会传递至 {@link onStepEnd}
|
||||
* @param step 当前移动步对象
|
||||
* @param tile 移动图块
|
||||
* @param controller 移动控制器
|
||||
*/
|
||||
protected abstract onStepStart(
|
||||
step: ObjectMoveStep,
|
||||
tile: T,
|
||||
controller: Readonly<IMoverController>
|
||||
): Promise<number>;
|
||||
|
||||
/**
|
||||
* 当单步移动结束时触发，返回坐标对象代表这一步移动结果
|
||||
* @param code 移动代码，由 {@link onStepStart} 返回值传递而来
|
||||
* @param step 当前移动步对象
|
||||
* @param tile 移动图块
|
||||
* @param controller 移动控制器
|
||||
*/
|
||||
protected abstract onStepEnd(
|
||||
code: number,
|
||||
step: ObjectMoveStep,
|
||||
tile: T,
|
||||
controller: Readonly<IMoverController>
|
||||
): Promise<ITileLocator>;
|
||||
|
||||
/**
|
||||
* 向计划队列末尾追加一个步骤
|
||||
* @param step 要追加的步骤
|
||||
*/
|
||||
protected pushStep(step: Readonly<ObjectMoveStep>): void {
|
||||
this.moveQueue.push(step);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取当前应当作为相对移动基准的方向
|
||||
*/
|
||||
private getCurrentDirection(): FaceDirection {
|
||||
if (this.moveDirection !== FaceDirection.Unknown) {
|
||||
return this.moveDirection;
|
||||
} else {
|
||||
return this.faceDirection;
|
||||
}
|
||||
}
|
||||
|
||||
// TODO: 需要做一个朝向系统以解决朝向难以处理的问题
|
||||
/**
|
||||
* 获取指定方向的反方向
|
||||
* @param dir 当前方向
|
||||
*/
|
||||
private getOppositeDirection(dir: FaceDirection): FaceDirection {
|
||||
switch (dir) {
|
||||
case FaceDirection.Left:
|
||||
return FaceDirection.Right;
|
||||
case FaceDirection.Up:
|
||||
return FaceDirection.Down;
|
||||
case FaceDirection.Right:
|
||||
return FaceDirection.Left;
|
||||
case FaceDirection.Down:
|
||||
return FaceDirection.Up;
|
||||
case FaceDirection.LeftUp:
|
||||
return FaceDirection.RightDown;
|
||||
case FaceDirection.RightUp:
|
||||
return FaceDirection.LeftDown;
|
||||
case FaceDirection.LeftDown:
|
||||
return FaceDirection.RightUp;
|
||||
case FaceDirection.RightDown:
|
||||
return FaceDirection.LeftUp;
|
||||
case FaceDirection.Unknown:
|
||||
return FaceDirection.Unknown;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 根据步骤内容预先同步移动器内部状态
|
||||
* @param step 当前步骤
|
||||
*/
|
||||
private prepareStep(step: ObjectMoveStep): void {
|
||||
switch (step.type) {
|
||||
case ObjectMoveStepType.Dir:
|
||||
this.moveDirection = step.move;
|
||||
this.faceDirection = step.move;
|
||||
break;
|
||||
case ObjectMoveStepType.DirFace:
|
||||
this.moveDirection = step.move;
|
||||
this.faceDirection = step.face;
|
||||
break;
|
||||
case ObjectMoveStepType.Face:
|
||||
this.faceDirection = step.value;
|
||||
break;
|
||||
case ObjectMoveStepType.Special: {
|
||||
const dir = this.getCurrentDirection();
|
||||
if (step.direction === ObjectSpecialStep.Backward) {
|
||||
const opposite = this.getOppositeDirection(dir);
|
||||
this.moveDirection = opposite;
|
||||
this.faceDirection = opposite;
|
||||
} else {
|
||||
this.moveDirection = dir;
|
||||
this.faceDirection = dir;
|
||||
}
|
||||
break;
|
||||
}
|
||||
case ObjectMoveStepType.AnimDir:
|
||||
this.currAnimDir = step.dir;
|
||||
break;
|
||||
case ObjectMoveStepType.Speed:
|
||||
this.currentSpeed = step.value;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
step(dir: FaceDirection, count: number = 1): this {
|
||||
for (let i = 0; i < count; i++) {
|
||||
this.pushStep({
|
||||
type: ObjectMoveStepType.Dir,
|
||||
move: dir
|
||||
});
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
stepFace(
|
||||
move: FaceDirection,
|
||||
face: FaceDirection,
|
||||
count: number = 1
|
||||
): this {
|
||||
for (let i = 0; i < count; i++) {
|
||||
this.pushStep({
|
||||
type: ObjectMoveStepType.DirFace,
|
||||
move,
|
||||
face
|
||||
});
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
forward(count: number = 1): this {
|
||||
for (let i = 0; i < count; i++) {
|
||||
this.pushStep({
|
||||
type: ObjectMoveStepType.Special,
|
||||
direction: ObjectSpecialStep.Forward
|
||||
});
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
backward(count: number = 1): this {
|
||||
for (let i = 0; i < count; i++) {
|
||||
this.pushStep({
|
||||
type: ObjectMoveStepType.Special,
|
||||
direction: ObjectSpecialStep.Backward
|
||||
});
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
speed(value: number): this {
|
||||
this.pushStep({
|
||||
type: ObjectMoveStepType.Speed,
|
||||
value
|
||||
});
|
||||
return this;
|
||||
}
|
||||
|
||||
face(dir: FaceDirection): this {
|
||||
this.pushStep({
|
||||
type: ObjectMoveStepType.Face,
|
||||
value: dir
|
||||
});
|
||||
return this;
|
||||
}
|
||||
|
||||
animDir(dir: ObjectAnimDirection): this {
|
||||
this.pushStep({
|
||||
type: ObjectMoveStepType.AnimDir,
|
||||
dir
|
||||
});
|
||||
return this;
|
||||
}
|
||||
|
||||
clear(): this {
|
||||
this.moveQueue.length = 0;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 开始移动流程
|
||||
* @param queue 移动队列
|
||||
*/
|
||||
private async moveProgress(
|
||||
queue: ObjectMoveStep[],
|
||||
controller: Readonly<IMoverController>
|
||||
) {
|
||||
// 移动开始
|
||||
await this.onMoveStart(this.tile, controller);
|
||||
await Promise.all(
|
||||
this.forEachHook(hook => {
|
||||
return hook.onMoveStart?.(this.tile, this);
|
||||
})
|
||||
);
|
||||
|
||||
// 移动流程
|
||||
while (queue.length > 0) {
|
||||
const step = queue.shift();
|
||||
if (!step || !this.moving || this.shouldStop) break;
|
||||
this.prepareStep(step);
|
||||
const code = await this.onStepStart(step, this.tile, controller);
|
||||
const stepStartHooks = this.forEachHook(hook =>
|
||||
hook.onStepStart?.(code, step, this.tile, this)
|
||||
);
|
||||
await Promise.all(stepStartHooks);
|
||||
const loc = await this.onStepEnd(code, step, this.tile, controller);
|
||||
this.tile.setPos(loc.x, loc.y);
|
||||
const stepEndHooks = this.forEachHook(hook =>
|
||||
hook.onStepEnd?.(code, step, this.tile, this)
|
||||
);
|
||||
await Promise.all(stepEndHooks);
|
||||
}
|
||||
|
||||
// 移动结束
|
||||
await this.onMoveEnd(this.tile, controller);
|
||||
const moveEndHooks = this.forEachHook(hook =>
|
||||
hook.onMoveEnd?.(this.tile, this)
|
||||
);
|
||||
await Promise.all(moveEndHooks);
|
||||
}
|
||||
|
||||
start(): IMoverController | null {
|
||||
if (this.moving) return null;
|
||||
|
||||
const queue = this.moveQueue.slice();
|
||||
this.clear();
|
||||
this.shouldStop = false;
|
||||
|
||||
this.faceDirection = this.tile.getCurrentFaceDirection();
|
||||
this.moveDirection = FaceDirection.Unknown;
|
||||
|
||||
const { promise, resolve } = Promise.withResolvers<void>();
|
||||
|
||||
const controller: IMoverController = {
|
||||
done: false,
|
||||
onEnd: promise,
|
||||
push: (...steps: ObjectMoveStep[]) => {
|
||||
if (!this.moving || this.shouldStop || controller.done) {
|
||||
return;
|
||||
}
|
||||
queue.push(...steps);
|
||||
},
|
||||
insert: (...steps: ObjectMoveStep[]) => {
|
||||
if (!this.moving || this.shouldStop || controller.done) {
|
||||
return;
|
||||
}
|
||||
queue.unshift(...steps);
|
||||
},
|
||||
stop: () => {
|
||||
this.shouldStop = true;
|
||||
return controller.onEnd;
|
||||
}
|
||||
};
|
||||
|
||||
this.moving = true;
|
||||
const moving = this.moveProgress(queue, controller);
|
||||
moving.then(() => {
|
||||
this.moving = false;
|
||||
controller.done = true;
|
||||
resolve();
|
||||
});
|
||||
|
||||
return controller;
|
||||
}
|
||||
}
|
||||
|
||||
//#endregion
|
||||
142
packages-user/data-base/src/map/dynamicLayer.ts
Normal file
142
packages-user/data-base/src/map/dynamicLayer.ts
Normal file
@ -0,0 +1,142 @@
|
||||
import {
|
||||
HookController,
|
||||
Hookable,
|
||||
IHookController,
|
||||
ITileLocator,
|
||||
logger
|
||||
} from '@motajs/common';
|
||||
import {
|
||||
IDynamicLayer,
|
||||
IDynamicLayerHooks,
|
||||
IDynamicTile,
|
||||
IMapLayer
|
||||
} from './types';
|
||||
import { FaceDirection, degradeFace } from '../common';
|
||||
import { DynamicTile } from './dynamicTile';
|
||||
|
||||
export class DynamicLayer
|
||||
extends Hookable<IDynamicLayerHooks>
|
||||
implements IDynamicLayer
|
||||
{
|
||||
/** 坐标到动态图块集合的映射，外层 key = y，内层 key = x，不使用 index 是为了支持地图外图块 */
|
||||
private readonly tilePosMap: Map<number, Map<number, Set<IDynamicTile>>> =
|
||||
new Map();
|
||||
/** 动态图块到其当前坐标的映射 */
|
||||
private readonly posTileMap: Map<IDynamicTile, ITileLocator> = new Map();
|
||||
|
||||
constructor(public readonly layer: IMapLayer) {
|
||||
super();
|
||||
}
|
||||
|
||||
protected createController(
|
||||
hook: Partial<IDynamicLayerHooks>
|
||||
): IHookController<IDynamicLayerHooks> {
|
||||
return new HookController(this, hook);
|
||||
}
|
||||
|
||||
createDynamic(num: number, x: number, y: number): IDynamicTile {
|
||||
const tile = new DynamicTile(num, x, y, this);
|
||||
this.addTileToPosMap(tile, x, y);
|
||||
this.posTileMap.set(tile, { x, y });
|
||||
this.forEachHook(hook => hook.onCreateTile?.(tile, this));
|
||||
return tile;
|
||||
}
|
||||
|
||||
transferToDynamic(x: number, y: number): IDynamicTile {
|
||||
const num = this.layer.getBlock(x, y);
|
||||
if (num === 0) {
|
||||
logger.warn(127, x.toString(), y.toString());
|
||||
}
|
||||
this.layer.setBlock(0, x, y);
|
||||
return this.createDynamic(num, x, y);
|
||||
}
|
||||
|
||||
transferToStatic(tile: IDynamicTile): void {
|
||||
const { x, y } = tile;
|
||||
const { width, height } = this.layer;
|
||||
if (x < 0 || y < 0 || x >= width || y >= height) {
|
||||
logger.warn(128, x.toString(), y.toString());
|
||||
return;
|
||||
}
|
||||
if (this.layer.getBlock(x, y) !== 0) {
|
||||
logger.warn(129, x.toString(), y.toString());
|
||||
}
|
||||
this.layer.setBlock(tile.num, x, y);
|
||||
this.removeTile(tile);
|
||||
this.forEachHook(hook => {
|
||||
void hook.onDeleteTile?.(tile, this);
|
||||
});
|
||||
}
|
||||
|
||||
transferToStaticIfSafe(tile: IDynamicTile): boolean {
|
||||
if (this.layer.getBlock(tile.x, tile.y) !== 0) return false;
|
||||
this.layer.setBlock(tile.num, tile.x, tile.y);
|
||||
this.deleteDynamic(tile);
|
||||
return true;
|
||||
}
|
||||
|
||||
async deleteDynamic(tile: IDynamicTile): Promise<void> {
|
||||
if (!this.posTileMap.has(tile)) {
|
||||
logger.warn(130);
|
||||
return;
|
||||
}
|
||||
this.removeTile(tile);
|
||||
const hooks = this.forEachHook(hook => hook.onDeleteTile?.(tile, this));
|
||||
await Promise.all(hooks);
|
||||
}
|
||||
|
||||
getDynamicTilesAt(x: number, y: number): Iterable<IDynamicTile> {
|
||||
return this.tilePosMap.get(y)?.get(x) ?? new Set();
|
||||
}
|
||||
|
||||
iterateDynamicTiles(): Iterable<IDynamicTile> {
|
||||
return this.posTileMap.keys();
|
||||
}
|
||||
|
||||
setDynamicDirection(tile: IDynamicTile, direction: FaceDirection): void {
|
||||
const numBefore = tile.num;
|
||||
tile.setFaceDirection(direction);
|
||||
if (tile.num !== numBefore) return;
|
||||
const degraded = degradeFace(direction);
|
||||
if (degraded !== direction) {
|
||||
tile.setFaceDirection(degraded);
|
||||
}
|
||||
}
|
||||
|
||||
updateDynamicTile(tile: IDynamicTile): void {
|
||||
const oldPos = this.posTileMap.get(tile);
|
||||
if (oldPos) {
|
||||
this.removeTileFromPosMap(tile, oldPos.x, oldPos.y);
|
||||
oldPos.x = tile.x;
|
||||
oldPos.y = tile.y;
|
||||
this.addTileToPosMap(tile, tile.x, tile.y);
|
||||
} else {
|
||||
this.addTileToPosMap(tile, tile.x, tile.y);
|
||||
this.posTileMap.set(tile, { x: tile.x, y: tile.y });
|
||||
}
|
||||
this.forEachHook(hook => hook.onUpdateTilePosition?.(tile, this));
|
||||
}
|
||||
|
||||
private addTileToPosMap(tile: IDynamicTile, x: number, y: number): void {
|
||||
const xMap = this.tilePosMap.getOrInsertComputed(y, () => new Map());
|
||||
const set = xMap.getOrInsertComputed(x, () => new Set());
|
||||
set.add(tile);
|
||||
}
|
||||
|
||||
private removeTileFromPosMap(
|
||||
tile: IDynamicTile,
|
||||
x: number,
|
||||
y: number
|
||||
): void {
|
||||
this.tilePosMap.get(y)?.get(x)?.delete(tile);
|
||||
}
|
||||
|
||||
/** 从两个内部映射中移除图块记录 */
|
||||
private removeTile(tile: IDynamicTile): void {
|
||||
const pos = this.posTileMap.get(tile);
|
||||
if (pos) {
|
||||
this.removeTileFromPosMap(tile, pos.x, pos.y);
|
||||
}
|
||||
this.posTileMap.delete(tile);
|
||||
}
|
||||
}
|
||||
72
packages-user/data-base/src/map/dynamicTile.ts
Normal file
72
packages-user/data-base/src/map/dynamicTile.ts
Normal file
@ -0,0 +1,72 @@
|
||||
import { isNil } from 'lodash-es';
|
||||
import {
|
||||
FaceDirection,
|
||||
IMoverController,
|
||||
IObjectMover,
|
||||
IRoleFaceBinder
|
||||
} from '../common';
|
||||
import { IDynamicLayer, IDynamicTile } from './types';
|
||||
import { DynamicTileMover } from './mover';
|
||||
|
||||
export class DynamicTile implements IDynamicTile {
|
||||
readonly mover: IObjectMover<IDynamicTile>;
|
||||
|
||||
/** 当前的朝向绑定对象 */
|
||||
private face: IRoleFaceBinder | null = null;
|
||||
|
||||
constructor(
|
||||
public num: number,
|
||||
public x: number,
|
||||
public y: number,
|
||||
public readonly layer: IDynamicLayer
|
||||
) {
|
||||
this.mover = new DynamicTileMover(this);
|
||||
}
|
||||
|
||||
setFaceBinder(binder: IRoleFaceBinder | null): void {
|
||||
this.face = binder;
|
||||
}
|
||||
|
||||
setFaceDirection(direction: FaceDirection): number {
|
||||
if (!this.face) return this.num;
|
||||
const next = this.face.getFaceOf(this.num, direction);
|
||||
if (next) {
|
||||
this.num = next.identifier;
|
||||
}
|
||||
return this.num;
|
||||
}
|
||||
|
||||
delete(): Promise<void> {
|
||||
return this.layer.deleteDynamic(this);
|
||||
}
|
||||
|
||||
toStatic(): void {
|
||||
this.layer.transferToStatic(this);
|
||||
}
|
||||
|
||||
toStaticIfSafe(): boolean {
|
||||
return this.layer.transferToStaticIfSafe(this);
|
||||
}
|
||||
|
||||
step(dir: FaceDirection, count?: number): IMoverController | null {
|
||||
if (this.mover.moving) return null;
|
||||
this.mover.step(dir, count);
|
||||
return this.mover.start();
|
||||
}
|
||||
|
||||
setPos(x: number, y: number): void {
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
this.layer.updateDynamicTile(this);
|
||||
}
|
||||
|
||||
getCurrentFaceDirection(): FaceDirection {
|
||||
if (this.face) {
|
||||
const face = this.face.getFaceDirection(this.num);
|
||||
if (isNil(face)) return FaceDirection.Unknown;
|
||||
else return face;
|
||||
} else {
|
||||
return FaceDirection.Down;
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,4 +1,5 @@
|
||||
export * from './layerState';
|
||||
export * from './mapLayer';
|
||||
export * from './mapStore';
|
||||
export * from './mover';
|
||||
export * from './types';
|
||||
|
||||
@ -1,11 +1,13 @@
|
||||
import { isNil } from 'lodash-es';
|
||||
import {
|
||||
IDynamicLayer,
|
||||
IMapLayer,
|
||||
IMapLayerData,
|
||||
IMapLayerHookController,
|
||||
IMapLayerHooks
|
||||
} from './types';
|
||||
import { Hookable, HookController, logger } from '@motajs/common';
|
||||
import { DynamicLayer } from './dynamicLayer';
|
||||
|
||||
// todo: 提供 core.setBlock 等方法的替代方法，同时添加 setBlockList，以及前景背景的接口
|
||||
|
||||
@ -23,6 +25,8 @@ export class MapLayer
|
||||
/** 地图数据引用 */
|
||||
private mapData: IMapLayerData;
|
||||
|
||||
readonly dynamicLayer: IDynamicLayer;
|
||||
|
||||
constructor(array: Uint32Array, width: number, height: number) {
|
||||
super();
|
||||
this.width = width;
|
||||
@ -35,6 +39,7 @@ export class MapLayer
|
||||
expired: false,
|
||||
array: this.mapArray
|
||||
};
|
||||
this.dynamicLayer = new DynamicLayer(this);
|
||||
}
|
||||
|
||||
resize(width: number, height: number): void {
|
||||
|
||||
78
packages-user/data-base/src/map/mover.ts
Normal file
78
packages-user/data-base/src/map/mover.ts
Normal file
@ -0,0 +1,78 @@
|
||||
import { ITileLocator, logger } from '@motajs/common';
|
||||
import {
|
||||
getFaceMovement,
|
||||
ObjectMover,
|
||||
ObjectMoveStep,
|
||||
ObjectMoveStepType
|
||||
} from '../common';
|
||||
import { IDynamicTile } from './types';
|
||||
|
||||
//#region 动态图块
|
||||
|
||||
const enum DynamicMoveCode {
|
||||
/** 正常执行 */
|
||||
Success
|
||||
}
|
||||
|
||||
export class DynamicTileMover extends ObjectMover<IDynamicTile> {
|
||||
constructor(public readonly tile: IDynamicTile) {
|
||||
super();
|
||||
}
|
||||
|
||||
protected onMoveStart(): Promise<void> {
|
||||
return Promise.resolve();
|
||||
}
|
||||
|
||||
protected onMoveEnd(): Promise<void> {
|
||||
return Promise.resolve();
|
||||
}
|
||||
|
||||
protected onStepStart(): Promise<number> {
|
||||
return Promise.resolve(DynamicMoveCode.Success);
|
||||
}
|
||||
|
||||
protected onStepEnd(
|
||||
code: number,
|
||||
step: ObjectMoveStep,
|
||||
tile: IDynamicTile
|
||||
): Promise<ITileLocator> {
|
||||
if (code !== DynamicMoveCode.Success) {
|
||||
logger.warn(126, 'DynamicMoveCode.Success (0)', code.toString());
|
||||
return Promise.resolve({ x: tile.x, y: tile.y });
|
||||
}
|
||||
const locator: ITileLocator = {
|
||||
x: tile.x,
|
||||
y: tile.y
|
||||
};
|
||||
switch (step.type) {
|
||||
case ObjectMoveStepType.Dir: {
|
||||
const { x, y } = getFaceMovement(step.move);
|
||||
tile.setFaceDirection(step.move);
|
||||
locator.x += x;
|
||||
locator.y += y;
|
||||
break;
|
||||
}
|
||||
case ObjectMoveStepType.DirFace: {
|
||||
const { x, y } = getFaceMovement(step.move);
|
||||
tile.setFaceDirection(step.face);
|
||||
locator.x += x;
|
||||
locator.y += y;
|
||||
break;
|
||||
}
|
||||
case ObjectMoveStepType.Face: {
|
||||
tile.setFaceDirection(step.value);
|
||||
break;
|
||||
}
|
||||
case ObjectMoveStepType.Special: {
|
||||
const { x, y } = getFaceMovement(this.moveDirection);
|
||||
tile.setFaceDirection(this.faceDirection);
|
||||
locator.x += x;
|
||||
locator.y += y;
|
||||
break;
|
||||
}
|
||||
}
|
||||
return Promise.resolve(locator);
|
||||
}
|
||||
}
|
||||
|
||||
//#endregion
|
||||
@ -1,5 +1,14 @@
|
||||
import { IHookable, IHookBase, IHookController } from '@motajs/common';
|
||||
import { ISaveableContent } from '../common';
|
||||
import {
|
||||
FaceDirection,
|
||||
IMoverController,
|
||||
IObjectMovable,
|
||||
IObjectMover,
|
||||
IRoleFaceBinder,
|
||||
ISaveableContent
|
||||
} from '../common';
|
||||
|
||||
//#region 静态图层
|
||||
|
||||
export interface IMapLayerData {
|
||||
/** 当前引用是否过期，当地图图层内部的地图数组引用更新时，此项会变为 `true` */
|
||||
@ -75,6 +84,9 @@ export interface IMapLayer extends IHookable<
|
||||
/** 图层纵深 */
|
||||
readonly zIndex: number;
|
||||
|
||||
/** 此图层对应的动态图块图层，z 层级与静态图块一致 */
|
||||
readonly dynamicLayer: IDynamicLayer;
|
||||
|
||||
/**
|
||||
* 设置某一点的图块
|
||||
* @param block 图块数字
|
||||
@ -154,6 +166,10 @@ export interface IMapLayer extends IHookable<
|
||||
setMapRef(array: Uint32Array): void;
|
||||
}
|
||||
|
||||
//#endregion
|
||||
|
||||
//#region 图层管理
|
||||
|
||||
export interface ILayerStateHooks extends IHookBase {
|
||||
/**
|
||||
* 当设置背景图块时执行，如果设置的背景图块与原先一样，则不会执行
|
||||
@ -288,6 +304,10 @@ export interface ILayerState extends IHookable<ILayerStateHooks> {
|
||||
setDirty(dirty: boolean): void;
|
||||
}
|
||||
|
||||
//#endregion
|
||||
|
||||
//#region 楼层管理
|
||||
|
||||
/** 单个 MapLayer 的存档数据 */
|
||||
export interface IMapLayerSave {
|
||||
readonly width: number;
|
||||
@ -428,3 +448,149 @@ export interface IMapStore extends ISaveableContent<IMapStoreSave> {
|
||||
*/
|
||||
notifyEnterFloor(id: string): void;
|
||||
}
|
||||
|
||||
//#endregion
|
||||
|
||||
//#region 动态图块
|
||||
|
||||
export interface IDynamicLayerHooks extends IHookBase {
|
||||
/**
|
||||
* 当图块被创建（含从静态图块转换）时触发
|
||||
* @param tile 被创建的动态图块
|
||||
* @param layer 所属的动态图层
|
||||
*/
|
||||
onCreateTile(tile: IDynamicTile, layer: IDynamicLayer): void;
|
||||
|
||||
/**
|
||||
* 当图块被删除时触发
|
||||
* @param tile 被删除的动态图块
|
||||
* @param layer 所属的动态图层
|
||||
*/
|
||||
onDeleteTile(tile: IDynamicTile, layer: IDynamicLayer): Promise<void>;
|
||||
|
||||
/**
|
||||
* 当更新动态图块的位置时触发（包括使用 `mover` 触发的移动）
|
||||
* @param tile 更新位置的图块
|
||||
* @param layer 所属的动态图层
|
||||
*/
|
||||
onUpdateTilePosition(tile: IDynamicTile, layer: IDynamicLayer): void;
|
||||
}
|
||||
|
||||
export interface IDynamicLayer extends IHookable<IDynamicLayerHooks> {
|
||||
/** 当前动态图层所属的静态图层 */
|
||||
readonly layer: IMapLayer;
|
||||
|
||||
/**
|
||||
* 在指定位置创建一个动态图块
|
||||
* @param num 图块数字
|
||||
* @param x 横坐标
|
||||
* @param y 纵坐标
|
||||
* @returns 创建的动态图块引用
|
||||
*/
|
||||
createDynamic(num: number, x: number, y: number): IDynamicTile;
|
||||
|
||||
/**
|
||||
* 从所属静态图层读取并清除指定位置的图块，创建对应动态图块并返回引用。
|
||||
* 若该位置图块为 0，则发出警告并仍然创建 `num = 0` 的动态图块
|
||||
* @param x 横坐标
|
||||
* @param y 纵坐标
|
||||
* @returns 创建的动态图块引用
|
||||
*/
|
||||
transferToDynamic(x: number, y: number): IDynamicTile;
|
||||
|
||||
/**
|
||||
* 将动态图块还原为静态图块。坐标越界则警告并放弃，
|
||||
* 否则写回静态图层并触发 {@link IDynamicLayerHooks.onDeleteTile}
|
||||
* @param tile 要还原的动态图块
|
||||
*/
|
||||
transferToStatic(tile: IDynamicTile): void;
|
||||
|
||||
/**
|
||||
* 仅当目标位置静态图块为 0（空白）时才还原为静态图块，否则不转换
|
||||
* @param tile 要还原的动态图块
|
||||
* @returns 是否转换成功
|
||||
*/
|
||||
transferToStaticIfSafe(tile: IDynamicTile): boolean;
|
||||
|
||||
/**
|
||||
* 删除指定动态图块，触发 {@link IDynamicLayerHooks.onDeleteTile} 钩子。
|
||||
* 若图块不属于此层则发出警告
|
||||
* @param tile 要删除的动态图块
|
||||
*/
|
||||
deleteDynamic(tile: IDynamicTile): Promise<void>;
|
||||
|
||||
/**
|
||||
* 获取指定格点上所有动态图块的可迭代对象
|
||||
* @param x 横坐标
|
||||
* @param y 纵坐标
|
||||
*/
|
||||
getDynamicTilesAt(x: number, y: number): Iterable<IDynamicTile>;
|
||||
|
||||
/**
|
||||
* 迭代所有的动态图块
|
||||
*/
|
||||
iterateDynamicTiles(): Iterable<IDynamicTile>;
|
||||
|
||||
/**
|
||||
* 手动设置动态图块的朝向，更新 `tile.num`（若有朝向绑定）。
|
||||
* 转向逻辑与移动时的转向逻辑相同，但不触发移动
|
||||
* @param tile 要设置朝向的动态图块
|
||||
* @param direction 目标朝向
|
||||
*/
|
||||
setDynamicDirection(tile: IDynamicTile, direction: FaceDirection): void;
|
||||
|
||||
/**
|
||||
* 更新图块内部存储位置
|
||||
* @param tile 动态图块
|
||||
*/
|
||||
updateDynamicTile(tile: IDynamicTile): void;
|
||||
}
|
||||
|
||||
export interface IDynamicTile extends IObjectMovable {
|
||||
/** 当前图块数字 */
|
||||
readonly num: number;
|
||||
/** 当前图块所属的动态图层 */
|
||||
readonly layer: IDynamicLayer;
|
||||
/** 当前动态图块的移动器 */
|
||||
readonly mover: IObjectMover<IDynamicTile>;
|
||||
|
||||
/**
|
||||
* 设置图块朝向，会一并修改 {@link num}，返回设置后的当前图块数字
|
||||
* @param direction 图块朝向
|
||||
*/
|
||||
setFaceDirection(direction: FaceDirection): number;
|
||||
|
||||
/**
|
||||
* 直接删除此图块
|
||||
*/
|
||||
delete(): Promise<void>;
|
||||
|
||||
/**
|
||||
* 将当前图块还原为静态图块
|
||||
*/
|
||||
toStatic(): void;
|
||||
|
||||
/**
|
||||
* 还原为静态图块，如果当前位置有东西则不转换
|
||||
*/
|
||||
toStaticIfSafe(): boolean;
|
||||
|
||||
/**
|
||||
* 单步便捷移动接口，适用于简单移动场景，复杂路径通过 `tile.mover` 访问。
|
||||
* 等价于：
|
||||
*
|
||||
* ```ts
|
||||
* mover.step(dir, count);
|
||||
* return mover.start();
|
||||
* ```
|
||||
*/
|
||||
step(dir: FaceDirection, count?: number): IMoverController | null;
|
||||
|
||||
/**
|
||||
* 注入朝向绑定器，初始状态视为无朝向绑定
|
||||
* @param binder 朝向绑定器
|
||||
*/
|
||||
setFaceBinder(binder: IRoleFaceBinder | null): void;
|
||||
}
|
||||
|
||||
//#endregion
|
||||
|
||||
@ -16,10 +16,6 @@ export class MainDamageCalculator implements IDamageCalculator<
|
||||
/** 当前是否正在计算支援怪的伤害 */
|
||||
private inGuard: boolean = false;
|
||||
|
||||
/**
|
||||
* 计算战斗伤害信息
|
||||
* @param handler 信息对象
|
||||
*/
|
||||
calculate(
|
||||
handler: IReadonlyEnemyHandler<IEnemyAttr, IHeroAttr>
|
||||
): IEnemyDamageInfo {
|
||||
@ -153,11 +149,6 @@ export class MainDamageCalculator implements IDamageCalculator<
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取临界计算的上界
|
||||
* @param handler 信息对象
|
||||
* @param attribute 目标属性名
|
||||
*/
|
||||
getCriticalLimit(
|
||||
handler: IReadonlyEnemyHandler<IEnemyAttr, IHeroAttr>,
|
||||
attribute: CriticalableHeroStatus<IHeroAttr>
|
||||
|
||||
@ -183,6 +183,11 @@
|
||||
"123": "MapLayer.setMapRef: array length $1 does not match expected size $2, setMapRef will be ignored.",
|
||||
"124": "MapStore.loadState: floor '$1' or its layer(s) not found in current reference data, skipping.",
|
||||
"125": "Expected sorted floor id array has a same floor id set, but an array with a different floor id set is returned.",
|
||||
"126": "Only move code '$1' is expected, but got '$2'.",
|
||||
"127": "Block at $1,$2 is 0, the dynamic tile will have num 0.",
|
||||
"128": "Position $1,$2 is out of map bounds, operation cancelled.",
|
||||
"129": "Position $1,$2 is not empty, existing block will be overwritten.",
|
||||
"130": "The given tile is not managed by this dynamic layer.",
|
||||
"1001": "Item-detail extension needs 'floor-binder' and 'floor-damage' extension as dependency."
|
||||
}
|
||||
}
|
||||
|
||||
@ -2,11 +2,12 @@
|
||||
|
||||
以下规则必须时刻遵守，任何情况下都不允许违反。
|
||||
|
||||
1. **不擅自修改已有代码**：将我已经写好的代码视为绝对正确。除非我**明确允许**，否则**不允许任何修改**，哪怕因为接口变化或其他原因导致其中出现类型错误。若认为我的代码存在逻辑错误，应在对话中提出，而不是直接修改。
|
||||
1. **不擅自修改已有代码**：将我已经写好的代码视为绝对正确。除非我**明确允许**，否则**不允许任何修改**，哪怕因为接口变化或其他原因导致其中出现类型错误。若认为我的代码存在逻辑错误，应在对话中提出，而不是直接修改，不要做任何“顺手”的事。
|
||||
2. **不恢复我的修改**：我做的任何代码修改都是有原因的。若我在两次对话期间新增、删除或修改了部分代码，不要将其恢复。
|
||||
3. **以目的驱动，而非以接口驱动**：实现前先想清楚我为什么要这样设计接口、这个接口设计的目的是什么，而不是单纯地以将接口填满为目标。
|
||||
4. **遇到歧义立即提问**：若思考或实现时遇到任何问题——例如描述模糊、接口不清晰、某些地方存在歧义等——应立即向我提问，而不是按自己的想法去写。
|
||||
5. **按我说的方式重构**：若目标是重构某个接口，按照我指定的方式执行：
|
||||
5. **接口缺失时停止并提问**：若完成需求所需的接口尚不存在，应立即停止实现，向我提出疑问，而不是擅自新增接口来推进。
|
||||
6. **按我说的方式重构**：若目标是重构某个接口，按照我指定的方式执行：
|
||||
- **彻底性重构**（新旧接口完全没有重合）：按正常方式全新实现，旧代码仅作逻辑与思路上的参考。
|
||||
- **结构性重构**（新旧接口基本一致，细节有差距）：将旧代码搬移到新接口上后进行微调。**不要**擅自新增任何参数、方法或接口，**不要**仅通过新增兼容层的方式应对重构。
|
||||
|
||||
@ -17,6 +18,8 @@
|
||||
1. **合理参考建议**：我有时会在对话中给出实现建议，应合理参考，切忌滥用。
|
||||
2. **以类型标注为参考依据**：实现与类型标注有冲突时，以类型标注（一般是 `types.ts`）中的内容为准。
|
||||
3. **发现接口问题时提问**：若认为类型标注中的接口设计有问题，或在实现中发现缺少某些接口，应向我提问是否添加，经我同意后方可添加。
|
||||
4. **接口设计兼顾合理性与便捷性**：设计接口时不仅要考虑合理性，还要考虑使用便捷性。罕见场景应当被支持，但不应与常见场景共用同一接口——这只会增加常见场景的使用难度。
|
||||
5. **避免多余的非空判断与类型守卫**：若某个类型已满足目标的类型约束，不应再对其添加任何判断或过滤操作。典型例子：`Promise.all` 对数组元素类型没有任何限制，传入 `(Promise<unknown> | void)[]` 完全合法，无需多此一举地写成 `Promise.all(arr.filter(v => !!v))`。
|
||||
|
||||
**时刻谨记上述要求，避免一个需求反复修改仍无法满足预期。**
|
||||
|
||||
@ -29,7 +32,7 @@
|
||||
|
||||
## 示例文档
|
||||
|
||||
大致按照以下格式编写，如某部分需要详细描述，可单独开设标题。我会使用引用块的形式在文档中提出建议或回答。
|
||||
大致按照以下格式编写，如某部分需要详细描述，可单独开设标题；若某个接口内容较多，也可以在文档中为其单独开一个章节进行讲述。我会使用引用块的形式在文档中提出建议或回答。Markdown 文档不需要刻意换行，我的编辑器有自动换行功能，正常写没有问题。
|
||||
|
||||
```md
|
||||
# 需求综述
|
||||
|
||||
Loading…
Reference in New Issue
Block a user