Explosion Control

ExplosionControl

Complete, per-source control over every explosion type in Minecraft, for Paper 1.21.11 /
Java 21.

Author: zSouul

---

What it does

ExplosionControl gives server administrators independent control over 15 explosion
categories, each with the same five options in config.yml:

Categories: tnt, tnt-minecart, creeper, charged-creeper, wither-spawn,
wither-skull, ghast-fireball, fireball, blaze-fireball, dragon-fireball,
end-crystal, respawn-anchor, bed, wind-charge, and a catch-all other.

Reload changes at any time with:

/explosioncontrol reload

which requires the explosioncontrol.reload permission (default: op).

---

How each explosion type is handled

Every explosion source in the game is hooked at the earliest point the Paper API exposes for
that source, so enabled: false prevents as much of the explosion (damage, knockback, and
block damage) as technically possible — not just the block destruction.

damage-multiplier is enforced for every category above through a single shared
EntityDamageEvent listener (for ENTITY_EXPLOSION/BLOCK_EXPLOSION causes, plus
DRAGON_BREATH for the Dragon Fireball special case), which resolves the responsible
category via DamageSource#getCausingEntity() for entity sources, falls back to
ExplosionOriginRegistry (a short-lived cache populated when the explosion was primed, for
the rare case the source entity is already gone), and finally to reading the block still
present at DamageSource#getDamageLocation() for block sources (Bed/Respawn Anchor).

knockback-multiplier is enforced through EntityKnockbackEvent
(KnockbackCause.EXPLOSION). Since that event does not expose which explosion caused it, the
category resolved a moment earlier by the damage listener (for the same victim) is reused —
see PendingKnockbackCache for the full explanation of why and how this is safe.

---

Paper API limitations encountered, and how they were addressed

1. Bed and Respawn Anchor explosions apply entity damage/knockback before Bukkit fires
   BlockExplodeEvent. Unlike entity-sourced explosions (which fire the cancellable
   ExplosionPrimeEvent before anything happens), Bukkit only exposes BlockExplodeEvent
   for these two sources — after damage and knockback have already been applied. Cancelling
   BlockExplodeEvent alone would therefore only stop block destruction, not enabled: false
   as a whole.

   • Bed — addressed with the dedicated, cancellable Paper event
     PlayerBedFailEnterEvent (willExplode() == true), which fires before vanilla starts
     the explosion. Cancelling it fully prevents the explosion (damage, knockback, and block
     damage). This is a complete fix, not a workaround.
   • Respawn Anchor — Paper does not expose an equivalent dedicated event. The closest
     available alternative is intercepting the triggering PlayerInteractEvent (a right-click
     on a charged anchor outside the Nether, without glowstone in hand) and cancelling it,
     which replicates vanilla's own trigger condition. This covers the normal player-driven
     case completely, but — unlike Bed — cannot guarantee prevention if some other means
     forces the anchor to explode outside that interaction. BlockExplodeListener still runs
     as a second line of defence for block damage in that edge case.

2. EntityKnockbackEvent does not expose which entity or block caused the knockback —
   only a coarse KnockbackCause.EXPLOSION value, with no accessor for the exploding
   entity/block. Addressed by correlating it with the EntityDamageEvent fired for the same
   victim immediately beforehand (vanilla always damages-then-knocks-back each affected entity
   before moving to the next one), via a small short-lived cache keyed by entity UUID
   (PendingKnockbackCache). If no matching entry is found (e.g. another plugin cancelled the
   damage event first), vanilla knockback is left untouched rather than guessed at.

3. Blaze Fireball (blaze-fireball) does not actually explode in vanilla Minecraft. A
   Blaze's small fireball only ignites its target; there is no explosion for the Paper API to
   expose here at all. This section is still fully wired up (identical hooks to every other
   entity-sourced explosion) so that if a data pack, mod, or future Minecraft version ever
   makes small fireballs explosive, it is instantly configurable with no further plugin
   changes — it simply has nothing to do on an unmodified vanilla/Paper server today.

4. Dragon Fireball (dragon-fireball) is not a block-destroying explosion at all. On
   impact it spawns a lingering AreaEffectCloud ("dragon's breath") that deals
   DRAGON_BREATH-cause damage over time; it never fires ExplosionPrimeEvent or
   EntityExplodeEvent, and has no knockback component. Addressed with a dedicated listener
   using the closest honest analogues available: enabled cancels
   EnderDragonFireballHitEvent outright (no cloud ever appears), damage-multiplier scales
   each tick of DRAGON_BREATH damage, and radius-multiplier scales the resulting cloud's
   radius. block-damage and knockback-multiplier are intentionally ignored for this
   category and documented as such in config.yml, since vanilla dragon fireballs never
   destroy blocks or apply knockback in the first place — there's nothing for either option
   to meaningfully control.

5. repo.papermc.io and Maven Central are unreachable from the sandbox this project was
   authored in, so a compiled jar could not be produced or linked against the genuine
   paper-api artifact in that environment (see the note under Building above for exactly
   how correctness was still verified without it).

---

Permissions

Commands