Coal Explosion

Join at least of us on Discord right now!

Previously on Coal Explosion (prior to Neoforge 26.3)

Open Spoiler to see that

If you want a server setup using Coal Explosion with zero effort, get a server with BisectHosting and receive 25% off your first month as a new customer using the code kreezxil

Explosive Coal

Making coal irritating to your players. :) Coal Explosion adds configurable danger to coal mining and block interactions. Features and settings differ between versions; see the section for your Minecraft version below.

NeoForge 26.3

Coal Explosion 1.14.0 · Minecraft 26.3 · NeoForge · Java 25
Authors: Kreezxil and Rick South. Tested with NeoForge 26.3.0.101.

This version provides independent igniter/reactor groups, a native group editor, advanced event rules, optional flaming-arrow reactions, and gradual primed-block warnings with configurable spread and final outcomes. It adds one temporary block and one block-entity type, not new ores or world generation.

Installation and ordinary common configuration

• Launch once to create config/coalexplosion-common.toml. All 26 settings are under [general]. Back up worlds and configuration before experimenting.
• Native saves and valid loader reloads are supported. Restarting after manual edits is the simplest reproducible workflow. Existing primed blocks retain saved fuse/spread deadlines; later outcome decisions can use changed settings.

What the shipped defaults actually do Defaults are written into the config instead of being hard coded so you can see how to do the configs yourself. The default igniter is the minecraft:torch and the default explodable ore is #c:ores/coal (that's a tag, so all modded coal ores will ignite).

• One default group pairing is already in place so you can see how it is done.
• Separately, 21 default advanced rules include ten left/right-click rules: each of the five items ignites coal ore with chance 1.0.
• A fire neighbor has a 1.0 ignition rule. Each of the five torch/campfire neighbors has a 0.01 ignition rule. Neighbor notifications and tracked rechecks drive these rules, not a whole-world scan.
• Default progression has a 0.01 ON_FIRE_TICK fire rule, then ordered 0.01 BURN_TICK magma and explosion rules.
• Advanced click rules take priority, so shipped torch/campfire clicks start a warning rather than an immediate group explosion. Defaults use an 80-tick fuse, four-tick spread delay, RULE_FAMILY spread, and diagonal candidates.
• Projectile, burning-projectile, and explosion-activity rules are opt-in. No dirt or uranium mapping is enabled by default. Neighbor bonuses default to zero and lava treatment defaults off.

Independent igniter and reactor groups

ignitersAndReactors uses ordinary nested TOML arrays. Each entry is exactly [[igniters], [reactive blocks]]. Any igniter pairs with any reactor inside that entry only; groups do not cross-match. The Java representation is an immutable IgniterGroup(List<String> igniters, List<String> reactiveBlocks).

I recommend editing this on the client side using the Neoforge Config GUI for the mod, then transfer that config to your server.

The default group looks like this:

[general]
ignitersAndReactors = [
  [
    ["minecraft:torch"],
    ["#c:ores/coal"]
  ]
]

Opt-in isolation example, not a default: flint and steel can activate coal/dirt, an iron pickaxe can activate the optional uranium block, and a torch can activate either group. Missing optional block IDs match nothing and do not introduce a dependency.

ignitersAndReactors = [
  [["minecraft:torch", "minecraft:flint_and_steel"], ["#c:ores/coal", "minecraft:dirt"]],
  [["minecraft:torch", "minecraft:iron_pickaxe"], ["nuclearcraft:uranium_ore"]]
]

• First-side entries are item IDs or #item-tags; second-side entries are block IDs or #block-tags. Use full namespaces. Surrounding whitespace is trimmed; syntax is validated.
• Unknown IDs and missing/empty tags match nothing. Fresh groups do not implicitly include #coalexplosion:igniters; add it explicitly if wanted. That bundled item tag contains the five shipped items.
• ignitersAndReactors = [] disables groups. Either side of an individual pair may also be empty, making that pair inactive.
• Malformed pairs are logged and skipped as whole groups. A wrong outer config type can trigger NeoForge correction/defaults.
• Groups are simple left/right-click mappings requesting immediate explosions. They do not configure mining, projectiles, neighbor ignition, probabilities, custom results, or gradual ignition.

Native group editor: add, edit, remove, save, or cancel

