Damage System

Damage types are stored under damage_types/*.yml. The current damage system uses a multi-stage pipeline instead of one fixed formula. Each damage type can define its own attack, defense, critical, penetration, recovery, and custom expression stages.

Damage type fields

Field	Description
id	Damage type id, such as physical, projectile, or spell.
display_name	Display name. Defaults to id.
aliases	Optional aliases.
hard_lock	Whether this damage type strongly takes over matching vanilla damage events.
allowed_events	Vanilla event/cause allowlist. Empty means unrestricted.
message / attacker_message / target_message	Combat messages.
stages	Ordered calculation stages.
recovery	Post-damage recovery or lifesteal calculation.

Default damage types include physical, projectile, and spell.

Stage pipeline

Each stage can read attributes from the attacker, target, or context, then add or subtract the calculated result.

Field	Description
id	Debug id for the stage.
kind	FLAT_PERCENT or CUSTOM.
source	ATTACKER, TARGET, or CONTEXT.
mode	ADD or SUBTRACT.
flat_attributes	Flat contribution attributes.
percent_attributes	Percentage contribution attributes.
chance_attributes	Chance attributes.
multiplier_attributes	Multiplier attributes.
expression	Custom expression when kind=CUSTOM.
min_result / max_result	Result clamps.
min_chance / max_chance	Chance clamps.
min_multiplier / max_multiplier	Multiplier clamps.

Vanilla damage takeover modes

Global vanilla_event_damage.enabled controls the current vanilla event takeover mode:

• enabled: true: recommended perfect takeover mode. Attribute does not cancel the vanilla damage event first. Instead, it resolves EA damage synchronously before the event returns and rewrites the final event damage in place. This preserves vanilla side effects such as burning zombies igniting players, iron golem knockback, shields, absorption hearts, thorns, death/stat handling, and other vanilla/plugin event effects.
• enabled: false: compatibility mode. The old behavior cancels the event and re-applies damage/feedback through Attribute. Use it only when a server needs the legacy behavior or is integrating with special combat plugins.

Perfect takeover changes how damage is applied, not the configured damage-number pipeline. If the result is dodge, event cancellation, or final damage <= 0, the original event is cancelled for that hit. Attribute side effects such as lifesteal, combat messages, and attack cooldown handling are still applied by Attribute.

Synthetic hit feedback

Synthetic feedback mainly matters in compatibility mode. In perfect takeover mode, vanilla usually produces knockback, hurt animation, and sound naturally.

synthetic_hit_feedback:
  knockback: true
  knockback_strength: 0.4
  hurt_sound: true

Field	Description
knockback	Whether to add knockback feedback.
knockback_strength	Knockback strength.
hurt_sound	Whether to play hurt sound feedback.

Debugging

Use /ea debug and the module's damage debug output to inspect context variables, stage results, final damage, recovery, and event behavior.