Attribute Definitions

Attribute definition files are located in the attributes/ directory. Each YAML file can contain one or more attribute definitions.

YAML Format

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: "物理伤害的基础攻击力"

Field Descriptions

Field	Type	Required	Default	Description
id	String	Yes	—	Unique attribute identifier, automatically converted to lowercase underscore format
display_name	String	No	Same as id	Display name
value_kind	Enum	No	FLAT	Value type, determines the semantics and calculation method of the attribute
target_type	Enum	No	GENERIC	Target type, determines the system category the attribute belongs to
target_id	String	No	""	Target ID; when target_type is DAMAGE or RESOURCE, points to the corresponding damage type or resource
default_value	double	No	0.0	Default value
min_value	Double	No	null	Minimum value limit, null means no limit
max_value	Double	No	null	Maximum value limit, null means no limit
allow_negative	boolean	No	false	Whether negative values are allowed
priority	int	No	0	Sort priority, higher values appear first
lore_format_id	String	No	""	Associated Lore format ID
lore_patterns	List	No	[]	Lore matching pattern list, used to parse attribute values from item Lore
attribute_power	double	No	1.0	Combat power score, used for combat power calculation
description	String	No	""	Attribute description

mmoitems_stat_id

Attribute definitions also support the mmoitems_stat_id field (mmoItemsStatId in source code), used to map MMOItems Stat IDs. When the MMOItems bridge is enabled, the system automatically reads the corresponding Stat values from MMOItems items as attribute contributions.

value_kind Enum

Value	Description	Typical Usage
FLAT	Fixed numeric value	Attack, defense, and other base attributes
PERCENT	Percentage value	Damage bonus, percentage lifesteal
CHANCE	Probability value (0–100)	Crit rate, dodge chance
REGEN	Regeneration value	Health regen, mana regen
RESOURCE	Resource value	Health, mana cap
DERIVED	Derived value	Attributes calculated from other attributes

Percent-like Attributes

PERCENT and CHANCE type attributes return true for isPercentLike(), and the Lore formatter will automatically append a % suffix.

target_type Enum

Value	Description	Typical Usage
DAMAGE	Damage-related attribute	Physical attack, spell defense, etc.; target_id points to a damage type
RESOURCE	Resource-related attribute	Health, mana; target_id points to a resource ID
GENERIC	Generic attribute	Dodge chance, lifesteal, and other attributes not belonging to a specific category
VANILLA	Vanilla mapping attribute	Attributes mapped to Bukkit vanilla Attributes

Default Attribute List

Resource

ID	Display Name	value_kind	target_type	target_id
health	Health	RESOURCE	RESOURCE	health
mana	Mana	RESOURCE	RESOURCE	mana
health_regen	Health Regen	REGEN	RESOURCE	health
mana_regen	Mana Regen	REGEN	RESOURCE	mana

Physical

ID	Display Name	value_kind	target_type	target_id
physical_attack	Physical Attack	FLAT	DAMAGE	physical
physical_damage_bonus	Physical Damage Bonus	PERCENT	DAMAGE	physical
physical_defense	Physical Defense	FLAT	DAMAGE	physical
physical_armor_penetration	Physical Armor Penetration	FLAT	DAMAGE	physical
physical_crit_rate	Physical Crit Rate	CHANCE	DAMAGE	physical
physical_crit_damage	Physical Crit Damage	FLAT	DAMAGE	physical
physical_crit_evasion	Physical Crit Evasion	CHANCE	DAMAGE	physical
physical_crit_multiplier_resistance	Physical Crit Multiplier Resistance	PERCENT	DAMAGE	physical

Projectile

ID	Display Name	value_kind	target_type	target_id
projectile_attack	Projectile Attack	FLAT	DAMAGE	projectile
projectile_damage_bonus	Projectile Damage Bonus	PERCENT	DAMAGE	projectile
projectile_defense	Projectile Defense	FLAT	DAMAGE	projectile
projectile_armor_penetration	Projectile Armor Penetration	FLAT	DAMAGE	projectile
projectile_crit_rate	Projectile Crit Rate	CHANCE	DAMAGE	projectile
projectile_crit_damage	Projectile Crit Damage	FLAT	DAMAGE	projectile
projectile_crit_evasion	Projectile Crit Evasion	CHANCE	DAMAGE	projectile
projectile_crit_multiplier_resistance	Projectile Crit Multiplier Resistance	PERCENT	DAMAGE	projectile

Spell

ID	Display Name	value_kind	target_type	target_id
spell_attack	Spell Attack	FLAT	DAMAGE	spell
spell_damage_bonus	Spell Damage Bonus	PERCENT	DAMAGE	spell
spell_defense	Spell Defense	FLAT	DAMAGE	spell
spell_armor_penetration	Spell Armor Penetration	FLAT	DAMAGE	spell
spell_crit_rate	Spell Crit Rate	CHANCE	DAMAGE	spell
spell_crit_damage	Spell Crit Damage	FLAT	DAMAGE	spell
spell_crit_evasion	Spell Crit Evasion	CHANCE	DAMAGE	spell
spell_crit_multiplier_resistance	Spell Crit Multiplier Resistance	PERCENT	DAMAGE	spell

Spell Naming Convention

Spell crit rate and crit damage use spell_crit_rate / spell_crit_damage naming, consistent with the {category}_crit_rate / {category}_crit_damage pattern used by the physical and projectile categories.

Movement/Utility

ID	Display Name	value_kind	target_type
speed	Speed	FLAT	GENERIC
movement_speed	Movement Speed	FLAT	GENERIC
attack_speed	Attack Speed	FLAT	GENERIC
entity_scale	Entity Scale	FLAT	GENERIC
entity_interaction_range	Entity Interaction Range	FLAT	GENERIC
block_interaction_range	Block Interaction Range	FLAT	GENERIC

Special Attributes

ID	Display Name	value_kind	target_type
real_damage	True Damage	FLAT	GENERIC
lifesteal	Lifesteal	FLAT	GENERIC
percentage_lifesteal	Percentage Lifesteal	PERCENT	GENERIC
lifesteal_resistance	Lifesteal Resistance	PERCENT	GENERIC
dodge_chance	Dodge Chance	CHANCE	GENERIC
attribute_power	Combat Power	DERIVED	GENERIC

Vanilla Mapping

ID	Display Name	value_kind	target_type
attack_speed_vanilla	Vanilla Attack Speed	FLAT	VANILLA
max_health_vanilla	Vanilla Max Health	FLAT	VANILLA

Vanilla Mapping Attributes

VANILLA type attributes are synchronized to the Bukkit vanilla Attribute system via VanillaAttributeSynchronizer. Modifying these attribute values will directly affect vanilla behavior.

attribute_balance.yml

The attribute balance configuration file defines attribute combat power score coefficients, used for the derived calculation of the attribute_power (Combat Power) attribute.

# Attribute groups and combat power scores
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

Combat Power Calculation

attribute_power is a DERIVED type attribute whose value is automatically calculated by AttributeBalanceRegistry based on group scores. Each attribute's contribution = attribute value × attribute definition's attribute_power × group score.