Skip to content

Add FinalDamageEvent, a shared final-damage event for damage plugins - #199

Open
Travja wants to merge 1 commit into
devfrom
feat/damage-final-event
Open

Travja wants to merge 1 commit into
devfrom
feat/damage-final-event

Conversation

@Travja

@Travja Travja commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Codex half of phase 4.3b of the combat restructure: a final-damage event that doesn't belong to any one plugin, in studio.magemonkey.codex.api.damage.

What it adds

FinalDamageEvent (Event, Cancellable, server thread only, plain Java, no 1.20.4+ types):

  • Context: victim, attacker (nullable), projectile (nullable), cause, the original EntityDamageEvent, the DamageRequest (nullable), DamageOrigin, WeaponStatsMode, getRequestedAmounts().
  • Damage: a Map<String, Double> keyed by type id. setDamage(type, amount) changes one type, and the total moves by the difference. setTotalDamage(total) scales every type by the same factor. If the total is 0, it splits evenly across the listed types; if there are no types, the amount goes to DEFAULT_TYPE ("default"). Amounts must be finite and not negative.
  • Cancel: a plain flag. The provider acts on it: it cancels the Bukkit event and deals no damage.
  • Providers: registerProvider(plugin[, Predicate<EntityDamageEvent>]), unregisterProvider, hasProvider(), willFire(EntityDamageEvent). A provider that is disabled but never unregistered is not counted.

Subclassing (so DivinityHitEvent.Result can extend it)

  • getHandlers() is final and subclasses must not declare getHandlerList(). I checked this against the 1.16.5 spigot-api jar Codex compiles with. SimplePluginManager.getRegistrationClass walks getSuperclass() looking for a declared getHandlerList(). The JavaPluginLoader executor drops events that aren't isAssignableFrom the listened class. So listeners on the subclass land in the base list and receive only subclass instances, while base listeners receive everything.
  • A subclass with its own per-type storage passes an empty map and overrides getDamages(), getDamage(String) and setDamage(String, double), all three. getTotalDamage() and setTotalDamage(double) are built on those three, so they stay correct without overrides.

Why a predicate rather than just a flag

Divinity depends on Fabled, so Fabled's HIGHEST handler normally runs before Divinity's. A per-event "was fired" marker would arrive too late. A plain global flag would make Fabled skip hits that Divinity leaves alone, so they would lose the trigger completely. The predicate is a pure, cheap check that the provider registers at enable time. It lets Fabled ask about each hit, up front, whether the event will come. registerProvider(plugin) is shorthand for "every hit".

How Divinity and Fabled will use this

  • Divinity: DivinityHitEvent.Result extends FinalDamageEvent, drops its own getHandlerList(), and overrides the three storage methods to map ids onto its attribute storage. In onEnable it calls FinalDamageEvent.registerProvider(this, e -> /* the hits Divinity calculates */), and in onDisable it calls unregisterProvider(this). It keeps firing the Result where it does now and honors isCancelled(). Existing Result listeners keep working.
  • Fabled: in MainListener.onPhysicalDamage, if FinalDamageEvent.willFire(event), it skips firing PhysicalDamageEvent and doesn't touch event.setDamage(...). A new FinalDamageEvent listener fires the Physical Damage trigger on getTotalDamage() and writes buffs back with setTotalDamage(...) or setDamage(type, …). Without a provider, behavior is unchanged.

Tests

FinalDamageEventTest (25 tests) covers:

  • getters;
  • copy and validation;
  • per-type vs total setters, including the zero-total and no-type cases;
  • a subclass with its own storage;
  • cancel semantics;
  • provider registration, predicates and disabled providers;
  • handler-list inheritance through a real SimplePluginManager + JavaPluginLoader.

mvn -DskipNms -pl codex-api -am verify: 432 tests pass.


Generated by Claude Code

A damage plugin fires it from its EntityDamageEvent handler with the final
per-type damage of a hit, before writing it to the Bukkit event. Other plugins
read and change the damage by type id or as a total, or cancel the hit,
without depending on the damage plugin. Subclasses share its handler list, so
a provider's own event can extend it. Providers register with a per-hit
predicate so that other plugins can ask whether the event will fire for a hit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FaEyTumvDQFz1sVuq8xWK9
@Travja Travja added the build:minor label Nov 18, 2026 — with Claude
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants