CBC Enchanced Shells [Create Big Cannons]

# Changelog

## [1.4.0] - 2026-09-11 — The Nuclear FX Update ☢️

The biggest visual update of the mod. The nuclear shells and the Singularity shell were rebuilt from the ground up around a new client-side FX engine: zero particles, a handful of draw calls, and explosions that finally look like the real thing. Nukes raise a real mushroom cloud, H-Bombs swallow the horizon in a sphere of fire and cloud, the Singularity is a true black hole, and the shells themselves are finally recognisable.

### Why

The mushroom clouds of 1.2.x were built from thousands of long-lived translucent smoke particles, the main cause of the "a nuke freezes my game" reports. Everything below runs on analytically placed geometry rebuilt every frame from the detonation time: no particle entities, no per-particle physics, no per-frame allocation.

### New — client FX engine

- **Zero particles.** A nuclear cloud is 1,500 to 4,000 pre-lit billboards in 4 to 6 draw calls, built from a shared sprite atlas (smoke, fire, glow) and a few flat primitives (rings, discs, walls, domes, ribbons).

- **Sun-lit, self-shadowing clouds.** Every smoke billboard is shaded from the in-game sun direction (time of day), the cap is lit on its sun-facing side and falls into its own shadow on the far side, the underside is warm brown, the top cream. Looking towards the sun through the cloud gives a silver lining. Night dims the smoke, the fire stays bright.

- **Pre-lit smoke sprites** with baked top lighting (8 cumulus puffs) and a sharper sheet for billboards close to the camera, so the volume reads at any distance.

- **Atmospheric perspective.** Distant smoke takes on the colour of the sky fog like a real far-away cloud (dedicated smoke shader with the vanilla fog, softened so the cloud stays visible beyond the terrain fog).

- **Inner fire.** Fire that belongs inside the cloud (the column in the stem, the fireball in the cap, the H-Bomb dome) is drawn in a batch flushed before the smoke, so it is veiled by it and only burns through the gaps.

- **Detail scaling.** Density follows the vanilla Particles setting and the config, drops with distance and when the camera is inside the cloud; billboards fade before they clip through the camera.

- **Shader-pack friendly.** Only the batches actually used are flushed (no global end-batch re-sorting every entity batch of the frame under Iris). A tiny custom core shader removes the vanilla alpha cutoff so smoke keeps its soft edges, with a silent fallback to the vanilla shader.

- **One packet per detonation** (players within 1536 blocks); the client builds everything from it.

### New — nuclear mushroom cloud (Nuke Mk.I / Mk.II)

Colour and motion follow the real thing (test footage, Glasstone, Los Alamos):

- **Fireball**: white → yellow → orange → dull red, breaking into soot patches as it cools, churning; an egg stretched upward that lifts off the ground, rounds off and becomes the mushroom head, with a blue-violet aura of ionised air in the first seconds and a dull red glow that keeps lighting the cloud from inside for a long time. Glare when you look straight into it.

- **Cap**: a boiling central mass rising above a torus that rolls (hot gas climbs in the centre, flows out and down at the rim), fine curls on the rim, rusty red-brown (nitrogen dioxide) when young and whitening as water condenses, flattening into an anvil as it ages and drifting downwind.

- **Stem**: a hollow sheath of dust around an incandescent **fire column** (axis beams, flame tongues racing upward, an ember core that lingers), leaning downwind, with a skirt at the base, cone-shaped skirts and collar rings of condensation while it climbs (3 rings on the Mk.I, 5 and an ice cap on the Mk.II).

- **Ground zero**: dirt eruption thrown straight up before the stem forms, heavy rocks and lumps tumbling out in ballistic arcs and trailing dust, dust lifted off the ground by the passing shock front, four dust waves with a vertical wall following the terrain over hills and valleys, successive ground shock rings, a base surge fog, scorched earth, molten ground that cools over minutes, and the afterwind dragging dust back towards the stem.

- **Blast**: double flash with glare rays, shock front with a dusty wake, the white condensation dome (Wilson cloud) forming behind it, and a thermal dome of fire.

- **Light and sky**: glow patches on the terrain following its height, the shadow of the cloud on the ground along the sun, the whole sky lighting up at night, lightning between the cap and the ground that brightens the cloud.

- **Fire**: a sea of fire over the blast radius in the first seconds, then a firestorm of individual fires with smoke plumes drifting downwind, dying one by one, with secondary explosions.

- **Aftermath**: ember streaks and rain, then fallout ash falling around the site for minutes after the cloud is gone.

- **Airburst / water burst** detected automatically: an airburst raises a white steamy stem with no debris, a burst over water raises a white spray column and a white base-surge ring (no fires, no scorch).

- **Sizes** (cap altitude / cap radius): Nuke Mk.I 120 / 60 blocks, Nuke Mk.II 240 / 130 blocks, living 100 s and 130 s before fading.

### New — H-Bomb and Mini H-Bomb