At the title screen, open Mods → Coal Explosion → Config → Common Configuration → General → Igniter and Reactor Groups → Edit Groups.... No loaded world is needed.

• Use Previous/Next to choose a group; Add Group creates an empty pair; Remove Group removes that pair from the draft. Removing all groups saves an empty array.
• Igniters and Reactive Blocks are separate scrollable text fields: one ID or #tag per line. Blank lines are ignored and empty lists are supported.
• Save validates every group and persists the normal common config. Errors identify group, side, and line. Validation checks syntax, not whether an optional mod/tag is installed.
• Cancel/Escape discards this editor's detached draft without changing its live group value or saving. Navigation/resizing preserves the draft.
• If the group value changed elsewhere while the editor was open, Save refuses to overwrite it: cancel and reopen. A persistence exception restores the previous live group value, retains the draft, and shows an error.
• Other settings retain native NeoForge controls. Group Cancel does not undo earlier changes in those controls; Group Save uses a whole-file save and can also persist their pending edits. Native section Reset can reset groups.
• All labels are localized and tooltips are at most 30 words; detailed instructions are in config comments. Very long advanced rules may be easier to edit directly in TOML.

Advanced reaction rules and precedence

reactionRules is an ordered array of strings, each with three to five semicolon-separated fields:

block-or-#block-tag;ACTIVITY;item-or-#item-tag[;chance[;result-block]]

• Target: a block ID or block tag; while primed, matching uses the saved original state. No * wildcard is supported.
• Activity: one of the nine activities below; names are case-insensitive.
• Filter: held item/ammunition ID or item tag, or a neighbor block/item identity for neighbor rules. minecraft:air is the tool-independent wildcard; none requires an empty supplied item. Empty-handed clicks are rejected before matching.
• Chance: optional finite number from 0 to 1; omitted/blank means 1.0. Invalid values, activities, field counts, and result tags are rejected and logged.
• Result: omitted/blank means explode. minecraft:fire or coalexplosion:primed_block requests ignition. An installed ordinary block ID replaces with its default state; minecraft:air removes the block.

Use fully qualified, case-sensitive IDs/tags. Missing target/tool IDs and tags match nothing. Group validation is stricter than the older advanced parser's unreliable unqualified-ID shorthand. Filters test IDs/tag membership, not enchantments, durability, components, names, or NBT. Neighbor tags may match the block or its block item's item tag.

Click priority: advanced rules run before groups. The first successful advanced click rule handles the interaction; if none succeeds, groups may still request an immediate explosion. Groups do not restrict advanced rules. Editing groups does not rewrite rules. A failed/zero-chance rule is not a deny rule and can fall through to a group. Clear both active arrays to disable all mod reactions.

Direct click, mining, projectile, and explosion processing stops at the first successful advanced rule. Neighbor/invisible progression has different loops and may process more than one rule; primed final resolution follows the order described below.

All nine supported activities

• LEFT_CLICK: server-side player left-click on a block, using the event's held item.
• RIGHT_CLICK: player right-click on a block, using that hand's item.
• MINE: actual block-break event, using the main-hand item; distinct from merely left-clicking.
• PROJECTILE: projectile block impact, burning or not. AbstractArrow supplies its origin/pickup ammunition; other projectile types supply an empty item.
• BURNING_PROJECTILE: the same impact, but only while the projectile entity is actually on fire.
• EXPLOSION: a position in an explosion's affected-block list; supplied item is empty, so normally use minecraft:air or none.
• NEIGHBOR_IGNITE: notified adjacent faces after neighbor updates, all six faces after placement, and tracked rechecks; the filter describes the neighbor.
• ON_FIRE_TICK: invisible burning progression; in primed mode, a specialized one-time hook for adjacent fire at ignition.
• BURN_TICK: invisible burning progression or final resolution of a primed block.

Opt-in flaming arrows, without changing ordinary projectile behavior

Append this string to your existing reactionRules array to retain its other rules:

"#c:ores/coal;BURNING_PROJECTILE;#minecraft:arrows;1.0;minecraft:fire"

Or use this complete replacement array if it should be the only advanced rule:

reactionRules = [
  "#c:ores/coal;BURNING_PROJECTILE;#minecraft:arrows;1.0;minecraft:fire"
]

