docs(10-23): 编写高级 II 新增勇士属性

2026-10-21 23:00:29 +08:00 · 2026-10-21 18:50:08 +08:00 · 2026-10-21 18:50:08 +08:00 · 548007cdb7
commit 548007cdb7
parent 64fb0494d7
1 changed files with 304 additions and 0 deletions
--- a/docs/advanced/ii/adding-hero-attribute.md
+++ b/docs/advanced/ii/adding-hero-attribute.md
@ -0,0 +1,304 @@
+# 新增勇士属性
+
+勇士属性不只是数据表里多一列。一个属性会同时被默认值、内容配置、修饰器、伤害计算、装备与界面读取；只在接口里加字段，读取处会拿到 `undefined`，参与运算后变成 `NaN`。新增属性真正要补的，是这条链路上的每一处。
+
+本篇以攻速（`atkSpeed`，每回合造成的伤害按百分比缩放）与护甲（`armor`，按百分比减免最终伤害）为例，走完「改接口 → 补默认值与初始值 → 读取与修饰 → 接入伤害计算」的数据端流程。编辑器新增属性项与状态栏显示属于对应端的实现，本篇只留占位。
+
+## 新增属性要改哪五处
+
+| 位置     | 文件                                     | 要做什么                               |
+| -------- | ---------------------------------------- | -------------------------------------- |
+| 类型     | `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/data/enemy/calculator.ts` 等读取处  | 让属性真正影响伤害或其他运算           |
+| 显示     | 编辑器与渲染端                           | 编辑器属性项、状态栏显示（本篇不实现） |
+
+前四处缺一不可。接口决定编译期可见性，默认值与内容配置决定运行期取值，计算接入决定属性是否真的起作用。显示可以后补，但数据端必须先跑通。
+
+中级教程的[勇士属性](../../intermediate/hero-attribute.md)已经讲过基础属性、最终属性与修饰器的常用调用，这里补齐「新增一个属性」的完整改动面。
+
+## 改接口
+
+`IHeroAttr` 位于 `packages-user/data-common/src/types.ts`。要给攻速与护甲留位置，就在接口中增加两个数值字段：
+
+```ts
+export interface IHeroAttr {
+    /** 勇士名称 */
+    name: string;
+    /** 勇士等级 */
+    level: number;
+    /** 勇士生命值 */
+    hp: number;
+    /** 勇士生命值上限 */
+    hpmax: number;
+    /** 勇士攻击力 */
+    atk: number;
+    /** 勇士防御力 */
+    def: number;
+    /** 勇士护盾 */
+    mdef: number;
+    /** 勇士魔法值 */
+    mana: number;
+    /** 勇士魔法上限 */
+    manamax: number;
+    /** 勇士拥有的金币 */
+    money: number;
+    /** 勇士拥有的经验 */
+    exp: number;
+    /** 勇士攻速，百分比。100 表示正常速度，115 表示每回合造成 115% 伤害 */
+    atkSpeed: number;
+    /** 勇士护甲，百分比减伤。15 表示受到的最终伤害降低 15% */
+    armor: number;
+}
+```
+
+字段名一旦定下，就会被存档、内容配置、装备与插件引用，旧存档里也会以这个键保存数值。按项目的命名约定，新增公共字段要先确认名字再落笔；改名相当于改存档格式。
+
+两个字段都参与伤害计算，因此都是 `number`。如果某个属性只用于展示、不参与数值运算，也仍然建议放在 `IHeroAttr` 之外，避免被存档与装备系统当成可修饰属性。
+
+## 补默认值与初始值
+
+`HERO_DEFAULT_ATTRIBUTE` 是属性对象的完整形状。接口增加字段后，这里必须同步补齐：
+
+```ts
+/** 勇士的初始属性，数值填多少目前都无所谓，因为最终会从旧样板读取，但是必须得填 */
+export const HERO_DEFAULT_ATTRIBUTE: IHeroAttr = {
+    name: '',
+    level: 0,
+    hp: 1,
+    hpmax: 0,
+    atk: 0,
+    def: 0,
+    mdef: 0,
+    mana: 0,
+    manamax: 0,
+    money: 0,
+    exp: 0,
+    // 100 表示正常攻速，低于 100 变慢，高于 100 变快
+    atkSpeed: 100,
+    // 0 表示没有减伤；15 表示减伤 15%
+    armor: 0
+};
+```
+
+实际进入游戏的初始值来自内容配置 `src/content/core.jsonc` 的 `init.hero.attribute`，由 `state.hero.createAttribute(...)` 直接交给 `HeroAttribute` 构造。它不会与默认值合并，缺键就是缺键：
+
+```jsonc
+"attribute": {
+    "name": "勇士",
+    "level": 0,
+    "hp": 10000,
+    "atk": 100,
+    "def": 100,
+    "mdef": 0,
+    "mana": 0,
+    "manamax": 0,
+    "money": 0,
+    "exp": 0,
+    // 攻速以百分数存储：100 是正常速度
+    "atkSpeed": 100,
+    // 护甲同样以百分数存储：0 是不减伤
+    "armor": 0
+}
+```
+
+`core.jsonc` 允许注释，但这两项不是可选项。若只在接口与默认值里加、忘了内容配置，`getBaseAttribute('atkSpeed')` 会返回 `undefined`，`atkSpeed / 100` 随之变成 `NaN`，伤害与回合数都会失真。
+
+## 读取与修饰
+
+属性对象有两套读取方式：
+
+- `getBaseAttribute(name)` 读基础值，也就是存档里保存的数值；
+- `getFinalAttribute(name)` 读最终值，也就是基础值依次经过全部修饰器后的结果。
+
+写基础值要用 `state.hero.getModifiableAttribute()`；只读场景用 `state.hero.getAttribute()`。直接改基础值会触发重算，最终值随之更新。
+
+修饰器通过 `addModifier(name, modifier, save?)` 挂到某个属性上。内置的 `ValueModifier` 做数值加减，`PercentageModifier` 按基础值计算百分比：
+
+```ts
+import { ICoreState } from '@user/data-state';
+import { PercentageModifier } from '@user/data-base';
+
+/** 给勇士挂一个临时的 +15% 攻速。 */
+function addTemporaryAtkSpeed(state: ICoreState): void {
+    const attribute = state.hero.getModifiableAttribute();
+    const modifier = new PercentageModifier(0.15);
+
+    // 第三个参数为 false：这个修饰器不进属性存档，由拥有它的系统负责恢复
+    attribute.addModifier('atkSpeed', modifier, false);
+
+    // 需要结束时用同一个修饰器对象移除
+    // attribute.deleteModifier('atkSpeed', modifier);
+}
+```
+
+`PercentageModifier` 的参数是倍率，`0.15` 表示基础值的 15%。基础攻速为 `100` 时，最终攻速是 `100 + 100 * 0.15 = 115`；它乘的是基础值，不会把其他修饰器的结果再乘一遍。
+
+`save` 的取舍决定了读档后由谁恢复这个修饰器：
+
+- 装备产生的加成用 `false`。装备槽在读档时会重新穿戴，实例修饰器随之重挂；属性存档再存一份会重复计算。详见[勇士的装备系统](./equipment-system.md)。
+- 由某个系统长期维护的加成，也建议用 `false`，让该系统在自己的读档流程里恢复，避免两套来源各恢复一次。
+- 确实需要属性自己保存的修饰器用 `true`，但它的 `type` 必须已经通过 `registerModifier` 注册；读档时找不到构造器会静默跳过该修饰器。
+
+## 接入伤害计算
+
+`IDamageCalculator.calculate(handler)` 接收只读的怪物与勇士信息，返回 `{ damage, turn }`：`damage` 是这场战斗勇士会损失的总生命，`turn` 是打完怪物需要的回合数。内置实现在 `src/data/enemy/calculator.ts`，由 `src/data/enemy/initialize.ts` 通过 `damageSystem.useCalculator(new MainDamageCalculator())` 注册。
+
+攻速与护甲的接入点不同：
+
+- **攻速影响「每回合伤害」**。先算 `atk - monDef`，再乘 `atkSpeed / 100`，最后用缩放后的每回合伤害计算回合数。
+- **护甲影响「最终伤害」**。所有回合伤害汇总后，再乘 `1 - armor / 100`，并把护甲夹在 `0` 到 `100` 之间，避免负伤害或反向治疗。
+
+顺序不能反：攻速要在算回合数之前生效，护甲要在最终伤害上生效。下面保留与这两处改动相关的分支，其余特殊属性逻辑按原版保留：
+
+```ts
+import { IEnemyAttr, IHeroAttr } from '@user/data-common';
+import {
+    CriticalableHeroStatus,
+    IDamageCalculator,
+    IEnemyDamageInfoBase,
+    IReadonlyEnemyHandler
+} from '@user/data-system';
+
+/** 带攻速与护甲的勇士伤害计算器。 */
+export class MainDamageCalculator implements IDamageCalculator<
+    IEnemyAttr,
+    IHeroAttr
+> {
+    calculate(
+        handler: IReadonlyEnemyHandler<IEnemyAttr, IHeroAttr>
+    ): IEnemyDamageInfoBase {
+        const { enemy, hero } = handler;
+        const atk = hero.getFinalAttribute('atk');
+        const def = hero.getFinalAttribute('def');
+        const monAtk = enemy.getAttribute('atk');
+        const monDef = enemy.getAttribute('def');
+        const monHp = enemy.getAttribute('hp');
+
+        // [需改] 攻速缩放勇士的每回合伤害，必须发生在计算回合数之前
+        const atkSpeed = hero.getFinalAttribute('atkSpeed');
+        const heroPerDamage = ((atk - monDef) * atkSpeed) / 100;
+        if (heroPerDamage <= 0) {
+            return { damage: Infinity, turn: 0 };
+        }
+
+        // 回合数随每回合伤害同步变化
+        const turn = Math.ceil(monHp / heroPerDamage);
+
+        let enemyPerDamage = monAtk - def;
+        if (enemyPerDamage < 0) enemyPerDamage = 0;
+
+        // 此处保留原版的吸血、支援、先攻、破甲、反击、魔防等分支
+        let damage = (turn - 1) * enemyPerDamage;
+
+        // [需改] 护甲是最终减伤，先夹到 0 到 100，再换算成 0 到 1 的系数
+        const armor = Math.min(
+            Math.max(hero.getFinalAttribute('armor'), 0),
+            100
+        );
+        damage *= 1 - armor / 100;
+
+        // 此处保留固伤、仇恨、自爆等分支，它们按原版顺序排在护甲减伤之后
+        return { damage: Math.floor(damage), turn };
+    }
+
+    getCriticalLimit(
+        handler: IReadonlyEnemyHandler<IEnemyAttr, IHeroAttr>,
+        attribute: CriticalableHeroStatus<IHeroAttr>
+    ): number {
+        return handler.hero.getFinalAttribute(attribute);
+    }
+}
+```
+
+原来的 `MainDamageCalculator` 还有支援、先攻、破甲、反击、净化、固伤、自爆等分支；它们的相对位置不变，只是每回合伤害与最终伤害各多了一次缩放。改动时不要把护甲乘进 `enemyPerDamage`：那样只减免每回合伤害，先攻、破甲等一次性伤害会漏掉护甲。
+
+`getCriticalLimit` 也要跟着新属性考虑。它决定临界计算的搜索上界；自定义属性若参与伤害，至少要让读取该属性的方式与计算器一致，避免界面显示一个值、战斗按另一个值结算。
+
+## 与装备和道具的关系
+
+装备的 `value` 与 `percentage` 是按属性名索引的记录，新属性不需要额外注册。只要 `IHeroAttr` 里有这个数值字段，装备定义就能直接写：
+
+```ts
+import { IHeroAttr, IItemEquipData } from '@user/data-common';
+
+/** 一件提供 +15% 攻速的武器。 */
+export const attackSpeedEquip: IItemEquipData<IHeroAttr> = {
+    slots: ['weapon'],
+    // 动画 id 由内容层定义，这里换成你自己的装备动画
+    animate: 'equip',
+    // 数值加成：攻速只走百分比，不额外加固定值
+    value: { atkSpeed: 0 },
+    // 百分比加成：沿用装备系统的约定，0.15 表示 15%
+    percentage: { atkSpeed: 0.15 },
+    // 这两个字段目前只是数据，引擎不会自动执行
+    loadEvent: null,
+    unloadEvent: null
+};
+```
+
+装备实例会把这些记录转成 `ValueModifier` 与 `PercentageModifier`，穿戴时挂到勇士属性，卸下时移除。基础攻速 `100` 配上 `percentage.atkSpeed = 0.15`，最终攻速就是 `115`。注意属性本身按百分数存储（`15` 表示 15%），而装备的 `percentage` 是倍率（`0.15` 表示 15%），两者写法不同。
+
+道具效果若要直接改攻速，也可以调用 `state.hero.getModifiableAttribute().add('atkSpeed', value)` 或挂修饰器；道具效果属于内容层，这里不额外展开。
+
+## 编辑器与状态栏
+
+编辑器需要在英雄属性面板增加攻速与护甲两个输入项；状态栏需要在合适的位置显示它们的当前值。两处都属于对应端的实现，不在本篇范围内：
+
+- `编辑器 · 新增英雄属性项`
+- `渲染端 · 状态栏`
+
+<!-- TODO(advanced-II): 编辑器属性项与状态栏显示 -->
+
+数据端完成后，这两个入口只需要读取 `getFinalAttribute('atkSpeed')` 与 `getFinalAttribute('armor')`。在它们实现之前，先用控制台或调试脚本确认数值正确。
+
+## 怎么验证
+
+先准备一只属性固定的怪物，避免光环、支援或随机因素干扰。把内容配置里的 `atkSpeed` 设为 `100`、`armor` 设为 `0`，读取最终属性，再穿上一件 +15% 攻速的装备，最后观察伤害变化：
+
+```ts
+import { IEnemyAttr } from '@user/data-common';
+import { ICoreState } from '@user/data-state';
+import { IEnemyView } from '@user/data-system';
+
+/** 打印攻速、护甲与对指定怪物的伤害。 */
+function verifyHeroAttribute(
+    state: ICoreState,
+    enemy: IEnemyView<IEnemyAttr>
+): void {
+    const attribute = state.hero.getAttribute();
+    console.log('攻速', attribute.getFinalAttribute('atkSpeed'));
+    console.log('护甲', attribute.getFinalAttribute('armor'));
+
+    const damageSystem = state.enemyContext.getDamageSystem();
+    if (!damageSystem) return;
+
+    const info = damageSystem.getDamageInfo(enemy);
+    if (!info) return;
+
+    console.log('伤害', info.damage, '回合', info.turn);
+}
+```
+
+预期现象：
+
+- 初始攻速为 `100`、护甲为 `0`；
+- 穿上 +15% 攻速的装备后，最终攻速变为 `115`，同一只怪物的战斗回合数下降；
+- 把护甲调高后，`damage` 随护甲上升而下降，`turn` 不变。
+
+若最终攻速是 `NaN`，先检查 `core.jsonc` 与 `HERO_DEFAULT_ATTRIBUTE` 是否都补了键；若装备穿上后数值不变，检查装备定义的键名是否与接口字段完全一致。
+
+## 边界与注意
+
+- **所有创建英雄属性的位置都要补键**：默认值、内容配置、测试夹具各一处。`Partial<IHeroAttr>` 不会报缺键，但运行时仍会读到 `undefined`。
+- **内容配置不会与默认值合并**：`createAttribute` 直接使用传入对象，缺键就是 `undefined`；不要指望默认值兜底。
+- **百分数属性统一用百分数存储**：`15` 表示 15%，计算时再除以 `100`。装备的 `percentage` 则是倍率，`0.15` 表示 15%。
+- **不要把新属性塞进既有汇总字段**：例如不要把攻速加进 `money` 或 `exp` 的统计逻辑，读这些字段的系统并不知道新属性的语义。
+- **新增字段会影响存档结构**：读旧档时缺失的键不会自动补齐，需要在使用前给默认值；写入新档后，旧版本读到多出的键通常可忽略，但不能假设旧版本认识它。
+- **`save = true` 的修饰器要注册类型**：读档按 `type` 查构造器，未注册的修饰器会被静默跳过，数值看起来「读档后消失了」。
+- **护甲要夹在有效区间**：大于 `100` 会变成治疗，负数会放大伤害；在计算器入口统一夹一次。
+- **攻速改动会影响回合数**：凡是依赖 `turn` 的逻辑（支援、先攻、状态持续时间）都要跟着复核，不能只改伤害数字。
+- **编辑器与状态栏尚未接入**：在对应端实现之前，不要假设属性会自动出现在界面上。
+
+渲染端如何展示这两个属性不在本篇范围内。 <!-- TODO(renderer): 攻速与护甲的状态栏显示 -->