desertKit.package
- .metadata83 B
- AudioMaster.module
- CaravanHunt.component
- Desert.component
- DesertAmbience.module
- DesertAtmos.module
- DesertAtmosphere.component
- DesertBuilder.module
- DesertCliffs.module
- DesertField.module
- DesertFootsteps.module
- DesertHorizon.module
- DesertLayout.module
- DesertRender.module
- DesertRules.module
- DesertShape.module
- DesertSite.module
- DesertSky.module
- DesertSurfaces.module
- DustStorm.module
- HeatShimmer.module
- HuntEvents.module
- README.md16.1 KB
- audio
- guides
- package.yaml1.7 KB
- reuse-review.md5.3 KB
- shaders
- tests
- textures
- workflows
This package holds more than this page lists. See all of its files in its world.
README.md
desertKit
Drop a whole walkable desert into any world with one component. Pick a size, how tall the dunes stand, how densely things grow and a seed, each one setting, and desertKit builds a sea of sand dunes with sharp crests, steep lee slip faces and wind ripples you can see up close and from far away, varnished sandstone outcrops and a natural rock arch, an oasis pool ringed by date palms and reeds, and the ruins of an old walled town half swallowed by the sand, joined by a signposted walk from a caravan camp. Pick the kind of desert (an endless dune sea, rocky mesa country, an oasis valley, a salt pan, a city buried in sand) and the dune shape (crescent, linear, star, transverse, barchanoid, parabolic, dome or reversing) with one more setting each. It comes with dawn, midday, dusk and night on a shared clock, heat shimmer in the midday air, dust storms that roll in, ambience that follows the time of day and where you stand, and footsteps that sound different on sand, rock and at the oasis edge. The same seed is the same desert for every player, on desktop and in the browser.
Version 1.0.12. Depends on desertProps 1.0.6 (palms, plants, cacti, rocks, arches, ruins, caravan leftovers), desertMaterials 1.0.4 (the surfaces), tropicalKit 1.0.4 (its deterministic noise, terrain grid, cloud domes and sand footprints), worldClockKit 1.6.3 (the shared clock and weather) and soundstage 2.1.2 (the sound); installing desertKit brings them all. The ground is the engine's own terrain. It works from wherever it is installed (a world's root or deps/).
Drop a desert into your world
Install desertKit from ZeroMind. Then, in an empty world, open scenes/main.scene/build.luau and paste this inside content(), just before its closing end (it uses the spawn entity the starter scene already makes):
local DESERT = { size = 640, kind = "duneSea", duneHeight = 18, density = "normal", seed = 7 }
entity.spawn("Desert").component.add("desertKit.Desert", DESERT)
-- one shared clock, and the desert's light, weather and sound on it
entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 24, startHour = 9, skyMode = "engine" })
entity.spawn("DesertAtmosphere").component.add("desertKit.DesertAtmosphere", { stormEveryMinutes = 15 })
-- players arrive at the caravan camp
local sp = require("desertKit.DesertBuilder").spawnPoint(DESERT)
spawn.localPosition = { sp[1], sp[2], sp[3] }
spawn.localRotation = { 0, math.sin(sp[4] / 2), 0, math.cos(sp[4] / 2) }
The first build of a new setting shapes and paints the ground (about half a minute in the editor) and saves it into your world under desertLands/; after that every machine loads it. Build it in the editor before you publish. The starter scene's floor, lamps and crate end up under the dunes, so delete those lines from build.luau too. Press Play: you arrive at the caravan camp at the start of the walk.
What you set
| Setting | Values | What it does |
|---|---|---|
size | 240-1600 (m) | the side of the walkable square; the dunes carry on to the horizon past it |
kind | duneSea, mesaCountry, oasisValley, saltPan, buriedCity | an endless sea of tall dunes; gravel plains between flat-topped sandstone mesas, hoodoos and cacti; a broad valley with a big spring-fed oasis between cliffs; a white cracked salt flat ringed by pale dunes; a large walled town swallowed by advancing dunes |
dunes | auto, crescent, linear, star, transverse, barchanoid, parabolic, dome, reversing | crescent (barchan) dunes with horns trailing downwind; long sinuous seif ridges; tall star dunes with three to five arms; long ridges across the wind; wavy ridges of linked crescents; U-shaped dunes with arms trailing upwind; low round mounds with no slip face; ridges with a slip face on both sides; auto takes the kind's own |
duneHeight | 2-60 (m) | how tall the biggest dunes stand |
density | sparse, light, normal, dense, lush | how thickly palms, plants, shrubs, rocks and litter stand |
seed | any whole number | each seed is a different desert; the same seed is always the same one |
sand | auto, ochre, red, pale | the dune sand's colour: Saharan ochre, Namib red, gypsum pale |
look | auto, real, painted, toon, lowpoly, pixel | how every prop and the ground are drawn; auto follows the world look |
route, spawnAtCamp, horizon | true/false | the signposts at the stops; moving the scene's player spawns to the camp; the dunes beyond the edge |
quality | 0.3-1 | draw distance (the browser caps it at 0.6; nothing moves or stops colliding) |
keepClear | text, "" by default | ground to keep free of props: corridors x1,z1,x2,z2,halfWidth and circles x,z,r in world metres, split by ; (see below) |
Keep a race track (or a road) clear
keepClear keeps every prop the desert places off the ground you name: palms, reeds, shrubs, cacti, rocks, litter, outcrops, hoodoos, ruins, the arch, the camp pieces, the far buttes and the signposts. Any prop whose footprint (its catalog radius times its scale) reaches into a corridor or a circle is left out, together with its collider. The ground itself is not touched: the dunes, the walk and the saved ground under desertLands/ stay exactly as they are, so no ground is cooked again.
Each entry is either a corridor x1,z1,x2,z2,halfWidth (the capsule around the segment from x1,z1 to x2,z2, halfWidth metres either side) or a circle x,z,r. Entries are split by ;. DesertBuilder.clearPath(points, halfWidth, closed) turns a track's points ({x, y, z} or { x =, z = }, y ignored) into the string: one corridor per side, closed back to the first point unless closed is false.
local Builder = require("desertKit.DesertBuilder")
local track = { { x = -120, y = 0, z = -80 }, { x = 140, y = 0, z = -80 }, { x = 140, y = 0, z = 90 }, { x = -120, y = 0, z = 90 } }
desertEntity.component.get("desertKit.Desert").keepClear = Builder.clearPath(track, 14) .. ";0,0,25" -- the loop, plus the pits
The same seed and the same keepClear give the same desert on every machine (desert.stats.fingerprint matches); desert.stats.keptClear counts the props left out. Builder.parseKeepClear(s), Builder.inKeepClear(zones, x, z, r) and Builder.keepClearFilter(instances, kinds, zones) are there for your own placement.
Switch the style with one change
Every prop and surface comes in five looks: real, painted (hand painted), toon (cartoon, cel shaded), lowpoly and pixel. Switch the whole world at once:
require("desertMaterials.DesertLook").set("toon") -- this machine
-- or for every player: a synced setting in your scene
entity.spawnSynced("Look").component.add("desertMaterials.DesertLookSetting", { look = "toon" })
It restyles everything at once: every prop, the signs, the oasis water, the dunes beyond the edge and the ground itself (the saved ground is shaded in the new look on the spot; nothing is cooked again, so one saved ground serves all five looks). A Desert's own look field pins that desert to one look whatever the world look is. DesertLook is the same switch as tropicalKit's, so a world holding both switches both.
Walk it
Every desert plans the same walk on its own ground, signposted: Caravan Camp (where you arrive: a tent, a fire ring that burns at night, crates, a lantern), up the windward slope to the Dune Crest (the arch, the palms and the town below), past the Lost Cart, under The Arch (a natural sandstone arch across the track), down to Mirage Wells (the oasis pool, date palms, reeds, a mud bank) and up through the gateway into The Buried Town (perimeter walls and towers, a street of roofless houses and a colonnade, the well in the plaza and a fallen statue head, giant stone feet beyond). The track is graded to a walking slope. Read the stops from code:
local Site = require("desertKit.DesertSite")
local site = Site.current() -- the desert on this machine (nil until built)
for _, poi in site.pois do print(poi.id, poi.name, poi.x, poi.y, poi.z) end
print(site:surfaceAt(x, z), site:footstepAt(x, z)) -- sandDune / sandSlipFace / mudWet ...; sand / softSand / rock / mud / water ...
print(site:zoneAt(x, z).oasis, site:heightAt(x, z), site:waterAt(x, z))
Time of day, weather and sound
local Atmos = require("desertKit.DesertAtmos")
Atmos.setTime("dusk") -- dawn | midday | dusk | night, for every player
Atmos.dustStorm({ duration = 120 }) -- a dust storm rolls in, blows through, then clears
See DesertAtmosphere and DesertAtmos for every field and call: the colour grade per time, the dust haze, the heat shimmer (strongest at midday, low over the ground and the horizon), the storm, the ambience and the footsteps.
What each time looks and sounds like: dawn, a violet sky and peach light with a lilac mist in the troughs, the night's crickets and frogs fading under still air and a busy bird chorus; midday, bleached sand and short hard shadows, heat shimmer, the wind up and a raptor overhead; dusk, a warm orange sunset with the sun just above the horizon, amber dunes and long shadows; night, silver-blue sand under the Milky Way, a cold breeze and the frogs at the oasis. A dust storm shows as a towering wall of dust on the horizon that rolls in over the approach (45 s unless you say otherwise), swallows everything in orange dust, blows for its duration and clears. It is shared: every player sees the same front at the same place, and it runs its full course even if the player who started it leaves. Past the walkable square the dunes carry on to the horizon in every direction.
A caravan treasure hunt
entity.spawn("CaravanHunt").component.add("desertKit.CaravanHunt", { count = 8, seed = 1 })
Relics a caravan lost lie along the walk, glinting; walk over one to pick it up, for everyone; when the last is found the chest by the town's well unlocks. require("desertKit.HuntEvents").on(fn) tells a game when a relic is found, all are found or the chest is opened, so it can give XP or unlocks. The guide Make a desert level: a caravan treasure hunt that ends at the oasis ruins builds it step by step, with saved player levels.
Every player, the same desert
The desert's heights are computed on the CPU from integer-hash noise using only addition, multiplication, division and square roots, so they are bit-identical on every machine, desktop or browser, and are written into the engine terrain as they are. The walk, the town and every placed prop are pure functions of those numbers and the seed, and the colliders are built from them. desert.stats.fingerprint (from the Desert component's :desert()) is a short code of every placement: equal fingerprints on two machines mean the same desert. Time and weather are worldClockKit's shared clock; footsteps are soundstage's, heard from every walker.
What is inside
- Desert (component), DesertBuilder (
build,planFor,spawnPoint,keyFor,clearPath,parseKeepClear): build and tear down a desert, and keep corridors clear of props. - DesertField: the shape as plain numbers (the five kinds, the eight dune shapes, the walk's line, the pool, the arch band, the town floor).
- DesertShape, DesertSurfaces: the ground written into the engine terrain and painted with eight surfaces.
- DesertLayout: the stops, the graded track, the camp, the cart, the arch and the town plan. DesertRules: what grows and lies where. DesertRender: the props as instanced draws with three levels of detail. DesertHorizon: the dunes to the horizon. DesertCliffs: real layered rock over every cliff (the terrain alone would smear its paint down them). DesertSite: questions about the ground.
- DesertAtmosphere (component), DesertAtmos, HeatShimmer, DustStorm, DesertSky, DesertAmbience, DesertFootsteps: light, weather, shimmer, storms, sky, sound and footsteps.
audio/: the kit's own recordings. - CaravanHunt (component), HuntEvents: the treasure hunt example.
- Guides: How do I add a desert with sand dunes, an oasis and ruins to my world, Make a desert level: a caravan treasure hunt that ends at the oasis ruins and Dress a desert step by step. Tests:
tests/desertKit.testSuite.
Built on, and how well it fit
reuse-review.md (in this package) rates every installed package the desert is built on, from 5 (dropped in unchanged) to 1 (thrown away and rewritten), says how much of the desert is installed and how much is new, and lists what was built new. The dress-a-desert workflow (workflows/) runs the guide Dress a desert step by step as a job: zero workflow start --name dress-a-desert.
Changes
1.0.12
- New
keepClearsetting on the Desert component: corridors (x1,z1,x2,z2,halfWidth) and circles (x,z,r) the desert keeps free of every prop it places, for a race track, a road or a landing pad. The ground is unchanged and is not cooked again.DesertBuilder.clearPath(points, halfWidth)makes the string from a track's points. Five new tests cover parsing, the overlap test,clearPath, the unchanged ground name and a scatter with a corridor. - Depends on worldClockKit 1.6.3 (was 1.4.7), whose clock also survives a scene swap.
- Fixed: after a scene swap,
DesertAtmosphereraised "entityRef: entity ... does not exist" every frame.entity.findAllcan still list an entity being despawned; the sky lookup in DesertSky and the campfire scan in DesertAtmos now pass over entities they cannot read and look the sky up again when the one held is gone.
Known limits
- The first build of a new setting cooks the ground (half a minute on a desktop); it is meant to happen in the editor, and a world that ships its saved ground never cooks it in a player's browser. Every machine still computes the heights once when it builds (a few seconds; longer in the browser).
- The engine terrain paints from above, so the kit lays a rock skin over every steep rock face (DesertCliffs). Steep ground that is not rock (a dune crest, the walk's graded cut) stays terrain-painted and can look a little stretched up close.
- In mesa country, where a mesa reaches the edge of the walkable square, the dunes beyond the edge ramp down from it and leave a thin wedge at the far corners; it shows only from high above, outside the square.
- Two engines signed in to one account show up as one player (#14448), so a two-player test needs two accounts.
- Frame rate drops when a world holds many shared things (#20750); the desert keeps its props as instanced draws, not shared entities, for that reason. Models load slowly on the web (#22751), so a desert takes longer to appear there, and frames are slow while the engine makes previews (#22778).
- A terrain redraws all its sun shadows every frame (#23704), so the editor is slow with a desert open; props cast shadows only from their nearest level to keep that cost down.
- The author cannot start a web build (#20946): the browser frame rate (about 30 fps is the target) and the look there are checked by the person who commissioned the kit, not measured here.
- Running the test suites in a shared editing room changes the scene for everyone in it (#23636); run them in a world of your own.
- Installing brings desertProps, desertMaterials, the tropical stack, the clock, the sound kit and seven material collections, so the first install can take several minutes (#21420); the ZeroMind listing text can trail the newest release (#19258), and a dependency removed from a nested package can come back on the next install (#23635).
- Republishing a changed copy: checking what changed is slow in a world this size (#23706), and publishing while previews are still being made makes the release change again once they land (#23611, #23686). Wait for the previews before you push.