This starts coal's warning only if the arrow is burning at impact. It checks the actual projectile's isOnFire(), not the shooter's fire state, a Flame enchantment alone, or an invented flaming-arrow item. Extinguished arrows do not qualify; arrows ignited by another mechanism can. Use ammunition IDs/tags, not bow/crossbow IDs or the owner's current hand.

Existing PROJECTILE rules still accept cold and burning projectiles. Both activities share one ordered pass: an earlier successful ordinary rule can handle the impact before a later burning-only rule. Player-owned, mob-owned, and ownerless/dispenser-style projectiles are accepted; no owner/team/claims condition exists. Non-arrow projectile classes supply an empty item and require a suitable wildcard/empty filter. Entity hits and misses are not triggers.

Alternative: #c:ores/coal;BURNING_PROJECTILE;minecraft:arrow;1.0 requests an immediate explosion instead of a warning. It filters the normal arrow item, not every ammunition item in a tag. No projectile rule is shipped enabled.

TOML allows only one assignment per key in a section. Edit the existing array; do not paste a second reactionRules key. Replacing the array removes its previous mining, neighbor, and progression examples.

Consumption, Creative mode, cancellation, and output safety

• A successful advanced/group right-click consumes one whole held item outside Creative, cancels normal use, and returns success. A tool used this way is consumed as an item, not damaged by one durability point.
• Advanced left-click cancels normal handling without consuming the item. Group left-click preserves historical PASS/non-cancel behavior while requesting an explosion.
• A successful mining rule cancels ordinary breaking and its normal drops; the mod adds no tool consumption or durability damage.
• A successful projectile rule cancels normal impact but does not discard the projectile or consume extra ammunition/owner items. The projectile can continue flying. Vanilla shooting costs remain separate.
• Explosion rules do not cancel/remove the original explosion's affected positions. Its blast can still affect newly placed non-resistant results.
• Missing output IDs can be handled no-ops in direct rules: cancellation/right-click consumption can still happen. Check output IDs carefully.
• Direct replacement uses a block's default state and does not preserve inventory or properties. This is not a general inventory-preserving transformation system.
• Use minecraft:fire for portable ignition. Other fire blocks are treated as ignition by the generic direct handler, but specialized primed tick hooks recognize exact markers differently; soul fire is not interchangeable everywhere.
• Other mods' cancellations, vanilla rules, resistance, and explosion behavior can affect the interaction. There is no permissions/claims integration or guaranteed alternate-drop system.

Primed warning: sound, particles, and an animated visual cycle

With primedIgnition = true, an ignition result attempts to create coalexplosion:primed_block, recording the original state, root family, vein budget, and fuse/spread deadlines. Each new primed block plays the vanilla TNT fuse sound, emits a prime-fuse event, and has smoke/occasional flame particles.

Its faces repeat coal-block pattern → bright white coal pattern → black/dark magma pattern. Three 16×16 frames last five ticks each, with no interpolation. This is a global texture-atlas animation, not a per-block fuse clock: a new block can start in any phase. The dark magma frame is only a visual warning; it does not commit or bias the final result. Healthy coal textures are untouched.

The temporary block is unbreakable in Survival, highly blast resistant, and piston-immovable. It has no block item, recipe, loot table, or creative-tab entry. Air, already-primed states, block-entity blocks, and fluid-containing/waterlogged states cannot normally prime. A failed root attempt falls back to invisible burning; a failed spread candidate is skipped. Manual malformed primed blocks are not a supported setup method.

Gradual spread, final magma/explosion outcomes, and persistence

Each newly primed block attempts one spread step after its stored delay, then resolves at its own fuse deadline. This produces a staggered front rather than converting a whole vein instantly. Nominally 20 ticks equal one second; lag changes wall-clock timing.

• RULE_FAMILY: same original block type or the root rule's target ID/tag; the coal tag can connect ordinary and deepslate ore.
• SAME_BLOCK: only the current original block type.
• ANY_REACTIVE: same type or a block named by any group/rule, regardless of that other mapping's activity/chance.
• NONE: no spread beyond the root.

Diagonal spread checks 26 surrounding positions; otherwise only six faces. Candidates must be loaded, eligible, and within the live vein budget and loaded-primed cap. Spread does not force-load candidate chunks or retry skipped candidates. Root item filters/chance are not independently rerolled for each child.

