Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion doc/COMBAT_RESTRUCTURE_NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ Update this file in the same pull request whenever something here stops being tr
| 4.1 Formulas in `combat.yml` | Done (#387) |
| 4.2 Stat snapshots | Done (#385) |
| 4.2b Vanilla Thorns | Done (#384) |
| 4.3 and 5 | Next: 4.3 |
| 4.3a New event surface, `DIVINITY_<type>` inside a request | Done (#389) |
| 4.3b Fabled: Physical Damage trigger and immediate buffs on `DivinityHitEvent.Result` | Next |
| 5. Clean-up | Not started |

## Rules for every pull request

Expand Down Expand Up @@ -160,6 +162,33 @@ lift the cap in the test and restore it.
roll fails or succeeds, the invulnerability reduction read, and resistance counting toward the absorption
cap. Only `VanillaDamageBridgeTest` catches them, so keep that test when the bridge changes.

## The new event surface (4.3a)

- **`DivinityHitEvent.Prepare` and `.Result`** are the supported events. `Prepare` is fired by
`VanillaWrapperListener` after Codex scaling and before `Start`. `Result` is fired by `DamageManager` after
the per-type loop and before the fully-mitigated check, so a listener that changes the numbers changes the
`BASE` written, the post-hit effects, `Exit` and the combat log. `DivinityHitEventTest` pins the order and
what each change does.
- **They extend Bukkit's `Event`, not Codex's `IEvent`.** `IEvent` has one static `HandlerList` shared by every
Codex event, so every listener of every such event is offered every one of them. Give any new event its own
`HandlerList`.
- **`DamageMeta` carries what the events report:** `origin`, `weaponStatsMode` (what Divinity did, not what the
request asked) and `requestedAmounts`. `VanillaWrapperListener#describe` sets them before the first event
fires. A meta built elsewhere has none; `DivinityHitEvent` then falls back to the inferred origin and `ADD`.
- **The old events are deprecated but still drive Divinity.** The calculation is a `Start` listener, and the
durability and stats-refresh listeners are on `Exit`. Do not move them to the new events without a decision:
`Exit` skips `IGNORE` hits and `Result` does not.
- **`DIVINITY_<type>` inside an open request.** `DamageManager#dealDamage` used to open its own `REPLACE` request,
which Codex's `claim` (newest unclaimed first) handed out in place of the dealer's. The dealer's request then
stayed open and unclaimed, so the next hit on the target inside the same scope claimed it. Now, when
`DamageContexts.isAnnounced(target)`, `dealDamage` opens a `TypedDeals.Deal` instead of a request, and the
listener claims both. `RAW` leaves the hit alone, `IGNORE` uses only the typed amount and is exempt, anything
else is `REPLACE` as before. Codex has no way to read an open request without claiming it; if it gains one,
`TypedDeals` could go. `TypedDamageInsideRequestTest` pins all of this; four of its tests fail without the fix.
- **Fabled's real call path for a `DIVINITY_<type>` skill was not checked** (Fabled is outside this repository's
scope and the published snapshots predate fabled#1919). The fix assumes what the task described: Fabled's
scope is open on the target while it calls `DamageRegistry.dealDamage`. Check this in 4.3b.

## Formulas in `combat.yml` (4.1)

- **Where things are.** `config/CombatCfg` loads and migrates the file and holds what is in force.
Expand Down
12 changes: 9 additions & 3 deletions doc/COMBAT_RESTRUCTURE_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,8 @@ still treated as swings and are left for a follow-up.

Not a bug after all: `DivinityDamageEvent.Exit` does not fire for `ignore-divinity` skill damage. Firing
it would make those hits start costing weapon and armor durability, which is a behaviour change. It is
left as it is and revisited with the new event surface in Phase 4.
left as it is and revisited with the new event surface in Phase 4. In 4.3a it stays that way;
`DivinityHitEvent.Result` does fire for those hits.

## Target design

Expand Down Expand Up @@ -197,7 +198,7 @@ These must keep working unchanged:
classifiers such as `skill_defense_default`. Any key clean-up is alias-only.
- The `ignore-divinity` skill setting, with its current behaviour.
- `DivinityDamageEvent.BeforeScale`, `Start`, `Pre`, `Dodge` and `Exit`, as deprecated shims, for at
least one release after 2.0.
least one release after 2.0. Deprecated in 4.3a in favour of `DivinityHitEvent.Prepare` and `.Result`.
- `DamageTypeProvider.dealDamage`, delegating to the new request API.
- Existing `engine.yml` combat options, migrated where they move.

Expand Down Expand Up @@ -260,12 +261,17 @@ Rules for every pull request:
| 4.1 | Divinity | Formulas move to `combat.yml` | Config layout |
| 4.2 | Divinity | Stat snapshots. Done | Projectile timing |
| 4.2b | Divinity | Stop treating hits that are not swings as swings: vanilla Thorns first (cause `THORNS` on every version, the damage type on 1.20.4+). Uses the origin from the damage request where there is one | Thorns damage |
| 4.3 | Divinity and Fabled | New event and API surface. Fabled stops mutating `BASE` when Divinity is present. The Physical Damage trigger and immediate buffs act on Divinity's final numbers | Yes |
| 4.3a | Divinity | New event and API surface (`DivinityHitEvent.Prepare` and `.Result`); the old events become deprecated shims. A `DIVINITY_<type>` hit dealt inside a dealer's open request honours that request's weapon-stats mode. Done (#389) | `DIVINITY_<type>` inside an `IGNORE` or `RAW` request |
| 4.3b | Fabled | Fabled stops mutating `BASE` when Divinity is present. The Physical Damage trigger and immediate buffs act on Divinity's final numbers through `DivinityHitEvent.Result` | Yes |

### Phase 5: clean-up

Remove the shims and dead paths after a release or two. Publish documentation for plugin authors.

`DivinityDamageEvent.Dodge` has no replacement in the new surface yet (4.3a). Do not remove it before one
exists. `ItemDurabilityListener` and `EntityManager` listen to `Exit`; moving them to `Result` would make
hits that ignore weapon stats cost durability, so they need their own decision before `Exit` goes.

## Still to verify

- That Fabled's `PhysicalDamageEvent` really runs before Divinity's calculation in practice. This is
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,14 @@
import java.util.Map;
import java.util.function.DoubleUnaryOperator;

/**
* The damage events Divinity fired before 2.0.
*
* @deprecated Use {@link DivinityHitEvent.Prepare} and {@link DivinityHitEvent.Result}. These events still fire at
* the same points with the same behaviour, and will be removed in a later 2.x release (not before
* {@link Dodge} has a replacement). See each subclass for the closest replacement.
*/
@Deprecated
public abstract class DivinityDamageEvent extends ICancellableEvent {

protected LivingEntity victim;
Expand Down Expand Up @@ -193,9 +201,13 @@ public final EntityStats getDamagerStats() {
}

/**
* Called at the start of Damage Event, before ANY calculations.
* This is the first QuantumDamageEvent instance.
* Called after Codex scaling, before any calculation. Divinity's own calculation listens to this event at
* {@code HIGHEST}.
*
* @deprecated Use {@link DivinityHitEvent.Prepare}, which fires just before this event with the same damage
* and defense maps.
*/
@Deprecated
public static class Start extends DivinityDamageEvent {

public Start(
Expand All @@ -217,6 +229,13 @@ public Start(
}
}

/**
* Called before Codex's attributes and buffs scale the damage and defense maps.
*
* @deprecated Use {@link DivinityHitEvent.Prepare}. It fires after the scaling; nothing replaces the point
* before it.
*/
@Deprecated
public static class BeforeScale extends DivinityDamageEvent {

public BeforeScale(
Expand All @@ -239,9 +258,12 @@ public BeforeScale(
}

/**
* Called at the start of Damage Event, before damage calculations.
* This is the second QuantumDamageEvent instance.
* Called after the dodge roll, critical hit, block and PvP or PvE modifiers, before the formula.
*
* @deprecated Use {@link DivinityHitEvent.Prepare} to change the inputs, or {@link DivinityHitEvent.Result}
* to cancel the hit once critical hit and block are known.
*/
@Deprecated
public static class Pre extends DivinityDamageEvent {

public Pre(
Expand All @@ -255,6 +277,13 @@ public Pre(
}
}

/**
* Called when the victim dodges. Cancelling it makes the hit land.
*
* @deprecated No replacement yet. It keeps firing and will not be removed before one exists. A dodged hit
* fires {@link DivinityHitEvent.Prepare} but no {@link DivinityHitEvent.Result}.
*/
@Deprecated
public static class Dodge extends DivinityDamageEvent {

public Dodge(
Expand All @@ -275,9 +304,14 @@ public void setCancelled(boolean cancelled) {
}

/**
* Called at the end of Damage Event, before return the damage value.
* This is the latest QuantumDamageEvent instance.
* Called at the end of the calculation, after the damage is written and the post-hit effects have run. Not
* called for hits that ignore Divinity's weapon stats.
*
* @deprecated Use {@link DivinityHitEvent.Result} for the final numbers (it fires for every calculated hit,
* those ignoring weapon stats included), or the Bukkit damage event at {@code MONITOR} for "after the hit
* landed".
*/
@Deprecated
public static class Exit extends DivinityDamageEvent {

public Exit(
Expand Down
Loading
Loading