ExplosionControl
对 Minecraft 中所有爆炸类型实现完全、按来源的控制,适用于 Paper 1.21.X 至 26.3。
作者:zSouul
功能说明
ExplosionControl 为服务器管理员提供对 15 种爆炸类别的独立控制权限,每个类别在 config.yml 中均提供相同的五项选项:
| 选项 |
类型 |
效果 |
enabled |
true/false |
总开关 — 尽可能早地阻止爆炸发生。 |
damage-multiplier |
≥ 0.0 |
缩放对任何单个活体实体造成的伤害(1.0 = 原版默认值,0.0 = 无伤害)。应用于护甲、抗性提升和吸收效果生效前的原始伤害,因此这些减伤机制仍会正常运作。 |
radius-multiplier |
≥ 0.0 |
缩放爆炸半径/威力(1.0 = 原版默认值)。 |
knockback-multiplier |
≥ 0.0 |
缩放施加给受影响实体的击退速度。 |
block-damage |
true/false |
是否允许该爆炸破坏方块或掉落物品。 |
类别包括:tnt、tnt-minecart、creeper、charged-creeper、wither-spawn、wither-skull、ghast-fireball、fireball、blaze-fireball、dragon-fireball、end-crystal、respawn-anchor、bed、wind-charge,以及一个兜底类别 other。
随时使用以下命令重载配置更改:
/explosioncontrol reload
该命令需要 explosioncontrol.reload 权限(默认为 op)。
各类爆炸的处理方式
游戏中的每种爆炸源都在 Paper API 针对该源暴露的最早时间点进行拦截,因此当设置 enabled: false 时,可以技术上阻止尽可能多的爆炸效果(包括伤害、击退和方块破坏)——而不仅仅是阻止方块破坏。
| 类别 |
主要拦截点 |
备注 |
tnt |
ExplosionPrimeEvent + EntityExplodeEvent |
标准的实体爆炸流程。 |
tnt-minecart |
ExplosionPrimeEvent + EntityExplodeEvent |
相同流程;实体类型为 ExplosiveMinecart。 |
creeper |
ExplosionPrimeEvent + EntityExplodeEvent |
Creeper#isPowered() == false。 |
charged-creeper |
ExplosionPrimeEvent + EntityExplodeEvent |
Creeper#isPowered() == true。radius-multiplier 是在原版双倍半径的基础上额外应用的。 |
wither-spawn |
ExplosionPrimeEvent + EntityExplodeEvent |
凋灵完成生成时触发的单次爆炸;来源实体即为 Wither 本身。 |
wither-skull |
ExplosionPrimeEvent + EntityExplodeEvent |
涵盖普通骷髅头以及蓝色/“充能”变体。 |
ghast-fireball |
ExplosionPrimeEvent + EntityExplodeEvent |
其 getShooter() 为 Ghast 的 LargeFireball。 |
fireball |
ExplosionPrimeEvent + EntityExplodeEvent |
其他任何 LargeFireball(例如由发射器发射的)。 |
blaze-fireball |
ExplosionPrimeEvent + EntityExplodeEvent |
见下方限制部分 — 在未修改的原版中无效。 |
dragon-fireball |
EnderDragonFireballHitEvent + EntityDamageEvent(DRAGON_BREATH) |
见下方限制部分 — 完全不同的机制。 |
end-crystal |
ExplosionPrimeEvent + EntityExplodeEvent |
实体类型为 EnderCrystal。 |
wind-charge |
ExplosionPrimeEvent + EntityExplodeEvent |
涵盖投掷/发射的 WindCharge 以及 Breeze 发射的 BreezeWindCharge(共享父类 AbstractWindCharge)。 |
respawn-anchor |
PlayerInteractEvent (爆炸前) + BlockExplodeEvent |
见下方限制部分。 |
bed |
PlayerBedFailEnterEvent (爆炸前) + BlockExplodeEvent |
可完全防止 — 详见下文。 |
other |
上述所有拦截点的回退分支 |
捕获任何未来或无法识别的爆炸源,确保没有任何内容不可配置。 |
damage-multiplier 通过单一的共享 EntityDamageEvent 监听器对上述所有类别强制执行(用于 ENTITY_EXPLOSION/BLOCK_EXPLOSION 原因,以及 Dragon Fireball 特殊情况的 DRAGON_BREATH),它通过 DamageSource#getCausingEntity() 解析实体来源的责任类别,如果来源实体已消失则回退到 ExplosionOriginRegistry(这是一个在引爆时填充的短期缓存,用于处理极少数情况),最后对于方块来源(床/重生锚),则读取 DamageSource#getDamageLocation() 处仍存在的方块。
knockback-multiplier 通过 EntityKnockbackEvent(KnockbackCause.EXPLOSION)强制执行。由于该事件不暴露是哪个爆炸引起的,因此会复用伤害监听器稍早前为该受害者解析出的类别 — 完整解释请参见 PendingKnockbackCache,了解为何及如何安全地这样做。
遇到的 Paper API 限制及其解决方案
-
床与重生锚爆炸会在 Bukkit 触发 BlockExplodeEvent 之前对实体造成伤害/击退。 不同于由实体引发的爆炸(在发生任何事之前会触发可取消的 ExplosionPrimeEvent),Bukkit 仅针对这两种来源暴露了 BlockExplodeEvent —— 此时伤害和击退已经生效。因此,仅取消 BlockExplodeEvent 只会阻止方块破坏,而非整体禁用(enabled: false)。
- 床 — 通过专用的、可取消的 Paper 事件
PlayerBedFailEnterEvent(willExplode() == true)解决,该事件在原版开始爆炸 之前 触发。取消它可完全防止爆炸(包括伤害、击退和方块破坏)。这是完整的修复方案,而非变通方法。
- 重生锚 — Paper 未提供等效的专用事件。最接近的可用替代方案是拦截触发的
PlayerInteractEvent(在非末地维度外对已充能的锚进行右键点击,且手中无萤石),并取消该事件,从而复现原版的触发条件。这完全覆盖了正常的玩家驱动情况,但 — 与床不同 — 无法保证在其他手段强制使锚爆炸时能完全阻止。在此边缘情况下,BlockExplodeListener 仍作为防止方块破坏的第二道防线运行。
-
EntityKnockbackEvent 不暴露造成击退的实体或方块 — 仅提供一个粗略的 KnockbackCause.EXPLOSION 值,没有用于获取爆炸实体/方块的访问器。解决方法是与立即在此之前为同一受害者触发的 EntityDamageEvent 进行关联(原版总是先对每个受影响的实体造成伤害再击退,然后才处理下一个实体),通过一个以实体 UUID 为键的小型短生命周期缓存(PendingKnockbackCache)实现。如果找不到匹配项(例如其他插件首先取消了伤害事件),则保留原版击退不变,而不是猜测。
-
烈焰火球 (blaze-fireball) 在原版 Minecraft 中实际上不会爆炸。 烈焰的小火球只会点燃目标;此处根本没有可供 Paper API 暴露的爆炸。本节仍完全连接好(与所有其他实体源爆炸相同的钩子),以便如果数据包、模组或未来 Minecraft 版本使小火球具有爆炸性,可以立即配置而无需进一步更改插件 — 在今天未修改的原版/Paper 服务器上,它没有任何作用。
-
龙息火球 (dragon-fireball) 根本不是破坏方块的爆炸。 撞击时它会生成一个滞留的 AreaEffectCloud(“龙息”),造成随时间流逝的 DRAGON_BREATH 类型伤害;它从不触发 ExplosionPrimeEvent 或 EntityExplodeEvent,也没有击退组件。使用可用的最诚实类比来解决:enabled 直接取消 EnderDragonFireballHitEvent(永远不会出现云团),damage-multiplier 缩放每次刻的 DRAGON_BREATH 伤害,radius-multiplier 缩放结果云团的半径。block-damage 和 knockback-multiplier 对此类别有意忽略,并在 config.yml 中记录说明,因为原版龙息火球本身就不会破坏方块或施加击退 — 这两个选项没有任何实质性的控制对象。
-
从编写此项目的沙箱环境中无法访问 repo.papermc.io 和 Maven Central,因此无法在该环境中生成编译好的 jar 文件或链接到真实的 paper-api 工件(有关如何在不依赖它的情况下验证正确性的详细信息,请参见上方 构建 部分下的注释)。
权限
| 权限 |
默认值 |
描述 |
explosioncontrol.reload |
op |
允许运行 /explosioncontrol reload。 |
命令
| 命令 |
描述 |
/explosioncontrol reload |
重新加载 config.yml,无需重启服务器。 |
ExplosionControl
Complete, per-source control over every explosion type in Minecraft , for Paper 1.21.X to 26.3
Author: zSouul
What it does
ExplosionControl gives server administrators independent control over 15 explosion
categories, each with the same five options in config.yml:
| Option |
Type |
Effect |
enabled |
true/false |
Master on/off switch — prevents the explosion as early as possible. |
damage-multiplier |
≥ 0.0 |
Scales the damage dealt to any single living entity (1.0 = vanilla, 0.0 = no damage). Applied to raw damage before armor, so armor/resistance/absorption still reduce it normally. |
radius-multiplier |
≥ 0.0 |
Scales the blast radius/power (1.0 = vanilla). |
knockback-multiplier |
≥ 0.0 |
Scales the knockback velocity applied to caught entities. |
block-damage |
true/false |
Whether the explosion is allowed to destroy/drop blocks. |
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.
| Category |
Primary hook(s) |
Notes |
tnt |
ExplosionPrimeEvent + EntityExplodeEvent |
Standard entity-explosion pipeline. |
tnt-minecart |
ExplosionPrimeEvent + EntityExplodeEvent |
Same pipeline; entity type ExplosiveMinecart. |
creeper |
ExplosionPrimeEvent + EntityExplodeEvent |
Creeper#isPowered() == false. |
charged-creeper |
ExplosionPrimeEvent + EntityExplodeEvent |
Creeper#isPowered() == true. radius-multiplier is applied on top of vanilla's own charged-creeper radius doubling. |
wither-spawn |
ExplosionPrimeEvent + EntityExplodeEvent |
The single explosion fired the moment a Wither finishes spawning; source entity is the Wither itself. |
wither-skull |
ExplosionPrimeEvent + EntityExplodeEvent |
Covers both the regular and blue/"charged" skull variants. |
ghast-fireball |
ExplosionPrimeEvent + EntityExplodeEvent |
LargeFireball whose getShooter() is a Ghast. |
fireball |
ExplosionPrimeEvent + EntityExplodeEvent |
Any other LargeFireball (e.g. dispenser-fired). |
blaze-fireball |
ExplosionPrimeEvent + EntityExplodeEvent |
See limitation below — inert on unmodified vanilla. |
dragon-fireball |
EnderDragonFireballHitEvent + EntityDamageEvent(DRAGON_BREATH) |
See limitation below — different mechanic entirely. |
end-crystal |
ExplosionPrimeEvent + EntityExplodeEvent |
Entity type EnderCrystal. |
wind-charge |
ExplosionPrimeEvent + EntityExplodeEvent |
Covers both thrown/dispensed WindCharge and Breeze-fired BreezeWindCharge (shared AbstractWindCharge supertype). |
respawn-anchor |
PlayerInteractEvent (pre-explosion) + BlockExplodeEvent |
See limitation below. |
bed |
PlayerBedFailEnterEvent (pre-explosion) + BlockExplodeEvent |
Fully preventable — see below. |
other |
Every hook above, as a fallback branch |
Catches any future/unrecognised explosion source so nothing is ever left unconfigurable. |
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
-
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.
-
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.
-
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.
-
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.
-
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
| Permission |
Default |
Description |
explosioncontrol.reload |
op |
Allows running /explosioncontrol reload. |
Commands
| Command |
Description |
/explosioncontrol reload |
Reloads config.yml without restarting the server. |
评论 0
登录后参与评分
还没有评论,来抢沙发吧