# 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
```lua
-- 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:
| Family | Field | Count | Variants |
|---|---|---|---|
| Styles | `style` | 8 | `storm`, `sandstorm`, `glitch`, `fog`, `collapse`, `lava`, `flood`, `void` |
| Pacing modes | `pacing` | 4 | `steady`, `speedUp`, `catchUp`, `checkpoints` |
| Catch outcomes | `onCatch` | 6 | `respawn`, `eliminate`, `damage`, `slow`, `pushForward`, `none` |
| Warning looks | `warning` | 5 | `vignette`, `edgePulse`, `siren`, `rumbleOnly`, `none` |
| Swallow effects | `swallowEffect` | 6 | `fall`, `sink`, `darken`, `shatter`, `dissolve`, `none` |
| Front modes | `mode` | 2 | `wall` (along a route), `rising` (from below) |
| **Total** | | **31** | (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
| Field | Default | What it does |
|---|---|---|
| `style` | `storm` | one of the 8 styles: look and sound |
| `mode` | `auto` | `wall`, `rising`, `auto` (lava/flood rise) |
| `warning` | `vignette` | `vignette`, `edgePulse`, `siren`, `rumbleOnly`, `none` |
| `route` / `points` | | parent entity whose children are waypoints, comma separated names, or a point list; empty = straight ahead |
| `width` `height` `bottom` `depth` | style's own | size of the front (m); `bottom` negative reaches below the route |
| `density` `rain` `seed` | 1, 1, 1 | thickness, storm rain / sandstorm sand streaks, variation |
| `pacing` | `steady` | `steady`, `speedUp`, `catchUp`, `checkpoints` |
| `speed` `acceleration` `maxSpeed` `minSpeed` | 6, 0, 18, 0.5 | m/s; never faster than `maxSpeed` |
| `startSpeed` `rampTime` `rampCurve` | 3, 60, `linear` | speedUp: from startSpeed to maxSpeed over rampTime s; `linear`, `easeIn`, `easeOut` |
| `catchDistance` `catchGain` | 30, 0.35 | catchUp: gap held behind the slowest living player |
| `checkpoints` `gateOffset` `holdTime` | "", 20, 25 | gate entities; stop short by offset; wait at most holdTime s (0 = forever) |
| `autoStart` `startDelay` `startProgress` `loop` | true, 5, 0, false | countdown and start point |
| `arriveBy` | 0 | a 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 |
| `onCatch` | `respawn` | `respawn`, `eliminate`, `damage`, `slow`, `pushForward`, `none` |
| `catchMargin` `graceTime` | 0, 2.5 | catch early/late (m); immunity after a respawn/push (s) |
| `damagePerSecond` `slowFactor` `pushDistance` `penaltyTime` | 25, 0.4, 25, 1.5 | outcome tuning |
| `respawnAhead` `respawnPoint` | 25, "" | the route fallback distance; a fixed respawn entity (used while it is safe) |
| `useTrapline` `traplineLoseLife` | true, false | with Trapline handed in: its checkpoint when safe, or lose a life |
| `warningDistance` | 60 | warning event, warning look, heartbeat/siren and sound swell start here |
| `zones` `zonePrefix` `swallowEffect` `zoneLead` | "", "", `auto`, 0 | what it swallows and how (see Swallowed zones) |
| `carryStanding` `carryHeight` | true, 25 | a swallowed zone takes what stands on it, up to carryHeight m above its top |
| `feedback` `sound` `volume` | true, true, 1 | local danger feedback and audio |
| `previewInEdit` `previewProgress` | true, 0 | draw 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`:
| `swallowEffect` | What you see |
|---|---|
| `fall` | darkens, shakes for a second, then drops away into the abyss, tumbling |
| `sink` | darkens and slowly sinks out of sight into the clouds, the lava or the water, rocking gently |
| `darken` | fades to black, consumed, and stays where it is as a dead husk |
| `shatter` | trembles, 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 |
| `dissolve` | crumbles from the edge inward into dust while it shrinks away; each prop crumbles when the edge reaches it |
| `none` | nothing 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.