Log inGet started
World

Mirage Wells: Desert Dunes, Oasis and Ruins Kit

README.md

desertProps

Desert props for any world, each placed with one component: date palms (tall, leaning, young, offshoot clumps, dead snags), doum and desert fan palms, oasis reeds, cattails, papyrus, rushes and grass, desert flowers and bunch grasses, saguaro, barrel, prickly pear, cholla, organ pipe, agave and aloe, creosote, saltbush, tamarisk and other shrubs, umbrella acacia and joshua trees, tumbleweeds and palm litter, plus boulders, sandstone formations and arches, ruins and caravan leftovers. Every prop has near, middle and far versions, 3 seeded shapes, colliders tagged with a footstep surface, and draws in five looks (real, painted, toon, lowpoly, pixel) that switch world-wide with one call. Materials come from its dependency desertMaterials; geometry kits from tropicalProps.

Quick start

Install desertProps (it brings desertMaterials and tropicalProps). In any world:

-- a date palm, and a leaning one over the water (+Z)
entity.spawn("palm", { position = { 0, 0, 0 } }).component.add("desertProps.DesertProp", { kind = "palmDate", variant = 2 })
entity.spawn("palm2", { position = { 5, 0, 2 } }).component.add("desertProps.DesertProp", { kind = "palmDateLeaning" })

-- reeds at its foot; shape and turn picked from a seed (for scattering)
entity.spawn("reeds", { position = { 2, 0, 4 } }).component.add("desertProps.DesertProp", { kind = "reedClump", seed = 41 })

-- every prop that follows the world look (look = "auto", the default) turns cartoon:
require("desertMaterials.DesertLook").set("toon")

-- or synced to every player: one entity of the scene carries the look
entity.spawn("Desert Look").component.add("desertMaterials.DesertLookSetting", { look = "lowpoly" })

Add a desertProps.PropGallery to an entity far from your playable area to see every kind side by side, one band per look ({ looks = "real", kinds = "palm,cactus" } narrows it).

The package works from wherever it is installed (the world root or deps/<world>/): its files reach each other with ~. names, its dependencies by package name, and the bakers find their folder from their own location.

Guides

  • How do I add date palms, cacti, oasis plants, desert shrubs, rocks and ruins to my world? Placing a prop, every kind by family, variants and seeds, looks, colliders and footsteps, scattering, the gallery.
  • Plant a small oasis: date palms, reeds and desert scrub round a pool. From an empty world to a planted oasis corner, step by step.

DesertProp

Builds one child entity per part (a Model whose mesh swaps between three LODs by screen size, every part together) and static colliders, all temporary and rebuilt from the synced fields, so every peer builds the same prop. Changing any field rebuilds.

FieldDefaultMeaning
kindpalmDateany kind Props.kinds() lists (tables below)
lookautoauto follows DesertLook; or real, painted, toon, lowpoly, pixel
variant1baked shape, 1..3 (wraps); used when seed is 0
seed0non-zero: picks the variant and a yaw turn from the seed
detailautoauto picks near / mid / far by screen size (one test per prop every 6 frames); near, mid, far pins one
collidetruebuild the colliders, each tagged with the attribute desertSurface = the entry's footstep class

real, painted and pixel draw the same geometry under that look's material; toon draws a chunkier bake (fewer, broader fronds and leaves, stacked trunks); lowpoly a faceted flat-shaded bake.

Kinds

Palms (category palm, footsteps wood, trunk capsule chains)

KindWhat it is
palmDateTall date palm 10-16 m: diamond-knobbed trunk, dense crown of 30-36 stiff blue-green fronds with V-raised leaflets and basal spines, dry-frond skirt, 4-7 orange-brown date bunches
palmDateLeaningDate palm leaning 20-32 degrees toward +Z (the water), curving back up; 8.5-13 m
palmDateYoung2-4 m: a knobbly stub and a fountain of upright fronds
palmDateClusterOffshoot clump: a 9-12 m mother palm and 2-4 younger trunks and trunkless offshoots, leaning apart
palmDateDeadv1 collapsed dry crown, v2 headless silvered snag with a splintered top, v3 tall grey trunk with a few dry fronds
palmDoumDoum palm: a trunk forking into 2-4 branches, each crowned with stiff fans, dead fans and brown fruit
palmFanDesertWashingtonia: stout column 9-14 m, crown of split-tipped fans, thatched skirt of dead fans (v1 long, v2 trimmed, v3 burnt)

