frostHazards
Winter and mountain hazards for platformers and obstacle courses: rolling snowballs, falling icicles, wind gusts, steam vents, avalanches, rockfall, thin ice and frost spikes. One `Hazard` component, one call: `FH.spawn(kind, look, opts)`.**
frostHazards 1.1.0
Winter and mountain hazards for platformers and obstacle courses: rolling snowballs, falling icicles, wind gusts, steam vents, avalanches, rockfall, thin ice and frost spikes. One Hazard component, one call: FH.spawn(kind, look, opts).
- 8 kinds, 29 looks. Every kind has a
storybooktoon look (snow white with lavender shadows, cold teal ice, warm amber) and two or three more of its own. Changelookand it turns into another one; changekindand it becomes another hazard. - Deadly ones kill through Trapline: the same death, kill feed ("Kai was killed by Falling icicles") and respawn at your last checkpoint as every other Trapline trap.
- Wind pushes and vents lift through platformsKit's rider, on the engine's built-in
CharacterController. A wind also drives the engine's ownWindfield, so physics bodies, cloth and particles feel the same gust. - Multiplayer-safe. Everything moves on platformsKit's shared host clock, so every player sees the same snowball in the same place and the danger matches what they see. Each machine only tests and moves its own player. Thin ice breaks for everyone through platformsKit's shared events, late joiners included.
- Telegraphed. Icicles shake and cast a growing shadow before they fall, rocks show a shadow where they will land, avalanches rumble at the top of their lane, vents sputter, spikes peek, wind streaks speed up before the gust.
Install
One call:
zeromind_install guid=<frostHazards package guid> (or search ZeroMind for "frostHazards" or "snowball icicle wind hazards" and install frostHazards.package).
It brings Trapline (lives, checkpoints, the kill) and platformsKit (shared clock, shared events, the rider) with the kits they are built on, under /source/deps/. A world that already has them (platformer3dKit brings both) keeps its copies.
Your first hazard
Paste at the end of your scene's content() in build.luau:
local FH = require("frostHazards.api")
FH.spawn("snowball", "storybook", { position = { 0, 0, 8 }, length = 16 })
Press Play: a lumpy snowball forms 8 m ahead, rolls 16 m along +Z, bursts into snow and rolls again every 5 seconds. Stand in its lane and you lose a life.
First example: a winter run
local FH = require("frostHazards.api")
local TL = require("Trapline.api")
TL.attach(body) -- your player template's body, so it has lives
FH.spawn("snowball", "twigs", { position = { 0, 0, 6 }, yaw = 90, length = 12, count = 2 }) -- across the path
FH.spawn("icicle", "cracked", { position = { 0, 0, 14 }, sizeY = 4.5 }) -- hang it under a ledge 4.5 m up
FH.spawn("wind", "flurry", { position = { 0, 0, 22 }, yaw = 90, size = { 4, 4, 10 }, power = 8 }) -- blows to +X across the path
FH.spawn("steamVent", "storybook", { position = { 0, 0, 30 }, sizeY = 6 }) -- lifts you up 6 m
FH.spawn("rockfall", "storybook", { position = { 0, 0, 38 } })
FH.spawn("frostSpikes", "crystal", { position = { 0, 0, 46 } })
Kinds
Each hazard stands on the ground at its entity, +Z is its forward (where it rolls or blows). Turn it with yaw.
| kind | what it does | size (x, y, z) | defaults |
|---|---|---|---|
snowball | Forms at the top of a lane, rolls length m along +Z (dropping drop m), bursts, rolls again. count balls take turns. Deadly. | ball diameter = sizeY | 1.8 m ball, 20 m lane, every 5 s |
icicle | Hangs from a snowy ledge sizeY m up, shakes and shadows the ground, drops, shatters, grows back. Deadly while falling. | cluster width, hang height, depth | 2.4 x 5 x 1.2 m, every 4 s |
wind | A box of air gusting along +Z: calm, warning streaks, then a gust of power m/s that pushes players. Not deadly: it blows you off ledges. cycle = 0 blows all the time. | the box | 4 x 4 x 10 m, 7 m/s, every 5 s |
steamVent | Idles, rumbles, blows a column sizeY m high. mode = "lift" carries players up (an updraft, power m/s); mode = "burst" scalds. cycle = 0 blows all the time. | footprint, column height | 1.6 x 7 x 1.6 m, 9 m/s, every 4 s |
avalanche | A wall of snow rumbles, then sweeps length m along +Z (dropping drop m). Deadly at its front. | wall width, height, depth | 8 x 2.4 x 3 m, 26 m lane, every 9 s |
rockfall | count rocks fall from sizeY m onto the patch, each with a landing shadow first. Deadly when it lands on you. | patch width, fall height, depth | 6 x 12 x 6 m, 3 rocks, every 3 s |
thinIce | A walkable ice slab. Step on it: it cracks, breaks wait s later (for everyone) and you drop, then it freezes back after respawn s. Put a gap, water or a KillZone under it. | slab | 3 x 0.3 x 3 m, 0.9 s, back after 4 s |
frostSpikes | Ice spikes shoot out of a frost patch: hidden, a warning peek, up and deadly, back down. | patch, spike height | 2.4 x 1.2 x 2.4 m, every 3 s |
Looks
| kind | storybook | more looks |
|---|---|---|
snowball | Plain Snowball | twigs Snowball with Pine Twigs, iceBoulder Icy Blue Boulder, muddy Muddy Thaw Snowball |
icicle | Clear Blue Icicles | frosted Frosted White Icicles, cracked Cracked Icicles (Watch Out!) with a warning sign, crystal Crystal Cave Icicles (glowing) |
wind | Curling White Ribbons | leaves Leaf-Carrying Gust, flurry Snow Flurry Gust, mist Mountain Mist |
steamVent | Steam from Ice Crack | geyser Stone Geyser, brass Brass Steam Pipe, hotspring Hot Spring Bubbler |
avalanche | Storybook Snow Slide | powder Powder Cloud, slush Slush Flow |
rockfall | Snow-Capped Boulders | slate Slate Shards, ice Ice Chunks |
thinIce | Thin Teal Ice | clear Clear Black Ice, crust Snow Crust |
frostSpikes | Frost Spikes | crystal Crystal Spikes, frosted Rime Spikes |
Looks are built from primitive shapes (Trapline's part helpers), so they take a world's toon / ink style stack and cost no texture memory.
Settings (frostHazards.Hazard)
| field | default | what it does |
|---|---|---|
kind | snowball | What it does (the 8 above). |
look | storybook | What it looks like. A look the kind does not have falls back to storybook. |
sizeX/Y/Z | 0 | Size in metres; 0 takes the kind's default (see Kinds for what each axis means). |
cycle | -1 | Seconds per loop; -1 is the kind's own. 0 = always on for wind, vents and spikes. |
offset | 0 | Seconds to shift it along its loop, to stagger a row of the same hazard. |
length, drop | 0 | Lane length along +Z and how far it drops, for snowballs and avalanches rolling downhill. |
count | 0 | Snowballs per lane, or rocks per rockfall cycle. |
power | 0 | Wind speed or vent lift speed in m/s. |
mode | lift | Steam vents: lift or burst. |
wait, respawn | 0 | Thin ice: seconds to break after the first step (0.9) and to freeze back (4). |
damage | 0 | 0: touching it costs a life. Above 0: that much SecondWind damage per hit instead. |
label | none | Its name in the kill feed. |
active | true | Switch it off. |
sound | true | Play its sounds (spatial, heard by every player near it). |
Methods: hazard:isDeadly(body, t?), hazard:pushOn(body, t?), hazard:capsuleOf(body), and for thin ice hazard:iceState(t?) and hazard:touch().
frostHazards.api
local FH = require("frostHazards.api")
| call | what it does |
|---|---|
FH.spawn(kind, look?, opts?) | Place a hazard; returns the entity. opts: position, rotation, yaw (deg), name, parent, synced, temporary, size = {x,y,z}, and any field above. Refuses an unknown kind or look by name. |
FH.get(entity) | The Hazard component on it. |
FH.setLook(entity, look), FH.setKind(entity, kind) | Switch a placed hazard; it rebuilds at once. |
FH.looks(kind), FH.list(filter?) | Browse: rows { kind, look, name, label, description, family, deadly, tags }, filtered by a kind, a look, a tag or a table. |
FH.now() | The shared clock every hazard runs on. |
Modules: frostHazards.catalog (the data), frostHazards.kinds (every kind's build, animate, danger and push, and the pure timing functions snowballState, icicleState, windState, ventState, avalancheState, rockState, thinIceState, spikeState). The contract for a kind of your own is written at the top of frostHazards.kinds.
Multiplayer
- Same place, same moment. Every hazard's pose and danger are functions of platformsKit's shared host clock (
FH.now()), so two players see the same snowball in the same place. - Your own player only. Each machine tests only its own player against danger, and pushes or lifts only its own player, through platformsKit's rider on the built-in
CharacterController. A death goes through Trapline and SecondWind, which tell everyone. - Thin ice is shared. The first step on it is sent to every machine as a platformsKit net event stamped with the shared time, so it breaks for everyone together; a machine that joins late asks the host for the events it missed.
Sound
Every kind makes its own sound, played in 3D at the right spot and heard by every player near it: a snowball rolls (a loop that follows the ball) and bursts at the bottom; icicles crack while they shake and shatter on the ground; a gust swells as its warning streaks start (always-on wind loops); a vent rumbles before it blows and hisses as it bursts; an avalanche roars as it starts to rumble; rocks rumble on the warning and clatter as they land; thin ice cracks under the first step and breaks with a splash; frost spikes ring as they shoot up. Looks shift the pitch (an ice boulder rolls lower, crystal icicles ring higher). Nothing is sent over the net: each machine works the moments out from the shared clock.
Sounds play on the engine's sfx mixer channel. Tune them with require("frostHazards.sounds"): setVolume(v), setChannel(ch), setEnabled(on), or one cue's CUES[kind][cue].volume. A hazard's sound field (default on) silences that one hazard.
Guides
- How to add snowballs, icicles, wind and steam vents to my platformer: placing each kind, turning lanes and gusts, telegraphing, fair checkpoints, thin ice over water, swapping looks, and multiplayer.
Tests
zero tests run frostHazards runs 25 tests: the catalog (8 kinds, each with storybook and at least three looks, unique names, filters, copies), every kind x look building and animating a whole cycle, timing as a pure function of the shared time, danger only where and when each hazard looks deadly (snowball on its lane, icicles only while falling, avalanche at its front, rocks never during their warning, spikes only when up), wind pushing only inside its box while it gusts, lift vs burst vents, thin ice cracking, breaking and freezing back from shared touches, switching kind and look, spawn options, and one version across package.yaml, this README and FH.VERSION.
Showcase
The world this package comes from opens on a snowfield with every kind in every look in rows, labelled, with Trapline lives: walk in and feel each one.
Known limits
- Hazards do not block movement. Snowballs, avalanches and rocks have no colliders: they take a life, they don't shove you. Thin ice is the one solid kind.
- Wind is a push, not physics. On players it is a sideways carry through platformsKit's rider (stopped by walls); on physics bodies it is the engine's
Windfield (world-aligned box). - Lanes are straight. A snowball or avalanche lane runs straight along +Z with an even drop; chain two hazards for a bend.
What's new in 1.1.0
- Every hazard makes a sound. Twelve generated sound effects (snowball roll and burst, icicle crack and shatter, wind gust, vent rumble and burst, avalanche roar, rock clatter, thin ice crack and break, spike shoot), played spatially by the new
frostHazards.soundsmodule, with per-look pitch and asoundfield per hazard. Added for Lantern Peak.
What's new in 1.0.1
- Steam vents carry you higher. A vent now blows for more than half of its cycle (it used to blow for about a third), so a lift vent carries a player the whole height of a tall column (checked: 10.5 m with
power = 14, cycle = 4) instead of letting go just short of the ledge. Found while building Lantern Peak's Storm Ridge.
Scoped to this part · feeds back into the world's score.