# AudioMaster
Masters generated recordings into the kit's sound clips, and is how every clip in `desertKit.package/audio` was made from the audio_gen takes. `loop` turns a take into a level, seamless ambience loop (trims head and tail, cross-fades the last 3 s into the first with an equal-power fade, levels to an RMS with a peak cap); `oneShot` trims a footstep or a call to its onset, fades it out and normalises it (optionally to mono).
```luau
local M = require("desertKit.AudioMaster")
M.loop(asset.resolve("/zero/source/tmp/raw.soundClip", "soundClip"), "/zero/source/desertKit.package/audio/beds", "dk_bed_x", { crossfade = 3, rms = 0.09 })
M.oneShot(asset.resolve("/zero/source/tmp/step.soundClip", "soundClip"), "/zero/source/desertKit.package/audio/steps", "dk_x_1", { length = 0.5, mono = true })
```
Check a loop with `clipRef:loopSeam().seamless`.
# CaravanHunt
A treasure hunt along a desert's walk: relics a caravan lost (desertProps kinds, glinting so they show from afar) lie a few metres off the track from the camp to the town; walk over one to pick it up. Every player sees the same relics, one a friend picks up is gone for everyone, a counter shows how many are found, and a late joiner is told what is already gone. When the last is found, the treasure chest by the town's well unlocks; walk up to it to open it for everyone. Fields: `count`, `seed`, `kinds`, `radius`, `chest`, `hud`. Needs a `Desert` in the scene (it reads the walk through DesertSite). `HuntEvents` reports each relic, all found and the chest opened, so a game can give XP or unlocks; `:progress()` answers (found, total, opened).
# Desert
Drops a whole walkable desert into a world. Add it to any entity (its position is the desert's centre): `size`, `kind` (duneSea, mesaCountry, oasisValley, saltPan, buriedCity), `dunes` (auto, crescent, linear, star, transverse, barchanoid, parabolic, dome, reversing), `duneHeight`, `density`, `seed`, `sand` (auto, ochre, red, pale), `look`, `route`, `spawnAtCamp`, `horizon`, `quality`, `keepClear`. Every field is synced and the desert is built from the fields alone on every machine, so every player walks the same dunes; changing a field rebuilds it. It needs no sibling components; add a `WorldClock` and a `DesertAtmosphere` for time of day, weather and sound. `:desert()` answers the built desert, `:status()` where it is in its life, `:rebuild()` builds it again.
`keepClear` (text, empty by default) keeps props off corridors and circles, such as a race track: entries split by `;`, each a corridor `x1,z1,x2,z2,halfWidth` or a circle `x,z,r`, in world metres. A prop whose footprint reaches into one is left out with its collider; the ground is not changed or cooked again. `require("desertKit.DesertBuilder").clearPath(points, halfWidth)` builds the string from a closed list of `{x, y, z}` points.
# DesertAmbience
The desert's ambience on soundstage, by time (DesertAtmos's preset weights), weather (wind, dust storm) and place (`DesertSite`'s `zoneAt`; no desert built = open dunes). Started and ticked by `DesertAtmos`.
| place | dawn | midday and afternoon | night | calls (3D, round the listener) |
|---|---|---|---|---|
| open dunes (and flat, at 0.8) | still air: the night breeze and last crickets fading under a quiet day bed | dry wind and sand hiss, louder with wind and in the heat | cold breeze, sparse crickets | sand gusts when the wind is up (rare at dawn) |
| oasis | the night chorus fading, a busy dawn chorus of songbirds and doves | trickling water, palm rustle, a few birds | frog chorus, crickets, water | songbirds and doves (tropicalKit), frogs by night and at first light |
| ruins | the hollow wind at half strength, sparrows | hollow wind moaning through walls | the wind, a little quieter | creaks, sparrows mostly at dawn |
| rocks | the wind at half strength | wind whistling over cliffs and arches | the wind, a little quieter | a distant raptor, mostly at midday |
| dust storm | everything ducks by 85%; worldClockKit plays its sandstorm roar from the shared weather | | | calls stop |
Dusk sits between day and night (about a third of the night beds).
```luau
local A = require("desertKit.DesertAmbience")
A.levelsAt(38, 5, { dawn = 0, midday = 1, dusk = 0, night = 0 }) -- bed levels at a point (pure)
A.report() -- levels asked, what soundstage sounds, calls placed, zone at the listener
```
Beds play only in play mode (soundstage's rule); `report().levels` shows what is asked in either mode. Beds are this kit's own recordings (`audio/beds`, generated, mastered by `AudioMaster` to seamless 26 s loops).
# DesertAtmos
The desert's time of day and weather on worldClockKit's shared clock, and the look, air and sound each machine makes of them. Started by the `DesertAtmosphere` component; modelled on tropicalKit's `Atmos`.
```luau
local DesertAtmos = require("desertKit.DesertAtmos")
DesertAtmos.setTime("dusk", { hold = true }) -- every player: "dawn" | "midday" | "dusk" | "night"
DesertAtmos.dustStorm({ approach = 45, duration = 60, clear = 25 }) -- a haboob rolls in for everyone
DesertAtmos.setWeather("clear") -- or "storm" (stays until changed), or any worldClockKit weather
print(DesertAtmos.report().time, DesertAtmos.report().ambience.levels)
```
- `setTime(name, { hold? })`: set the shared clock to a preset (`hold = true` pauses it there).
- `dustStorm(opts)` / `clearStorm(fade?)`: a dust storm for every player (see `DustStorm`); `setWeather(name, { fade? })`.
- `configure(opts)`: what this machine draws and plays: `look`, `grade`, `haze`, `shimmer`, `storm`, `milkyWay`, `ambience`, `ambienceVolume`, `footsteps`, `footprints`, `stormEveryMinutes`.
- `override({ dawn = { haze = 0.003, heat = 0.2, grade = { saturation = 1.2 } }, ... })`: per-time overrides on top of the presets.
- `current()` / `lookFor(weights, storm, overrides?)` (pure): the blended `{ grade, haze, hazeTint, hazeTintMix, heat, storm, weights }`.
- `weights()` / `weightsAt(solar)`, `timeOfDay()`, `stormAmount()`, `weather()`, `hourForSolar(solar)`.
- `report()`: time, weights, storm amount and state, weather, clock hour, look, shimmer, sky, ambience levels and calls, footstep counts, footprints.
- `PRESETS`, `STORM`, `KEYS`, `CAMPFIRE`, `start(opts, holder)` / `stop(holder)` / `tick(dt)`.
## The presets (compared against the reference sheet `design/references/mirage_wells`)
| time | solar hour | look | reference |
|---|---|---|---|
| dawn | 6.35 | pink-peach light on the crests, blue-violet shadow, a low pink dust mist (haze 0.0026) | `time_dawn` |
| midday | 12.3 | bleached high white sun, short shadows, pale hazy blue-white sky, heat shimmer 1 and a mirage on the horizon, grade desaturated (0.86) | `time_midday_heat_shimmer2` |
| dusk | 17.75 | sun on the horizon, amber and rust dunes, orange-to-magenta sky, purple shadows, palms in silhouette | `time_dusk` |
| night | 22.4 | high bright moon (silver-blue light), navy sky with stars and the Milky Way, sand readable, a cool blue grade | `time_night` |
The light and sky colours are the "desert" sky look (`DesertSky.SKY_LOOK`), so they apply with the WorldClock's `skyMode` "kit" (the clock's sky shader) and "engine" (the scene's ProceduralSky, coloured by `DesertSky`).
## What it does on each machine
- Holds the "desert" sky look (`look = false` frees it), colours the engine sky in skyMode "engine".
- Three of the engine's post passes for the grade (colorGrade, color_correction tint, vignette) per time and storm.
- Wraps the clock director's `evaluate` so its fog becomes dust haze (chained after other kits' hooks).
- Heat shimmer (`HeatShimmer`), the storm (`DustStorm`), the Milky Way (`DesertSky`), each one full-screen pass, registered only when it has something to draw.
- Campfires: every Light whose entity carries attribute `desertLight = "campfire"` is lit warm and flickering from dusk to dawn and put out by day (`CAMPFIRE`).
- Ambience (`DesertAmbience`), footsteps (`DesertFootsteps`) and tropicalKit's `Footprints`, taught the desert's sand and mud.
# DesertAtmosphere
The desert's light, air and sound on worldClockKit's shared clock. Put ONE on any entity of a scene that also has a `WorldClock` (worldClockKit); it runs `DesertAtmos` on every machine: the "desert" sky look, a grade per time, dust haze, heat shimmer and mirage at midday, the Milky Way at night, dust storms that roll in, campfires lit after dusk, ambience by time and place, desert footsteps and footprints.
```luau
entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 24, startHour = 10, skyMode = "engine" })
entity.spawn("DesertAtmosphere").component.add("desertKit.DesertAtmosphere", { stormEveryMinutes = 15 })
```
Fields: `look`, `grade`, `haze`, `shimmer`, `storm`, `stormEveryMinutes`, `milkyWay`, `ambience`, `ambienceVolume`, `footsteps`, `footprints`, and per-time overrides `dawnHaze`, `middayHaze`, `duskHaze`, `nightHaze`, `middayHeat`, `dawnSaturation`, `middaySaturation`, `duskSaturation`, `nightBrightness` (-1 keeps the preset). Change the time and weather for everyone with `require("desertKit.DesertAtmos")`: `setTime("dusk")`, `dustStorm({ duration = 60 })`, `setWeather("clear")`.
With skyMode "engine", give the scene's ProceduralSky `syncSunToLight = false` (the clock drives the light; the atmosphere also switches it off at runtime).
# DesertBuilder
Builds a whole walkable desert from settings: `build({ size, kind, dunes, duneHeight, density, seed, sand, look, origin, route, spawn, horizon, quality })` stands the cooked terrain, the horizon apron, the oasis water, every scattered prop and set piece as instanced draws, their colliders, the signposts, the camp fire's light, and moves the scene's player spawns to the camp; it answers the desert (`update`, `setLook`, `setQuality`, `destroy`, `.site`, `.plan`, `.instances`, `.stats` with `fingerprint`). `keyFor(opts)` names the saved ground, `planFor(opts)` the field, grid and walk without building, `spawnPoint(opts)` where players arrive. The `Desert` component calls it.
# DesertCliffs
Real rock over a desert's steep ground. The engine terrain paints from straight above, so on a cliff its texture smears down the face into vertical streaks; DesertCliffs lays a thin skin over every stretch steeper than about 40 degrees that the desert paints as rock (a sand slip face, a dune crest or the walk's graded cut stays sand), built from the same heights the terrain stands, 0.35 m proud of it, with its texture wrapped round the wall (u along the face, v up it, 4 m a repeat) and drawn with desertMaterials' `sandstoneVarnished`, whose strata follow world height and whose desert varnish hangs from the ledges. One mesh, one draw, no collider: the terrain under it is what you walk on.
`DesertBuilder` spawns it with every desert (mesa walls, valley sides, the arch's rock band) and switches its material with the look. `Cliffs.spawn(grid, parent, material)` answers the entity, or nil when nothing is steep; `Cliffs.mesh(grid, { steep?, minRock?, offset?, uvMetres? })` builds the mesh alone. `STEEP`, `MIN_ROCK` (the grid's rock weight a quad needs), `OFFSET` and `UV_METRES` hold the defaults; `DesertBuilder.CLIFF_SURFACE` names the surface.
# DesertField
The shape of a desert as plain numbers: from a size, a desert kind (`duneSea`, `mesaCountry`, `oasisValley`, `saltPan`, `buriedCity`), a dune shape (`crescent`, `linear`, `star`), a dune height and a seed it answers the ground height at any point and how much of it is slip face, rock and interdune flat, and it lays out the walk (camp, dune crest, arch, oasis pool, ruined town) the ground is shaped around. Integer-hash noise and plain arithmetic only, so every machine computes the same dunes. Used by the desert builder; `DF.KINDS` and `DF.SHAPES` list what a world can choose.
# DesertFootsteps
Desert footsteps on soundstage, for every walker. The footstep class under each step comes from a collider's (or parent's) `desertSurface` attribute first (`"ground"` defers to the site), then `DesertSite:footstepAt(x, z)`, with wading where `site:waterAt` is deeper than 6 cm.
| class | plays as |
|---|---|
| `sand` | soundstage `sand` |
| `softSand` | `desertSoftSand` (kit recording: foot sinking, sand sliding) |
| `rock` | `desertRock` (kit recording: gritty sandstone scuff) |
| `stone` | soundstage `stone` |
| `gravel` | soundstage `gravel` |
| `mud` | `desertMud` (kit recording: squelch) |
| `water` | soundstage `water` |
| `wood` / `grass` | soundstage `wood` / `grass` |
| `salt` | `desertSalt` (kit recording: crust crunch) |
```luau
local F = require("desertKit.DesertFootsteps")
F.install() -- DesertAtmos does this
F.play({ surface = "softSand" }) -- hear one
F.counts() -- steps heard per soundstage surface
```
`install` also teaches tropicalKit's `Footprints` the desert (where no tropical island stands): sand and soft sand print dry, oasis mud prints wet.
# DesertHorizon
The dunes carry on past the walkable edge: one square apron mesh around the desert's terrain out to several times its size, its inner edge on the field's own heights so it meets the terrain without a seam, the same dune field sampled coarsely further out, settling low into the distance. No collider. `mesh(field, opts)`, `spawn(field, parent, material)`. Stood by DesertBuilder.
# DesertLayout
Plans the walk through a desert on its own ground: the stops (Caravan Camp, Dune Crest, Lost Cart, The Arch, Mirage Wells, The Buried Town) with their heights, the levelled camp and arch floor, the track graded to a walking slope, where the trodden track lies (`plan.pathCover`), and the set pieces as placements: the camp (tent, fire ring, crates, lantern, signpost), a wrecked cart, the arch across the track, and the town (gateway, perimeter walls and towers, a street of roofless houses with a colonnade, a plaza with the well, the fallen statue head and columns, giant feet beyond). `Layout.plan(field, grid)`; plain arithmetic, so every machine plans the same walk. Used by DesertBuilder.
# DesertRender
Draws a desert's props and set pieces as hardware-instanced draws, one per prop part per level of detail, re-sorting every instance into its level by distance from the camera as you move (a few groups a frame). Distances and shadow casting per category (`BANDS`): palms, trees, formations, ruins, camp, rocks, cacti, bushes, plants, litter. `new(instances, { look, parent, quality })`, `update()`, `refresh(at?)`, `holdAt(at, seconds)`, `setQuality(q)`, `destroy()`. tropicalKit's IslandRender with desertProps' catalog and the desert's categories.
# DesertRules
What grows and lies where in a desert: rule layers of candidate points on jittered grids decide, from the ground's own numbers (height, slope, slip face, rock, interdune floor, distance to the oasis water, the walk and the town), where date palms ring the pool, reeds stand at the waterline, acacias and shrubs dot the floors, mesa country grows saguaros and joshua trees, boulders, hoodoos and outcrops gather on rock, tumbleweeds, bones and pots lie about, and ruin fragments rise from the sand of a buried city. `Rules.scatter(field, grid, plan, { density, kinds })` answers the placements; `Rules.fingerprint(instances)` a short code of them all (equal on two machines means the same desert). Integer hashing only.
# DesertShape
Turns a DesertField into ground on the engine terrain: `grid(field)` computes every cell's height on the CPU (tropicalKit's IslandShape grid), `paint(field, grid, plan)` the eight surface weights, and `write(...)` saves both as `<folder>/<key>.terrainData`, which the `Terrain` component stands. `VERSION` changes whenever shaping or painting changes, so older saved ground is cooked again. Used by DesertBuilder.
# DesertSite
Questions you can ask a desert's ground on any machine: `Site.current()`, `site:heightAt(x, z)`, `site:surfaceAt(x, z)` (the terrain layer under a point: sandDune, sandRippled, sandSlipFace, gravelPlain, saltFlat, rockSandstone, mudWet, grassOasis, ...), `site:footstepAt(x, z)` (sand, softSand, gravel, rock, stone, mud, water, wood, grass, salt), `site:zoneAt(x, z)` (weights of dunes, oasis, ruins, rocks and flat), `site:waterAt(x, z)` (the oasis pool's surface height, or nil), `site.pois` (the stops of the walk), `site.kind`. Answers come from the same CPU heights the terrain stands, so every machine answers alike.
# DesertSky
The desert's sky. Defines the "desert" sky look for worldClockKit (`SKY_LOOK`: four palettes that set both the sky and the light the clock casts, with a big moon, many stars and a strong horizon glow), draws the Milky Way over the night sky, and in the WorldClock's skyMode "engine" colours the scene's ProceduralSky from the same palettes (dust-brown in a storm, stars by night) and stops it from driving the sun light itself (the clock does).
```luau
local DesertSky = require("desertKit.DesertSky")
require("worldClockKit.kit").Sky.set(DesertSky.LOOK) -- "desert" (DesertAtmos holds it for you)
DesertSky.MILKY_WAY.intensity = 1.2 -- brighter galaxy (default 0.9)
```
The Milky Way is one post pass (`shaders/dk_night_sky`) on sky pixels only: the view ray becomes coordinates along a tilted great circle and the kit's panorama (`textures/dk_milky_way`, generated) is added to the sky. Registered at night only. A small material holds the texture on the GPU, since a post pass binds only textures the renderer already holds.
# DesertSurfaces
The eight surfaces a desert's ground is painted with and the rules that decide which covers where. Every desert paints eight roles (dune sand, wind ripples, slip faces, the trodden track, the interdune floor, rock, oasis mud, oasis grass); `layersFor(kind, recipe, sand)` names the desertMaterials terrain layer each role takes for a desert kind and sand colour, `records(layers, look)` answers the records `terrain.write` takes (ripple and slip layers tinted to the dune sand), `weights(w, cell)` the role weights at one cell, and `FOOTSTEP` the footstep class of each layer. Used by DesertShape and the desert site.
# DustStorm
A desert dust storm (haboob) that rolls in, for every player at the same moment, drawn as one full-screen pass (`shaders/dk_dust_storm`). Called through `DesertAtmos.dustStorm`, or directly:
```luau
local DustStorm = require("desertKit.DustStorm")
DustStorm.start({ approach = 45, duration = 60, clear = 25, from = { 0, 1 } }) -- comes from +Z
print(DustStorm.state().phase, DustStorm.state().dist) -- "approach", metres to the front
DustStorm.stop() -- clear it now
```
## How it is shared
`start` writes a record to `runtime_data.world` (`desertKit/dustStorm`): the shared start time (worldClockKit's timeline) and the real time it started (`born`), approach / peak / clear seconds, the direction it comes from, the distance it starts at and its origin (the desert's centre). How long a storm has run comes from the shared timeline while that agrees with real time to within 20 s, and from real time otherwise: a session's host can keep a timeline of its own, and the store keeps a record after its session ends, so this is what lets every machine, and a later session, agree on where a storm is and when it is over (a leftover record reads as long over and is cleared). Every machine draws from the record; the front is anchored in the world, so every player sees it at the same place. Whoever holds the clock moves the shared weather: the air stays as it was while the front is far off, then worldClockKit's own `sandstorm` weather (thick orange dust, dim sun, sand streaks, the sandstorm roar) fades in over the second half of the approach (`HAZE_FROM`), so it is at full strength as the wall arrives; `clear` when it ends, then the record is deleted. The kit defines no weather of its own. `autoStep(minutes)` starts one on its own every so many minutes (the component's `stormEveryMinutes`).
## How it is drawn (cost)
One post pass, registered only while a storm shows, idle (returns the frame) otherwise:
- **the wall**: each view ray meets a vertical front of dust (bent back at its sides) once; where it does before the scene, a towering billowing cliff is drawn from 4-octave value noise: rolling heads, cauliflower billows lit on their upper sides, a dark foot, dust rolling out ahead of it over the ground. No ray march.
- **inside**: sheets of dust streaming downwind (two noise lookups along the ray) over the clock's thick fog.
- worldClockKit draws the blowing sand streaks round the camera (its 2,400-drop mesh) and plays its sandstorm bed from the weather.
`stateAt(rec, t, x, z)` is pure: `{ phase, front, dist, wall, engulf, progress }`. `LOOK` holds the colours, visibility, wind speed, roll and curve; `DEFAULTS` the timings.
# HeatShimmer
Desert heat shimmer as one full-screen post pass (`shaders/dk_heat_shimmer`): far rays that skim the hot ground wobble with rising, horizontally stretched noise; anything nearer than 25 m stays sharp (no ghost edges); just below the horizon, far ground turns into an inferior mirage that mirrors the sky and whatever stands on the horizon. `DesertAtmos` drives it every frame from the heat of the day (midday 1, dusk 0.18, dawn 0.04, night 0, nothing in a storm).
```luau
local HeatShimmer = require("desertKit.HeatShimmer")
HeatShimmer.configure({ amplitude = 4, mirage = 0.8 }) -- tunables, see SETTINGS
HeatShimmer.apply(1.0, { 0.9, 0.9, 0.88 }) -- heat 0-2 and the mirage colour (DesertAtmos does this)
HeatShimmer.remove() -- out of the frame
print(HeatShimmer.report().strength)
```
Cost: one pass, two depth reads and two or three scene reads per pixel. At heat 0 the pass stays registered but returns the frame untouched; `DesertAtmosphere.shimmer = false` removes it.
# HuntEvents
What a CaravanHunt tells the rest of a game on each machine: `Hunt.on(fn)` calls `fn(event)` for every relic found (`kind = "relic"`), for the last one (`"allFound"`) and for the chest opened (`"opened"`), with `mine` true when this machine's own player did it, plus `found`, `total`, `index` and `by`. Use it to give XP or unlocks (the showcase gives saveKit XP). `Hunt.emit(ev)` is what the component calls.
# dk_bed_dunes_day
A looping desert ambience bed: dry hot wind blowing over open sand dunes, a soft continuous hiss of sand grains skittering over ripples, gusts swelling and fading, no birds. The open dunes by day. Mastered to a seamless 26.2 s loop (3 s equal-power cross-fade), Opus stereo; desertKit's DesertAmbience plays it as a bed.
# dk_bed_dunes_night
A looping desert night bed: a low cold breeze over the open dunes and sparse distant crickets in a vast quiet. The open dunes at night. Mastered to a seamless 26.2 s loop (3 s equal-power cross-fade), Opus stereo; desertKit's DesertAmbience plays it as a bed.
# dk_bed_oasis_day
A looping oasis bed by day: a small spring trickling and lapping at a pool, date palm fronds rustling dryly, a few distant songbirds and turtle doves. Mastered to a seamless 26.2 s loop (3 s equal-power cross-fade), Opus stereo; desertKit's DesertAmbience plays it as a bed.
# dk_bed_oasis_night
A looping oasis bed at night: a chorus of frogs croaking by the water, crickets, a faint trickle and a warm breeze in the palms. Mastered to a seamless 26.2 s loop (3 s equal-power cross-fade), Opus stereo; desertKit's DesertAmbience plays it as a bed.
# dk_bed_rocks_wind
A looping rock-country bed: wind whistling and gusting across sandstone cliffs, arches and canyon walls, an airy high whistle over a low rumble. Mastered to a seamless 26.2 s loop (3 s equal-power cross-fade), Opus stereo; desertKit's DesertAmbience plays it as a bed.
# dk_bed_ruins_wind
A looping ruins bed: hollow wind moaning and whistling through ruined mud-brick and stone walls, doorways and window gaps, a little sand hiss. Mastered to a seamless 26.2 s loop (3 s equal-power cross-fade), Opus stereo; desertKit's DesertAmbience plays it as a bed.
# dk_creak_a
An old dry wooden beam creaking slowly in the wind inside a ruin. Heard in the ruins, more often in wind. A one-shot call desertKit's DesertAmbience places in 3D around the listener.
# dk_creak_b
A weathered wooden door on rusty hinges creaking as the wind pushes it. Heard in the ruins, more often in wind. A one-shot call desertKit's DesertAmbience places in 3D around the listener.
# dk_gust_a
A gust of wind whipping fine sand off a dune crest: a rising and falling sandy whoosh. Heard on the open dunes when the wind is up. A one-shot call desertKit's DesertAmbience places in 3D around the listener.
# dk_gust_b
A short sharp desert gust carrying blowing sand past. Heard on the open dunes when the wind is up. A one-shot call desertKit's DesertAmbience places in 3D around the listener.
# dk_raptor_a
A single distant hawk screech echoing over a desert canyon. Heard by day over rock country. A one-shot call desertKit's DesertAmbience places in 3D around the listener.
# dk_raptor_b
A distant eagle calling twice high above rocky desert cliffs, with canyon echo. Heard by day over rock country. A one-shot call desertKit's DesertAmbience places in 3D around the listener.
# dk_sparrow_a
A small desert sparrow chirping a few short notes. The ruins' occasional bird. A one-shot call desertKit's DesertAmbience places in 3D around the listener.
# dk_mud_1
A squelchy step in wet sticky oasis mud. Surface desertMud (the oasis edge). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_mud_2
A squelchy step in wet sticky oasis mud. Surface desertMud (the oasis edge). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_mud_3
A squelchy step in wet sticky oasis mud. Surface desertMud (the oasis edge). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_rock_1
A boot on hard gritty sandstone bedrock: a dry scuff with sand grit under the sole. Surface desertRock. One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_rock_2
A boot on hard gritty sandstone bedrock: a dry scuff with sand grit under the sole. Surface desertRock. One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_rock_3
A boot on hard gritty sandstone bedrock: a dry scuff with sand grit under the sole. Surface desertRock. One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_salt_1
A step breaking a dry salt crust: a brittle crisp crunch. Surface desertSalt (salt flats). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_salt_2
A step breaking a dry salt crust: a brittle crisp crunch. Surface desertSalt (salt flats). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_salt_3
A step breaking a dry salt crust: a brittle crisp crunch. Surface desertSalt (salt flats). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_softsand_1
A footstep sinking into soft loose dune sand that slides away: a muffled sandy crunch. Surface desertSoftSand (slip faces, dune crests). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_softsand_2
A footstep sinking into soft loose dune sand that slides away: a muffled sandy crunch. Surface desertSoftSand (slip faces, dune crests). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_softsand_3
A footstep sinking into soft loose dune sand that slides away: a muffled sandy crunch. Surface desertSoftSand (slip faces, dune crests). One take of a footstep, mono; desertKit's DesertFootsteps registers it with soundstage for every footwear.
# dk_dust_storm.shader
A light-space post-process pass for a desert dust storm (haboob), with no ray march. Each view ray is intersected once with a vertical front of dust standing `wallDist` metres away, bent back at its sides: where the ray meets the front before the scene, a towering orange-brown cliff of dust is drawn, its rolling crest broken into heads and billows, its upper billows sunlit and its foot dark. As the front passes the camera, `engulf` takes over: sheets of blown dust that thicken with distance and stream downwind over the clock's fog. One full-screen pass of a handful of value-noise octaves; with `wall` and `engulf` at 0 it returns the frame untouched. desertKit's `DustStorm` module registers it only while a storm is on and drives every property from the shared storm record.
# dk_heat_shimmer.shader
A light-space post-process pass for desert heat: rays that skim the hot ground near the horizon and travel far wobble with rising, horizontally stretched noise, while anything nearer than `nearStart` stays sharp (the pass refuses to pull near pixels into the shimmer, so no ghost edges). Just below the horizon line, far ground turns into an inferior mirage: the sky and whatever stands on the horizon are mirrored faintly upside down as a bright shimmering "pool". One full-screen pass, two depth reads and two or three scene reads per pixel; `strength = 0` returns the frame untouched. desertKit's `HeatShimmer` module registers it and drives `strength` from the heat of the day.
# dk_night_sky.shader
A light-space post-process pass that lays the Milky Way over the desert night sky: on sky pixels only (where no surface was drawn), the view ray is turned into coordinates along a tilted great circle and the kit's galactic-band panorama (`textures/dk_milky_way`) is added on top of the sky's own stars and moon, fading toward the horizon. `amount` follows the night (0 by day, when the pass is not registered at all). One full-screen pass with one texture read on sky pixels; desertKit's `DesertSky` module drives it.
# desertKit tests
Checks that the same settings give the same desert (heights, walk and placement fingerprint), that every desert kind with every dune shape plans all six stops inside the ground with a track no steeper than a walk up loose sand, a wadeable oasis pool and a level camp, that dune seas have real slip faces near the angle of repose and taller settings make taller dunes, and that the painted surfaces each carry a footstep class and their weights sum to one. It runs on the CPU numbers only (no terrain cook, no scene, no rendering). Run with `zero tests run desertKit` in edit mode, in a world of its own (#23636).
# dk_milky_way
A 2304x768 astrophotography panorama of the Milky Way band across a black sky (warm golden core, blue-white star fields, dark dust lanes), generated with image_gen. desertKit's DesertSky lays it along a tilted great circle of the night sky in the dk_night_sky post pass.
# dress-a-desert
A workflow that dresses a desert scene with desertKit from bare sand to a walkable, lit place, in the order a real desert forms. It is the program behind the guide **Dress a desert step by step**: the guide explains each stage, and this runs them, one agent per stage, each request carrying everything it needs.
1. **Wind: the sand sea.** Builds (or re-sets) the scene's `Desert` from the settings you start it with, checks that the dune crest gives a view of the arch, the oasis and the town, and keeps a seed that works.
2. **Skin: the ground.** Checks ripples, slip faces, rock and the track near and far, the sand colour, and that the ground switches with the world look.
3. **Bones and water**, side by side: hero rocks sunk into the sand at the feet of outcrops, and the oasis ring of reeds, grass, flowers and date palms round the pool.
4. **What people left:** caravan leftovers along the walk and extra half-buried ruins, with doorways kept clear and walked through.
5. **Air and light:** a shared `WorldClock` and a `DesertAtmosphere`, checked at dawn, midday, dusk, night and in a dust storm.
6. **Walk it:** plays the route from the camp to the town and lists what blocks it; **Fix** runs only if something did.
```
zero workflow start --name dress-a-desert
zero workflow start --name dress-a-desert --args '{"kind":"oasisValley","seed":12,"dunes":"star"}'
zero workflow next --runner me
zero workflow answer --request <id> --value '<the answer, in the shape the request asks for>'
```
Every argument is optional: `scene`, `kind`, `dunes`, `size`, `duneHeight`, `density`, `seed`, `sand`, `look`. The run answers with the seed it kept, what each stage added, picture paths for every time of day and the storm, and what the walk found and fixed. Everything a stage adds goes into the scene's `build.luau`, so it survives a reload.
It needs desertKit installed (a stage installs it if the world lacks it) and a scene with a player prototype for the walk.