Kzeroko KTM2

Terrain impacts

Ground fractures, lifted plates, tumbling fragments and radius-scaled spell shake.

Updated Nov 8, 2026 7 min read

TerrainImpactAPI supplies server-authored terrain contacts and client-rendered ground destruction effects. A major impact combines tilted surface plates, crack strips and airborne fragments; permanent block removal is separately controlled by the server.

What it does

The facade lives under net.kzeroko.isekaiexpansion.api. emit accepts a server world, an Area, a Profile and a nullable caster. shake uses the explosion radius to scale both viewing distance and strength through ImpactShakeAPI.

Fallen Down sends the SOUL_WAVE profile from each advancing damage shell. Its radius is 24 blocks and its 10 shells advance over 25 ticks (1.25 seconds). Astral Eschaton sends CATACLYSM on the delayed detonation and AFTERSHOCK on subsequent surges; barrier impacts suppress the terrain effect. Both spells use radius-scaled shake. Ordinary projectile splashes and Celestial Dew use IMPACT.

ProfileSurface samplesFragment sizeImpulsePlate liftLifetimeWave delayCan break blocks
IMPACT240.45 blocks×0.70 blocks42 ticks (2.1 seconds)0 ticks (0 seconds)false
CATACLYSM960.85 blocks×1.351.2 blocks90 ticks (4.5 seconds)10 ticks (0.5 seconds)true
SOUL_WAVE400.65 blocks×1.10.95 blocks80 ticks (4 seconds)0 ticks (0 seconds)true
AFTERSHOCK320.5 blocks×0.80.45 blocks48 ticks (2.4 seconds)5 ticks (0.25 seconds)false

These are profile inputs, not exact dimensions for every piece. Fragments vary below their configured size; plate widths range from 0.85–1.5 blocks. Plates rise, remain tilted and settle into the surface. They have no collision and never place blocks. Fragments use swept voxel collision, bounce, friction and water drag.

The shared rigid-body solver lives in internal.physics.block. Geomancy uses the same vertical displacement for the client’s ground reveal and the server’s Earthfang strike. The mesh keeps its dimensions as its buried faces cross the ground line. Earthfang reaches its full height in 3–6 ticks, depending on the weave.

Runtime model

internal.terrainimpact.TerrainImpact samples only loaded columns. It searches exposed contacts within the damage shape, bounded to 3 blocks above and 16 blocks below the origin. Fluids, excluded materials, block entities, unbreakable blocks and non-model blocks stop that column. Sampling finishes before optional block removal, so one impact never excavates successive layers.

The isekaiexpansion:terrain_impact packet carries the dimension, origin, radius, deterministic seed, visual profile and material contacts. Clients resolve each block model’s face sprite and tint index. They simulate and render the pieces locally after entities, skip Iris shadow passes and clear state on disconnect, world replacement and resource reload. Particle quality reduces admission.

Earthfang, Wall of Sighs and Gaia’s Refuge can release a rigid piece when a temporary block disappears. As the formation nears expiry, the client reserves available slots for falling pieces. Excess cells fade in place. A spire section keeps its voxel outline. A shelter block keeps its baked model, orientation, and face textures. The Ochre Colossus releases its textured pieces from their animated poses. Pieces tumble against terrain, can settle on earlier rubble, and fall again when their support disappears. These effects share the terrain-impact budget. The client captures each formation cell’s material model once and reuses its geometry until its material changes or resources reload. Fragments, plates and cracks fade along the same curve.

BudgetLimit
Packet contacts96
World probes per tick16384
World contacts per tick384
World removed blocks per tick32
Client admissions per tick192 pieces
Active pieces at default settings, all / decreased / minimal384 / 256 / 96
Client sample stride: all / decreased / minimal1 / 2 / 4
Default client draw distance64 blocks

The local Block debris settings apply to geomancy and terrain impacts. blockDebris.enabled defaults to true. blockDebris.fadeTicks defaults to 22 ticks (4–80), blockDebris.maxPieces to 384 (16–768) and blockDebris.viewingDistance to 64 blocks (8–80). Particle quality caps the active count at 768, 256 or 96 respectively.

