配置目录

EmakiAttribute 的配置由主配置、属性定义、伤害类型、条件、Lore 格式和属性平衡文件组成。先定属性 ID 和命名规则，再扩展伤害类型和装备来源。

默认目录结构

plugins/EmakiAttribute/
├── config.yml
├── attribute_balance.yml
├── attributes/
├── damage_types/
├── conditions/
├── lore_formats/
├── presets/
├── gui/
├── lang/
└── data/

路径	作用
config.yml	主配置，控制默认资源、伤害接管、自然回复、衰减曲线和原版伤害映射。
attribute_balance.yml	属性战力分数与平衡语义参数。
attributes/	单个属性定义，例如攻击、防御、暴击、资源、原版属性映射。
damage_types/	伤害类型管线，例如物理、投射物、法术。
conditions/	属性读取条件（PDC 读取规则）。
lore_formats/	属性展示格式模板。
presets/	属性预设定义。
gui/	属性点 GUI 配置（attribute_points.yml）。
lang/	多语言文本，内置 zh_CN.yml 与 en_US.yml。
data/	运行时数据目录，例如 data/parent_attributes/<UUID>.yml；通常不手动编辑。

建议修改顺序

1. 先在 attributes/ 定义属性 ID、展示名、数值类型和上限。
2. 再在 lore_formats/ 定义旧物品 Lore 的读取或展示格式。
3. 接着在 damage_types/ 配置伤害阶段。
4. 最后接入 Item、Forge、Strengthen、Gem 等模块写入 PDC 属性。
5. 每次改完先运行 /ea lint，再 /ea reload 和 /ea resync <player>。

主配置关键字段

字段	说明
version	配置版本，由默认资源同步维护。
language	使用的语言文件 ID。
release_default_data	是否释放内置示例属性、伤害类型、读取规则、词条格式与平衡系数。默认开启。
attribute_sources.read_lore_attributes	是否从物品 Lore 解析属性。默认开启。
attribute_sources.read_pdc_attributes	是否从物品 PDC 读取属性。默认开启。
attribute_sources.require_lore_pdc_match	是否要求 Lore 与 PDC 按属性 ID 逐项一致。默认关闭。
hard_lock_damage	兼容保留项。会被配置解析器读取，但运行时没有消费点，改动它不改变任何行为。未命中白名单的原版伤害实际由 vanilla_event_damage 决定。
default_damage_type	回退使用的默认伤害类型。
projectile_damage_type	投射物命中时使用的默认伤害类型；默认 projectile，也可改为 physical 等已有伤害类型。
vanilla_event_damage	原版事件伤害接管配置。启用时保留原版副作用并替换最终伤害值；关闭时走兼容合成伤害模式。
same_signature_ignores_invulnerability	同一攻击者在同属性快照签名、同伤害类型下的多段攻击是否互相无视原版受伤间隔；window_ms 为批次时间窗，默认 500 毫秒。
attack_speed.scope	攻速冷却应用范围。global（默认）由 EA 接管全部攻击，未写 EA 攻速属性的物品按原版当前 ATTACK_SPEED 换算冷却；attribute_only 只对写了 EA 攻速属性的物品拦截，其余物品完全交还原版机制。
regen_interval_ticks	资源自然回复间隔。
sync_delay_ticks	属性同步到 Bukkit 的延迟。
health_display_scaling	客户端血量显示压缩；只缩放血条显示，不改变真实最大生命、当前生命或伤害结算。
default_profile	默认属性与资源基础值。
synthetic_hit_feedback	接管原版伤害后的击退和受伤音效补偿。
shield	盾牌格挡归属。mode（vanilla / attribute）、require_facing、facing_angle_degrees。
damage_indicator	伤害飘字。渲染后端由 EmakiCoreLib 的 display.backend 决定。子键见下方「伤害飘字」。
scaling_curves	属性超过阈值后的衰减规则。默认为空，即不启用。
allowed_damage_causes	原版 DamageCause 到属性伤害类型的映射。

物品属性来源策略

attribute_sources 控制物品属性是否从 Lore、PDC 读取，以及双来源是否需要互相校验：

attribute_sources:
  read_lore_attributes: true
  read_pdc_attributes: true
  require_lore_pdc_match: false

默认模式保持旧行为：启用的 Lore 与 PDC 来源会共同参与物品属性收集。若开启 require_lore_pdc_match，则按属性 ID 逐项比较：

• Lore 与 PDC 都存在且数值一致：该属性只计入一次。
• 两侧数值不一致：该属性不计入。
• 仅 Lore 或仅 PDC 存在：该属性不计入。
• 固定值与区间（spread）值都执行相同的一致性检查。

一致模式要求两个读取开关同时开启；若关闭任一来源，预检会给出警告，物品属性也无法形成双来源一致结果。若 Lore 与 PDC 都关闭，玩家仍可拥有默认、临时和其他实体来源属性，但装备物品不会贡献 Lore/PDC 属性。

默认资源与属性

default_profile 定义玩家初始化时拥有的资源和属性基础值：

default_profile:
  resources:
    health:
      display_name: "生命值"
      default_max: 20.0
      min_max: 1.0
      max_max: 2048.0
      sync_to_bukkit: true
      full_on_init: true
    mana:
      display_name: "法力值"
      default_max: 100.0
      min_max: 0.0
      max_max: 99999.0
      sync_to_bukkit: false
      full_on_init: true
  attributes:
    physical_attack: 0.0
    physical_defense: 0.0
    health_regen: 0.1
    mana_regen: 0.1

