配置目录

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	是否接管未命中白名单的原版伤害。
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	接管原版伤害后的击退和受伤音效补偿。
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 对应表现，常用于生命值。

原版伤害映射

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	可选；进入属性管线前的基础伤害。留空时直接使用服务端已算好的原版伤害值，适合摔落、爆炸、燃烧、溺水等随高度或状态变化的来源。

当 hard_lock_damage: true 时，未命中映射的原版伤害会回退到 default_damage_type；当为 false 时，未命中的伤害保留原版行为。

配置修改顺序

推荐按以下顺序调整：

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 是否与伤害类型、条件或外部模块一致。
• 环境伤害异常：检查 hard_lock_damage 与 allowed_damage_causes。
• 生命不同步：检查资源是否设置 sync_to_bukkit: true，以及 max_health_vanilla 等原版属性是否冲突。
• 数值膨胀：为核心输出、防御、暴击等属性配置 scaling_curves。