属性定义

属性文件位于 attributes/*.yml。每个文件通常定义一个属性。属性定义决定一个数值如何被识别、限制、展示和参与战斗。

完整字段参考

字段	类型	必填	默认值	说明
id	string	是	—	属性唯一 ID。其他模块引用属性时使用它。
display_name	string	否	同 id	展示名称。也用于 Lore 匹配时的 %Key% 变量。
value_kind	enum	否	FLAT	数值类型（见下方枚举说明）。
target_type	enum	否	GENERIC	属性目标类型（见下方枚举说明）。
target_id	string	否	""	目标 ID。DAMAGE 类型对应伤害类型 ID；RESOURCE 对应资源 ID；VANILLA 对应原版属性名。
mmoitems_stat	string	否	""	MMOItems stat ID 映射。安装 MMOItems 时用于桥接属性读取。
default_value	double	否	0	默认基础值。
min_value	double	否	无限制	最小值限制。低于此值会被截断。
max_value	double	否	无限制	最大值限制。高于此值会被截断。
allow_negative	boolean	否	true	是否允许负值。为 false 时等效于 min_value: 0。
priority	integer	否	0	Lore 匹配优先级。越高越先匹配，避免短名称误匹配长名称。
lore_format_id	string	否	""	关联的 Lore 格式 ID（定义在 lore_formats/ 中）。
lore_pattern	string	否	—	单条 Lore 匹配正则表达式。与 lore_patterns 二选一。
lore_patterns	list<string>	否	[]	多条 Lore 匹配正则表达式。
attribute_power	double	否	1.0	属性战力权重系数。用于计算装备或玩家总战力。
description	string / list	否	""	描述文本，可用于 GUI 或帮助展示。

value_kind 数值类型

值	说明	典型用途
FLAT	平坦数值（默认）。直接加减的固定值。	物理攻击 +10、防御 +5。
PERCENT	百分比数值。Lore 匹配时自动处理 % 后缀。	物理伤害 +8%、防御加成 +12%。
CHANCE	概率数值。与 PERCENT 类似，视为百分比类。	暴击率 +15%、闪避率 +10%。
REGEN	回复速率。表示每秒或每 tick 的回复量。	生命恢复 +2/s、法力恢复 +5/s。
RESOURCE	资源上限加成。增加资源的最大值。	最大生命 +100、最大法力 +50。
DERIVED	派生属性。由其他属性计算得出，不直接从装备读取。	综合战力、有效生命。

target_type 目标类型

值	说明	target_id 用途
GENERIC	通用属性（默认）。不参与特定系统，供条件、展示或其他模块读取。	不需要。
DAMAGE	伤害相关属性。参与 damage_types/*.yml 中的伤害计算管线。	对应伤害类型 ID，如 physical、spell。
RESOURCE	资源类属性。影响玩家资源的最大值或回复。	对应资源 ID，如 health、mana。
VANILLA	映射到 Minecraft 原版属性。属性值变化时同步到 Bukkit 原版属性系统。	对应原版属性名，如 generic.movement_speed。

示例：物理攻击

id: physical_attack
display_name: '<red>物理攻击'
value_kind: FLAT
target_type: DAMAGE
target_id: physical
default_value: 0
min_value: 0
max_value: 999999
allow_negative: false
priority: 100
lore_format_id: default_flat
attribute_power: 1.0
description:
  - '提高物理伤害。'

示例：暴击率

id: physical_crit_rate
display_name: '<yellow>物理暴击率'
value_kind: CHANCE
target_type: DAMAGE
target_id: physical
default_value: 0
min_value: 0
max_value: 1
allow_negative: false
priority: 200
lore_format_id: default_percent
attribute_power: 1.5
description:
  - '提高物理暴击触发概率。'
  - '数值范围 0~1，0.15 表示 15%。'

示例：最大生命加成

id: max_health_bonus
display_name: '<green>最大生命'
value_kind: RESOURCE
target_type: RESOURCE
target_id: health
default_value: 0
min_value: 0
max_value: 10000
allow_negative: false
priority: 50
lore_format_id: default_flat
attribute_power: 0.5

示例：移动速度（原版映射）

id: movement_speed
display_name: '<aqua>移动速度'
value_kind: FLAT
target_type: VANILLA
target_id: generic.movement_speed
default_value: 0.1
min_value: 0
max_value: 1
allow_negative: false
priority: 10
lore_format_id: default_flat
attribute_power: 0.3

示例：法力恢复

id: mana_regen
display_name: '<blue>法力恢复'
value_kind: REGEN
target_type: RESOURCE
target_id: mana
default_value: 0
min_value: 0
max_value: 100
allow_negative: false
priority: 60
lore_format_id: default_regen
attribute_power: 0.8
description:
  - '每秒恢复的法力值。'

区间随机值

当前 Attribute 支持把单个属性贡献写成区间值。区间会在解析时得到最小值、最大值和本次实际取值，可用于“随机攻击力”“随机百分比加成”等装备词条。

常见写法示例：

ea_attributes:
  physical_attack: "10-20"
  physical_crit_rate: "5%-12%"

使用建议：

• 整数或普通数值区间适合攻击、防御、资源上限等平坦属性。
• 百分比区间适合 PERCENT / CHANCE 类型属性；仍建议在系统内部统一使用同一数值尺度，避免 0.15 与 15 混用。
• 区间最终会写入快照贡献，调试时应同时关注最小值、最大值与实际取值。
• 新装备系统仍优先通过 PDC 属性 payload 写入区间结果，不建议只依赖 Lore 文本。

Lore 解析

lore_pattern 模板变量

在 lore_pattern / lore_patterns 中可使用以下模板变量：

变量	展开为
%Key% / %key%	属性 display_name 的正则转义字符串。
%Value% / %value%	数值捕获组 ([+-]?\d+(?:\.\d+)?)。

示例

lore_patterns:
  - '%Key%：%Value%'
  - '%Key% \\+%Value%'

如果 display_name 为 物理攻击，上面的模式会匹配：

• 物理攻击：15
• 物理攻击 +15

Lore 解析的局限性

lore_patterns 用于从已有物品 Lore 中解析属性。它适合兼容旧物品或外部插件物品，但不建议作为新装备系统的主要数据来源。原因：

• 文本解析容易受颜色、语言、格式影响。
• 玩家或其他插件可能修改 Lore。
• 性能和稳定性不如 PDC。
• 正则匹配可能误匹配相似文本。

新系统建议让 EmakiItem、Forge、Strengthen、Gem 等模块直接写入 PDC 属性 payload。

lore_format_id 优先级

内置 Lore 格式的默认优先级：

格式 ID	优先级
default_percent	100
default_regen	80
default_resource	60
default_flat	50

优先级越高，在 Lore 中越先匹配。

数值范围设计

百分比属性

如果模块使用 0.15 表示 15%，就保持配置和公式都使用 0 到 1 的范围。不要一部分用 15，一部分用 0.15。

# 推荐：统一使用 0~1
min_value: 0
max_value: 1  # 100% 上限

# 不推荐：混用
min_value: 0
max_value: 100  # 如果其他地方用 0.15 表示 15%，这里就矛盾了

攻击和防御

建议设置合理上限，防止数值膨胀：

# 攻击
max_value: 999999

# 防御（通常不应超过攻击上限）
max_value: 999999

# 穿透（通常不应超过防御上限）
max_value: 999999