- **Thermal dome**: an enormous fire-covered hemisphere growing in steps synced with the server shockwave rings (32 + 15 n ticks), each pushing a wall of dust, with a blinding rim.

- **Cloud sphere** instead of a mushroom: as the fire cools, an enormous sphere of cloud forms over the dome (boiling surface, turbulent rim, dense inner volume), lit by the sun on top and by the fire underneath, growing for the whole life of the effect, lifting off and flattening slightly at altitude.

- **Rings blown out of the sphere**, born on its surface at their own height, racing outward and fading, on top of the ground shock rings.

- Sizes: Mini H-Bomb 320 / 170, H-Bomb 520 / 300 blocks, up to 3 minutes.

### New — immersion

- **Flash** on the screen (stronger when you look at the blast) and an orange **thermal wash** that lasts far longer than the light; a faint **retinal afterimage** if you looked straight at it.

- **Sound with a real delay**: the detonation is played when the shock front arrives (distance / 12 blocks per tick), followed by rolling rumbles and a long blast roar; a sharp crack within 90 blocks. A distant blast is seen first and heard later.

- **Shock front impact**: camera shake with a distance-dependent delay, a field-of-view punch, and the blast wind pushing the player away.

- **Recognisable shells**: new textures (olive-drab with yellow/black danger bands and a radiation trefoil for the Nuke Mk.I, gunmetal with a red tip for the Mk.II, silver with red trefoil and stripes for the Mini H-Bomb, black with red and silver bands for the H-Bomb); in the air a nuclear shell carries a blinking red warning light with a halo sized to stay visible far away, a tracer trail, a smoke trail, and whistles on the way down.

### New — thermal pulse on the world (server)

- **Terrain**: grass turns to coarse dirt / dirt, vegetation and the top layer of leaves burn away, snow and ice melt, a few fires start where fire can exist, spread over a few seconds with a distance falloff, capped radius, never in claimed chunks, never on water.

- **Entities**: living entities within 1.2 cloud radii are set on fire and thrown away from the blast, weaker with distance (in water, fire-immune, creative and claimed-chunk entities are spared).

### Singularity Shell — rebuilt as a real black hole

18 s (Mk.I) to 30 s (Mk.V), radius 24 to 80 blocks, colour cyan (Mk.I) → violet (Mk.III) → orange (Mk.V):

- **Collapse**: streaks of light race inward into a blinding point, then the event horizon opens.

- **Horizon** with a photon ring and halo; an **accretion disk**, tilted, turbulent, in differential rotation with Doppler beaming, hot white inside and tier-coloured outside, with filaments of matter spiralling into the horizon; an **Einstein ring** (rays skimming the horizon are bent around it, so the disk hidden behind the hole reappears as arcs above and below); **polar jets** of plasma from Mk.II, longer and brighter with the tier; the light around the hole is swallowed.

- **Instability**: the horizon pulses and cracks with light, the disk flares.

- **Collapse and release**: the hole shrinks to a point, then bursts in a shell of light and a ground wave, a burst of sparks, a strong shake and a flash; a glowing **wound in space** stays at the centre for 20 s.

- **World**: debris torn from the surroundings spirals into the hole with a glowing tail, dust is dragged along the ground, the disk lights the terrain in the tier colour, a deep gravitational hum swells with the hole and throbs during the instability, the camera shakes at each seismic ring.

- **Terrain destruction synced with the visual**: each shell of blocks is swallowed once the visible horizon has covered it; the seismic rings crack the ground along a jagged trench that follows the ring the shader draws, silently, no vanilla explosion, no particles; the release blast is a silent crater. Absorption up to 80 blocks of radius iterates shell by shell (no more full-cube scans).

- **Gravity**: every entity within 3 radii is dragged in (creative players excluded), crushed at the horizon; the release throws everything outward.

- Image warping (gravitational lensing with chromatic aberration) is available but off by default: `singularityLensing` in the client config.

### Configuration

- `config/cbc_enhanced_shells-client.toml`: quality, render distance, max clouds, screen flash on/off and intensity (for photosensitive players), heat wash, afterimage, camera shake and intensity, blast wind, sounds and volume, lightning, cloud shadow, fallout ash, singularity lensing.

- `config/cbc_enhanced_shells-common.toml`: thermal pulse on the terrain (on/off, radius, leaves, snow, fire chance, columns per tick) and on entities (on/off, radius).

### Dev / testing

- Client command `/cbcesfx <nuke_mk1|nuke_mk2|h_bomb_mini|h_bomb|singularity_mk1..5|clear>` previews an effect where you look, without an explosion.

- `generate_fx_textures.py` regenerates the FX sprite atlas, `generate_nuke_textures.py` the nuclear shell textures.

### Removed

- The `nuke_mushroom_cloud`, `nuke_mushroom_cloud_mk2`, `h_bomb_dome` and `h_bomb_mini_dome` particle types and their client orchestrators.

- The server no longer plays the nuclear detonation sounds itself (the client plays them with the shock-front delay).