Log inGet started
World

Storm Front Kit: Storm Walls, Fog, Lava and Hazards That Chase the Player

README.md

stormFrontKit: storm walls, fog, lava and hazards that chase the player

stormFrontKit gives you a hazard that chases your players through the level: a towering thunderstorm wall with lightning, rain and thunder, a sandstorm, a pixel glitch wall, creeping fog, a collapse wave, rising lava, a flood or a shadow void, picked with one field of one StormFront component. You choose its pacing (steady, speeding up, rubber-banding behind the slowest player, or waiting at checkpoint gates), how it warns players (vignette, edge pulse, siren banner, rumble only), what happens when it catches them (respawn at the last checkpoint still ahead of it, eliminate, damage, slow, fling forward), and how the islands and platforms it passes are swallowed: they fall away, sink, fade to black, shatter into chunks or crumble into dust, taking every prop standing on them along. One shared front for 1-4+ players, exact for late joiners, clean across replays. Volumetric, animated, lit by your sun, with its own sound.

Install: zero zeromind installAsset 72559a0d-2787-4ec3-a040-16201a704d47 (the stormFrontKit package; or search ZeroMind for stormFrontKit / "storm that chases the player"), then open the stormFrontKit.stormGallery scene (it comes with the package, and is the Storm Front Kit world's startup scene) to see every style side by side and try the warning looks in the warning lane. Current version: 1.0.11 (see the Changelog at the end).

Step-by-step workflow: for the whole job (survey the level, plan the chase, build the route and the front, wire catches to checkpoints, play it until it runs clean) start the set-up-a-storm-chase workflow that ships in this package: zero workflow start --name stormFrontKit.set-up-a-storm-chase (args: level, look, duration).

Quick start

-- scenes/<level>.scene/build.luau, inside content()
-- islands to run across (the storm swallows every entity named Island...)
for i = 1, 6 do
    local isle = entity.spawn(string.format("Island%02d", i))
    isle.position = { 0, -1 + i * 0.5, 20 + i * 15 }
    isle.localScale = { 10, 2, 10 }
    isle.component.add("Model", { model = "cube" })
    isle.component.add("BoxCollider", {})
end
-- checkpoint gates: the children of "Gates"; a caught player comes back at the last one still ahead
local gates = entity.spawn("Gates")
entity.spawn("Gate1", { parent = gates }).position = { 0, 1.2, 65 }
entity.spawn("Gate2", { parent = gates }).position = { 0, 2.7, 110 }
-- the storm's route: waypoints in name order, starting BEHIND the players' spawn
local path = entity.spawn("StormPath")
for i, p in { {0,0,-70}, {0,0,0}, {0,3,90}, {0,6,190} } do
    entity.spawn(string.format("wp%02d", i), { parent = path }).position = p
end
local storm = entity.spawn("Storm")
storm.position = { 0, 0, -70 }
storm.component.add("StormFront", { style = "storm", route = "StormPath", bottom = -40,
    pacing = "speedUp", startSpeed = 3, maxSpeed = 12, rampTime = 60,
    warning = "siren", onCatch = "respawn", checkpoints = "Gates", zonePrefix = "Island" })

Start the route well behind your PlayerSpawn (a new world's spawn is at the origin): the front starts at the first waypoint, and a route that starts on the spawn catches everyone the moment the countdown ends.

Press play: the countdown runs, the storm rolls in and keeps getting faster, a DANGER banner and a siren warn you as it closes in, the islands named Island... fall into it as it passes, and anyone it catches comes back at the last gate still ahead of it.

Variants: 31 storm fronts from one component

Every variant below is a real, separately implemented behaviour, picked with one field:

FamilyFieldCountVariants
Stylesstyle8storm, sandstorm, glitch, fog, collapse, lava, flood, void
Pacing modespacing4steady, speedUp, catchUp, checkpoints
Catch outcomesonCatch6respawn, eliminate, damage, slow, pushForward, none
Warning lookswarning5vignette, edgePulse, siren, rumbleOnly, none
Swallow effectsswallowEffect6fall, sink, darken, shatter, dissolve, none
Front modesmode2wall (along a route), rising (from below)
Total31(plus 3 speedUp ramp curves: linear, easeIn, easeOut)

require("stormFrontKit.catalog").variants() answers the same lists, and the test suite checks the total is at least 24.

Styles. storm (wall: anvil overhang, rain curtains, lightning bolts lighting the cloud, thunder delayed by distance), sandstorm (wall: a towering ochre haboob with a rolling nose of dust, swirling towers, sand streaks blowing ahead, visibility dropping, howling wind), glitch (wall: blocky voxels that flicker in and out in time slices, split red/cyan/yellow light, scanlines, chromatic tearing bands, crackling static), fog (wall: low fingers creeping ahead), collapse (wall: dust and falling rock, swallowed zones shatter), lava (rising: glowing crust and smoke, orange light), flood (rising: waves, foam, spray), void (wall: black with a burning violet edge).

Fields

FieldDefaultWhat it does
stylestormone of the 8 styles: look and sound
modeautowall, rising, auto (lava/flood rise)
warningvignettevignette, edgePulse, siren, rumbleOnly, none
route / pointsparent entity whose children are waypoints, comma separated names, or a point list; empty = straight ahead
width height bottom depthstyle's ownsize of the front (m); bottom negative reaches below the route
density rain seed1, 1, 1thickness, storm rain / sandstorm sand streaks, variation
pacingsteadysteady, speedUp, catchUp, checkpoints
speed acceleration maxSpeed minSpeed6, 0, 18, 0.5m/s; never faster than maxSpeed
startSpeed rampTime rampCurve3, 60, linearspeedUp: from startSpeed to maxSpeed over rampTime s; linear, easeIn, easeOut
catchDistance catchGain30, 0.35catchUp: gap held behind the slowest living player
checkpoints gateOffset holdTime"", 20, 25gate entities; stop short by offset; wait at most holdTime s (0 = forever)
autoStart startDelay startProgress looptrue, 5, 0, falsecountdown and start point
arriveBy0a deadline: the front reaches the route end exactly this many seconds after it starts moving, never later and never earlier, whatever the pacing does in between (not with loop or checkpoints). Set a game clock to startDelay + arriveBy and 0:00 is the moment the end is swallowed
onCatchrespawnrespawn, eliminate, damage, slow, pushForward, none
catchMargin graceTime0, 2.5catch early/late (m); immunity after a respawn/push (s)
damagePerSecond slowFactor pushDistance penaltyTime25, 0.4, 25, 1.5outcome tuning
respawnAhead respawnPoint25, ""the route fallback distance; a fixed respawn entity (used while it is safe)
useTrapline traplineLoseLifetrue, falsewith Trapline handed in: its checkpoint when safe, or lose a life
warningDistance60warning event, warning look, heartbeat/siren and sound swell start here
zones zonePrefix swallowEffect zoneLead"", "", auto, 0what it swallows and how (see Swallowed zones)
carryStanding carryHeighttrue, 25a swallowed zone takes what stands on it, up to carryHeight m above its top
feedback sound volumetrue, true, 1local danger feedback and audio
previewInEdit previewProgresstrue, 0draw and animate it while authoring

Swallowed zones: five effects, and everything standing on them goes too

Name the zones the front swallows with zones (comma separated names, or one parent whose children are the zones) or zonePrefix (every entity whose name starts with it). When the front passes a zone's far edge (plus zoneLead metres), the zone plays its swallowEffect:

swallowEffectWhat you see
falldarkens, shakes for a second, then drops away into the abyss, tumbling
sinkdarkens and slowly sinks out of sight into the clouds, the lava or the water, rocking gently
darkenfades to black, consumed, and stays where it is as a dead husk
shattertrembles, then bursts into chunks cut from its own bounds (turf on top, rock below) that fly apart and fall; the props on it are flung off
dissolvecrumbles from the edge inward into dust while it shrinks away; each prop crumbles when the edge reaches it
nonenothing moves; only the swallowed event fires
auto (default)the style's own: storm fall, sandstorm dissolve, glitch and void darken, fog, lava and flood sink, collapse shatter

One zone can have its own effect with the attribute stormFrontKit.swallow (e.g. "shatter"; crumble, break, fade and drop are understood as dissolve, shatter, darken, fall).

What a zone carries. Everything standing on it goes with it, whatever its place in the hierarchy:

  • every descendant of the zone entity;
  • with carryStanding = true (the default), every other entity whose position lies inside the zone's footprint (its bounds in x and z) and between the zone's middle and carryHeight (default 25) metres above its top: the arch, trees, bridge posts, banners, crates and fence posts you placed on an island from anywhere in the scene. Players and their bodies, runners, cameras, spawns, storm fronts, other zones, the sun and ambient light, and anything wider than the zone (a ground plane, a group root) are never carried;
  • any entity marked with the attribute stormFrontKit.zone = "<zone name>", wherever it stands (a bridge reaching off the island, a lantern hanging under its rim);
  • an entity with the attribute stormFrontKit.noCarry = true is left behind.

Set carryStanding = false to carry only descendants and marked entities.

Every peer sees the same. Each peer works the effect out from the shared front progress and the time since the zone was passed, with every random choice (spin, chunk sizes and paths, dust) seeded from the zone's name, so all players see the same island break the same way at the same moment. A late joiner sees a zone passed long ago already gone (or blackened), and one passed a moment ago mid-effect at the same frame as everyone else. A reset or loop puts every zone and every carried prop back. In the gallery each lane's second island carries props that are not its children, and the five effects are on the storm (fall), fog (sink), void (darken), collapse (shatter) and sandstorm (dissolve) lanes.

Respawn: always ahead of the front

onCatch = "respawn" puts a caught player back at their last checkpoint that is still AHEAD of the front, never on a zone it already swallowed. In order: respawnPoint (when safe), their Trapline checkpoint (Trapline handed in), the last kit gate they reached, the nearest gate ahead of the front, then a point respawnAhead m ahead on the route. Safe means the front cannot reach it before graceTime runs out at its current speed. With traplineLoseLife, a Trapline respawn that lands behind the front is moved to the safe point. Games with their own rescue read the same answer: front:safePointAhead(player?), require("stormFrontKit.api").safePointAhead(player?), and the caught event's safePoint {x,y,z} and safeKind (respawnPoint, trapline, gate, gateAhead, route).

Events and API

Events on the component (front.events.caught:connect(fn)) or for every front at once (require("stormFrontKit.api").on("caught", function(front, e) end), which returns its unsubscribe function): caught {player, outcome, distance, safePoint, safeKind}, warning {player, distance}, swallowed {zone, index, progress}, waiting {gate}, released {gate, reason}, started, finished, looped, eliminated {player}, revived {player}, damaged {player, amount, health}.

Methods (any peer may call; control calls route to the owner on the stormFrontKit.cmd channel): start(delay?), pause(), resume(), reset(andStart?), setProgress(m), releaseGate(); reads: progress(), frontPosition(), distanceAhead(pos), isBehindFront(pos), localDistance(), phase(), secondsToStart(), secondsToEnd() (exact with arriveBy, the same on every peer), speedNow(), gate(), length(), snapshot(), safePointAhead(player?); revive(). stormFrontKit.api: get(name), all(), nearest(), localDistance(), localDanger() (0-1 for a HUD), safePointAhead(player?), isOut(player), revive(), on(name, fn, owner?), integrate({ trapline, secondWind }), CMD_CHANNEL.

Multiplayer and replays

One front for everyone. The scene entity replicates; its owner (the first peer in play) runs the pacing and publishes a motion anchor {p0, t0, v, cap} on multiplayer.sessionTime(). Every peer extrapolates the same front from it, so a late joiner sees it exactly where it is, and if the owner leaves the next owner rebuilds from the anchor and carries on. Lightning strikes are picked from the shared clock. Each player's catch is decided on their own peer; an eliminated player's body carries a synced StormRunner mark (out) so pacing ignores them.

Play, stop, play again runs clean: the command channel listener is owned by the api module and goes inert when its run ends (multiplayer.on has no unsubscribe), each front's command handler is removed in onDestroy and ignores commands once its front is destroyed, listeners tied to a front leave with it, the warning banner and post effect are removed with the last front and on module unload, and scene code is shown unsubscribing in onUnload.

Integrations (optional)

stormFrontKit needs nothing else. With Trapline or SecondWind in your game, hand them in once: require("stormFrontKit.api").integrate({ trapline = require("Trapline.api"), secondWind = require("SecondWind.api") }).

Contents

StormFront (the component), StormRunner (per-player mark), api, catalog, route, pacing, visuals, swallow, feedback modules; chase_volume, chase_surface, chase_danger shaders and chase_noise; generated sounds in audio/ (incl. sand_howl, glitch_static, warning_siren); the stormGallery scene and its gallery/ parts; guides How to make a storm or hazard wall chase the player (guides/how-to-make-a-storm-or-hazard-wall-chase-the-player.guide) and Example: build a small outrun-the-storm level (guides/example-build-a-small-outrun-the-storm-level.guide); tests/stormFrontKit.testSuite.

Changelog

  • 1.0.11: the package description says what stormFrontKit gives you and how to install it. No code change.

  • 1.0.10: both guides say which version they describe ("Part of stormFrontKit 1.0.10"), like this README. M.VERSION and the catalog's VERSION read 1.0.10. Text and version numbers only: every field, style, event and network message works exactly as in 1.0.9.

  • 1.0.9: arriveBy, a deadline for the front, and secondsToEnd(). With arriveBy = N the front reaches the end of its route exactly N seconds after it starts moving under steady, speedUp or catchUp: it speeds up when it would be late and holds back (never closer to the end than minSpeed covers in the time left) when it would be early, so a race clock and the storm tell the same story. Found in a two-player race where catchUp at minSpeed reached the end in under 4 minutes while the game clock said 10. Two new tests: every pacing with runners racing ahead, stuck or absent finishes within 0.05 s of the deadline without a jump; arriveBy is ignored with loop and checkpoints. Without arriveBy nothing changes.

  • 1.0.8: a race with the storm logs no errors. A swallowed island darkened, moved and restored every prop that stood on it each frame, and a prop removed mid-show (a taken pickup, a game's own cleanup) made each of those writes log "was despawned" (one race logged 490 and 1,259 in a burst). Every write now checks the prop is still there; a new test despawns props partway through all five effects and expects no error. New: the set-up-a-storm-chase workflow for the whole job in stages.

  • 1.0.7: the example guide's "Play it" step says to turn around first: the player starts facing back toward the storm, so pressing forward ran into it. Checked by installing into a brand-new world and following the guide: the countdown, the rolling storm, the siren, catches with respawn ahead (route, then gateAhead) and the finish all work. api and catalog report 1.0.7. Behaviour is unchanged.

  • 1.0.6: both guides open with a "Part of stormFrontKit" line naming the ZeroMind package and how to install it, and their descriptions name the kit. api and catalog report 1.0.6. Behaviour is unchanged.

  • 1.0.5: the README Quick start works in a brand-new world. Its route started at the origin, where a new world's player spawns, so the player was caught the moment the countdown ended; and it named Island zones and Gates checkpoints without making any, so nothing was swallowed. It now starts the route 70 m behind the spawn and makes six Island zones and two gates. Checked by installing into a brand-new empty world and following the README. api and catalog report 1.0.5. Behaviour is unchanged.

  • 1.0.4: the stormGallery scene spawns a player again (its player intent was none, so after a fresh install nobody appeared and the warning lane could not be tried); api and catalog report 1.0.4. Behaviour is otherwise unchanged.

  • 1.0.3: guides renamed after what you want to do (how-to-make-a-storm-or-hazard-wall-chase-the-player, example-build-a-small-outrun-the-storm-level; the old kit-named guides are gone); the example now creates its scene from the player template, because a scene made from empty spawns no player and the race could not be played; the world's storm_run and flood_race scenes spawn players; the predecessor package's name is gone from the docs; api and catalog report 1.0.3. Behaviour is unchanged from 1.0.2.

  • 1.0.2: five clearly different swallow effects (fall, sink, darken, plus the new shatter and dissolve), each one field; a swallowed zone now carries everything standing on it from anywhere in the hierarchy (carryStanding, carryHeight, the stormFrontKit.zone and stormFrontKit.noCarry attributes) as well as its own children; per-zone effect attribute stormFrontKit.swallow; effects seeded from the zone name and timed from the shared progress so every peer and every late joiner sees the same frame; collapse defaults to shatter and sandstorm to dissolve; the gallery puts props on an island in every lane; loading the gallery no longer rewrites its scene (StormGallery no longer writes lights and labels in edit mode, and the build bakes the same lighting); guides renamed; store description leads with what the kit does.

  • 1.0.1: the README install line names the stormFrontKit package guid.

  • 1.0.0: first release: eight styles (storm, sandstorm, glitch, fog, collapse, lava, flood, void), four pacings including speedUp, the warning field with five looks, respawn that always lands ahead of the front (Trapline checkpoints and kit gates, safePointAhead, caught.safePoint), clean replays (no stale command listener or event listeners across play sessions), gallery with eight lanes, a warning lane and a variant board.