Oasis plants, grasses and flowers (category plant, no colliders)

KindWhat it is
reedClumpCommon reed, 26-36 culms 2-3 m with drooping blades and feathery plumes
cattailStrap leaves and 3-6 brown velvet heads
papyrus12-22 splaying stems topped by starburst umbels
grassOasis5-8 fresh green tufts
rushWaterDense thin upright rushes at the water line
flowerDesertSmall blooms on a leafy tuft: v1 yellow, v2 purple, v3 a mixed patch
grassDesertTuftStraw bunch grass
grassDuneTuftSparse splayed dune grass (footsteps softSand)

Cacti and succulents (category cactus)

KindWhat it isCollider
saguaroRibbed column 6-11 m, v1 three arms, v2 one, v3 fivecapsule chain (column + arms)
saguaroYoungArmless column 1-3 m (v3 an arm bud)capsule chain
barrelCactusSquat ribbed barrel leaning toward +Z, crown of yellow flowerscapsule
pricklyPearChains of oval pads with bloomssphere
chollaFuzzy pale-gold jointed stemscapsule
organPipe7-14 columns 2-5 m from one basecapsule
agaveRosette of thick blue-grey leaves; v3 with a 5 m flower polesphere
aloeFleshy recurved rosette(s) with orange flower spikesnone

Shrubs (category bush, footsteps grass, no colliders) and trees (category tree)

KindWhat it is
creosoteBushOpen vase of slender grey stems, small dark leaves at the twig ends (v2 flowering)
saltbushDense silvery grey-green mound
tamariskFeathery small tree 3-4.5 m, drooping sprays, pink plumes (v1, v3)
desertBroomUpright green switch twigs
shrubDeadBleached bare twig tangle
acaciaUmbrellaFlat-topped thorn acacia, layered canopy 8-10 m across (trunk and limb capsules)
joshuaTreeShaggy forking arms ending in balls of dagger leaves (trunk capsule)

Litter (category litter, no colliders)

tumbleweed (0.8-1.1 m), tumbleweedSmall (0.4-0.6 m), deadBranch (silvered, 1.6-2.8 m), palmFrondFallen (a dry date frond on the sand), dateLitter (fallen dates, a fruit stalk, loose leaflets).

Rocks, formations, ruins and caravan leftovers

<!-- STONE HALF: the agent building RockCatalog fills this section (kinds tables for rock, formation, ruin, camp; colliders; budgets). -->

Categories rock, formation, ruin and camp (50 kinds, registered by RockCatalog). Walk-through and walk-on pieces carry mesh colliders with one collision mesh per variant; footsteps are rock on natural stone, stone on ruins, wood on timber.

Rocks (category rock, footsteps rock)

KindWhat it isCollider
boulderSandstoneLayered orange sandstone block, rounded strata edges, jointed faces, sand-dusted foot (1.6-3.8 m)mesh
boulderVarnishedAngular fractured block under black-brown desert varnish streaks (1.3-3.2 m)mesh
boulderRoundedSmooth wind-rounded corestone with faint exfoliation, bigger ones two-lobed (1.2-3.4 m)mesh
rockCluster3-5 jointed blocks fused into one heap (3.5-6 m)mesh
rockSlabBroad tilted tabular slab, one end buried; walk on it (2.6-5 m)mesh
pebbleScatterDesert pavement: 40-96 dark varnished flat pebbles over 1.6-3.2 mnone
ventifactWind-polished three-faceted stone, fluted along the wind (0.5-1.4 m)sphere

Formations (category formation, footsteps rock)

