From 0207f3ce7b1a16f064621ef7f85be3e566c740e9 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Sat, 17 Oct 2026 21:59:56 +0800 Subject: [PATCH] =?UTF-8?q?docs(10-11):=20=E8=BF=AD=E4=BB=A3=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=E8=AF=BB=E8=80=85=E9=98=BB=E6=96=AD=E9=97=AE=E9=A2=98?= =?UTF-8?q?=EF=BC=88=E7=AC=AC2=E8=BD=AE=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - B-03: enemy-specials.md 新增「内置属性编号表」（0..26，逐条抄自当前 special.ts），表下 warning 诚实标注地图伤害转换器编号未对齐（以 special.ts 为准，不臆造对齐表） - B-03: enemy-map-damage.md 明确点出 code 18 在内置表=无敌、转换器=阻击的双重含义 - B-03: enemy-combat-script.md 的 code 18 示例注明 18=无敌，并说明转换器未对齐与本篇无关 - R2-01: 解释 @motajs/anon-tokyo 的来历（events.md + src-tour.md「包从哪来」） - R2-02: enemy-aura.md 补 ISpecial23Value 字段说明表 - R2-03: 补 initializeEnemy 一句话介绍（集中注册入口，内置/自定义同一流程） - R2-04: events.md 说明参数接口实际放入 src/data/event/types.ts - R2-05: hero-equipment.md 接口清单补 compareEquip - R2-06: enemy-map-damage.md code-43 示例补关键类型注解 - 追加第 2 轮复审与修正记录到 10-11-READER-REVIEW.md --- .../10-11-READER-REVIEW.md | 52 +++++++++++++++++++ docs/intermediate/enemy-aura.md | 12 ++++- docs/intermediate/enemy-combat-script.md | 4 +- docs/intermediate/enemy-map-damage.md | 4 +- docs/intermediate/enemy-specials.md | 40 +++++++++++++- docs/intermediate/events.md | 6 +-- docs/intermediate/hero-equipment.md | 3 +- docs/intermediate/src-tour.md | 2 +- 8 files changed, 114 insertions(+), 9 deletions(-) diff --git a/.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md b/.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md index c4cf275..f6ee3af 100644 --- a/.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md +++ b/.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md @@ -90,4 +90,56 @@ - 构建门禁：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` → **green**，输出 `build complete`，dead link = 0。 - 非阻断项（N-01..N-18）：本轮不修，留待用户判断。 +--- + +## 第 2 轮 · 复审问题清单（round 2 recheck） + +**复审结果：** 首轮 13 条阻断性问题中 **12 条已消除**；`B-03` 仍阻断，另有 6 个新的可操作困惑点。 + +### 仍阻断（1） + +| # | 问题 | 定位 | +|---|------|------| +| B-03 | 特殊属性 `code` 仍无统一编号表，读者不知哪个号对应哪种机制；且同一数字在不同页面含义不同（18 在 `enemy-combat-script.md` 作「无敌」，在 `enemy-map-damage.md` 作「阻击」），内置属性无法据此配置 | `enemy-specials.md`、`enemy-map-damage.md`、`enemy-combat-script.md` | + +### 新的可操作困惑点（6） + +| # | 问题 | 定位 | +|---|------|------| +| R2-01 | `@motajs/anon-tokyo`（`BuiltInFunction` 的来源）从未解释 | `events.md` | +| R2-02 | 内置光环 code 23 经 `setValue({...})` 使用的字段（`range/square/hpBuff/atkBuff/defBuff`）未定义 | `enemy-aura.md` | +| R2-03 | `initializeEnemy` 被战斗各篇反复引用却从未介绍 | `enemy-specials.md`、`enemy-aura.md`、`enemy-map-damage.md` | +| R2-04 | 参数接口该放哪（`src/data/event/types.ts`）与内联示例混淆 | `events.md` | +| R2-05 | `compareEquip` 在正文使用，却未列入 `IHeroEquipment` 接口清单 | `hero-equipment.md` | +| R2-06 | code-43 示例中 `FaceGroup.Dir4` / `IFaceHandler` / `dir.mapMovement()` / `MapDamageType.Layer` 未作注解 | `enemy-map-damage.md` | + +### 记录但不修（供用户判断） + +- N-4：`data-plugins.md` 的示例仍为占位（已知，待用户提供「较简单插件」，D-44）。 + +## 第 2 轮迭代记录（Task 2 · round 2） + +**本轮目标：** 消除仍阻断的 `B-03`，并处理 6 个新的可操作困惑点（`R2-01..R2-06`）。 + +### 逐条处置 + +| # | 处置 | 改动文件 | +|---|------|----------| +| B-03 | `enemy-specials.md` 新增「内置属性编号表」小节：从**当前** `src/data/enemy/special.ts` 的 `map.set(code, ...)` 逐条抄录 `0..26` 的 code→名称（0 空 / 1 先攻 / 2 魔攻 / 3 坚固 / 4 n连击 / 5 破甲 / 6 反击 / 7 净化 / 8 模仿 / 9 吸血 / 10 中毒 / 11 衰弱 / 12 诅咒 / 13 领域 / 14 夹击 / 15 仇恨 / 16 阻击 / 17 自爆 / 18 无敌 / 19 退化 / 20 固伤 / 21 重生 / 22 激光 / 23 光环 / 24 支援 / 25 捕捉 / 26 特殊光环），并附各 code 的参数形态。表下以 warning 说明地图伤害转换器读取的编号与内置表**不一致**，不臆造「已对齐」的编号。核心信息按用户口径落定：以 `special.ts` 注册的编号为**权威**，转换器偏差标注为「编号未对齐 / 待补齐」。 | `enemy-specials.md` | +| B-03 | `enemy-map-damage.md` 的「编号未对齐」warning 明确点出 18 号的双重含义（`special.ts` 定义 18 = 无敌，转换器却读作阻击），并说明 16、24 同样不一致；保留「改用转换器真正读取的 code，或改转换器使其对齐」的可操作二选一。 | `enemy-map-damage.md` | +| B-03 | `enemy-combat-script.md` 的 code 18 示例注明「18 = 无敌」（链到编号表），并说明地图伤害转换器把 18 读作阻击是转换器自身未对齐，与本篇判定无关——两处不再在无提示的情况下给出同一数字的两种含义。 | `enemy-combat-script.md` | +| R2-01 | `events.md` 的 `BuiltInFunction` 注明来自 `@motajs/anon-tokyo`（负责解释执行事件脚本的包）；`src-tour.md`「包从哪来」把 `@motajs/anon-tokyo` 补为该层示例。 | `events.md`、`src-tour.md` | +| R2-02 | `enemy-aura.md` 内置光环表下补 `ISpecial23Value` 字段说明表（`range` / `square` / `hpBuff` / `atkBuff` / `defBuff`，已核对 `special.ts`）。 | `enemy-aura.md` | +| R2-03 | `enemy-specials.md`、`enemy-aura.md` 补 `initializeEnemy` 一句介绍（`src/data/enemy/initialize.ts` 中集中注册内置怪物功能的入口函数），并说明内置与自定义走同一注册流程。 | `enemy-specials.md`、`enemy-aura.md` | +| R2-04 | `events.md` 两处示例注明：参数接口实际应放入 `src/data/event/types.ts`，示例为紧凑才内联书写。 | `events.md` | +| R2-05 | `hero-equipment.md` 的 `IHeroEquipment` 接口清单补入 `compareEquip(equipA, equipB, slot)`。 | `hero-equipment.md` | +| R2-06 | `enemy-map-damage.md` code-43 示例补 `FaceGroup.Dir4` / `dir.mapMovement()` / `IFaceHandler` / `IFaceDescriptor` / `MapDamageType.Layer` 各一句简短注解。 | `enemy-map-damage.md` | + +### 校验 + +- 源码核对：`src/data/enemy/special.ts`（`map.set` 0..26）、`src/data/enemy/mapDamage.ts`（转换器读取 15/16/18/24/27）、`src/data/enemy/types.ts`（`MapDamageType`：`Unknown/Zone/Layer/Repulse/Between`）、`src/data/enemy/initialize.ts`（`initializeEnemy` 集中注册）。 +- 结构门禁：本轮被改的 7 篇（`enemy-specials`、`enemy-map-damage`、`enemy-combat-script`、`src-tour`、`events`、`enemy-aura`、`hero-equipment`）均 CRLF、单 H1。 +- 构建门禁：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` → **green**，输出 `build complete`，dead link = 0。 +- 非阻断项（N-01..N-18）：本轮仍不修，留待用户判断；N-4 已知、待用户提供示例后处理。 + diff --git a/docs/intermediate/enemy-aura.md b/docs/intermediate/enemy-aura.md index ba05c77..e0578d9 100644 --- a/docs/intermediate/enemy-aura.md +++ b/docs/intermediate/enemy-aura.md @@ -28,7 +28,17 @@ | 支援 | 24 | `GuardAura` | 5 | 把范围内的怪物登记为支援者，战斗时一起结算 | | 特殊光环 | 26 | `SpecialAura` | 20 | 通过 `SpecialAuraModifier` 给目标添加或修改特殊属性 | -这三类都在 `src/data/enemy/aura.ts` 中实现，并在 `initializeEnemy` 里通过 `ctx.registerAuraConverter(...)` 注册。 +这三类都在 `src/data/enemy/aura.ts` 中实现，并在 `initializeEnemy` 里通过 `ctx.registerAuraConverter(...)` 注册（`initializeEnemy` 是 `src/data/enemy/initialize.ts` 中集中注册内置怪物功能的入口函数；内置的光环转换器与你自己新增的转换器都从这里注册）。 + +普通光环（code 23）的参数接口是 `ISpecial23Value`，下文示例里 `setValue({...})` 传入的就是这几个字段： + +| 字段 | 含义 | +|------|------| +| `range` | 光环范围值；为 0 时作用于同楼层所有怪物 | +| `square` | `true` 为矩形范围，`false` 为十字范围（范围大于 1 时按曼哈顿距离计算） | +| `hpBuff` | 目标生命值提升百分比 | +| `atkBuff` | 目标攻击力提升百分比 | +| `defBuff` | 目标防御力提升百分比 | ## 运作方式 diff --git a/docs/intermediate/enemy-combat-script.md b/docs/intermediate/enemy-combat-script.md index 328627c..4781faf 100644 --- a/docs/intermediate/enemy-combat-script.md +++ b/docs/intermediate/enemy-combat-script.md @@ -52,7 +52,7 @@ state.combat.addCombatScript(new MainCombatScript()); ## 战前示例：拥有某特殊属性时无法战斗 -下面的脚本检查怪物是否拥有 code 18 的特殊属性（无敌），有则直接放弃战斗（示例里的 `@motajs/*`、`@user/*` 是包名，含义见 [src 导览](./src-tour.md) 的「包从哪来」）： +下面的脚本检查怪物是否拥有 code 18 的特殊属性（无敌，编号见[特殊属性](./enemy-specials.md)的「内置属性编号表」），有则直接放弃战斗（示例里的 `@motajs/*`、`@user/*` 是包名，含义见 [src 导览](./src-tour.md) 的「包从哪来」）： ```ts import { IEnemyAttr, IHeroAttr } from '@user/data-common'; @@ -84,6 +84,8 @@ state.combat.addCombatScript(new SealCombatScript()); `priority = 100` 让它先于内置脚本执行；返回 `false` 后，后续战前脚本、战后脚本与 `onAfterCombat` 钩子都不会执行。 +这里的 18 号在内置属性编号表里就是「无敌」。地图伤害转换器把 18 读作「阻击」是它自身的编号未对齐（见[地图伤害](./enemy-map-damage.md)），与本篇的判定无关。 + ## 战后示例：战后玩家回复固定量生命值 下面的脚本在每场战斗后给勇士回复 20 点生命： diff --git a/docs/intermediate/enemy-map-damage.md b/docs/intermediate/enemy-map-damage.md index 44439d6..480fbdf 100644 --- a/docs/intermediate/enemy-map-damage.md +++ b/docs/intermediate/enemy-map-damage.md @@ -44,7 +44,7 @@ mapDamage?.useConverter(new MainMapDamageConverter()); :::warning 编号与结算：今日可用 vs 待补齐 - **今日可用**：地图伤害系统本身的三个部件——伤害视图、转换器、合并器——都已实现，注册（`useConverter` / `useReducer`）照常可用。只要让特殊属性使用转换器真正读取的 code，或按下方「受地形遮挡的激光」那样自定义属性 + 转换器，地图伤害就能生效。 -- **待补齐（编号未对齐）**：上表两组 code 目前并不一致——转换器实际读取的是 15、16、18、24、27，而 `special.ts` 注册的是 13、14、16、22、24，且没有 27。因此按当前 `src/` 代码，直接给怪物挂上内置的「领域 / 夹击 / 阻击 / 激光」特殊属性，并不会产生对应的地图伤害；「伏击」在内置特殊属性里也没有登记。使用内置编号前，请以你的 `src/data/enemy/mapDamage.ts` 为准二选一：让特殊属性改用转换器真正读取的 code，或修改转换器使其与 `special.ts` 对齐。 +- **待补齐（编号未对齐）**：上表两组 code 目前并不一致——转换器实际读取的是 15、16、18、24、27，而 `special.ts` 注册的是 13、14、16、22、24，且没有 27。因此按当前 `src/` 代码，直接给怪物挂上内置的「领域 / 夹击 / 阻击 / 激光」特殊属性，并不会产生对应的地图伤害；「伏击」在内置特殊属性里也没有登记。其中 18 号尤其容易混淆：`special.ts` 把 18 定义为「无敌」（[战斗脚本](./enemy-combat-script.md)的示例正是用它判断怪物不可战胜），而这里的转换器却把 18 读作「阻击」——同一个数字在被两处代码赋予两种含义，这正是编号未对齐的直接体现；16、24 同样存在转换器与内置表不一致的情况。使用内置编号前，请以你的 `src/data/enemy/mapDamage.ts` 为准二选一：让特殊属性改用转换器真正读取的 code，或修改转换器使其与 `special.ts` 对齐。 - **待补齐（实际结算）**：移动时真正的结算逻辑仍在补齐，见下文「实际结算」。 ::: @@ -59,6 +59,8 @@ mapDamage?.useConverter(new MainMapDamageConverter()); 示例里的 `@motajs/*`、`@user/*` 是包名，含义见 [src 导览](./src-tour.md) 的「包从哪来」；`map.set(...)` 的 `map` 是 `special.ts` 中 `createSpecials(state)` 建的属性表，见[特殊属性](./enemy-specials.md)。 +示例里出现的几个名字先简单说明：`FaceGroup.Dir4` 是「四方向」朝向组，`faceManager` 按朝向组管理朝向；`dir.mapMovement()` 把朝向处理器映射成各方向对应的移动量，示例据此取出四个方向；`IFaceHandler` / `IFaceDescriptor` 分别是「朝向处理器」与「单个朝向」的类型；`MapDamageType.Layer` 是伤害类型枚举里的「激光伤害」（定义在 `src/data/enemy/types.ts`）。 + ```ts /** 43 - 遮挡激光 */ export interface ISpecial43Value { diff --git a/docs/intermediate/enemy-specials.md b/docs/intermediate/enemy-specials.md index 5bd3cb2..5386d01 100644 --- a/docs/intermediate/enemy-specials.md +++ b/docs/intermediate/enemy-specials.md @@ -8,6 +8,44 @@ 访问怪物特殊属性的入口见[战斗总览](./combat-overview.md)。 +## 内置属性编号表 + +下表是 `src/data/enemy/special.ts` 里 `map.set(code, ...)` 当前注册的全部内置属性，code 与名称一一对应。判断「某个数字代表哪种机制」时以本表为准： + +| code | 名称 | 参数 | +|------|------|------| +| 0 | 空 | 无 | +| 1 | 先攻 | 无 | +| 2 | 魔攻 | 无 | +| 3 | 坚固 | 无 | +| 4 | n连击 | 每回合攻击次数 | +| 5 | 破甲 | 附加伤害百分比 | +| 6 | 反击 | 附加伤害百分比 | +| 7 | 净化 | 附加伤害倍数 | +| 8 | 模仿 | 无 | +| 9 | 吸血 | `ISpecial9Value`（比例与是否加到自身） | +| 10 | 中毒 | 每步损失生命值 | +| 11 | 衰弱 | 攻防下降比例 | +| 12 | 诅咒 | 无 | +| 13 | 领域 | `ISpecial13Value` | +| 14 | 夹击 | 无 | +| 15 | 仇恨 | 无 | +| 16 | 阻击 | 伤害值 | +| 17 | 自爆 | 无 | +| 18 | 无敌 | 无 | +| 19 | 退化 | `ISpecial19Value`（攻防下降值） | +| 20 | 固伤 | 固定伤害值 | +| 21 | 重生 | 无 | +| 22 | 激光 | 伤害值 | +| 23 | 光环 | `ISpecial23Value` | +| 24 | 支援 | 无 | +| 25 | 捕捉 | 无 | +| 26 | 特殊光环 | `ISpecial26Value` | + +:::warning 地图伤害转换器编号未对齐 +`src/data/enemy/mapDamage.ts` 里的转换器目前读取的编号与上表**不一致**：它把 15 当作领域、18 当作阻击、24 当作激光（详见[地图伤害](./enemy-map-damage.md)）。以**本表**为准理解「编号代表哪种机制」；地图伤害的这条偏差属于转换器尚未对齐，挂上内置属性不一定立刻产生对应效果。 +::: + ## 在数据里的样子 数据端的怪物对象（`IReadonlyEnemy`）提供三个读取接口： @@ -112,7 +150,7 @@ map.set( ); ``` -`createSpecials(state)` 返回 `Map>`。`initializeEnemy` 会遍历这个 Map，逐个调用 `state.enemyManager.registerSpecial(code, cons)`，所以新增属性只要放进这个 Map 就会完成注册。 +`createSpecials(state)` 返回 `Map>`。`initializeEnemy`（`src/data/enemy/initialize.ts`，数据端集中注册内置怪物功能的入口函数）会遍历这个 Map，逐个调用 `state.enemyManager.registerSpecial(code, cons)`。也就是说，内置属性与你自己新增的属性走的是同一套注册流程：只要把新属性放进这个 Map，它就会随 `initializeEnemy` 一起完成注册。 ## 属性实现位置 diff --git a/docs/intermediate/events.md b/docs/intermediate/events.md index f2d2dee..71203f3 100644 --- a/docs/intermediate/events.md +++ b/docs/intermediate/events.md @@ -6,7 +6,7 @@ ## 内建函数（BuiltInFunction） -事件里能调用的每一个动作都叫**内建函数**，接口为 `BuiltInFunction`： +事件里能调用的每一个动作都叫**内建函数**，接口为 `BuiltInFunction`（来自 `@motajs/anon-tokyo`——引擎里负责把事件脚本解释执行的包，其归属层级见 [src 导览](./src-tour.md) 的「包从哪来」）： ```ts interface BuiltInFunction { @@ -93,7 +93,7 @@ export function createEventRegistrations(): BuiltInFunction[] { ## 示例：设置 Flag -下面这个事件函数把参数里的 Flag 名与值写进 Flag 系统（示例里的 `@motajs/*`、`@user/*` 是包名，含义见 [src 导览](./src-tour.md) 的「包从哪来」）： +下面这个事件函数把参数里的 Flag 名与值写进 Flag 系统。示例为了紧凑，把参数接口 `ISetFlagEventParam` 直接写在同一个代码块里；实际编写时按上文「参数接口」一节，把它放进 `src/data/event/types.ts`，只把事件函数类放到 `src/data/event/` 下（示例里的 `@motajs/*`、`@user/*` 是包名，含义见 [src 导览](./src-tour.md) 的「包从哪来」）： ```ts import { BuiltInFunction } from '@motajs/anon-tokyo'; @@ -133,7 +133,7 @@ Flag 的读写接口见 [Flag 变量](./flags.md)。 ## 示例：勇士回血 -再写一个让勇士回复生命值的事件函数。它读取参数里的回复量，通过可修改属性接口加到勇士的 `hp` 上： +再写一个让勇士回复生命值的事件函数。它读取参数里的回复量，通过可修改属性接口加到勇士的 `hp` 上（参数接口同样应放入 `src/data/event/types.ts`，这里为紧凑仍内联书写）： ```ts import { BuiltInFunction } from '@motajs/anon-tokyo'; diff --git a/docs/intermediate/hero-equipment.md b/docs/intermediate/hero-equipment.md index d68a618..9f31f53 100644 --- a/docs/intermediate/hero-equipment.md +++ b/docs/intermediate/hero-equipment.md @@ -13,7 +13,8 @@ - `unequip(slot)`：卸下指定槽的装备； - `equipped(uid)`：查询某装备是否处于装备状态； - `getEquipped(slot)`：取指定槽的装备 uid； -- `getEquips()`：按槽位顺序取所有已装备实例。 +- `getEquips()`：按槽位顺序取所有已装备实例； +- `compareEquip(equipA, equipB, slot)`：比较两件装备在同一槽位上的属性表现，详见下文「比较装备」。 `slot` 可以传装备槽索引（数字）或槽位名称（字符串）。`EquipStatus` 有三个取值：`CanEquip`（可以直接装备）、`CannotEquip`（不能装备）、`NeedReplace`（需要替换槽位上的装备）。 diff --git a/docs/intermediate/src-tour.md b/docs/intermediate/src-tour.md index 2ee0968..106e109 100644 --- a/docs/intermediate/src-tour.md +++ b/docs/intermediate/src-tour.md @@ -10,7 +10,7 @@ - `src/`：你的**游戏本体**，入口代码与游戏内容都放这里。它对应的包名是 `@user/main`，但教程几乎不会在 `import` 里写出它； - `packages-user/`：**用户工程包**，包名以 `@user/` 开头（如 `@user/data-base`、`@user/data-system`）。它是引擎面向游戏的二次封装，改动这里相当于扩展引擎； -- `packages/`：**核心引擎包**，包名以 `@motajs/` 开头（如 `@motajs/common`）。它由引擎作者维护，一般不需要改。 +- `packages/`：**核心引擎包**，包名以 `@motajs/` 开头（如 `@motajs/common`；[自定义事件](./events.md)里 `BuiltInFunction` 来自的 `@motajs/anon-tokyo` 也在这一层，它负责解释执行事件脚本）。它由引擎作者维护，一般不需要改。 依赖方向是单向的：`src` → `packages-user` → `packages`。也就是说，`src` 可以引用 `@user/*` 与 `@motajs/*`，`packages-user` 只能引用 `@motajs/*`，反过来不行。所以看到示例里 `import ... from '@user/xxx'` 或 `'@motajs/xxx'`，照抄即可——这些包都已随项目安装好，不需要你手动创建。