属性定义

属性定义文件放在 attributes/ 目录下，每个 YAML 文件可以包含一个或多个属性。你可以按自己的习惯组织文件——比如把物理系属性放一个文件，法术系放另一个，或者全部写在一个文件里都行。

YAML 格式

yaml

id: physical_attack
display_name: "物理攻击"
value_kind: FLAT
target_type: DAMAGE
target_id: physical
default_value: 0.0
min_value: 0.0
max_value: 99999.0
allow_negative: false
priority: 100
lore_format_id: default_flat
lore_patterns:
  - "物理攻击: {value}"
  - "物理攻击力: {value}"
attribute_power: 1.0
description: "物理伤害的基础攻击力"

字段说明

字段	类型	必填	默认值	说明
`id`	String	是	—	属性唯一标识，自动转为小写下划线格式
`display_name`	String	否	同 `id`	显示名称，用于 Lore 和消息中
`value_kind`	Enum	否	`FLAT`	值类型，决定属性的语义和计算方式（见下方枚举表）
`target_type`	Enum	否	`GENERIC`	属性归属的系统分类
`target_id`	String	否	`""`	当 `target_type` 为 `DAMAGE` 时指向伤害类型 ID，为 `RESOURCE` 时指向资源 ID
`default_value`	double	否	`0.0`	默认值
`min_value`	Double	否	`null`	最小值限制，`null` 表示不限制
`max_value`	Double	否	`null`	最大值限制，`null` 表示不限制
`allow_negative`	boolean	否	`false`	是否允许负值。大多数属性不需要负值，但像"伤害加成"这类属性可能需要允许负数来表示减益
`priority`	int	否	`0`	排序优先级，数值越大在列表中越靠前
`lore_format_id`	String	否	`""`	关联的 Lore 格式 ID，决定这个属性在物品描述中怎么显示
`lore_patterns`	List	否	`[]`	Lore 匹配模式列表，用于从物品 Lore 中反向解析出属性值
`attribute_power`	double	否	`1.0`	战力分数，用于计算 `attribute_power`（战力）属性
`description`	String	否	`""`	属性描述文本

MMOItems 映射

属性定义中还支持 mmoitems_stat_id 字段，用于映射 MMOItems 的 Stat ID。配了这个字段后，MMOItems 桥接启用时会自动从 MMOItems 物品中读取对应 Stat 的值，作为属性贡献注入快照。

value_kind 枚举

value_kind 决定了属性值的语义——同样是数字 10，在 FLAT 下表示固定值 10，在 CHANCE 下表示 10% 的概率。

值	说明	典型用途
`FLAT`	固定数值	攻击力、防御力等基础属性
`PERCENT`	百分比数值	伤害加成、百分比吸血
`CHANCE`	概率数值（0–100）	暴击率、闪避率
`REGEN`	回复数值	生命回复、法力回复
`RESOURCE`	资源数值	生命值、法力值上限
`DERIVED`	派生数值	由其他属性计算得出，比如战力

百分比类属性

PERCENT 和 CHANCE 在内部都被视为"百分比类"（isPercentLike() 返回 true），Lore 格式化时会自动加上 % 后缀。两者的区别主要是语义上的：CHANCE 明确表示概率，值域通常在 0–100。

target_type 枚举

target_type 决定属性归属哪个系统，配合 target_id 使用。

值	说明	典型用途
`DAMAGE`	伤害系属性	物理攻击、法术防御等。`target_id` 填伤害类型 ID（如 `physical`）
`RESOURCE`	资源系属性	生命值、法力值。`target_id` 填资源 ID（如 `health`）
`GENERIC`	通用属性	闪避率、吸血等不归属特定系的属性
`VANILLA`	原版映射属性	会同步到 Bukkit 原版 Attribute 系统

默认属性列表

以下是插件自带的 42 个属性定义。你可以修改它们的数值范围和显示名称，也可以添加自己的自定义属性。

资源类

ID	显示名称	value_kind	target_type	target_id
`health`	生命值	RESOURCE	RESOURCE	health
`mana`	法力值	RESOURCE	RESOURCE	mana
`health_regen`	生命回复	REGEN	RESOURCE	health
`mana_regen`	法力回复	REGEN	RESOURCE	mana

物理系

ID	显示名称	value_kind	target_type	target_id
`physical_attack`	物理攻击	FLAT	DAMAGE	physical
`physical_damage_bonus`	物理伤害加成	PERCENT	DAMAGE	physical
`physical_defense`	物理防御	FLAT	DAMAGE	physical
`physical_armor_penetration`	物理穿透	FLAT	DAMAGE	physical
`physical_crit_rate`	物理暴击率	CHANCE	DAMAGE	physical
`physical_crit_damage`	物理暴击伤害	FLAT	DAMAGE	physical
`physical_crit_evasion`	物理暴击抵抗	CHANCE	DAMAGE	physical
`physical_crit_multiplier_resistance`	物理暴伤削减	PERCENT	DAMAGE	physical