KindWhat it isCollider
archNaturalThe big walk-through arch: a thick, irregular, slightly lopsided span of cross-bedded sandstone with overhanging ledges, a lumpy spalled underside and varnish streaks running down from its ledges, over a leaning opening 8.6-10 m wide and 7.6-8.8 m high, span 21-25 m along X, on uneven legs and stepped buttresses. Walk through along Z; origin on the ground under the opening's centremesh, opening clear
archSmallWindow arch: a fin 11-15 m long, 6.5-9 m tall, with a 3.6-5.2 m windowmesh
outcropLayered2-4 tiers stepping back into ledges and undercuts, cut by joints (6.5-15 m)mesh
hoodooBanded spire 5.5-11.5 m necking under a pale caprock, on a talus moundmesh
hoodooCluster3-5 capped hoodoos on one mound (9-13 m across)mesh
rockFinThin ragged blade 9-14 m long, 6-10 m high, notched by jointsmesh
mushroomRockSand-blasted pedestal under a broad pale head (3-5.5 m)mesh
cliffWall12 m layered cliff face 10-16 m tall facing +Z; tiles along X (shared edge profile at x = +-6), top runs 4 m backmesh
mesaButteHorizon landmark: talus apron, sheer banded cliff, flat caprock; v1 butte 40 m, v2 table mesa ~115 x 68 m, v3 two-tiermesh (far LOD)

Ruins (category ruin, footsteps stone)

KindWhat it isCollider
ruinWallMudBrick4 m mud-brick wall along X, top broken in brick steps, eroding plaster, 2.2-3.6 m tallmesh
ruinWallCornerL-shaped corner, 3 m arms along +X and +Zmesh
ruinWallStone4 m coursed ashlar wall, stepped broken top, fallen blocksmesh
ruinWallWindow4 m mud-brick wall with an arched window (v3 also a niche)mesh
ruinGatewayStone gateway: coursed piers, round arch with keystone, entablature, engaged columns; opening 2.6-2.9 m x 4.3-4.8 m; walk through along Z (v2 broken side, v3 pediment)mesh, opening clear
ruinArchwayMud-brick archway 4.4-5 m wide, arch 2-2.4 m; walk through along Zmesh, opening clear
ruinColumnFluted column 4.8-5.6 m with base and capital (v3 snapped)capsule
ruinColumnBrokenStump 1-2.3 m with a jagged top (v3 a drum beside it)capsule
ruinColumnFallen3-4 drums lying along X, half sunk (v2 with its capital)mesh
ruinTowerCrumbling watchtower 4-4.6 m square, 6.8-8.8 m tall, door on +Z, slit windows; walk inmesh, door clear
ruinHouseRoofless room 5.5-7 x 4.5-5.5 m, doorway on +Z, window on +Xmesh
ruinDomeBrokenBleached pavilion, an arch on every side, dome half fallen in; walk inmesh
ruinStairs6-8 worn steps rising toward -Z to a landing, cheek wallsmesh (stepped)
ruinFloorTiles4 x 4 m flagstones with a band of faded glazed tilesbox
wellStoneRound coursed-stone well, timber frame, pulley, rope, hanging bucketmesh
statueHeadHuge fallen carved head (3.2-4 m) on its side, striped headcloth (v2 nose broken)mesh
statueFeetGiant feet and snapped shins on a stepped plinthmesh
obeliskFallen7.2-8.8 m obelisk snapped in two, incised glyph columnsmesh
amphoraTwo-handled terracotta jar 0.85 m: upright, leaning, broken on its sidecapsule
potteryShards6-14 curved terracotta sherdsnone

Caravan leftovers (category camp)

