伤害系统

Attribute 的伤害类型位于 damage_types/*.yml。当前伤害系统采用 stages 多阶段管线计算，而不是固定公式。每个伤害类型都可以配置自己的攻击、防御、暴击、穿透和恢复规则。

伤害类型配置

顶层字段

字段	类型	必填	默认值	说明
`id`	string	是	—	伤害类型唯一 ID，例如 `physical`、`projectile`、`spell`。
`display_name`	string	否	同 `id`	显示名称。
`aliases`	list<string>	否	`[]`	别名列表，用于兼容旧配置或简写。
`hard_lock`	boolean	否	`false`	是否强接管该类型伤害。为 true 时，匹配的原版伤害事件会被完全替换为属性伤害计算。
`allowed_events`	list<string>	否	`[]`	允许触发此伤害类型的事件名白名单。空列表表示不限制。
`description`	string	否	`""`	描述文本。
`message`	string	否	—	攻击者和目标共用的战斗消息。可被下面两个字段覆盖。
`attacker_message`	string	否	—	攻击者收到的消息。
`target_message`	string	否	—	目标收到的消息。
`stages`	list	否	`[]`	伤害计算阶段列表。
`recovery`	object	否	—	战后恢复或吸血计算配置。

内置伤害类型

默认生成三个伤害类型文件：

physical.yml — 物理伤害（近战）
projectile.yml — 投射物伤害（弓箭、三叉戟）
spell.yml — 法术伤害

stages 多阶段管线

伤害计算按 stages 列表顺序执行。每个阶段读取指定属性，按规则计算后叠加到最终伤害值上。

stage 字段

字段	类型	必填	默认值	说明
`id`	string	否	`"stage"`	阶段 ID，用于调试输出。
`kind`	enum	否	`FLAT_PERCENT`	计算类型。
`source`	enum	否	`ATTACKER`	属性来源。
`mode`	enum	否	`ADD`	结果叠加方式。
`flat_attributes`	list<string>	否	`[]`	参与平坦加成的属性 ID 列表。
`percent_attributes`	list<string>	否	`[]`	参与百分比加成的属性 ID 列表。
`chance_attributes`	list<string>	否	`[]`	参与概率触发的属性 ID 列表。
`multiplier_attributes`	list<string>	否	`[]`	参与乘数的属性 ID 列表。
`expression`	string	否	`""`	自定义计算表达式（`kind=CUSTOM` 时使用）。
`min_result`	double	否	—	阶段结果下限。
`max_result`	double	否	—	阶段结果上限。
`min_chance`	double	否	—	概率下限。
`max_chance`	double	否	—	概率上限。
`min_multiplier`	double	否	—	乘数下限。
`max_multiplier`	double	否	—	乘数上限。

kind 计算类型

值	说明
`FLAT_PERCENT`	标准模式：先计算 flat 属性总和，再乘以 percent 属性加成，再判断 chance 触发和 multiplier 乘数。
`CUSTOM`	自定义表达式模式：使用 `expression` 字段的公式计算。

source 属性来源

值	说明
`ATTACKER`	从攻击方读取属性。
`TARGET`	从防御方读取属性。
`CONTEXT`	从上下文读取（用于特殊场景）。

mode 叠加方式

值	说明
`ADD`	将阶段结果加到当前伤害值上。
`SUBTRACT`	将阶段结果从当前伤害值中减去。

典型物理伤害管线

yaml

id: physical
display_name: '物理伤害'
hard_lock: true
stages:
  # 阶段 1：基础攻击
  - id: base_attack
    kind: FLAT_PERCENT
    source: ATTACKER
    mode: ADD
    flat_attributes:
      - physical_attack
    percent_attributes:
      - physical_attack_percent

  # 阶段 2：暴击
  - id: critical
    kind: FLAT_PERCENT
    source: ATTACKER
    mode: ADD
    chance_attributes:
      - physical_crit_rate
    multiplier_attributes:
      - physical_crit_damage
    min_chance: 0
    max_chance: 1
    min_multiplier: 0

  # 阶段 3：防御减伤
  - id: defense
    kind: FLAT_PERCENT
    source: TARGET
    mode: SUBTRACT
    flat_attributes:
      - physical_defense
    percent_attributes:
      - physical_defense_percent
    min_result: 0

  # 阶段 4：穿透（减少防御效果）
  - id: penetration
    kind: FLAT_PERCENT
    source: ATTACKER
    mode: ADD
    flat_attributes:
      - physical_penetration
    percent_attributes:
      - physical_penetration_percent
    min_result: 0

recovery:
  source: ATTACKER
  flat_attributes:
    - lifesteal_flat
  percent_attributes:
    - lifesteal_percent
  min_result: 0

recovery 恢复配置

恢复配置用于计算攻击后的吸血或回复效果。

字段	类型	默认值	说明
`source`	enum	`ATTACKER`	回复属性来源。
`resistance_source`	enum	`TARGET`	抗性属性来源。
`flat_attributes`	list<string>	`[]`	平坦回复属性。
`percent_attributes`	list<string>	`[]`	百分比回复属性（基于最终伤害的百分比）。
`resistance_attributes`	list<string>	`[]`	抗性属性（减少回复效果）。
`expression`	string	`""`	自定义回复表达式。
`min_result`	double	—	回复结果下限。
`max_result`	double	—	回复结果上限。

原版伤害接管模式

全局 vanilla_event_damage.enabled 是当前原版伤害接管模式开关：

enabled: true：当前推荐的完美接管模式。Attribute 不取消原版伤害事件，而是在事件返回前同步结算 EA 伤害并原地改写最终伤害值。这样能保留原版副作用，例如着火僵尸点燃玩家、铁傀儡击飞、盾牌格挡、吸收之心、荆棘、死亡统计等。
enabled: false：兼容模式。按旧逻辑取消事件后由 Attribute 重放伤害与反馈，适合需要保留旧行为或与特殊战斗插件联调的服务器。

完美接管模式只改变“伤害如何施加”，不改变当前伤害数值管线。结算结果为闪避、事件取消或最终伤害小于等于 0 时，本次原版事件会被取消。吸血、战斗消息和攻击冷却等 Attribute 自身副作用仍由 Attribute 补发。

合成命中反馈

合成命中反馈主要服务于兼容模式；在完美接管模式下，原版通常会自然产生击退、受伤动画和音效。synthetic_hit_feedback 用于在需要时补发击退和受伤音效，让战斗反馈更接近原版体验。

yaml

synthetic_hit_feedback:
  knockback: true
  knockback_strength: 0.4
  hurt_sound: true

字段	说明
`knockback`	是否补发击退。
`knockback_strength`	击退强度。数值越高，目标位移越明显。
`hurt_sound`	是否播放受伤音效。

调参建议：

如果服务器有自定义击退插件，先关闭 knockback 测试兼容性。
如果战斗节奏偏快，过强的击退会影响近战连段，可降低 knockback_strength。
如果战斗消息、粒子和音效较多，可以关闭 hurt_sound 降低反馈噪音。

hard_lock 与 allowed_events

hard_lock

hard_lock: true 表示该伤害类型会完全接管匹配的原版伤害事件。原版伤害值会被忽略，改为使用属性系统计算。

全局配置 config.yml 中的 hard_lock_damage 会影响未命中任何伤害类型白名单的原版伤害。配置时要谨慎：

设为 true：所有伤害都走属性系统，包括火焰、摔落、药水等。
设为 false：只有明确配置的伤害类型才走属性系统。

allowed_events

限制哪些原版伤害事件可以触发此伤害类型。空列表表示不限制。常见事件：

ENTITY_ATTACK — 近战攻击
PROJECTILE — 投射物
ENTITY_SWEEP_ATTACK — 横扫攻击

伤害系统 ​

伤害类型配置 ​

顶层字段 ​

内置伤害类型 ​

stages 多阶段管线 ​

stage 字段 ​

kind 计算类型 ​

source 属性来源 ​

mode 叠加方式 ​

典型物理伤害管线 ​

recovery 恢复配置 ​

原版伤害接管模式 ​

合成命中反馈 ​

hard_lock 与 allowed_events ​

hard_lock ​

allowed_events ​