At fuse completion, ordered matching BURN_TICK rules inspect the original state, ignoring their item field. Exact normal-fire/primed-block results are skipped to avoid restarting the fuse. The first successful explosion or usable concrete result wins; unknown outputs are skipped. If no rule resolves the block, magmaChance selects the fallback block or an explosion. An invalid magmaResultBlock falls back to vanilla magma.

The 0.25 default is a fallback chance, not an overriding final percentage. Earlier BURN_TICK rules run first. With the exact shipped rules and zero bonuses, total final magma probability is approximately 25.5025% per block. Setting magmaChance to 0 or 1 does not override earlier output/explosion rules; remove those rules for deterministic fallback behavior.

Primed ON_FIRE_TICK processing is a one-time ignition hook for exact minecraft:fire outputs, ignoring the tool field. It does not run arbitrary ON_FIRE replacements. Other fire outputs may be literal blocks in specialized final processing and disappear if unsupported.

Deadlines and original states are saved with primed block entities and use scheduled ticks. Existing deadlines do not reset on config edits; new children use current timing. Loaded-position tracking is released on removal/unload. Vein budget snapshots can be reconstructed after unload/restart, so the limit is a bounded live budget, not an exact persistent lifetime counter across every history.

Invisible burning, neighbor ignition, and optional lava

If priming is disabled or a root cannot prime, the original block remains invisibly tracked. The mod tries valid fire above first, then horizontally. causeFire = false controls explosion-created fire, not this initial ignition fire.

Invisible burning progresses through ON_FIRE/BURN rules using empty-item filters and the tracker cooldown. It has no temporary block, saved fuse, primed spread step, or magmaChance fallback. More than one applicable rule can execute as transformations progress. These in-memory watch/burn jobs are not serialized and are cleared on level unload.

Neighbor detection uses relevant adjacent faces and watched rechecks; unignited watches are removed when the source disappears. With treatLavaAsMagma = true, lava counts as magma for bonuses and is presented as fire for neighbor matching. A fire-neighbor rule can then ignite ore beside lava. An explicit lava filter is not equivalent under that substitution. With the option false, an explicitly configured lava rule can still match. Lava treatment is off by default to avoid broad cascades.

Neighbor modifiers, cooldowns, blast range, and safety caps

Eligible chance calculations add six-face fire/magma/coal-like/flammable bonuses and clamp the result to 0–1. These bonuses apply to explosion-result BURN_TICK rules and EXPLOSION-activity rules, not every trigger. Coal-like includes the coal tag or blocks named by any active group/rule; flammable excludes air, fire, magma-like, and coal-like blocks. Diagonal spread does not change these six-face counts.

Zero base chance is not a universal disable: eligible positive bonuses can raise it, and failed click rules can fall through to groups. Remove applicable mappings for safety; there is no negative/deny rule or exempt-tool override.

chanceCooldownTicks controls tracked progression/rechecks and direct probabilistic attempts. Guaranteed direct rules bypass that gate. A failed attempt can reserve a position's cooldown and suppress later probabilistic rules. Primed final resolution does not use that direct cooldown. It is not a universal debounce of all events.

Final blast radius is max(0, explosionRange + adjacentCoalLike * coalExplosionRangeBonus + adjacentFlammable * flammableExplosionRangeBonus + adjacentMagma * magmaExplosionRangeBonus). Bonuses can raise the final radius above the base option's maximum. There is no independent explosion-strength setting in this version.

• explosionChainLimit bounds nested mod-generated explosion depth including the root; zero suppresses mod explosion calls, not all transformations/ignitions or a preexisting vanilla blast. A suppressed blast does not undo item consumption or restore an already removed primed block.
• maxTrackedBlocks limits watched/invisible positions per dimension. Burning can evict watches first; immediate events may still react at the tracking cap.
• maxPrimedBlocks limits loaded primed positions per dimension. A capped root can fall back to invisible burning; capped spread candidates are skipped.
• veinScanLimit includes the root and bounds a live ignition budget.
• Parsed settings are cached and primed timing uses scheduled ticks, not whole-world scans. Only explicit primed spread has the stated no-force-loading guarantee; fallback tracker reads have different limits.

