# fx_noise
Procedural noise for effect shaders, as WGSL other shaders include with `#include "fx_noise"`:
integer hashes, value and gradient noise in 2D and 3D, fBm and ridged fBm over them, curl noise, and
worley (cellular) noise that returns the distance to the nearest feature point and that cell's id.
The functions are pure math over their arguments, so a material's fragment shader and a compute
shader can both include it and read the same field. Every generator takes an explicit `seed`, so one
shader draws several uncorrelated fields from the same coordinates. The hashes mix integers, so a
value is the same bit pattern wherever it runs; the float entry points hash a float's bit pattern,
with `0.0` and `-0.0` folded together.
```wgsl
#include "fx_noise"
```
| Function | Returns |
|---|---|
| `fx_hash11(x)`, `fx_hash21(p)`, `fx_hash31(p)` | a stable value in [0, 1) for a number or point |
| `fx_value_noise2(p, seed)`, `fx_value_noise3(p, seed)` | smooth value noise in [0, 1) |
| `fx_gradient_noise2(p, seed)`, `fx_gradient_noise3(p, seed)` | gradient (Perlin-style) noise in [-1, 1], exactly 0 at every integer point |
| `fx_fbm2(p, octaves, lacunarity, gain, seed)`, `fx_fbm3(...)` | fractal sum of gradient noise in [-1, 1]: clouds, smoke, rock |
| `fx_ridged_fbm3(p, octaves, lacunarity, gain, seed)` | ridged fractal noise in [0, 1]: cracks, crags, veins |
| `fx_curl_noise3(p, seed)` | a divergence-free flow vector: swirling smoke and dust |
| `fx_worley2(p, seed)`, `fx_worley3(p, seed)` | `{ dist, cell, id }` of the nearest feature point: foam cells, stone, sparkle |
| `fx_worley_fbm2(p, octaves, lacunarity, gain, seed)` | fractal cellular noise in [0, 1] |
## Arguments
- `p` is an `f32`, `vec2f` or `vec3f` coordinate, matching the function's dimension.
- `seed` is a `u32`.
- `octaves` is a `u32`, clamped to 1 through `FX_FBM_MAX_OCTAVES` (12). Each octave multiplies the
frequency by `lacunarity` and the amplitude by `abs(gain)`, and the fBm functions divide by the
summed amplitudes, which keeps the stated range for any gain. Octave `i` uses seed `seed + i *
1013`.
## Building blocks
The module also exports the pieces the generators are built from:
| Function or item | What it is |
|---|---|
| `fx_hash_u32(x)`, `fx_hash_u2(x, y)`, `fx_hash_u3(x, y, z)` | Integer avalanche hashes of one, two or three `u32` words, returning a `u32`. |
| `fx_unorm(h)`, `fx_snorm(h)` | A hashed `u32` as an `f32` in [0, 1) or [-1, 1), from its top 24 bits. |
| `fx_bits(x)` | The `u32` bits of an `f32`, with negative zero folded onto positive zero. |
| `fx_hash22(p)`, `fx_hash33(p)` | Two or three decorrelated values in [0, 1) for a 2D or 3D point. |
| `fx_lattice_u2(cell, seed)`, `fx_lattice_u3(cell, seed)` | The hashed `u32` a seeded integer lattice corner (`vec2i` or `vec3i`) carries. |
| `fx_lattice21(cell, seed)`, `fx_lattice31(cell, seed)` | That corner's value in [0, 1); `fx_value_noise2` at an integer point equals `fx_lattice21` of that point. |
| `fx_fade(t)` | The quintic fade `t^3 * (t * (6t - 15) + 10)` used to interpolate across a cell. |
| `fx_gradient2(cell, seed)`, `fx_gradient3(cell, seed)` | The unit gradient a seeded lattice corner carries; the 3D one is spread evenly over the sphere. |
| `fx_curl_potential3(p, seed)` | The three-component potential `fx_curl_noise3` takes the curl of, by central differences over `FX_CURL_EPSILON` (0.05). |
| `fx_cell_point2(cell, seed)`, `fx_cell_point3(cell, seed)` | Where a cell's feature point sits inside the cell, in [0, 1) per axis. |
| `fx_cell_id2(cell, seed)`, `fx_cell_id3(cell, seed)` | The id in [0, 1) a cell is tinted by. |
| `FxWorley2`, `FxWorley3` | The worley result: `dist` (`f32`), `cell` (`vec2i` or `vec3i`) and `id` (`f32`). |
| `FX_TAU` | 2 pi. |
`fx_worley2` searches the 3 by 3 cells around the sample and `fx_worley3` the 3 by 3 by 3 cells.
`fx_worley_fbm2` sums `1 - dist`, clamped to [0, 1], over its octaves, so feature points read as
peaks.
## Used by
The waterfall (`wf_particle`, `wf_pool`, `wf_rock`, `wf_sheet`) and wall blast (`blast_puff`,
`blast_shock`, `blast_stone`) shaders in this package draw their foam, mist, rock, dust and debris
from it, and so does the Procgen Effects Showcase world's `blast_ground`.
# skyhookRace
**A complete co-op sky-island race for 1 to 4 players, as one installable part.** Players grapple,
swing, let go, pop a wingsuit and glide across floating islands at sunset, collect starfruit for one
shared team count, ring bells that raise new routes out of the clouds, outrun a storm front that
swallows the islands behind them, and reach the finish for a results table. It is the game the
Skyhook world plays, with every rule, layout and number exposed so you can make your own from it.
It holds:
- **The race rules**: MatchFlow's lobby, 3-2-1-GO, finish order and a results table (place, time, you),
Trapline checkpoints on every main island, falls respawn at your checkpoint, and a race clock that is the storm's own (`storm.startDelay + storm.arriveBy`).
- **The team starfruit count**: one shared count every player sees, fruit taken once for the team.
- **Bells that open new routes**: touch or hook a bell and it rings for everyone; its islets rise out
of the clouds; one bell can seal the finish until it rings. The objective guides each player to
the next bell with a beam, a waypoint and a hint.
- **The finish and the results screen**: walking through the finish arch records your time, personal
best (saveKit) and XP. Every runner gets their own finish: the race goes on for everyone still
flying after the first runner crosses. MatchFlow's results show each runner's time, or what
happened to them ("Caught by the storm"), and each player gets their own place toast.
- **The storm and the clock tell one story**: stormFrontKit's front follows the islands in order and
ends on the finish, catches up with the slowest runner and swallows islands it passes; a caught
player is put back on the nearest safe checkpoint ahead of it. It reaches the finish exactly
`storm.arriveBy` seconds after it starts (stormFrontKit `arriveBy`), and the race clock is
`storm.startDelay + storm.arriveBy` (4:00 by default), so 0:00 on the clock is the storm
swallowing the finish, and only then is the race over for anyone still out there.
- **Island layouts**: `skyhookRace.layouts.sunsetIsles` (the default) is plain data you can copy.
- **All the tuning numbers**: `skyhookRace.tuning`, with defaults that play well.
- **Controls**: a controlsKit scheme, `skyhook`, plays on keyboard + mouse, gamepad and touch at once.
Every player can remap jump, boost, hook, reel and wingsuit on keys and pad, and move their touch
buttons (swap places, left-handed mirror, stick type) in controlsKit's Controls screen (press **C**,
View on a controller, or the Controls button on touch); each player keeps their remaps between visits.
- **Progression**: XP, levels, best time and unlockable hook and glider styles (saveKit).
**Multiplayer**: everything shared is synced. The course and tuning ride in the RaceDirector's synced
fields, bells keep a synced `rung` state, the fruit count is a shared objective and the storm is one
shared front, so a player who joins late sees the same open routes, fruit count and storm as everyone
else, and races straight away (`joinInProgress`).
## Install it into an empty world
1. Search ZeroMind for a **sky-island grappling-hook race** (the package is **skyhookRace**, guid
`b129e4fa-6753-4be9-a147-9d48fc887711`) and install it, or in the engine shell:
`zero zeromind installAsset b129e4fa-6753-4be9-a147-9d48fc887711`. It lands at
`/source/skyhookRace.package` and brings what it builds on: floatingIslands 1.0.11, grappleKit 1.0.15,
glideKit 1.0.16, airMotor 1.0.9, stormFrontKit 1.0.11, MatchFlow 1.4.3, Trapline 1.5.8, pickupsKit
2.3.14, scoreKit 1.4.10, navUiKit 1.3.14, saveKit 1.3.16, platformsKit 1.6.4, juiceKit 1.2.12,
cloudburst 1.5.3, worldClockKit 1.7.7 and controlsKit 1.4.2, and through them menusKit, soundstage,
barsKit, SecondWind and Lifeline. It is a large install (about 6,600 files) and takes a minute or
more; "waiting for content" warnings while it lands are normal.
2. Make a scene for the race, build the race in it, then switch players on. In this order, checking
each before the next:
a. In the engine shell: `zero scene create --startup race empty`. You should see an empty scene
named `race`, which the world now starts in.
b. Open its build file, `scenes/race.scene/build.luau`, and replace everything in it with:
```lua
function content()
require("skyhookRace.race").build()
end
```
Save. You should see, within a few seconds, Sunset Isles' islands, the sea of clouds and the
sunset sky. The build also placed the race's player (body, camera, hook, wingsuit) and four
spawns on the start island.
c. Once the islands are there, switch players on (an `empty` scene starts with them off):
`zero scene player spawns`. You should see the report list one prototype,
`DefaultSocialPlayer`, four spawns `Spawn0` to `Spawn3`, and `intent: spawns`. Run it only
after the build has landed: before it, the command authors a plain player of its own, with no
hook or wingsuit, beside the race's.
Why a new scene rather than the world's starter `scenes/main.scene`? The starter scene carries
editor edits on its own floor, camera and player; replacing its contents leaves those edits pointing
at things that are gone, and the rebuild stops on them. A fresh `empty` scene has none.
3. Press **Play**. You should see the lobby count down, then GO, a glowing ring over the first gap
(the ring to aim at next is always lit for you), and the storm rolling in behind you. You finish
by reaching the finish island: within `race.finishRadius` (9 m) of its centre and no more than
`race.finishHeight` (12 m) above its top.
## A tiny race of your own
Make a module for your course: a folder `/source/myCourse.module` with this `init.luau` (positions
are `{ x, height, z }` in metres; roles are `start`, `checkpoint`, `finish` and `rest`):
```lua
local L = {}
L.name = "Tiny Hop"
L.islands = {
{ id = "start", label = "Start", role = "start", theme = "start", pos = { 0, 0, 0 }, radius = 16, depth = 18, seed = 1, shape = "mesa" },
{ id = "middle", label = "Middle Isle", role = "checkpoint", theme = "waterfall", pos = { 0, 4, 45 }, radius = 14, depth = 18, seed = 2, shape = "round" },
{ id = "finish", label = "Finish Isle", role = "finish", theme = "finish", pos = { 0, 8, 90 }, radius = 14, depth = 18, seed = 3, shape = "spire" },
}
L.anchors = { -- hook points over the gaps
{ name = "Hook_1", pos = { 0, 20, 24 }, look = "ring" },
{ name = "Hook_2", pos = { 0, 24, 68 }, look = "ring" },
}
return L
```
Then build it instead of Sunset Isles in `scenes/race.scene/build.luau`:
```lua
function content()
require("skyhookRace.race").build({ layout = require("myCourse") })
end
```
Bells, air currents, zip lines and the rest are optional; copy them from
`skyhookRace.layouts.sunsetIsles` when you want them. In a script, the local runner is
`layers.active.players.localPlayer.avatar`, and `require("MatchFlow.api").find():getStandings()`
lists who has finished and their times.
Controls (defaults, all remappable): walk with WASD / left stick, look with the mouse / right stick,
jump with Space / A (press it again in the air to open the wingsuit), boost with Left Shift / L3 (a
sprint on foot, a dive for speed with the wingsuit open), fire and release the hook with the left
mouse button or E / RT, hold the right mouse button or Q / LT to reel in, open and fold the wingsuit
with G / LB, steer it with the stick or WASD. C (View on a pad) opens the Controls screen. On a phone:
a floating stick on the left, drag the right half to look, Hook / Jump / Wingsuit / Reel / Boost on
the right.
## Change it
For a whole course of your own in stages (survey, design the islands and bells, build the layout, tune the storm, race it solo and with two players until clean), start the workflow that ships in this package: `zero workflow start --name skyhookRace.build-a-sky-island-race-course` (args: `course`, `name`).
```lua
function content()
require("skyhookRace.race").build({
layout = require("myCourse"), -- your own course (copy sunsetIsles)
tuning = { -- any subset of skyhookRace.tuning.defaults
race = { lobbySeconds = 5 },
storm = { maxSpeed = 8, startDelay = 10, arriveBy = 290 }, -- the clock reads 5:00
hook = { range = 60 },
glide = { style = "paraglider" },
},
})
end
```
- **Tuning** (`skyhookRace.tuning`): race, bells, fruit, hook, glide, storm, progression, world, score. Leave
out what you don't change. `storm.arriveBy` sets how long the race lasts (the clock is
`storm.startDelay + storm.arriveBy`); `storm = { enabled = false }` races without the storm, on
`race.roundSeconds`. A layout can carry its own `tuning` table too (Sunset Isles sets its ring
heights there); it sits between the defaults and the `tuning` you pass to `build`.
- **Layouts** (`skyhookRace.layouts.sunsetIsles`): islands with a role (`start`, `checkpoint`,
`finish`, `rest`), a look and a shape. Islands are grown by the **floatingIslands** part: give an
island any of its `look`s (meadow, waterfall, farmland, crystal, fortress, marble, snowy, autumn,
mesa, volcanic, lowpoly, pixel) and `shape`s (round, stone, stepping, ridge, arch, ring, cluster), or
a Skyhook `theme` (start, waterfall, windmill, crystal, fortress, finish, islet: a look plus Sunset
Isles' own ground and cliff materials), and the shape numbers (radius, depth, seed, stretch, bumps,
hanging, roots, crags, debris). Also `bellRoutes` (islets each bell raises); `bells` (in order,
with `where` and `hint`, `opensFinish`); `air` (thermals, updrafts, rings); `anchors`, `zipLines`,
`slingshots`, `crumbleStones`, `hookShells`; `stormStart`; and an optional `decorate(ctx)` for set
pieces. The same seed is the same island on every machine.
- **Dressing**: `tuning.world.dressing = false` drops Sunset Isles' own props, falls and per-island
ambience, so you can dress the islands yourself. The sunset atmosphere (sky haze and grade, cloud
sea, horizon islands, cloud wisps, open-sky wind) still builds for any course; `tuning.world.atmosphere
= false` drops it too.
## What is inside
| Part | What it does |
|---|---|
| `race.module` | `build(options)`: the whole race into a scene |
| `tuning.module` | every number, `defaults` and `merge(overrides)` |
| `course.module` | a layout as a course (roles, route, start, finish), to and from JSON |
| `layouts/sunsetIsles.module` | the default course |
| `islands.module` | one floating island per layout entry, grown by floatingIslands (look, shape, theme) |
| `controls.module` | the `skyhook` controlsKit scheme (move, look, jump, boost, hook, reel, wingsuit), turning it into grappleKit / glideKit calls, and controlsKit's Controls screen |
| `RaceDirector.component` | runs the race on every peer: phases, objectives, bells guide, storm rescue, finish, results, music, progression, controls |
| `Bell.component` / `bellNet.module` | a bell that rings for the team and raises its route |
| `Starfruit.component` | the glowing fruit drawn for a shared pickup |
| `input/air` | the map the hook's swing pump and the wingsuit's steering read `move` from under the scheme |
| `env/` | dressing, sunset atmosphere, cloud sea, waterfall water |
| `art/` | the meshes, materials, sounds and music the race uses |
## Guides
- **how-skyhook-is-built-and-how-to-change-it**: how the parts fit and where to change each thing.
- **example-make-your-own-sky-island-race-level**: build a small race of your own, step by step.
Read one with `guides { path = "skyhookRace.package/guides/<name>" }`.
## What's new in 1.5.1
- **A package description that says what you get and how to install it**, here and in each part
it is built on: grappleKit 1.0.15, glideKit 1.0.16, airMotor 1.0.9, stormFrontKit 1.0.11 and
floatingIslands 1.0.11 (description and version only; floatingIslands also ships fresh previews).
- **Fresh preview pictures** for the runner suits, the bell beams, the amethyst and cyan crystals
and the four new cloud seas. The released ones were out of date, so every world that installed
the race redrew them and then reported the install as changed. No change to how the race plays.
## What's new in 1.5.0
- **The ring to aim at is lit.** Each runner's next ring glows inside a pulsing ball of light on
their own screen (grappleKit 1.0.15's `cue`), and the gap rings use grappleKit's new `halo` look, a
ring of cool light that reads against a warm sky. `hook.anchorLook` picks another look for the
whole course (`ring`, `lantern`, `star`, `beacon`, `balloon`, or `themed` for 1.4's per-island
looks); `hook.cueNextRing = false` turns the glow off.
- **Soft clouds instead of pale rectangles.** The cloud wisps over the cloud sea are cloudburst 1.5.3
`cloud` banks: round, ragged at the rim and soft underneath, from near and far.
- **Five sky moods in one line.** `world.mood = "sunset"` (the default), `"dawn"`, `"noon"`,
`"night"` or `"storm"` sets the sky, the light, the haze and the cloud sea together
(`skyhookRace.moods`). The sun now stands where the course wants it through worldClockKit 1.7.7's
own `sunBearing`, `sunTilt` and `ambientBoost`, so the race no longer overrides the clock's sun.
- **Island and bell styles in one line.** `world.islandStyle` regrows every island from another set
of floatingIslands looks (`winter`, `autumn`, `volcanic`, `meadow`, `lowpoly`, `pixel`);
`bells.style` gives every bell another body and beam (`bronze`, `gold`, `crystal`, `amethyst`).
- **A fresh course plays well out of the box.** Leave `storm.arriveBy` out and the clock comes from
the course's own length (`storm.autoPace`, never under 1:30; Sunset Isles keeps its 4:00). The
launch ring never hangs further out than the hook can reach from the edge.
- **Starfruit come back through pickupsKit, and score through scoreKit.** Each race's fruit returns
with pickupsKit 2.3.14's `restore`; every runner's fruit is scored by scoreKit 1.4.10's pickup scorer
on the machine keeping the score, whoever took it. The race's own workarounds are gone.
- **One health stack.** Trapline 1.5.8 reaches Lifeline through SecondWind 1.4.8, and loads barsKit
only when a hearts or pips lives display is drawn (Skyhook draws none).
- **The README and the example guide go step by step,** each step saying what you should see:
build the race, then switch players on (the order matters), turning off Sunset Isles' dressing for
your own course, how checkpoints and the line to the next ring stay clear of props, and aiming at
the lit ring ahead. The guide's numbers match its course (18 starfruit, a 2:40 clock).
## What's new in 1.4.9
- **Your own course keeps the sunset.** The example guide's `world.dressing = false` (the right call for
a custom layout, since Sunset Isles' props are placed for its islands) also dropped the sky haze,
colour grade, cloud sea, horizon islands and cloud wisps, leaving a flat pink fog. Those are now
`env/dressing`'s `buildAtmosphere` and build for any course unless `world.atmosphere = false`.
Sunset Isles with the default dressing builds exactly as before.
- **The next-bell message shows once.** At every countdown "Next: <bell>" was shown twice (the
twice-a-second refresh and the forced refresh a second later both announced it). It now shows once
per bell; the waypoint and objective still refresh.
- **The example guide counts its starfruit right**: its course shows Team starfruit 0/18, not 0/12.
- **The example guide says when to switch players on.** An `empty` scene starts with players off, so
`zero scene player spawns` is still needed, but only after the build has landed: run before it, it
authored a plain player and spawn of its own beside the race's, and a joiner could come in with no
hook or wingsuit. The guide and this README now say to run it once the islands are in the scene.
- **A fall respawns you at your own checkpoint.** Any runner below y -60 was "rescued" as if the
storm had caught them, and sent to the checkpoint nearest to where they fell, reached or not:
falling off past an island put you on the next one (or two) ahead, skipping checkpoints, bells and
whole gaps, with a "The storm caught you!" toast. A fall now goes to Trapline's respawn at your own
checkpoint (or the start); the rescue only steps in when that spot has been swallowed, and then
picks the first safe checkpoint in course order, not the nearest.
- **Flying high over the finish no longer finishes the race.** The line counted at any height above
the finish island (a fling 50 m over it recorded a finish). It now counts up to
`race.finishHeight` (12 m) over the island's top.
- **You can aim at the ring ahead, as the guide says.** Each gap's launch ring hung 17 m up, close to
the departure rim: from the edge it sat far above where the follow camera can look, so the reticle
took the higher re-hook ring instead. The launch ring now hangs over the middle of the gap at 11 m
(`hook.launchAlong` 0.5, `hook.launchHeight` 11), and the re-hook ring over the arrival rim
(`hook.rehookAlong` 0.95), still ahead when you let go of the launch swing. Checked with real
input: every run-up locked the ring ahead, and a full lap finished in 1:38.8. **Sunset Isles keeps
its own rings** (17 m, 0.3 and 0.8 across), tuned and raced for its long gaps: a layout can now
carry its own `tuning`, laid between the defaults and the game's `tuning`, and Sunset Isles uses it.
- **Custom courses keep the race clear of props.** With `world.dressing = false` each island grows its
look's dressing from floatingIslands, which placed rocks and trees anywhere, including between a
checkpoint and the next gap's rings (the reticle then jumped to a bell 57 degrees off). The build
now gives every island clear zones (`FloatingIsland.clear`, new in floatingIslands 1.0.11, which
this release takes): a lane toward each neighbouring main island, the checkpoint and any bell
standing on it. Sunset Isles with the default dressing is unchanged.
- **Hooking a bell from the ground rings it and lets go.** The hook rang the bell and then swung you
toward it, which pulled a runner standing on Lantern Rock toward the Wind Bell's crag. Now a runner
who was standing gets a ring shot: the bell rings and they stay where they stood. A runner already
in the air keeps the swing, since the bell hooks also carry you up to the crags and towers.
## What's new in 1.4.8
- **Takes stormFrontKit 1.0.11**, whose two guides now say which version they describe. The README's
install list and both guides name it. Text and the dependency pin only: play, layouts, tuning and
every file of 1.4.7 are unchanged.
## What's new in 1.4.7
- **Installs match the release exactly.** Eleven preview pictures in 1.4.6 (the six runner suits, the
two crystal materials, and the cloud-sea, waterfall pool and waterfall sheet shaders) were rendered
before their assets' last change, so every world that installed the kit redrew them and then showed
the install as changed from the release. They are re-rendered and current. Takes floatingIslands
1.0.9 (the same fix for its island rock shader). Play, layouts and tuning are unchanged from 1.4.6.
## What's new in 1.4.6
- **A new hook or glider style waits until you land.** An unlock earned mid-race is saved at once and
equipped when you are standing on the ground with the glider closed and the hook idle, so a
wingsuit is never swapped for a canopy in the air (that cut a 25 m/s glide to 11). The unlock
listener is removed when the race director goes away, so restarts never stack handlers.
- **A starfruit no longer flashes a big pale ball in front of the camera.** Takes juiceKit 1.2.12,
whose cartoon look draws its pickup glow as a soft glow instead of a solid ball.
- **Courses of your own build without Sunset Isles' waterfall.** The default dressing skipped no
set piece, so a layout without a `waterfall` island and its `waterfall_crag` stopped with
"attempt to index nil with 'theme'". The falls, river, pool and their sound now appear only when
those two islands exist; the tiny course above builds and races to the finish.
- Takes saveKit 1.3.16. The README names every part and version it brings, warns that the install is
large, and gives a tiny course; the guides name the installed versions. Older changes are in
`CHANGELOG.md`.