Budgets are shared by simultaneous impacts. Excess samples or pieces are dropped; they do not create server entities, save data or queued backlogs. The probe budget limits sampling at every supported radius.

Contracts

Call the facade on the server thread with a live world. Area requires finite coordinates and horizontal bounds within 128 blocks of its origin. sphere and ring accept a positive outer radius up to 128 blocks; ring vertical extents are non-negative. A custom area supplies its exact point predicate. Vertical bounds also constrain contacts.

Profile constructor inputs are required Java arguments. Invalid or non-finite inputs throw IllegalArgumentException.

FieldTypeDefaultWhat it does
samplesintegerrequiredMaximum surface contacts; 1–96.
fragmentSizenumberrequiredMaximum fragment edge length; 0.1–1.5 blocks.
impulsenumberrequiredVelocity multiplier; greater than 0 and at most 3.
plateLiftnumberrequiredNominal plate displacement; 0–3 blocks. Zero disables plates.
lifetimeTicksintegerrequiredNominal lifetime; 20–120 ticks (1–6 seconds). Individual pieces shorten it.
waveTicksintegerrequiredRadial start delay; 0–30 ticks (0–1.5 seconds).
breaksTerrainbooleanrequiredPermits permanent removal only when the remaining server checks pass.
spellTerrainDestructionbooleanfalseServer-synchronised option in config/isekaiexpansion.json, under the spell GUI category. Enables permanent removal for eligible profiles and casters.

Permanent removal requires a living caster in the same world. Players must be allowed to modify the world and pass spawn protection and the world border; non-player casters require mobGriefing. Existing protected-area checks run through actor-attributed breakBlock. Removed blocks drop no items. Their hardness must be at most 5 and the block must belong to the breakable tag; block entities and excluded materials remain ineligible. A null caster always produces visuals only.

The three block tags live in data/isekaiexpansion/tags/blocks/:

TagRole
isekaiexpansion:terrain_impact_materialsMaterials eligible for visual sampling.
isekaiexpansion:terrain_impact_excludedMaterials rejected even when included above.
isekaiexpansion:terrain_impact_breakableAdditional restriction for permanent removal; bundled values cover natural terrain.

Shake reach is min(96, 2 × radius + 12) blocks. Source strength is multiplied by min(2, sqrt(radius / 6)), then ImpactShakeAPI applies distance attenuation and its strength cap. Particle admission does not suppress shake.

Extending it

Use a preset for a complete impact. Pass the caster only when permanent removal is allowed for that call:

var area = TerrainImpactAPI.Area.sphere(point, radius);
TerrainImpactAPI.emit(world, area, TerrainImpactAPI.CATACLYSM, caster);
TerrainImpactAPI.shake(world, point, radius,
        ImpactShakeAPI.Shake.impact(12, 24));

The internal AoECommonUtil builders accept .terrainImpact(profile, caster) so terrain contacts use the exact damage shape and scheduled pulse. They select damage targets and test cover before optional block removal. Scheduled areas and sweeps stop when the captured world is no longer the server’s active world instance. Call shake once for a whole expanding ring, or per distinct detonation, rather than once per sampled contact.

Verifying

Run compileJava, then check both spells on stone, grass, stairs, slopes and cave floors. Check an impact above the surface, unloaded chunk edges, overlapping casts, all particle settings, dimension changes and resource reloads. Confirm grass top tint leaves untinted dirt faces unchanged. Check foreground occlusion and the intended Iris shader pack in game.

With destruction disabled, compare the terrain before and after the effect. With it enabled, verify natural surface removal, no drops, protected-area rejection, block-entity exclusion, player build restrictions and mobGriefing for NPC casters. Confirm the advancing Fallen Down shell and delayed Astral Eschaton detonation match their damage timing. These are acceptance checks, not recorded visual test results.

See spell integration for delivery contracts and camera API for the underlying camera controls.