Caps are safeguards, not a lag-proof promise. Large radii, broad tags, overlapping rules, and increased caps can still be destructive and expensive. Test a backed-up world first.

All 26 common settings: defaults and allowed values

All entries belong to [general]. Numeric bounds are inclusive; booleans accept true/false. Empty active arrays are valid. Wrong option types can trigger NeoForge correction/defaults.

Setting	Default	Range / role
explosionRange	5.0	0..256; base radius before neighbor additions
causeFire	false	Request fire from mod explosions
ignitersAndReactors	One five-item / coal-tag group	Nested two-list pairs; empty outer/sides allowed
reactionRules	21 rules described above	Ordered 3–5-field strings; empty allowed
neighborFireChanceBonus	0.0	0..1 per adjacent fire, for eligible chance calculations
neighborMagmaChanceBonus	0.0	0..1 per adjacent magma-like block
neighborCoalChanceBonus	0.0	0..1 per adjacent coal-like/reactive block
neighborFlammableChanceBonus	0.0	0..1 per qualifying flammable neighbor
coalExplosionRangeBonus	0.0	0..64 radius per adjacent coal-like/reactive block
flammableExplosionRangeBonus	0.0	0..64 radius per qualifying flammable neighbor
magmaExplosionRangeBonus	0.0	0..64 radius per magma-like neighbor
treatLavaAsMagma	false	Lava enters magma counts and becomes fire for neighbor matching
chanceCooldownTicks	20	1..200 ticks; cooldown qualifications explained above
explosionChainLimit	8	0..64 nested mod explosion depth
maxTrackedBlocks	256	1..4096 watched/invisible positions per dimension
primedIgnition	true	Use temporary warning blocks for eligible new roots
warningTicks	80	1..1200 ticks; nominal four-second fuse
spreadTicks	4	1..200 ticks before each block’s one spread attempt
magmaChance	0.25	0..1; final fallback only, after BURN_TICK rules
magmaResultBlock	minecraft:magma_block	Concrete fallback output; invalid/unknown falls back to vanilla magma
veinScanLimit	64	1..4096; live vein budget including root
maxPrimedBlocks	1024	1..4096 loaded primed blocks per dimension
spreadMode	RULE_FAMILY	RULE_FAMILY, SAME_BLOCK, ANY_REACTIVE, NONE
spreadDiagonally	true	26 surrounding candidates instead of six faces
configuredIgniters	Five torch/campfire IDs	Retained one-time compatibility input, not a second active global list
configuredBlocks	["#c:ores/coal"]	Retained one-time compatibility input, not a second active global list

Existing configurations and compatibility migration

If coalexplosion-synced.toml exists and the common file does not, the mod attempts a one-way rename to coalexplosion-common.toml. If both exist, the common file wins; the other file is not merged/deleted. Check logs for rename errors.

For an existing common file without general.ignitersAndReactors, migration reads the old configuredIgniters/configuredBlocks before defaults are inserted. It creates one combined group, preserving their old all-to-all relationship inside that group, and explicitly adds #coalexplosion:igniters because the old click path always included that tag. Empty old block lists remain disabled; invalid old entries are not silently promoted into new matching behavior. Original key strings remain untouched.

A backup named coalexplosion-common.toml.pre-groups.bak is created if absent before saving migrated groups. Migration failure stops loading instead of silently substituting new group defaults. Once the group key exists, even as [], it is authoritative: later old-list edits do not merge back or reactivate groups. Existing advanced rules retain their semantics; migration does not enable burning arrows.

Verification and realistic limitations

The real headless GameTest suite passed 16/16 required tests, including the vanilla always-pass test. Coverage includes real arrow fire states/impact events, filters and owners, old grammar, group isolation/migration, editor model/save/cancel/conflict handling, defaults, priming/spread/outcomes, lava behavior, assets, and tooltip length. The extracted source archive was independently rebuilt and tested.

The custom screen and animated warning have not been graphically verified here. Server tests do not prove appearance, layout, smoke, or sound. Tests also do not simulate every full arrow flight through water, optional mod/tag, event conflict, or restart/unload history. Delayed primed blasts do not preserve shooter attribution. No new ores/worldgen, recipes, safe-tool list, independent strength option, owner selectors, permission system, remote configuration, or custom warning HUD is implemented.

Older versions