KindWhat it isCollider
crateWoodenSlatted plank crate 0.7-0.95 m (v3 burst open)box
barrelWoodenStaved barrel, iron hoops: standing, on its side, sprungmesh
cartBrokenTwo-wheeled cart tipped where a wheel came off, shaft snapped, the wheel beside itmesh
wheelBrokenSpoked wheel with iron tyre, half buried, spokes missingnone
tentBedouinTattered striped goat-hair tent 6-7.2 x 4-4.8 m on poles, back wall to the sand (-Z), open to +Z; walk undermesh (poles)
rugRolledRolled red woven rug (v2 half unrolled)none
campfireRingSoot-blackened stone ring, ash bed, charred crossed logs; light hooknone
camelSkullBleached camel skull (v2 with its jaw)none
bonesRibcageSpine and curved ribs half sunk (v2 with leg bones)none
saddleBagsTwo leather bags on a strap, brass bucklesnone
lanternBrassPierced brass lantern: on the sand, or hanging from a crook pole; light hooknone
signpostWooden~2 m post with a 0.9 x 0.3 m board facing +Z and arrow boards; label face at (0, 1.45, 0.1)box
treasureChestClosed chest 0.9 x 0.68 x 0.6 m: vaulted lid, iron bands, brass lock plate on +Z; origin on the groundbox
waterskinGoatskin waterskin with a tied necknone

Hooks for night and for labels: RockCatalog.LIGHTS (campfireRing at (0, 0.45, 0), lanternBrass per variant; RC.lightOffset(kind, variant)), RockCatalog.SIGN_FACE (the signpost board face), RockCatalog.shape(kind, variant) (baked size, arch / gateway opening, tower door).

Budgets (stone half, triangles, real form, variant 1)

LOD0LOD1LOD2
archNatural17.6-18.9k4.4-4.8k950-970
other formations (window arch, outcrop, hoodoos, fin, mushroom)4.3-11.8k1.1-2.5k240-510
cliffWall / mesaButte7.3k / 3.4k1.6k / 740190 / 150
boulders, cluster, slab, ventifact0.9-3.6k220-85050-180
mud-brick walls, archway, house, tower3.3-10.4k0.7-2.4k150-450
stone wall, gateway, columns, stairs, floor0.7-6.2k170-1.6k12-420
well, statue head / feet, obelisk6.6-14.1k1.7-3.4k340-710
camp kinds, pottery0.1-4.4k50-1.2k4-400

1-3 parts per kind (stone body + pale cap, brick + plaster, stone + carved trim, wood + iron + brass, ...); collision meshes 24-3.6k triangles.

<!-- /STONE HALF -->

Props API

local Props = require("desertProps.Props")        -- "~.Props" inside the package
Props.kinds() -> { string }                       -- every kind, registration order
Props.kindsOf(category) -> { string }             -- palm, plant, cactus, bush, tree, litter, rock, formation, ruin, camp
Props.info(kind) -> Entry?                        -- { kind, category, variants, radius, height, collider?, surface?, walkable?, trunks?, description }
Props.parts(kind, { look?, variant?, lod? }) -> { { mesh, material, part } }   -- same parts, same order at every LOD
Props.register(entry, partsFn)                    -- how a catalog adds kinds

info.radius is the footprint radius (metres) to space props by; info.surface the footstep class. info.collider is the kind's one collider (capsule radius/height/offset, sphere, box size/offset, or mesh with meshes[variant]). Palms, saguaros, the acacia and the joshua tree also carry info.trunks[variant] = { { x0, y0, z0, x1, y1, z1, r }, ... }: capsule segments (local metres) following that variant's baked trunk(s), columns or limbs, which DesertProp builds as a capsule chain instead.

For thousands of props draw Props.parts instanced: one draw per part per LOD, 1-4 parts per vegetation kind, every part of a kind sharing one bounding box.

Budgets (vegetation, triangles, worst variant, real form)

LOD0LOD1LOD2
date palm / leaning9.5-11.9k2.3-2.7k354-386
young / dead date palm2.7-4.1k574-76890-160
date palm clump (3-5 trunks)19.0k4.7k546
doum palm (2-4 crowns)13.9k4.1k380
desert fan palm9.7k2.7k294
reeds, cattail, papyrus, rushes296-1960104-64032-116
grasses, flowers42-1926-42culled
saguaro6.1k1.8k288
organ pipe8.0k2.5k324
other cacti, agave, aloe748-1620248-76836-180
shrubs1.3-3.8k516-130054-158
acacia, joshua tree1.1-1.8k650-994248-250
litter128-58842-186culled-33

