Skip to content

Combat 4.3a: Add DivinityHitEvent and honour the outer request for DIVINITY_ types - #389

Merged
Travja merged 2 commits into
devfrom
combat-4.3a-hit-event
Nov 18, 2026
Merged

Travja merged 2 commits into
devfrom
combat-4.3a-hit-event

Conversation

@Travja

@Travja Travja commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Design

Phase 4.3a of the combat restructure (#365). Divinity only. Fabled's side (4.3b) comes later and is not part of this PR.

Events

There is a new class, studio.magemonkey.divinity.api.event.DivinityHitEvent, with two concrete events. Each one has its own HandlerList and extends Bukkit's Event directly, not Codex's IEvent. IEvent has one HandlerList shared by every Codex event. Listen to Prepare or Result, not to the abstract base.

Both events expose the same read-only hit description:

Accessor Meaning
getVictim(), getAttacker() (nullable), getProjectile() (nullable), getWeapon(), getCause(), getOriginalEvent() as on the old events
getRequest() (nullable) the Codex DamageRequest this hit claimed. For a DIVINITY_<type> hit dealt inside a dealer's open request, this is the dealer's own request (see below)
getOrigin() the request's DamageOrigin. With no request, Divinity infers one: projectile → WEAPON_PROJECTILE, living attacker → WEAPON_MELEE, vanilla Thorns → EFFECT, otherwise ENVIRONMENT. isDescribed() says whether the origin came from a request or was inferred
getWeaponStatsMode() how Divinity actually handled the hit. This can differ from what the request asked for: no request means ADD, Fabled's legacy ignore-divinity mark means IGNORE, and a DIVINITY_<type> hit means REPLACE (or IGNORE, see below). RAW never appears, because Divinity fires nothing for a RAW hit
getRequestedAmounts() the typed amounts the hit was described with, as the dealer wrote them (DIVINITY_fire, default, ...). Empty when there are none

DivinityHitEvent.Prepare: the inputs, before the formula. You can change the damage per type and the defense per type (get/setDamage and get/setDefense, keyed by DamageAttribute/DefenseAttribute or by id). These are the same maps Start receives.

DivinityHitEvent.Result: Divinity's final numbers after defenses, before anything is written to the Bukkit event. It gives:

  • getDamage(type), getDamages() and getDamagesById(), plus getDefended(type) and getIncomingDamages(), which are the inputs the formula saw
  • isCritical() and isBlocked()
  • mutators setDamage(type, amount) and setTotalDamage(total). setTotalDamage scales every type proportionally. If every type is at 0, the whole total goes on the default damage type.

Whatever the listeners leave in place is what Divinity then uses: the fully-mitigated check, the BASE it writes (rounded to 0.01 as today), the post-hit effects (vampirism, bleed, thornmail, AoE), Exit, and the combat log (DamageMeta).

Firing order

EntityDamageEvent (HIGHEST, VanillaWrapperListener)
  BeforeScale            (deprecated)
  Codex attribute/buff scaling
  DivinityHitEvent.Prepare      ← new
  Start                  (deprecated; DamageManager does the calculation at HIGHEST)
    dodge roll → Dodge   (deprecated)  — a dodged hit stops here
    crit, block, PvP/PvE modifiers
    Pre                  (deprecated)
    per-type formula (+ the damage type's hit actions, as today)
    DivinityHitEvent.Result     ← new
    fully-mitigated check, BASE written
    post effects (skipped for IGNORE, as today)
    Exit                 (deprecated; not fired for IGNORE, as today)

Prepare fires for every hit Divinity manages. It does not fire for: RAW requests, vanilla-only damage handling, Fabled's throwaway events, non-living victims, hits refused by Hooks.canFights or the disabled sweep, and hits whose BeforeScale was cancelled. Result fires if nothing cancelled Prepare, Start or Pre and the hit was not dodged. This includes IGNORE hits, which Exit skips.

Threading

Both events are synchronous. They fire on the server thread, inside the EntityDamageEvent handler, like the old events.

Cancellation

  • Cancelling Prepare is the same as cancelling Start: the Bukkit event is cancelled and no further Divinity event fires.
  • Cancelling Result cancels the hit after the calculation. The Bukkit event is cancelled, nothing is written to BASE, and the post effects and Exit do not run. The damage type's hit actions have already run by then, as they do today before Pre/Exit listeners can react.
  • As on the old events, setCancelled(x) also sets the Bukkit event's cancelled flag to x.

How the old events map onto the new ones

All five old events keep firing at the same points with the same objects. They are marked @Deprecated with a pointer to the new API, and Divinity's own listeners (durability, the stats refresh and the calculation itself) stay on them, so their behaviour does not change.

Old New Notes
BeforeScale Prepare Prepare runs after Codex scaling. Nothing replaces "before scaling"
Start Prepare Same maps. Start listeners still run after Prepare and can override it
Pre Result to cancel after crit/block are known; Prepare to change inputs
Dodge none yet Kept. The plan is updated so that Phase 5 does not remove it before a replacement exists
Exit Result for the final numbers; MONITOR on the Bukkit event for "after the hit landed" Exit skips IGNORE hits; Result does not

DIVINITY_<type> inside an outer request

I checked this in the code. DamageManager.dealDamage always opens its own scope with a REPLACE/EXTERNAL request. Codex's DamageContexts.claim takes the newest unclaimed scope for the target, which is that inner one. The dealer's outer request (for example Fabled's IGNORE or RAW from the editor) is never claimed, so its mode and origin are lost. A new test pins the current behaviour first, then the fix.

Codex has no public way to read an open request without claiming it, so the fix lives in Divinity and needs no Codex change. When DamageContexts.isAnnounced(target) is true, dealDamage does not open an inner scope. Instead it records the typed amount locally for the duration of the damage() call. This uses the same claim-once-per-event rule as Codex. The listener then claims the dealer's own request and combines it with the typed amount:

Outer mode Divinity does
RAW Leaves the event alone. The amount is dealt as given
IGNORE Uses only the typed amount. The hit is exempt: no on-hit effects, no attack power, no Exit. Defenses, dodge, crit and block still apply. This is what Fabled's legacy ignore-divinity mark already produces with a DIVINITY_<type> classifier
ADD, REPLACE Uses only the typed amount (REPLACE), as today

Either way the claimed request, and so the origin, is the dealer's (for example SKILL, not EXTERNAL), and Fabled's outer scope reports isClaimed() == true. With no outer request, dealDamage keeps its current path unchanged.

Not in this PR

  • The Fabled side (4.3b).
  • A way for Fabled to ask, from the Bukkit event, whether Divinity calculated the hit. Every hit Divinity manages gets a Result, and Fabled can tell a RAW hit apart itself, so I left this out. If 4.3b needs it, it is a small addition.

What changed

  • api/event/DivinityHitEvent.java (new): Prepare and Result, as designed above.
  • api/event/DivinityDamageEvent.java: the class and all five subclasses are @Deprecated, each with its closest replacement. Their behaviour is unchanged.
  • VanillaWrapperListener: claims a TypedDeals.Deal next to the request, records origin, handled mode and requested amounts on the DamageMeta (describe), and fires Prepare before Start.
  • DamageManager: fires Result after the per-type loop. dealDamage uses a TypedDeals.Deal instead of its own request when a request is already open on the target.
  • TypedDeals (new): the typed amount of such a hit, claimed once per event by the same rule as Codex's DamageContexts.
  • DamageMeta: origin, weaponStatsMode, requestedAmounts.
  • ItemDurabilityListener and EntityManager stay on Exit, with @SuppressWarnings("deprecation"). The durability listener has a comment saying why.

What the DIVINITY_<type> fix changes on a live server

This only affects a DIVINITY_<type> hit dealt through DamageRegistry.dealDamage while a dealer's request is open on the target. With no outer request, dealDamage takes exactly its old path.

  • An outer RAW request is now honoured: the hit is not touched. It used to be calculated as REPLACE.
  • An outer IGNORE request now makes the hit exempt: no on-hit effects, no attack power, no Exit, so no durability cost. It used to be a full REPLACE hit with on-hit effects.
  • The claimed request is the dealer's, so DamageMeta.getRequest() and the new events report the dealer's origin (for example SKILL) instead of EXTERNAL.
  • Bug fixed along the way: the dealer's request used to stay open and unclaimed after the hit. The next hit on the same target inside that scope then claimed it. aSecondHitInsideTheSameRequest_isAnOrdinarySwing shows this: before the fix, a plain sword swing inside an IGNORE scope did 6 (the event's damage, as IGNORE) instead of the sword's 20.

Characterization tests

None touched. CombatCharacterizationTest has no diff and every expectation in it still passes. New tests:

  • TypedDamageInsideRequestTest (8 tests): the DIVINITY_<type> fix. I ran it against the unfixed dealDamage first; 4 tests failed (outerIgnore, outerRaw, outerAdd (request not claimed), aSecondHitInsideTheSameRequest). All 8 pass with the fix.
  • DivinityHitEventTest (19 tests): firing order relative to the old events, no Result on dodge, nothing on RAW, origin and mode reporting (undescribed swing, environment, described request, legacy ignore-divinity), and changing or cancelling each event.
  • CombatTestBase: shared setup for the two new classes. CombatCharacterizationTest keeps its own copy on purpose, so it stays untouched.

As a break-the-code check, I removed if (result.isCancelled()) return; and result_cancelled_writesNothingAndSkipsPostEffects failed.

Build and test

mvn test, exit code 0: 316 run, 0 failures, 0 errors, 2 skipped. The 2 skipped are the existing trident tests in VanillaWrapperListenerTest, which need item cooldowns MockBukkit does not implement. The baseline on dev was 289 run with the same 2 skipped.

No Codex change is needed. DamageContexts.isAnnounced is already in the Codex this compiles against (1.3.0-SNAPSHOT), so codex.version and MIN_CORE_VERSION are unchanged.

Not verified: Fabled's real call path for a DIVINITY_<type> skill. Fabled is outside this session's GitHub scope, and the published Fabled snapshots predate fabled#1919. The fix assumes what the task describes: Fabled's scope is open on the target while it calls DamageRegistry.dealDamage. If Fabled instead calls it outside its scope, nothing changes from today. This is noted in the notes doc for 4.3b to check.

Label

build:minor. release.yml bumps by the highest build:* label among the PRs merged since the last release (1.1.1). Earlier build:major PRs already make the next release 2.0.0, so any label keeps this PR in 2.0.0; none of them leads to 3.0.0. minor describes the change itself: additive API plus deprecations.

Docs

  • COMBAT_RESTRUCTURE_PLAN.md: 4.3 is split into 4.3a (this PR, done) and 4.3b (Fabled). The compatibility contract notes the deprecation. Phase 5 now says not to remove Dodge before a replacement exists, and that the Exit listeners need a decision first.
  • COMBAT_RESTRUCTURE_NOTES.md: the status table, and a new section "The new event surface (4.3a)" covering where the events fire, the IEvent shared-handler-list trap, the new DamageMeta fields, TypedDeals, and the Fabled call path that was not checked.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FaEyTuWrM4QJyDXghv2vfE

@Travja Travja added the build:minor label Nov 18, 2026 — with Claude
…VINITY_ types

DivinityHitEvent.Prepare fires after Codex scaling and before Start, with the
damage and defense per type open to change. DivinityHitEvent.Result fires after
the per-type formula and before anything is written to the Bukkit event, with
Divinity's final numbers per type open to change. Both report the claimed Codex
request, the hit's origin (inferred without a request), how Divinity handled
the weapon, and the typed amounts. The old DivinityDamageEvent subclasses are
deprecated and keep firing at the same points.

DamageManager.dealDamage used to open its own REPLACE request even when a
dealer's request was already open on the target, so the dealer's weapon-stats
mode and origin were lost, and its request stayed open for the next hit to
claim. It now records the typed amount locally and lets the listener claim the
dealer's request: RAW leaves the hit alone, IGNORE uses only the typed amount
and is exempt, anything else replaces as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FaEyTuWrM4QJyDXghv2vfE
@Travja
Travja merged commit d33f327 into dev Nov 18, 2026
2 checks passed
@Travja
Travja deleted the combat-4.3a-hit-event branch November 18, 2026 07:35
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