The settings, examples, and historical plans below describe older releases or earlier design ideas. They are not the NeoForge 26.3 configuration reference.

Earlier configurable settings

Range (historical default = 5.0, min 0 max 256.0): The range of the explosion of a coal block.

Strength (historical default = 10.0, min 0, max 256.0): The amount of damage the explosions do.
causeFire (historical description: default = false): Whether an exploding coal block should cause fire.

Sparks (historical default = iron and gold pickaxes): Whatever you add to this list will trigger explosions like Pigporker below was expecting.

1.19+

I've implemented a tag coalexplosion:igniters to Coal explosion and added all vanilla torches to it. I've also added a config option to add more igniting items that way (which I was able to confirm works by inserting "minecraft:stick")
This way new items can be either done through a datapack or a config option
I also kept an extra check for instanceof TorchBlock to keep the same level of compatibility with any mods that extend the class

Example Config from NeoForge 1.21.1

This preserved older-version example is not the current default configuration. In particular, its causeFire value is true.

[general]
    #General settings
    #The range of the explosion of a coal block.
    #Range: 0.0 ~ 256.0
    explosionRange = 5.0
    #Whether an exploding coal block should cause fire.
    causeFire = true
    #A list of extra configured items that can cause coal to explode
    configuredIgniters = ["minecraft:iron_sword", "minecraft:iron_pickaxe", "minecraft:iron_axe", "minecraft:iron_shovel", "minecraft:iron_hoe", "minecraft:golden_sword", "minecraft:golden_pickaxe", "minecraft:golden_axe", "minecraft:golden_shovel", "minecraft:golden_hoe", "minecraft:netherite_sword", "minecraft:netherite_pickaxe", "minecraft:netherite_axe", "minecraft:netherite_shovel", "minecraft:netherite_hoe"]
    #A list of extra configured blocks that igniters can cause to explode
    configuredBlocks = ["minecraft:coal_block", "minecraft:magma_block", "minecraft:nether_wart_block", "minecraft:crimson_nylium", "minecraft:warped_nylium"]

Historical planned features for older versions

The following is preserved historical planning text, not a promise that every proposal was implemented. Refer to the version-specific documentation for actual settings and behavior.

The mod offers a variety of configuration options to fine-tune the explosive behavior of coal blocks:

• Allowed Tools: A list of tools allowed for harvesting without triggering a calamity. By default, this includes wood and diamond tools. There is no blacklist; tools are either exempt or they are not.
• Base Chance to Ignite: The base probability that a coal block will ignite upon certain triggers, such as being mined with non-exempt tools or being near fire sources.
• Base Chance After Ignition to Become Magma Block: The base chance that an ignited coal block will transform into a magma block.
• Base Chance After Ignition to Explode: The base chance that an ignited coal block will explode.
• Explosion Chance Increases: Various factors can increase the chance of an explosion:
  • Neighbor on Fire: Chance increase amount if a neighboring block is on fire.
  • Neighbor is Magma Block: Chance increase amount if a neighboring block is a magma block.
  • Neighbor is Coal: Base chance to increase explosion if a neighboring block is coal.
  • Neighbor is Flammable: Base chance to increase explosion if a neighboring block is flammable.
• Explosion Strength Modifiers: The explosion strength can be increased based on adjacent blocks:
  • Coal Explosion Increase Amount: For each adjacent coal ore, this increases the explosion strength.
  • Flammable Explosion Increase Amount: For each adjacent flammable block, this increases the explosion strength.
  • Magma Explosion Increase Amount: For each adjacent magma block, this increases the explosion strength.
• Lava Interaction: There is a configuration option to consider lava as an ignition source. By default, this is turned off to prevent excessive explosion lag. If enabled, coal veins touching lava will ignite and be treated as if adjacent to a magma block.
• Ignition by Torches: Regular torches can ignite coal blocks with a chance each tick update.

This configuration system allows for a dynamic and challenging gameplay experience, where coal mining can become a risky endeavor, especially when using non-exempt tools or in the presence of certain environmental factors.

Reminder: the paragraphs above are historical plans, not evidence of an implemented exempt-tool list or separate strength setting.

Fabric Versions require Fabric API and ClothConfig

Recommend Mod Companions:
https://www.curseforge.com/minecraft/mc-mods/spelunkers-charm-ii