The toon form is about a quarter of real and the low form a tenth; far LODs of small plants are culled (the empty mesh).

Mesh contract

Real-world metres, +Y up, origin at the ground contact. Leaning palms lean toward +Z; barrel cacti lean toward +Z (the sun). Vertex RGB is a tint the material multiplies its albedo by; vertex alpha is the wind weight on foliage cards (0 at the base, 1 at the tips; near 0 on litter) and 1 on solid parts (trunks, cactus bodies, pads, stalks, wood, dates). Front faces are counter-clockwise and agree with the normals. Every part of a prop shares one bounding box, so all parts swap LOD together.

UVs: cards (leaflets, fan segments, reed blades and plumes, blooms, small leaves, acacia sprays, agave leaves) carry one item per 0..1 square (u across, midrib u = 0.5, v = 0 at the base) and never leave 0..1 (card textures are clamped); grass is tuft cards (v = 0 at the ground); tumbleweeds are shells mapped u around, v pole to pole; bark, cactus skin and wood wrap u once per metre of girth with v = metres along; cactus pads map one pad card per face. Leaf-material stalks sample the opaque midrib strip of the leaf texture. No texture is shipped here: every surface comes from desertMaterials.DesertMaterials.get(surface, { look }).

Regenerating

Meshes are generated once and baked into the package (meshes/flora/<kind>/), read through the generated literal index BakedFlora, so installing costs no generation and gameplay never resolves a computed asset name.

  • Vegetation: edit FloraPalms / FloraPlants / FloraCacti (shared helpers FloraKit, on tropicalProps' VegGeo; catalog FloraCatalog), then in a task require("desertProps.FloraBake").run() (all, about two minutes) or .run({ kinds = { "palmDate" }, forms = { "toon" } }); .report() answers the triangle table. Mesh names: <kind>_<form>_v<n>_l<lod>_<part>, forms real, toon, low.
<!-- STONE HALF: RockCatalog regeneration notes go here. -->
  • Stone and built kinds: edit RockGen (rocks, formations), Ruins or Camp (shared helpers RockGeo: signed-distance shapes meshed by surface nets at a triangle budget, strata and varnish tints, lathes, dressed blocks, on tropicalProps' ShoreGeo; catalog RockCatalog), then in a task require("desertProps.RockBake").run() (all 50, about three minutes) or .run({ kinds = { "archNatural" } }); .status() answers progress. Meshes land under meshes/rock/<kind>/ with the same names (<kind>_<form>_v<n>_l<lod>_<part>, plus <kind>_v<n>_col collision meshes) and the literal index BakedRock. zero tests run desertRocks checks the stone half (bake completeness, budgets, colliders, clear walk-through openings, ground contact, hooks, determinism).

Tests: zero tests run desertProps (edit mode) checks every kind x look x variant x LOD, contract categories and surfaces, colliders and trunk chains, budgets and DesertProp rebuilds.

Known limits

  • The props were measured in the desktop editor only. The author cannot start a web build (#20946), so the frame rate in the browser is checked by whoever commissioned the package; models load slowly on the web (#22751), so a scene full of props takes longer to appear there.
  • Every DesertProp is a shared entity. A world that places thousands of them as entities loses frame rate to keeping them in sync (#20750); for big scatters draw Props.parts instanced (as desertKit does) and keep entities for the few props players touch.
  • Installing brings desertMaterials and its seven material packages plus tropicalProps, so the first install can take a few 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).
  • Running zero tests run desertProps or desertRocks in a shared editing room swaps the open scene for everyone in it (#23636); run them in a world of your own.
  • Re-baking writes about 3000 meshes. Frames are slow while the engine makes their previews (#22778), publishing before the previews finish makes the release change again once they land (#23611, #23686), and checking what changed takes a while in a world this size (#23706). Wait for the previews before you push.