mirror of
https://github.com/motajs/template.git
synced 2026-10-29 20:30:20 +08:00
docs(10-27): U7 修订批次E（范围/录像/寻路/编辑器占位）
- U7-02：删除范围对象调用处的模块级复用说明注释 - U7-05：指令码位宽收敛为一句，细节指向高级 III - U7-06：选择框只作概念示例，代码示例恢复为技能示例 - U7-07：NoPath 改为正常结果，无需处理 - U7-08：移除编辑器过渡说法，jsonc 内容改为「需要编辑器」占位
This commit is contained in:
parent
112e46f1e1
commit
7409a47037
@ -90,7 +90,7 @@
|
||||
| U7-07 | `NoPath` 是正常输出，不是错误；被怪物挡着去不了很正常。当前「NoPath 处理建议」不对，只需说明「找不到可行路径」，无需处理 | `pathfinding.md` |
|
||||
| U7-08 | 假定编辑器已完成：不要写「编辑器就位前改文件、就位后用编辑器」。需要编辑器的地方只写「需要编辑器」标识，不讲没有编辑器时怎么做。所有 `.jsonc` 都由编辑器负责，涉及部分先写占位（长期规范 D-73） | 全部 |
|
||||
|
||||
**状态：执行中**（批次 D 已完成 U7-01、U7-03、U7-04；其余待执行）
|
||||
**状态：第 2 轮已全部处理**（U7-01..U7-08）
|
||||
|
||||
### 批次 D（U7-01、U7-03、U7-04）执行记录（2026-10-22）
|
||||
|
||||
@ -102,3 +102,13 @@
|
||||
|
||||
**验证：** `node node_modules/prettier/bin/prettier.cjs --write` 两篇文档 → CRLF、单 H1；`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 退出 0、`build complete in 19.04s`、无 dead link。
|
||||
|
||||
### 批次 E（U7-02、U7-05、U7-06、U7-07、U7-08）执行记录（2026-10-22）
|
||||
|
||||
- U7-02：`custom-range.md` 删去「范围对象提到模块级复用；引擎风格不建议在调用处内联 new」与「同样复用模块级范围实例，不要在调用处内联 new」两处说明性注释；代码仍保留模块级常量写法。
|
||||
- U7-05：`custom-replay-command.md` 删去位宽整节（`Uint8` / `Uint16` 切换、`setCommandWidth` 示例与格式变更说明），改为一句「指令码默认能容纳 255 个，99.9% 的项目都用不完；若确实可能超过，参考 `高级 III · 录像格式与指令码位宽`」；边界条目同步删除。
|
||||
- U7-06：选择框只保留为被动步的概念示例，并注明一般由样板内置、作者通常不需要自己实现；代码示例恢复为技能示例（`UseSkill` / `SkillEffect`、`ReplayUseSkill`、`ReplaySkillEffect`、`DataSkillPlugin`、`SkillSystem`），注册仍在插件 `awake`，`@shouldReplay` 仍在 `apply`。
|
||||
- U7-07：`pathfinding.md` 的 `NoPath` 由「错误 / 先检查通行谓词与图层」改为「找不到可行路径，例如被怪物挡住；正常结果，不需要处理」；验证段与边界条目同步。
|
||||
- U7-08/D-73：`adding-hero-attribute.md` 与 `adding-enemy-attribute.md` 删除「编辑器就位前 / 接入前 / 在它们实现之前 / 尚未接入」等过渡说法；`core.jsonc`、`enemy.jsonc`、默认模板与装备内容的示例改为 `> **需要编辑器**：...` 占位；编辑器与状态栏 / 图鉴章节只保留「需要编辑器」标识。
|
||||
|
||||
**验证：** `node node_modules/prettier/bin/prettier.cjs --write` 五个文件 → CRLF、单 H1；`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 退出 0、`build complete in 14.56s`、无 dead link。
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
怪物属性和勇士属性一样，不只是数据表里多一列。属性对象要在接口、默认模板、内容数据与伤害计算之间保持一致；只在接口里加字段，读取处会拿到 `undefined`，参与运算后变成 `NaN`。新增属性真正要补的，是这条链路上的每一处。
|
||||
|
||||
本篇以攻速（`atkSpeed`，怪物每回合的伤害按百分比缩放）与护甲（`armor`，怪物受到的伤害按百分比减免）为例，走完「改接口 → 补数据 → 读取与修改 → 接入伤害、光环、查询与最终效果」的数据端流程。它与[新增勇士属性](./adding-hero-attribute.md)构成对照：勇士属性偏重修饰器与装备，怪物属性偏重上下文构建时的计算顺序。编辑器新增属性项与怪物图鉴属于对应端的实现，本篇只留占位。
|
||||
本篇以攻速（`atkSpeed`，怪物每回合的伤害按百分比缩放）与护甲（`armor`，怪物受到的伤害按百分比减免）为例，走完「改接口 → 补数据 → 读取与修改 → 接入伤害、光环、查询与最终效果」的数据端流程。它与[新增勇士属性](./adding-hero-attribute.md)构成对照：勇士属性偏重修饰器与装备，怪物属性偏重上下文构建时的计算顺序。编辑器新增属性项与怪物图鉴属于对应端的实现，需要编辑器的部分只留占位。
|
||||
|
||||
## 怪物属性在哪里
|
||||
|
||||
@ -31,9 +31,9 @@ export interface IEnemyAttr {
|
||||
|
||||
具体数值来自 `IEnemyRawData.attribute`：怪物模板由 `num`（图块数字）、`attribute`（属性对象）与 `special`（特殊属性）组成。默认模板写在 `src/content/defaults/enemy.jsonc`，实际内容写在 `src/content/enemy.jsonc`。内容文件里每个怪物条目都有一份自己的 `attribute`，不会与默认模板合并。
|
||||
|
||||
默认模板在运行时不会被用来补全内容条目：加载器只是把它以 `enemy-default` 的标识读进配置表，供编辑器/校验端新建条目、核对字段形状；`enemyStore` 构建怪物时只读 `enemy.jsonc` 里的条目。因此它既不是新游戏内容的兜底值，也不会参与读档迁移。编辑器接入前，可以把它当作字段清单与类型示例。
|
||||
默认模板在运行时不会被用来补全内容条目：加载器只是把它以 `enemy-default` 的标识读进配置表，供编辑器/校验端新建条目、核对字段形状；`enemyStore` 构建怪物时只读 `enemy.jsonc` 里的条目。因此它既不是新游戏内容的兜底值，也不会参与读档迁移。
|
||||
|
||||
`guard` 与其他字段不同：它是运行时由支援光环写入的集合（`GuardAura.apply` 会把来源怪物视图 `add` 进去），不是内容文件里手填的普通数值。改接口时不要把它当成内容字段，也不要在 `enemy.jsonc` 里补它。
|
||||
`guard` 与其他字段不同：它是运行时由支援光环写入的集合（`GuardAura.apply` 会把来源怪物视图 `add` 进去），不是内容文件里手填的普通数值。改接口时不要把它当成内容字段，也不要通过编辑器给它填值。
|
||||
|
||||
## 改接口
|
||||
|
||||
@ -56,53 +56,19 @@ export interface IEnemyAttr {
|
||||
|
||||
## 补数据
|
||||
|
||||
接口增加字段后，默认模板与每一条怪物内容都要补齐。默认模板 `src/content/defaults/enemy.jsonc` 的 `attribute` 是单个对象：
|
||||
接口增加字段后，默认模板与每一条怪物内容都要补齐。默认模板 `src/content/defaults/enemy.jsonc` 的 `attribute` 是单个对象。
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"num": "@required",
|
||||
"attribute": {
|
||||
"name": "新怪物",
|
||||
"hp": 0,
|
||||
"atk": 0,
|
||||
"def": 0,
|
||||
"money": 0,
|
||||
"exp": 0,
|
||||
"point": 0,
|
||||
"atkSpeed": 100,
|
||||
"armor": 0
|
||||
},
|
||||
"special": {}
|
||||
}
|
||||
```
|
||||
> **需要编辑器**：在默认怪物模板的 `attribute` 中补齐 `atkSpeed` 与 `armor`。
|
||||
|
||||
`src/content/enemy.jsonc` 是一个数组，每个怪物条目也要补同样的两个键：
|
||||
`src/content/enemy.jsonc` 是一个数组，每个怪物条目也要补同样的两个键。
|
||||
|
||||
```jsonc
|
||||
[
|
||||
{
|
||||
"num": 130,
|
||||
"attribute": {
|
||||
"name": "怪王",
|
||||
"hp": 100,
|
||||
"atk": 120,
|
||||
"def": 0,
|
||||
"money": 10,
|
||||
"exp": 0,
|
||||
"point": 0,
|
||||
"atkSpeed": 100,
|
||||
"armor": 0
|
||||
},
|
||||
"special": {}
|
||||
}
|
||||
]
|
||||
```
|
||||
> **需要编辑器**：在每条怪物内容的 `attribute` 中补齐 `atkSpeed` 与 `armor`。
|
||||
|
||||
内容对象不会与默认模板合并，缺键就是缺键。读取到 `undefined` 后，`armor / 100` 与 `atkSpeed / 100` 都会变成 `NaN`，伤害与回合数随之失真。新增属性后，最好全局搜索一遍 `"attribute"`，确认每个模板入口都补齐。
|
||||
内容对象不会与默认模板合并，缺键就是缺键。读取到 `undefined` 后，`armor / 100` 与 `atkSpeed / 100` 都会变成 `NaN`，伤害与回合数随之失真。新增属性后，确认编辑器里的默认模板与每条怪物内容都补齐了这两个键。
|
||||
|
||||
### 旧存档迁移
|
||||
|
||||
新游戏补 `enemy.jsonc` 与默认模板即可；旧存档不会自动补键。`state.loadState(save, compression)` 读取 `@system/enemy` 时，会把每个脏模板的 `attrs` 原样交给怪物模板，缺失的键不会从内容配置或默认模板回填。迁移点在调用 `loadState` 之前：
|
||||
新游戏通过编辑器补齐怪物内容与默认模板即可；旧存档不会自动补键。`state.loadState(save, compression)` 读取 `@system/enemy` 时，会把每个脏模板的 `attrs` 原样交给怪物模板，缺失的键不会从内容配置或默认模板回填。迁移点在调用 `loadState` 之前：
|
||||
|
||||
```ts
|
||||
import { IEnemyAttr, SaveCompression } from '@user/data-common';
|
||||
@ -340,7 +306,7 @@ export class PackAtkSpeedQuery implements IEnemyCommonQueryEffect<
|
||||
state.enemyContext.registerCommonQueryEffect(40, new PackAtkSpeedQuery());
|
||||
```
|
||||
|
||||
注册只决定「拥有 code 40 的怪物会执行哪条查询」，**不会让任何怪物自动拥有 40**。常规查询的执行条件是怪物身上有对应特殊属性：在 `src/content/enemy.jsonc` 的 `special` 里写 `"40": ...`，或在运行时用 `enemy.addSpecial(...)` 添加。只注册效果、不给怪物 code，查询一次也不会触发。
|
||||
注册只决定「拥有 code 40 的怪物会执行哪条查询」，**不会让任何怪物自动拥有 40**。常规查询的执行条件是怪物身上有对应特殊属性：在编辑器里给怪物挂上特殊属性 40，或在运行时用 `enemy.addSpecial(...)` 添加。只注册效果、不给怪物 code，查询一次也不会触发。
|
||||
|
||||
查询效果需要 `registerCommonQueryEffect` 注册；引擎的 `src/data/enemy/initialize.ts` **没有注册任何查询实现**，不注册就不会执行。如果要增删或改写目标拥有的特殊属性，应使用特殊查询 `IEnemySpecialQueryEffect`，写法见[怪物查询](../../intermediate/enemy-query.md)，本篇不重复。
|
||||
|
||||
@ -378,12 +344,12 @@ state.enemyContext.registerFinalEffect(new ArmorFinalEffect());
|
||||
|
||||
编辑器需要在怪物属性面板增加攻速与护甲两个输入项；怪物图鉴需要显示它们的当前值。两处都属于对应端的实现，不在本篇范围内：
|
||||
|
||||
- `编辑器 · 新增怪物属性项`
|
||||
- `需要编辑器 · 新增怪物属性项`
|
||||
- `怪物图鉴`
|
||||
|
||||
<!-- TODO(advanced-II): 编辑器属性项与怪物图鉴 -->
|
||||
|
||||
数据端完成后，这两个入口只需要读取计算后怪物的 `atkSpeed` 与 `armor`。在它们实现之前，先用控制台或调试脚本确认数值正确。
|
||||
数据端完成后，这两个入口只需要读取计算后怪物的 `atkSpeed` 与 `armor`。
|
||||
|
||||
## 怎么验证
|
||||
|
||||
@ -451,7 +417,7 @@ function verifyEnemyAttribute(
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- **接口、内容条目、默认模板都要补键**：接口决定类型，内容条目决定运行时取值，默认模板只供编辑器/校验对照。内容对象不会与默认模板合并，运行时缺键就是 `undefined`。
|
||||
- **接口、内容条目、默认模板都要补键**：接口决定类型，内容条目决定运行时取值，默认模板只供编辑器/校验对照；内容条目与默认模板由编辑器维护。内容对象不会与默认模板合并，运行时缺键就是 `undefined`。
|
||||
- **`guard` 不要写进内容**：它是运行时由支援光环维护的集合，手填会与运行时行为冲突。
|
||||
- **百分数统一用整数存储**：`20` 表示 20%，计算时再除以 `100`；不要一处存 `0.2`、另一处存 `20`。
|
||||
- **新增字段会进入怪物存档**：读旧档时缺失的键不会自动补齐，需要按上文「旧存档迁移」在 `state.loadState` 之前给默认值。
|
||||
@ -459,6 +425,6 @@ function verifyEnemyAttribute(
|
||||
- **直接改原始怪物要标脏**：`getModifiableEnemy()` 的修改不会自动同步，必须 `markDirty()` 后调用 `state.enemyContext.requestRefresh(view)`，再重新读取计算后怪物与伤害。
|
||||
- **护甲要夹在有效区间**：计算器先把护甲夹到 `0`–`100`；夹紧后 `≥ 100` 时勇士每回合伤害为 `0`、怪物无法被击败，负值会被夹到 `0`，不会放大伤害。
|
||||
- **攻速改动会影响回合数**：凡是依赖 `turn` 的逻辑（支援、先攻、状态持续时间）都要跟着复核，不能只改伤害数字。
|
||||
- **编辑器与图鉴尚未接入**：在对应端实现之前，不要假设属性会自动出现在界面上。
|
||||
- **编辑器与图鉴读取计算后怪物**：它们不属于本篇的数据端流程。
|
||||
|
||||
返回[高级 II 导览](./index.md)。
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
勇士属性不只是数据表里多一列。一个属性会同时被类型常量、内容配置、修饰器、伤害计算、装备与界面读取；只在接口里加字段，读取处会拿到 `undefined`，参与运算后变成 `NaN`。新增属性真正要补的，是这条链路上的每一处。
|
||||
|
||||
本篇以攻速（`atkSpeed`，每回合造成的伤害按百分比缩放）与护甲（`armor`，按百分比减免最终伤害）为例，走完「改接口 → 补默认值与初始值 → 读取与修饰 → 接入伤害计算」的数据端流程。编辑器负责新增属性项与内容配置，状态栏负责显示；这些都属于对应端的实现，本篇只留占位。
|
||||
本篇以攻速（`atkSpeed`，每回合造成的伤害按百分比缩放）与护甲（`armor`，按百分比减免最终伤害）为例，走完「改接口 → 补默认值与初始值 → 读取与修饰 → 接入伤害计算」的数据端流程。编辑器负责新增属性项与内容配置，状态栏负责显示；这些都属于对应端的实现，需要编辑器的部分只留占位。
|
||||
|
||||
## 新增属性要改哪五处
|
||||
|
||||
@ -10,7 +10,7 @@
|
||||
| -------- | ---------------------------------------- | -------------------------------------- |
|
||||
| 类型 | `packages-user/data-common/src/types.ts` | 在 `IHeroAttr` 中增加字段 |
|
||||
| 默认值 | `packages-user/data-state/src/shared.ts` | 补齐 `HERO_DEFAULT_ATTRIBUTE` |
|
||||
| 初始值 | `src/content/core.jsonc` | 补齐 `init.hero.attribute` |
|
||||
| 初始值 | `src/content/core.jsonc` | 由编辑器补齐 `init.hero.attribute` |
|
||||
| 计算接入 | `src/data/enemy/calculator.ts` 等读取处 | 让属性真正影响伤害或其他运算 |
|
||||
| 显示 | 编辑器与渲染端 | 编辑器属性项、状态栏显示（本篇不实现） |
|
||||
|
||||
@ -86,26 +86,11 @@ export const HERO_DEFAULT_ATTRIBUTE: IHeroAttr = {
|
||||
};
|
||||
```
|
||||
|
||||
实际进入游戏的初始值来自内容配置 `src/content/core.jsonc` 的 `init.hero.attribute`，由 `src/data/initialize.ts` 的 `afterLoad` 调用 `state.hero.createAttribute(coreConfig.init.hero.attribute)`，直接交给 `HeroAttribute` 构造。它不会与默认值合并，缺键就是缺键；`HERO_DEFAULT_ATTRIBUTE` 不会在运行时兜底：
|
||||
实际进入游戏的初始值来自内容配置 `src/content/core.jsonc` 的 `init.hero.attribute`，由 `src/data/initialize.ts` 的 `afterLoad` 调用 `state.hero.createAttribute(coreConfig.init.hero.attribute)`，直接交给 `HeroAttribute` 构造。它不会与默认值合并，缺键就是缺键；`HERO_DEFAULT_ATTRIBUTE` 不会在运行时兜底。
|
||||
|
||||
```jsonc
|
||||
"attribute": {
|
||||
"name": "勇士",
|
||||
"level": 0,
|
||||
"hp": 10000,
|
||||
"atk": 100,
|
||||
"def": 100,
|
||||
"mdef": 0,
|
||||
"mana": 0,
|
||||
"manamax": 0,
|
||||
"money": 0,
|
||||
"exp": 0,
|
||||
"atkSpeed": 100,
|
||||
"armor": 0
|
||||
}
|
||||
```
|
||||
> **需要编辑器**：在 `core.jsonc` 的 `init.hero.attribute` 中补齐 `atkSpeed` 与 `armor`。
|
||||
|
||||
这两项不是可选项。内容配置通常由编辑器维护；样板里的 `.jsonc` 只保留文件开头那段系统前缀注释，加载器会按前缀切开后直接 `JSON.parse`，所以后面不能再写注释。编辑器就位前可以直接改文件，就位后按编辑器的方式补字段。
|
||||
这两项不是可选项。`core.jsonc` 的 `init.hero.attribute` 由编辑器维护，必须补齐这两个键。
|
||||
|
||||
若只在接口与默认值里加、忘了内容配置，`getBaseAttribute('atkSpeed')` 会返回 `undefined`，`atkSpeed / 100` 随之变成 `NaN`，伤害与回合数都会失真。
|
||||
|
||||
@ -390,27 +375,9 @@ export class MainDamageCalculator implements IDamageCalculator<
|
||||
|
||||
## 与装备和道具的关系
|
||||
|
||||
装备的 `value` 与 `percentage` 是按属性名索引的记录，新属性不需要额外注册。只要 `IHeroAttr` 里有这个数值字段，内容层的装备定义就能直接写（`category: 4` 即 `ItemCategory.Equipment`）：
|
||||
装备的 `value` 与 `percentage` 是按属性名索引的记录，新属性不需要额外注册。只要 `IHeroAttr` 里有这个数值字段，装备定义就能直接配置（`category: 4` 即 `ItemCategory.Equipment`）。
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"num": 120,
|
||||
"category": 4,
|
||||
"name": "疾风剑",
|
||||
"text": "攻击速度 +15%",
|
||||
"hideInToolbox": false,
|
||||
"equip": {
|
||||
"slots": ["weapon"],
|
||||
"animate": "equip",
|
||||
"value": {},
|
||||
"percentage": { "atkSpeed": 0.15 },
|
||||
"loadEvent": null,
|
||||
"unloadEvent": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
内容层是 JSONC，直接写在 `src/content/item.jsonc` 里即可（同样由编辑器维护，开头之外不能写注释）。
|
||||
> **需要编辑器**：在装备内容里把 `percentage.atkSpeed` 设为 `0.15`。
|
||||
|
||||
装备实例会把这些记录转成 `ValueModifier` 与 `PercentageModifier`，穿戴时挂到勇士属性，卸下时移除。基础攻速 `100` 配上 `percentage.atkSpeed = 0.15`，最终攻速就是 `115`。注意属性本身按百分数存储（`15` 表示 15%），而装备的 `percentage` 是倍率（`0.15` 表示 15%），两者写法不同。
|
||||
|
||||
@ -420,17 +387,17 @@ export class MainDamageCalculator implements IDamageCalculator<
|
||||
|
||||
编辑器需要在英雄属性面板增加攻速与护甲两个输入项，并负责维护 `core.jsonc` 里的内容配置；状态栏需要在合适的位置显示它们的当前值。这些都属于对应端的实现，不在本篇范围内：
|
||||
|
||||
- `编辑器 · 新增英雄属性项`
|
||||
- `编辑器 · 内容配置`
|
||||
- `需要编辑器 · 新增英雄属性项`
|
||||
- `需要编辑器 · 内容配置`
|
||||
- `渲染端 · 状态栏`
|
||||
|
||||
<!-- TODO(advanced-II): 编辑器属性项、内容配置与状态栏显示 -->
|
||||
|
||||
数据端完成后，编辑器与状态栏只需要读取 `getFinalAttribute('atkSpeed')` 与 `getFinalAttribute('armor')`。在它们实现之前，先用控制台或调试脚本确认数值正确。
|
||||
数据端完成后，编辑器与状态栏只需要读取 `getFinalAttribute('atkSpeed')` 与 `getFinalAttribute('armor')`。
|
||||
|
||||
## 怎么验证
|
||||
|
||||
先准备一只属性固定的怪物，避免光环、支援或随机因素干扰。把内容配置里的 `atkSpeed` 设为 `100`、`armor` 设为 `0`，读取最终属性，再穿上一件 +15% 攻速的装备，最后观察伤害变化：
|
||||
先准备一只属性固定的怪物，避免光环、支援或随机因素干扰。在编辑器里把内容配置的 `atkSpeed` 设为 `100`、`armor` 设为 `0`，读取最终属性，再穿上一件 +15% 攻速的装备，最后观察伤害变化：
|
||||
|
||||
```ts
|
||||
import { IEnemyAttr } from '@user/data-common';
|
||||
@ -462,7 +429,7 @@ function verifyHeroAttribute(
|
||||
- 穿上 +15% 攻速的装备后，最终攻速变为 `115`，同一只怪物的战斗回合数下降；
|
||||
- 把护甲调高后，`damage` 随护甲上升而下降，`turn` 不变。
|
||||
|
||||
若最终攻速是 `NaN`，先检查 `core.jsonc` 的 `init.hero.attribute` 是否补了键；`HERO_DEFAULT_ATTRIBUTE` 只影响类型检查，补了它也不会在运行时兜底。若装备穿上后数值不变，检查装备定义的键名是否与接口字段完全一致。
|
||||
若最终攻速是 `NaN`，先检查编辑器里 `core.jsonc` 的 `init.hero.attribute` 是否补了键；`HERO_DEFAULT_ATTRIBUTE` 只影响类型检查，补了它也不会在运行时兜底。若装备穿上后数值不变，检查装备定义的键名是否与接口字段完全一致。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
@ -474,7 +441,7 @@ function verifyHeroAttribute(
|
||||
- **`save = true` 的修饰器要注册类型**：读档按 `type` 查构造器，未注册的修饰器会被静默跳过，数值看起来「读档后消失了」。
|
||||
- **护甲要夹在有效区间**：计算器先把护甲夹到 `0`–`100`；夹紧后 `≥ 100` 时最终伤害为 `0`，不是治疗，负值会被夹到 `0`，不会放大伤害。
|
||||
- **攻速改动会影响回合数**：凡是依赖 `turn` 的逻辑（支援、先攻、状态持续时间）都要跟着复核，不能只改伤害数字。
|
||||
- **编辑器与状态栏尚未接入**：在对应端实现之前，不要假设属性会自动出现在界面上。
|
||||
- **编辑器与状态栏读取最终属性**：它们不属于本篇的数据端流程。
|
||||
|
||||
渲染端如何展示这两个属性不在本篇范围内。 <!-- TODO(renderer): 攻速与护甲的状态栏显示 -->
|
||||
|
||||
|
||||
@ -157,7 +157,6 @@ export class RingRange extends BaseRange<IRingRangeParam> {
|
||||
|
||||
```ts
|
||||
// RingRange 即上一节定义的自定义范围类
|
||||
// 范围对象提到模块级复用；引擎风格不建议在调用处内联 new
|
||||
const ringRange = new RingRange();
|
||||
|
||||
const loc = state.hero.getLocation();
|
||||
@ -206,7 +205,6 @@ function collectRing(
|
||||
`scanRange` 只返回范围内的怪物，所以验证要摆好怪物，而不是只看格子。先以勇士为中心，在中心、曼哈顿距离 `1`、距离 `2` 的位置各放一只测试怪，再执行：
|
||||
|
||||
```ts
|
||||
// 同样复用模块级范围实例，不要在调用处内联 new
|
||||
const ringRange = new RingRange();
|
||||
|
||||
state.enemyContext.bindHero(state.hero.getAttribute());
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
高级 I 的[录像一致性](../replay-consistency.md)讲的是「已有行为该不该记」，回答方式是给方法加 `@shouldReplay`。还有一种情况它覆盖不到：行为本身不在引擎里，录像里没有对应的指令码，回放时根本无从执行。这时需要新增一条录像指令。
|
||||
|
||||
本篇讲一条自定义指令从指令码、指令对象、注册到记录的完整路径，并用选择框讲清主动步与被动步怎么配合。新增指令码会修改 `packages-user` 下的引擎内容，升级时要预期合并成本；如果只是给已有行为补标记，回到[录像一致性](../replay-consistency.md)即可，不必新增指令。
|
||||
本篇讲一条自定义指令从指令码、指令对象、注册到记录的完整路径，并用技能给出完整示例。主动步与被动步的配合会先用选择框说明。新增指令码会修改 `packages-user` 下的引擎内容，升级时要预期合并成本；如果只是给已有行为补标记，回到[录像一致性](../replay-consistency.md)即可，不必新增指令。
|
||||
|
||||
## 什么时候需要自定义指令
|
||||
|
||||
@ -22,30 +22,18 @@
|
||||
export const enum ReplayCode {
|
||||
// ...已有录像码省略
|
||||
|
||||
/** 打开选择框（本篇新增） */
|
||||
OpenChoice,
|
||||
/** 玩家在选择框中的选择，紧跟主动步的被动步（本篇新增） */
|
||||
ChoiceSelect
|
||||
/** 使用技能（本篇新增） */
|
||||
UseSkill,
|
||||
/** 技能特效的被动步，紧跟主动步（本篇新增） */
|
||||
SkillEffect
|
||||
}
|
||||
```
|
||||
|
||||
本篇新增两个码：`OpenChoice` 是主动步，`ChoiceSelect` 是紧跟其后的被动步；两者都要在 `registerCommand` 里注册，否则沙盒按指令码查表时会中止播放。
|
||||
本篇新增两个码：`UseSkill` 是主动步，`SkillEffect` 是紧跟其后的被动步；两者都要在 `registerCommand` 里注册，否则沙盒按指令码查表时会中止播放。
|
||||
|
||||
新增一项意味着修改 `packages-user` 的引擎内容，而不是只改 `src`。`registerCommand` 收的是普通 `number`，跳过枚举直接写数字也能注册；但引擎之后分配新码时可能撞号，所以正式做法仍然是在枚举末尾追加。
|
||||
|
||||
指令码的取值还受位宽限制。默认的 `ReplayCommandWidth.Uint8` 只支持 `0–255`，超出后写入会被截断。需要更多指令码时，在开始录制前切到 `ReplayCommandWidth.Uint16`（`0–65535`）：
|
||||
|
||||
```ts
|
||||
import { ReplayCommandWidth } from '@user/data-common';
|
||||
import { ICoreState } from '@user/data-state';
|
||||
|
||||
/** 在注册/录制超过 255 的指令码之前调用。 */
|
||||
function useUint16ReplayCodes(state: ICoreState): void {
|
||||
state.replaySystem.array.setCommandWidth(ReplayCommandWidth.Uint16);
|
||||
}
|
||||
```
|
||||
|
||||
`setCommandWidth` 会重新编码现有指令；`ReplaySystem.saveState` 会把当前 `commandWidth` 一并存入录像，`loadState` 再按存档里的宽度恢复，所以本系统自己的存读档不需要额外转换。但这是录像格式变更：外部工具或旧版本若固定按 Uint8 解析，就读不了 Uint16 录像；从 Uint16 降回 Uint8 时，大于 255 的指令码会告警 code 154 并被截断。确定要扩容后就不要来回切换。
|
||||
指令码默认能容纳 255 个，99.9% 的项目都用不完，本篇不展开位宽细节。若指令码数量确实可能超过 255，参考 `高级 III · 录像格式与指令码位宽`。
|
||||
|
||||
## 指令对象
|
||||
|
||||
@ -69,7 +57,7 @@ function useUint16ReplayCodes(state: ICoreState): void {
|
||||
|
||||
`ReplayCommandType.Active` 的指令自己执行逻辑，实现 `execute` 即可，是最常见的形式。
|
||||
|
||||
被动步不执行自己的逻辑，它的参数要由知道「什么时候该用它」的那一方来取。最典型的例子是选择框：玩家打开选择框并选择一项。录像无法提前知道这里会弹出什么选择框、有哪些选项，只能等选择框出现后，由选择框系统自己读录像里的选择。
|
||||
被动步不执行自己的逻辑，它的参数要由知道「什么时候该用它」的那一方来取。最典型的例子是选择框：玩家打开选择框并选择一项。录像无法提前知道这里会弹出什么选择框、有哪些选项，只能等选择框出现后，由选择框系统自己读录像里的选择。选择框一般由样板内置，作者通常不需要自己实现；这里只用它说明被动步的场景。
|
||||
|
||||
回放时，主动步负责让选择框出现并等它结束；选择框系统在框出现后取被动步，用录下来的选择代替玩家点击，然后调用 `next` 推进。这样，选择框什么时候弹、弹出什么，都由当时运行的界面决定，录像只负责回答「玩家选了什么」。
|
||||
|
||||
@ -95,83 +83,30 @@ export interface IReplayPassiveHandler {
|
||||
忘记 `next` 不会让整条录像停住，只是这一步没有读到下一个录像。主动步返回后，沙盒发现这条被动录像没被消费，会告警并跳过它，然后继续播放后面的录像。
|
||||
:::
|
||||
|
||||
下面这个选择框系统同时处理正常游玩与回放：
|
||||
回放链路可以拆成三步：
|
||||
|
||||
```ts
|
||||
import {
|
||||
ReplayCode,
|
||||
ReplayCommandResult,
|
||||
shouldReplay
|
||||
} from '@user/data-common';
|
||||
import { ICoreState } from '@user/data-state';
|
||||
1. 玩家入口先 `record` 主动指令，再紧接着 `record` 被动指令——两个录像步必须相邻：
|
||||
|
||||
/** 选择框服务：由作者自己的选择框系统实现，引擎不内置 */
|
||||
export interface IChoiceService {
|
||||
/** 打开选择框并返回选择结果；回放时返回录像里的选择 */
|
||||
open(choiceId: number): Promise<number>;
|
||||
}
|
||||
```ts
|
||||
this.state.replaySystem.record(ReplayCode.UseSkill, skillId, x, y);
|
||||
// 紧随其后的被动步，给渲染端播放技能特效
|
||||
this.state.replaySystem.record(ReplayCode.SkillEffect, skillId);
|
||||
```
|
||||
|
||||
/** 选择框系统：正常游玩时等玩家点击，回放时读被动录像 */
|
||||
export class ChoiceSystem implements IChoiceService {
|
||||
constructor(private readonly state: ICoreState) {}
|
||||
2. 回放时，主动指令的 `execute` 在自己的执行期间取被动 handler：
|
||||
|
||||
async open(choiceId: number): Promise<number> {
|
||||
if (!this.canOpen(choiceId)) {
|
||||
// 不可用时直接提示并返回，不记录录像
|
||||
this.state.emitTip('当前不能打开这个选择框');
|
||||
return -1;
|
||||
}
|
||||
|
||||
// 先让选择框出现；数据端只给出选项 id，显示交给渲染端
|
||||
this.show(choiceId);
|
||||
|
||||
// 有沙盒说明正在回放，此时没有玩家点击，由选择框系统自己读被动录像
|
||||
const sandbox = this.state.replaySystem.sandbox;
|
||||
if (sandbox) {
|
||||
const passive = sandbox.getPassive();
|
||||
if (!passive) {
|
||||
// 主动步预期有被动步，但下一步不是被动步；getPassive 已经报错
|
||||
return -1;
|
||||
}
|
||||
|
||||
// 被动步的参数就是玩家当时的选择
|
||||
const [selected] = passive.step.params as [number];
|
||||
// 用完必须 next，否则再次 getPassive 还是这一步
|
||||
await passive.next(ReplayCommandResult.Success);
|
||||
this.apply(choiceId, selected);
|
||||
return selected;
|
||||
}
|
||||
|
||||
// 正常游玩：等待玩家点击
|
||||
const selected = await this.waitForPlayer(choiceId);
|
||||
// 主动步与紧跟其后的被动步必须相邻
|
||||
this.state.replaySystem.record(ReplayCode.OpenChoice, choiceId);
|
||||
this.state.replaySystem.record(ReplayCode.ChoiceSelect, selected);
|
||||
this.apply(choiceId, selected);
|
||||
return selected;
|
||||
```ts
|
||||
const passive = this.state.replaySystem.sandbox?.getPassive();
|
||||
if (passive) {
|
||||
// 参数在 passive.step.params；先确认它确实是预期的那条被动指令
|
||||
const [effectSkill] = passive.step.params as [number];
|
||||
console.log('播放技能特效', effectSkill);
|
||||
// 渲染端处理完后推进；不调用 next 就不会进入下一步
|
||||
await passive.next(ReplayCommandResult.Success);
|
||||
}
|
||||
```
|
||||
|
||||
/** 真正修改状态的地方，@shouldReplay 写在这里 */
|
||||
@shouldReplay('Applying a choice should be replayed.')
|
||||
apply(choiceId: number, selected: number): void {
|
||||
// ...把选择结果写进游戏状态
|
||||
}
|
||||
|
||||
private canOpen(choiceId: number): boolean {
|
||||
// ...判断当前能否打开这个选择框
|
||||
return true;
|
||||
}
|
||||
|
||||
private show(choiceId: number): void {
|
||||
// ...渲染端弹出选择框
|
||||
}
|
||||
|
||||
private waitForPlayer(choiceId: number): Promise<number> {
|
||||
// ...等待玩家点击并返回选项索引
|
||||
return Promise.resolve(0);
|
||||
}
|
||||
}
|
||||
```
|
||||
3. `next` 推进读取流并触发 `onStep`；重复调用 `getPassive()` 在推进前会拿到同一个 handler / 同一步。
|
||||
|
||||
主动步的 `execute` 返回值决定播放是否继续；被动步的 `next` 只负责推进读取。通常应在 `await passive.next(...)` 之后返回 `Success`。
|
||||
|
||||
@ -181,11 +116,11 @@ export class ChoiceSystem implements IChoiceService {
|
||||
import { ReplayCommandResult, ReplayCommandType } from '@user/data-common';
|
||||
import { BaseReplayCommand } from './commands';
|
||||
|
||||
/** 玩家在选择框中的选择：被动步 */
|
||||
export class ReplayChoiceSelect extends BaseReplayCommand {
|
||||
/** 技能特效的被动步：参数由主动步通过 getPassive 取走。 */
|
||||
export class ReplaySkillEffect extends BaseReplayCommand {
|
||||
readonly type: ReplayCommandType = ReplayCommandType.Passive;
|
||||
|
||||
protected readonly name: string = 'choice-select';
|
||||
protected readonly name: string = 'skill-effect';
|
||||
protected readonly paramTypes: readonly string[] = ['number'];
|
||||
|
||||
async wrappedExecute(): Promise<ReplayCommandResult> {
|
||||
@ -195,7 +130,7 @@ export class ReplayChoiceSelect extends BaseReplayCommand {
|
||||
}
|
||||
```
|
||||
|
||||
渲染端的播放表现按渲染端教程处理，本篇只写数据端。 <!-- TODO(renderer): 选择框的渲染端消费 -->
|
||||
渲染端的播放表现按渲染端教程处理，本篇只写数据端。 <!-- TODO(renderer): 被动录像的渲染端消费 -->
|
||||
|
||||
## 用基类减少样板
|
||||
|
||||
@ -205,7 +140,7 @@ export class ReplayChoiceSelect extends BaseReplayCommand {
|
||||
- `paramTypes`：参数类型名数组，取值只能是 `'number'`、`'string'`、`'boolean'`、`'bigint'`；
|
||||
- `wrappedExecute(step)`：真正的执行逻辑，不需要再校验参数类型。
|
||||
|
||||
下面这条 `ReplayOpenChoice`：参数为 `[number choiceId]`，`open` 返回负数时判定为失败。
|
||||
下面是一条 `ReplayUseSkill`：参数为 `[number skillId, number x, number y]`，技能不可用时返回 `Failed`。
|
||||
|
||||
```ts
|
||||
import {
|
||||
@ -215,21 +150,32 @@ import {
|
||||
} from '@user/data-common';
|
||||
import { IStateSystem } from '@user/data-system';
|
||||
import { BaseReplayCommand } from './commands';
|
||||
import { IChoiceService } from './choice';
|
||||
|
||||
/** 技能服务：由作者自己的技能系统实现，引擎不内置 */
|
||||
export interface ISkillService {
|
||||
/** 判断技能能否在目标点使用 */
|
||||
canUse(skillId: number, x: number, y: number): boolean;
|
||||
/** 执行技能效果；回放时也走这里，注意不要在这里写录像 */
|
||||
apply(skillId: number, x: number, y: number): void;
|
||||
}
|
||||
|
||||
/**
|
||||
* 打开选择框。
|
||||
* 参数：选择框 id。
|
||||
* 使用技能。
|
||||
* 参数顺序必须与 paramTypes 一致：技能 id、目标横坐标、目标纵坐标。
|
||||
*/
|
||||
export class ReplayOpenChoice extends BaseReplayCommand {
|
||||
export class ReplayUseSkill extends BaseReplayCommand {
|
||||
readonly type: ReplayCommandType = ReplayCommandType.Active;
|
||||
|
||||
protected readonly name: string = 'open-choice';
|
||||
protected readonly paramTypes: readonly string[] = ['number'];
|
||||
protected readonly name: string = 'use-skill';
|
||||
protected readonly paramTypes: readonly string[] = [
|
||||
'number',
|
||||
'number',
|
||||
'number'
|
||||
];
|
||||
|
||||
constructor(
|
||||
state: IStateSystem,
|
||||
private readonly choices: IChoiceService
|
||||
private readonly skills: ISkillService
|
||||
) {
|
||||
super(state);
|
||||
}
|
||||
@ -238,15 +184,14 @@ export class ReplayOpenChoice extends BaseReplayCommand {
|
||||
step: IReplayStepHandler
|
||||
): Promise<ReplayCommandResult> {
|
||||
// 参数已由基类校验过，这里可以直接断言类型
|
||||
const [choiceId] = step.params as [number];
|
||||
const [skillId, x, y] = step.params as [number, number, number];
|
||||
|
||||
// 打开选择框；回放时选择框系统会在框出现后读取被动录像
|
||||
const selected = await this.choices.open(choiceId);
|
||||
if (selected < 0) {
|
||||
// 没有读到选择，后续步骤无法继续
|
||||
// 技能不可用时不继续播放，避免后续步骤建立在错误状态上
|
||||
if (!this.skills.canUse(skillId, x, y)) {
|
||||
return ReplayCommandResult.Failed;
|
||||
}
|
||||
|
||||
this.skills.apply(skillId, x, y);
|
||||
return ReplayCommandResult.Success;
|
||||
}
|
||||
}
|
||||
@ -254,7 +199,7 @@ export class ReplayOpenChoice extends BaseReplayCommand {
|
||||
|
||||
`BaseReplayCommand` 的 `execute` 会先校验参数再调用 `wrappedExecute`。因此不要在 `wrappedExecute` 里重复写 `typeof` 判断；参数个数或类型错了，基类已经返回 `Failed`。
|
||||
|
||||
如果打开选择框是异步的，要在 `wrappedExecute` 里 `await` 完再返回 `Success`，否则后续录像步可能在选择结果落地前就开始执行。
|
||||
如果技能效果是异步的，要在 `wrappedExecute` 里 `await` 完再返回 `Success`，否则后续录像步可能在效果完成前就开始执行。
|
||||
|
||||
## 注册
|
||||
|
||||
@ -263,31 +208,31 @@ export class ReplayOpenChoice extends BaseReplayCommand {
|
||||
```ts
|
||||
import { ReplayCode } from '@user/data-common';
|
||||
import { ICoreState, IDataPluginDefine } from '@user/data-state';
|
||||
import { ChoiceSystem, IChoiceService } from './choice';
|
||||
import { ReplayChoiceSelect, ReplayOpenChoice } from './commands';
|
||||
import { ISkillService, ReplaySkillEffect, ReplayUseSkill } from './commands';
|
||||
import { SkillSystem } from './skill';
|
||||
|
||||
/**
|
||||
* 选择框插件：指令随插件一起注册。
|
||||
* 技能插件：技能服务与录像指令一起注册。
|
||||
* 把插件加进 src/data/plugin/list.ts 的 dataPlugins 后，它会随数据端一起初始化。
|
||||
*/
|
||||
export class DataChoicePlugin implements IDataPluginDefine {
|
||||
readonly id: string = 'data-choice-plugin';
|
||||
export class DataSkillPlugin implements IDataPluginDefine {
|
||||
readonly id: string = 'data-skill-plugin';
|
||||
readonly dataDeps: string[] = [];
|
||||
|
||||
/** 选择框服务：主动步通过它打开选择框 */
|
||||
choice!: IChoiceService;
|
||||
/** 技能服务：主动步通过它执行技能 */
|
||||
skill!: ISkillService;
|
||||
|
||||
awake(state: ICoreState): void {
|
||||
this.choice = new ChoiceSystem(state);
|
||||
this.skill = new SkillSystem(state);
|
||||
|
||||
// 注册必须发生在第一次创建沙盒之前；插件的 awake 满足这个时机
|
||||
state.replaySystem.registerCommand(
|
||||
ReplayCode.OpenChoice,
|
||||
new ReplayOpenChoice(state, this.choice)
|
||||
ReplayCode.UseSkill,
|
||||
new ReplayUseSkill(state, this.skill)
|
||||
);
|
||||
state.replaySystem.registerCommand(
|
||||
ReplayCode.ChoiceSelect,
|
||||
new ReplayChoiceSelect(state)
|
||||
ReplayCode.SkillEffect,
|
||||
new ReplaySkillEffect(state)
|
||||
);
|
||||
}
|
||||
|
||||
@ -301,22 +246,52 @@ export class DataChoicePlugin implements IDataPluginDefine {
|
||||
|
||||
## 记录
|
||||
|
||||
注册只让回放认识这条指令，录制仍要在行为入口写入。选择框系统里，`open` 负责记录：先 `record` 主动步，再 `record` 紧跟其后的被动步，两个录像步必须相邻；回放时走沙盒分支，只读被动步，不再记录。
|
||||
注册只让回放认识这条指令，录制仍要在行为入口写入。技能系统里，`use` 负责记录：先 `record` 主动步，再 `record` 紧跟其后的被动步，两个录像步必须相邻；回放时由 `ReplayUseSkill` 执行，不再记录。
|
||||
|
||||
`@shouldReplay` 写在 `apply` 上，而不是 `open` 上：真正可能修改状态的是 `apply`，`open` 只是调用它；而且 `open` 里的 `if` 在不可用时会直接提示并返回，不会走到记录。把标记写在 `apply` 上，任何调用 `apply` 的路径都会被检查到。
|
||||
`@shouldReplay` 写在 `apply` 上，而不是 `use` 上：真正可能修改状态的是 `apply`，`use` 只是调用它；而且 `use` 里的 `if` 在不可用时会直接返回，不会走到记录。把标记写在 `apply` 上，任何调用 `apply` 的路径都会被检查到。
|
||||
|
||||
把「记录 + 执行」的玩家入口与「只读取 / 只执行」的回放入口分开，可以避免同一次选择被记两遍。如果某个被动触发的路径会调用带记录的入口，用 `disable()` 与 `revert()` 把那段包住，并且必须配对。
|
||||
```ts
|
||||
import { ReplayCode, shouldReplay } from '@user/data-common';
|
||||
import { ICoreState } from '@user/data-state';
|
||||
import { ISkillService } from './commands';
|
||||
|
||||
/** 技能系统：玩家入口写录像，回放入口只执行效果 */
|
||||
export class SkillSystem implements ISkillService {
|
||||
constructor(private readonly state: ICoreState) {}
|
||||
|
||||
canUse(skillId: number, x: number, y: number): boolean {
|
||||
// ...判断技能是否可用
|
||||
return true;
|
||||
}
|
||||
|
||||
use(skillId: number, x: number, y: number): void {
|
||||
if (!this.canUse(skillId, x, y)) return;
|
||||
|
||||
// 先记录主动步，再记录紧随其后的被动步；两者必须相邻
|
||||
this.state.replaySystem.record(ReplayCode.UseSkill, skillId, x, y);
|
||||
this.state.replaySystem.record(ReplayCode.SkillEffect, skillId);
|
||||
this.apply(skillId, x, y);
|
||||
}
|
||||
|
||||
/** 真正修改状态的地方，@shouldReplay 写在这里 */
|
||||
@shouldReplay('Applying a skill should be replayed.')
|
||||
apply(skillId: number, x: number, y: number): void {
|
||||
// ...真正的技能效果；回放时由 ReplayUseSkill 调用这里
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
把「记录 + 执行」的玩家入口与「只执行」的回放入口分开，可以避免同一次技能被记两遍。如果某个被动触发的路径会调用带记录的入口，用 `disable()` 与 `revert()` 把那段包住，并且必须配对。
|
||||
|
||||
## 怎么验证
|
||||
|
||||
录一段包含选择框的录像，再用样板内置的沙盒播放验证：回放时选择框会出现，并按录像里的选择自动选中，而不是等你点击；结束后检查选择带来的状态变化（例如 Flag 或道具数量）是否与录制时一致，并确认没有出现「选择录像缺失」的提示。
|
||||
录一段包含技能的录像，再用样板内置的沙盒播放验证：回放时技能会按录像里的参数再次执行，而不是等你操作；结束后检查技能带来的状态变化（例如目标怪物掉血、勇士属性变化）是否与录制时一致。
|
||||
|
||||
播放时不要禁用录制。沙盒播放本身也是一遍真实运行；禁用录制的话，这一遍不会留下任何录像，既不能重播，也无法拿它和原录像对比。样板的播放入口已经处理好播放流程，作者一般不需要自己写。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- **不要复用已删除的旧指令码**：数值属于录像格式，旧录像会按旧值解码。新语义一律追加新值。
|
||||
- **`Uint8` 下不要超过 255**：写入会截断，产生无法回放的录像。需要更多码时切 `Uint16`，并把它当成格式变更处理。
|
||||
- **参数类型必须与 `paramTypes` 一致**：只支持 `number`、`string`、`boolean`、`bigint`。传对象等无法编码的值会被丢弃，参数个数随之变化，基类会判为失败。
|
||||
- **被动步必须在主动步期间消费**：`getPassive()` 只在当前主动步执行期间暴露下一步；主动步返回后，未消费的被动步会被沙盒告警并按 code 194 跳过，等待它的代码会一直等下去。取到 handler 后一定要 `next`；忘记 `next` 不会让整条录像停住，只是不会读到下一个录像，沙盒随后会跳过这一步继续播放。
|
||||
- **`finalize` 返回 `Failed` 会中止播放**：它返回的是 `Promise<ReplayCommandResult>`，和 `execute` 一样会中断后续步骤，不要在里面吞掉错误。它需要跨步状态时，只能把数据保存在指令对象的成员里；指令对象在注册时创建一次，之后复用。
|
||||
|
||||
@ -65,12 +65,12 @@ function bindPathfindingLayer(state: ICoreState): void {
|
||||
|
||||
`IPathfindingResult` 只有两个字段：`status` 与 `path`。`path` 仅在状态为 `Success` 时非空。
|
||||
|
||||
| 状态 | 含义 | 处理建议 |
|
||||
| -------------------------------- | ------------------------------------------------------------------ | ------------------------------ |
|
||||
| `PathfindingStatus.Success` | 找到路径 | 读取 `path`，交给移动器 |
|
||||
| `PathfindingStatus.InvalidInput` | 输入不合法：未绑定移动器、图层、谓词或方向处理器，或起点不在地图内 | 检查绑定与起点坐标 |
|
||||
| `PathfindingStatus.NoPath` | 从起点出发无法到达目标点 | 不要移动；先检查通行谓词与图层 |
|
||||
| `PathfindingStatus.TargetUnder` | 目标点就在起点脚下 | 不需要移动 |
|
||||
| 状态 | 含义 | 处理建议 |
|
||||
| -------------------------------- | ------------------------------------------------------------------ | ----------------------- |
|
||||
| `PathfindingStatus.Success` | 找到路径 | 读取 `path`，交给移动器 |
|
||||
| `PathfindingStatus.InvalidInput` | 输入不合法：未绑定移动器、图层、谓词或方向处理器，或起点不在地图内 | 检查绑定与起点坐标 |
|
||||
| `PathfindingStatus.NoPath` | 找不到可行路径，例如目标被怪物挡住 | 正常结果，不需要处理 |
|
||||
| `PathfindingStatus.TargetUnder` | 目标点就在起点脚下 | 不需要移动 |
|
||||
|
||||
每一步是 `IPathfindingStep`，包含 `dir`（移动方向）、`from`（出发位置）与 `to`（到达位置）。`from` 与 `to` 都是只读的坐标对象；路径按起点到终点的顺序排列。
|
||||
|
||||
@ -298,7 +298,7 @@ async function verifyPathfinding(
|
||||
}
|
||||
```
|
||||
|
||||
预期英雄沿最小损失路径到达目标点；目标不可达时 `status` 为 `NoPath`，不会发生移动。若状态是 `InvalidInput`，按顺序检查移动器、图层、通行谓词与方向处理器是否都已绑定。
|
||||
预期英雄沿最小损失路径到达目标点；目标不可达时 `status` 为 `NoPath`，不会发生移动，这是正常结果（例如被怪物挡住）。若状态是 `InvalidInput`，按顺序检查移动器、图层、通行谓词与方向处理器是否都已绑定。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
@ -306,7 +306,7 @@ async function verifyPathfinding(
|
||||
- **`moveTo` 与 `teleportTo` 只在 `Success` 时启动**：`NoPath`、`TargetUnder`、`InvalidInput` 都会返回 `null`。
|
||||
- **上一次移动未结束时返回 `null`**：连续调用 `moveTo` 前先等 `controller.onEnd`，或显式 `interrupt()`。
|
||||
- **目标点在脚下不会移动**：`find` 在起点与终点相同时直接返回 `TargetUnder`。
|
||||
- **目标格必须可达**：图只包含从起点沿可通行边能到达的节点，不可达区域不会进入图。
|
||||
- **`NoPath` 是正常结果**：图只包含从起点沿可通行边能到达的节点；目标被怪物挡住或不可达时返回 `NoPath`，不会移动，也不需要特殊处理。
|
||||
- **谓词的 `shouldHit` 会标记终端节点**：终端节点只能作为路径终点，不能作为中间点；目标点不可达时优先检查 `canPass` 与 `shouldHit` 的组合。
|
||||
- **换楼层要重新绑定**：`useMapLayer` 绑定的是具体图层对象，旧楼层失效后必须换成新楼层的图层。
|
||||
- **图层必须属于同一个数据端对象**：`useMapLayer` 会校验图层来源，不属于当前状态时告警并忽略这次绑定。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user