射击系

ID	显示名称	value_kind	target_type	target_id
`projectile_attack`	射击攻击	FLAT	DAMAGE	projectile
`projectile_damage_bonus`	射击伤害加成	PERCENT	DAMAGE	projectile
`projectile_defense`	射击防御	FLAT	DAMAGE	projectile
`projectile_armor_penetration`	射击穿透	FLAT	DAMAGE	projectile
`projectile_crit_rate`	射击暴击率	CHANCE	DAMAGE	projectile
`projectile_crit_damage`	射击暴击伤害	FLAT	DAMAGE	projectile
`projectile_crit_evasion`	射击暴击抵抗	CHANCE	DAMAGE	projectile
`projectile_crit_multiplier_resistance`	射击暴伤削减	PERCENT	DAMAGE	projectile

法术系

ID	显示名称	value_kind	target_type	target_id
`spell_attack`	法术攻击	FLAT	DAMAGE	spell
`spell_damage_bonus`	法术伤害加成	PERCENT	DAMAGE	spell
`spell_defense`	法术防御	FLAT	DAMAGE	spell
`spell_armor_penetration`	法术穿透	FLAT	DAMAGE	spell
`spell_crit_rate`	法术暴击率	CHANCE	DAMAGE	spell
`spell_crit_damage`	法术暴击伤害	FLAT	DAMAGE	spell
`spell_crit_evasion`	法术暴击抵抗	CHANCE	DAMAGE	spell
`spell_crit_multiplier_resistance`	法术暴伤削减	PERCENT	DAMAGE	spell

三个伤害系的属性结构完全一致，都遵循 {系}_crit_rate / {系}_crit_damage 这样的命名模式。如果你要新增一个伤害系（比如"元素系"），照着这个模式定义属性就行。

移动/工具类

ID	显示名称	value_kind	target_type
`speed`	速度	FLAT	GENERIC
`movement_speed`	移动速度	FLAT	GENERIC
`attack_speed`	攻击速度	FLAT	GENERIC
`entity_scale`	实体缩放	FLAT	GENERIC
`entity_interaction_range`	实体交互距离	FLAT	GENERIC
`block_interaction_range`	方块交互距离	FLAT	GENERIC

特殊属性

ID	显示名称	value_kind	target_type
`real_damage`	真实伤害	FLAT	GENERIC
`lifesteal`	吸血	FLAT	GENERIC
`percentage_lifesteal`	百分比吸血	PERCENT	GENERIC
`lifesteal_resistance`	吸血抵抗	PERCENT	GENERIC
`dodge_chance`	闪避率	CHANCE	GENERIC
`attribute_power`	战力	DERIVED	GENERIC

原版映射

ID	显示名称	value_kind	target_type
`attack_speed_vanilla`	原版攻击速度	FLAT	VANILLA
`max_health_vanilla`	原版最大生命	FLAT	VANILLA

原版映射属性

VANILLA 类型的属性会通过 VanillaAttributeSynchronizer 同步到 Bukkit 原版 Attribute 系统。改动这些属性的值会直接影响原版行为——比如修改 max_health_vanilla 会改变玩家头顶的心显示数量。谨慎使用。

attribute_balance.yml

这个文件定义战力计算的分数系数。attribute_power 是一个 DERIVED 类型的属性，它的值不是直接配置的，而是根据玩家所有属性的加权求和自动算出来的。

这样设计的好处是：你可以通过调整分数系数来控制"什么属性对战力贡献更大"，而不需要改任何代码。

yaml

# 属性分组与战力分数
groups:
  physical_offense:
    score: 1.0
    attributes:
      - physical_attack
      - physical_crit_rate
      - physical_crit_damage
  physical_defense:
    score: 0.8
    attributes:
      - physical_defense
      - physical_armor_penetration
  projectile_offense:
    score: 1.0
    attributes:
      - projectile_attack
      - projectile_crit_rate
      - projectile_crit_damage
  spell_offense:
    score: 1.0
    attributes:
      - spell_attack
      - spell_crit_rate
      - spell_crit_damage
  survival:
    score: 0.6
    attributes:
      - health
      - dodge_chance
      - lifesteal

战力计算公式

每个属性对战力的贡献 = 属性值 × 属性定义中的 attribute_power × 所在分组的 score。所有贡献加起来就是最终战力。比如一个玩家有 100 物理攻击（attribute_power=1.0），所在分组 score=1.0，那这项贡献就是 100 × 1.0 × 1.0 = 100。

属性定义 ​

YAML 格式 ​

字段说明 ​

value_kind 枚举 ​

target_type 枚举 ​

默认属性列表 ​

资源类 ​

物理系 ​

射击系 ​

法术系 ​

移动/工具类 ​

特殊属性 ​

原版映射 ​

attribute_balance.yml ​