mirror of
https://github.com/motajs/template.git
synced 2026-07-17 09:21:09 +08:00
73 lines
5.4 KiB
Markdown
73 lines
5.4 KiB
Markdown
> 本示例文档以物体移动为例，代码参考 `packages-user/data-common/src/common/mover.ts`。文档较为简略，实际编写的时候可以更丰富一些。
|
||
|
||
# 需求综述
|
||
|
||
为提供更便捷的物体移动接口，故进行本设计。本设计提供统一的移动接口 `IObjectMover`，并完成其抽象实现 `abstract class ObjectMover`，以方便具体拓展。
|
||
|
||
# 接口设计分析
|
||
|
||
默认场景下，移动主要发生在两种物体上：地图动态图块及玩家操控的勇士。二者的主要差别在于后者由玩家操控，需要进行移动判定，例如需要进行通行性判定，事件触发判定等，而前者通常由系统代码控制，且常用于演出，并不需要进行判定。
|
||
|
||
## IObjectMover
|
||
|
||
### 设计意图
|
||
|
||
对于玩家操控，判定往往发生在移动前，因此为统一接口，设计出 `onStepStart` 与 `onStepEnd` 两个接口，前者进行判定，后者根据判定结果进行相应的操作。为了让后者知道判定结果，将 `onStepStart` 的返回值设计为 `Promise<number>`，`onStepEnd` 接收之并执行操作。
|
||
|
||
在实际情况中，常见的使用场景是先规划好线路，然后让物体移动，因此接口需要设计成计划式，计划完成后通过 `start` 接口开始移动，故需要两个接口 `onMoveStart` 和 `onMoveEnd` 分别在移动开始前和结束后执行某些操作。
|
||
|
||
为了能够在开始移动后对移动进行干预及监听，`start` 应返回 `IMoveController` 作为返回值，其中应包含临时在当前步后插入一步、在当前移动队列后插入一步、下一步结束后立刻停止移动、当移动结束后兑现的 `Promise` 等内容。
|
||
|
||
接下来考虑移动计划，最通用的移动方法是指定移动方向与物体的面朝朝向，然后物体面朝指定朝向，向移动方向移动一格，故需要 `stepFace` 接口。在绝大多数情况下，移动方向与朝向是一致的，故提供 `step` 接口。除了这种情况，还会包含前进一格的需求，故提供 `forward` 接口；与之对应，还提供 `backward` 后退接口，而且在多数情况下，后退往往代表面朝前向后走，这里也使用这一语义。在后退时，移动动画的播放进度应该相反，故提供 `animDir` 接口。在移动时，移动速度是一个重要参数，故提供 `speed` 接口。在某些情况下，物体可能会需要瞬移，故提供 `tp` 接口。除了这些，还需要提供转向接口 `face`，调整面朝朝向；以及一个相对比较常见的 `jump` 接口。
|
||
|
||
对于移动对象，仅需要 `x` `y` `setPos` `getCurrentFaceDirection` 接口即可完成所有上述行为，故将这几个接口包装为 `IObjectMovable`，同时 `interface IObjectMover<T extends IObjectMovable>` 允许自定义拓展。
|
||
|
||
### 接口分析
|
||
|
||
> 此处仅列出部分。
|
||
|
||
- `IObjectMover.forward()`：预期频率**高频**。向前移动一格是地图行走、动画演出等场景的核心需求，在逻辑与演出中都会频繁出现，故为高频。典型使用场景：演出中玩家或 NPC 沿某方向连续移动。
|
||
- `IObjectMover.speed()`：预期频率**中频**。移动中修改移速有一定使用场景，但远不及 `forward`、`step` 等移动接口的频率，通常只在特殊演出或逻辑中出现，故为中频。典型使用场景：NPC 逃离怪物时先定在原地，随后逐渐加速逃跑。
|
||
- `IObjectMover.stepFace()`：预期频率**低频**。移动方向与朝向不同的常见场景（后退）已由 `backward` 覆盖，只有极特殊情况才需要此接口（如角色朝向固定但沿垂直方向平移），相当罕见，故为低频。
|
||
|
||
### 预期体量
|
||
|
||
本节应当写出预期的代码体量，并分析原因。示例如下：
|
||
|
||
预期代码体量为 200-300 行。分析如下：
|
||
|
||
- `IObjectMover` 首先需要完成计划存储与计划的定义，这些接口基本大致就是向数组中添加元素，每个方法内容都不多，整体预计在 100 行左右。
|
||
- `IObjectMover` 还需要完成移动流程的编写工作，需要根据每个移动步按照流程执行不同的行为，这一过程较为复杂，预计需要 100-200 行。
|
||
|
||
## IMoveController
|
||
|
||
...
|
||
|
||
# 实现思路
|
||
|
||
## 移动流程控制
|
||
|
||
核心难点在于如何进行移动控制，以下为核心思路。
|
||
|
||
1. 为实现移动流程，首先需要写一个大循环来处理每一个移动步。
|
||
2. 对于每一个移动步，首先调用 `onStepStart` 接口，获取移动 `code`，然后触发钩子，然后进行 `onStepEnd` 的执行，其返回值作为移动后的目标位置，最后触发钩子。
|
||
|
||
# 涉及文件
|
||
|
||
## 需要引用的文件
|
||
|
||
- `lodash-es`: 引用 `lodash` 工具库，使用某些工具函数。
|
||
- `@motajs/common`: 引用系统基本库，使用钩子相关接口。
|
||
- `types.ts`: 引用当前子模块的类型标注文件，使用相应的接口声明。
|
||
|
||
## 需要修改的文件
|
||
|
||
### `@user/data-common/src/common/mover.ts`
|
||
|
||
- [ ] 编写 `IObjectMover` 接口：按照本文描述完成设计
|
||
- [ ] 编写 `IObjectMovable` 接口：按照本文描述完成设计
|
||
- [ ] 编写 `IMoveController` 接口：按照本文描述完成设计
|
||
- [ ] 完成每个移动步的接口设计：每个移动步都需要一个接口对象，本文未明确提及，需包含每种移动计划
|
||
- [ ] 完成移动枚举的编写：每种移动计划都需要一个枚举类型来标注
|
||
- [ ] 编写 `ObjectMover` 抽象类：实现 `IObjectMover` 接口，作为移动基类
|