资源用于生命、法力、怒气等可变化数值；属性用于装备、宝石、强化、技能和伤害计算。sync_to_bukkit: true 的资源会同步到 Bukkit 对应表现，常用于生命值。

伤害飘字

damage_indicator 控制伤害飘字。渲染后端由 EmakiCoreLib 的 display.backend 决定：packet 后端只有下方 visible_to 指定的相关玩家能看到；bukkit 后端飘字是真实体，附近所有玩家都能看到，visible_to 不生效。

字段	默认值	说明
enabled	true	是否启用伤害飘字。
merge_window_ms	500	同一目标在该窗口（毫秒）内的多次伤害累加合并为一个飘字。0 表示不合并；窗口内再次命中会让飘字从起点重新抛出。
max_per_target_per_second	4	同一目标每秒最多生成的飘字数，用于抑制 AOE 刷屏。0 表示不限制。
visible_to	involved	仅 packet 后端生效。involved 只有攻击者与受击者可见；all 附近所有玩家可见。
ignored_causes	7 项	不显示飘字的伤害原因，默认为 FIRE_TICK、POISON、WITHER、DROWNING、FREEZE、SUFFOCATION、STARVATION。
lifetime_ticks	24	飘字存活时长（tick），同时是一次抛物运动的总时长。到期由 CoreLib 展示实体服务自动回收。
spawn.offset	x: 0.0 / y: 2.0 / z: 0.0	相对目标脚部的固定偏移（格）。
spawn.random_offset	x: 0.4 / y: 0.15 / z: 0.4	各轴随机散布范围（格），实际取 ±该值。0 表示该轴不散布。
motion.enabled	true	是否启用抛物运动。
motion.step_ticks	2	关键帧间隔（tick），同时是客户端插值时长。1 最平滑，值越大包越少、折线感越强。
motion.speed	0.30	抛出初速度（格/tick）。
motion.gravity	-0.030	竖直加速度（格/tick²），负值下坠，决定抛物线弯曲程度。
motion.direction.mode	random	抛出方向模式：random 按 pitch / yaw 区间随机；fixed 使用 direction.fixed 向量；away_from_attacker 沿攻击者到目标的水平方向抛出并叠加仰角，无攻击者时退化为 random。
motion.direction.pitch	min: 55.0 / max: 85.0	仰角区间（度），90 为正上方。
motion.direction.yaw	min: -180.0 / max: 180.0	水平角区间（度）。
motion.scale.pop_from / pop_ticks	0.6 / 3	出场起始缩放，前 pop_ticks 内线性放大到 1.0。
motion.scale.shrink_to / shrink_ticks	0.0 / 6	退场目标缩放，最后 shrink_ticks 内从 1.0 线性缩到该值。0 表示缩到不可见。
triggers	四个触发器	normal、critical、heal、dodge。每个触发器可只写需要改的键，未写的键继承上面的默认值。dodge 还需要闪避判定本身被启用；原版战斗默认不进行闪避判定。

原版伤害映射

allowed_damage_causes 决定哪些 Bukkit DamageCause 会进入 Attribute 结算：

allowed_damage_causes:
  - cause: FALL
    damage_type: physical
    enabled: true
  - cause: LAVA
    damage_type: physical
    enabled: true

字段	说明
cause	Bukkit DamageCause 名称。
damage_type	使用的 damage_types/*.yml 伤害类型 ID。
enabled	该条映射是否生效。
damage	可选；进入属性管线前的基础伤害。留空时直接使用服务端已算好的原版伤害值，适合摔落、爆炸、燃烧、溺水等随高度或状态变化的来源。

未命中映射的原版伤害由 vanilla_event_damage 决定，与 hard_lock_damage 无关：enabled: true 时按 vanilla_event_damage.damage_type 进入属性管线；enabled: false 时只有本表中允许的原因进入 EA，其余保留原版行为。

配置修改顺序

推荐按以下顺序调整：

1. 在 attributes/ 中确定属性 ID、显示名、默认展示格式。
2. 在 config.yml 的 default_profile 中补齐玩家基础值。
3. 在 damage_types/ 中配置伤害管线。
4. 在 attribute_balance.yml 中调整分数权重。
5. 在装备、宝石、强化、锻造或物品模块中写入对应属性。
6. 使用 /ea lint 检查配置问题。
7. 使用 /ea preview 或 /ea dump 验证玩家最终属性。

排查建议

• 属性不显示：检查属性文件是否加载、Lore 格式是否匹配、物品装配是否触发刷新。
• 属性不生效：检查属性 ID 是否与伤害类型、条件或外部模块一致。
• 环境伤害异常：检查 vanilla_event_damage 与 allowed_damage_causes（hard_lock_damage 无运行时效果，不必排查）。
• 生命不同步：检查资源是否设置 sync_to_bukkit: true。health 资源的天花板取修饰后的 MAX_HEALTH：EA 自算值写入 base，max_health_vanilla、生命提升药水与第三方插件贴的 modifier 叠加在其上，三者不再互相冲突。若上限与预期不符，开启 resource 调试查看 生命上限解析 与 最大生命修饰器 两行，逐条定位修饰器来源。
• 外部回血被撤销：health 的当前值以玩家实体血量为准，因此其他插件或命令直接设置血量后不会被下一次同步抹掉。若仍出现回落，开启 resource 调试对比 生命自然回复 行的 旧当前值 与 引擎基线值：两者持续偏离说明该资源未同步到 Bukkit，或血量被另一插件在同 tick 内反复改写。
• 数值膨胀：为核心输出、防御、暴击等属性配置 scaling_curves。