Mirage Wells: Desert Dunes, Oasis and Ruins Kit
README.md
desertMaterials: Mirage Wells desert surfaces
Every surface of a desert behind one name, in five looks (real, painted, toon, lowpoly, pixel): 53 named surfaces, 46 of them the package's own generated materials (three more built at runtime from its textures), plus 14 terrain layers for the engine terrain. Warm ochre dune sand with fine wind ripples, crisp rippled sand, granule megaripples, smooth slip faces, pale gypsum and rust-red sand, trodden tracks, desert pavement, cracked salt flats and playa mud cracks; layered orange sandstone whose strata follow world height and black desert-varnish streaks that run down from ledges; cream limestone, carved stone, ashlar, mud brick, earthen plaster, terracotta and faded turquoise tile; date palm bark and fronds, fan palm, dates, reeds, grasses, flowers, saguaro, prickly pear, agave, acacia and tumbleweeds; dead wood, planks, rope, canvas, rugs, leather, rusty iron, brass, bone, ash and clear teal oasis water. DesertMaterials.get("sandstoneVarnished", { look = "toon" }) returns a material you put straight on a Model or an instanced draw, DesertMaterials.terrainLayer("sandDune") a layer record for the engine terrain and DesertMaterials.footstep("sandSlipFace") the footstep class to play.
Install and use: install desertMaterials from ZeroMind. It brings tropicalMaterials (its shaders, card baker and the world look switch), the materialLibraryKit core and the Terra Firma, Bedrock, Heartwood, Scale and Feather and Brick and Mortar collections. Then require("desertMaterials.DesertMaterials") and ask for a surface by name and look, as in the first example. A DesertLookSetting component switches every desert surface (and every tropical one, since the switch is shared) between the looks for every player at once. Nothing in the package looks for a fixed path, so it works in a world's own folder, as a dependency of desertProps or desertKit, or as a library.
Guides: "How do I use desert sand, sandstone and oasis materials?" (getting a surface, the desert shading, the five looks and the one switch, terrain layers, footsteps, UV conventions, the full list) and "Make a desert ground with dunes, gravel, salt flat and an oasis edge" (an empty world to a baked desert ground with an oasis pool). Both ship in guides/; man or the Docs panel opens them.
First example
Runs as written in an empty world that installed only desertMaterials:
local DM = require("desertMaterials.DesertMaterials")
local sand = entity.spawn("dunePatch", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane",
material = DM.get("sandDune"), -- ochre dune sand with fine wind ripples
} } })
sand.localScale = { 4, 1, 4 }
local rock = entity.spawn("varnishedBoulder", { temporary = true, components = { Model = {
model = "@builtin::meshes.sphere",
material = DM.get("sandstoneVarnished"), -- orange sandstone, black varnish streaks
} } })
rock.localPosition = { 5, 1, 0 }
rock.localScale = { 2, 2, 2 }
local brick = entity.spawn("mudBrickBlock", { temporary = true, components = { Model = {
model = "@builtin::meshes.cube",
material = DM.get("mudBrick", { look = "toon" }), -- the same mud bricks, cel shaded
} } })
brick.localPosition = { -4, 0.5, 0 }
local frond = entity.spawn("dateLeaflet", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane",
material = DM.get("palmFrondDate"), -- one blue-green date palm leaflet (a card)
} } })
frond.localPosition = { 1.6, 0.9, 1 } -- standing on the sand, clear of the player at the centre
frond.localRotation = { 90, 0, 0 }
frond.localScale = { 0.45, 1, 1.8 } -- a leaflet card is four times as long as it is wide
print(DM.source("sandDune")) -- own:sandDune
print(DM.source("bone")) -- installed:organicMaterials.materials.bone
print(DM.source("oasisWater")) -- runtime:desertMaterials:oasisWater|real|w
print(DM.terrainLayer("saltFlat").albedo) -- desertMaterials.textures.saltFlat_albedo
print(DM.terrainLayer("sandDune", "toon").albedo) -- desertMaterials.textures.terrain_sandDune_toon_albedo
print(DM.footstep("sandSlipFace")) -- softSand
API
DM.get(surface, { look? }) -> material, never nil.lookisreal | painted | toon | lowpoly | pixel; nil or"auto"followsDesertLook.get(), an unknown look isreal, an unknown surface returns a neutral weathered wood.DM.surfaces()(the 53 names, terrain layers first),DM.group(s)(ground | rock | stone | built | bark | leaf | flower | fruit | cactus | camp | water),DM.isCard(s)(alpha-cut two-sided card),DM.palette(s)(flat lowpoly colour, linear{ r, g, b, a }).DM.source(surface, opts):own:,installed:,runtime:(a key ending|ois built from the package's textures,|wis water) orfallback:.DM.refresh()drops the cache.DM.terrainLayers()->sandDune, sandRippled, sandMegaRipple, sandSlipFace, sandPale, sandRed, sandPacked, gravelPlain, saltFlat, clayCracked, rockSandstone, rockVarnished, mudWet, grassOasis(a terrain carries at most eight).DM.terrainLayer(name, look?) -> { name, albedo, normal?, mask?, tiling, tint }: texture identities, metres per repeat and a linear tint, exactly whatterrain.write'ssurfacestakes. The mask uses the terrain layout (R metallic, G AO, B height, A smoothness); sand masks carry the ripple height,mudWet's is glossy.DM.terrainAlbedo(layer, look) -> guid?: a terrain layer's colour texture in a stylised look. Each look's textures share one size, so a ground cooked once can be shaded in any look at runtime from its own weight maps (desertKit's look switch does this); nil forreal.DM.footstep(surface)->sand | softSand | gravel | rock | stone | mud | water | wood | grass | salt.DesertLook(module):set,get,resolve,valid,onChanged,LOOKS; it istropicalMaterials.TropicalLook.DesertLookSetting(component): a syncedlookfield that callsDesertLook.seton every peer.SurfaceGallery(component): every surface side by side and labelled, one band per look and a row per family, each a tile with a ball on it (cards stand up).entity.spawn("surfaces", { position = { 0, 0, -60 } }).component.add("desertMaterials.SurfaceGallery", {});looksandgroupsnarrow it.
Every asset DM returns or builds from is resolved from a string literal in the generated DesertMaterialsTable, so the props and scenes that call it stay publishable.
Every surface
Own = a material this package ships, from generated textures. Installed = a collection material used as installed. Every surface also has painted, toon, lowpoly and pixel looks, built at runtime from the same textures.
| Surface | Looks like | Comes from |
|---|---|---|
| Ground (all 14 are terrain layers) | ||
sandDune | warm ochre-orange dune sand: broad swells with fine 10 cm wind ripples baked over them, quartz glints on meshes | own, 1024² tile, 2.5 m |
sandRippled | crisp asymmetric wind ripples about 10 cm apart, neutral ochre so a terrain can tint it | own, 1024² tile, 2 m |
sandMegaRipple | coarse granule ridges about 0.4-0.6 m apart, darker grit on the crests | own, 512², 2.5 m |
sandSlipFace | smooth lee-face sand, faint avalanche streaks, no ripples, neutral ochre | own, 512², 2.5 m |
sandPale | pale cream gypsum and quartz sand, soft ripples | own, 512², 2.5 m |
sandRed | deep rust-red iron-oxide sand | own, 512², 2.5 m |
sandPacked | trodden track: compacted sand, footprints, hoof marks, cart ruts | own, 512², 2.5 m |
gravelPlain | desert pavement: varnished dark pebbles over tan silt | own, 512², 2 m |
saltFlat | white salt polygons with raised crusty rims | own, 512², 3 m |
clayCracked | dry playa clay, curling mud-crack polygons | own, 512², 2 m |
rockSandstone | layered orange sandstone bedrock (sandstoneLayered's textures) | runtime on desertRock |
rockVarnished | sandstone with black varnish streaks (sandstoneVarnished's textures) | runtime on desertRock |
mudWet | dark glossy oasis mud with hoof prints and puddles | own, 512², glossy mask and clear coat |
grassOasis | patchy green grass over damp tan sand | own, 512², 2 m |
| Rock, stone, built | ||
sandstoneLayered | deep orange cross-bedded strata with cream bands; world-height strata on desertRock | own, 1024² albedo |
sandstoneVarnished | orange sandstone with black-brown varnish streaks running down; more streaks hang from ledges every 2.2 m on desertRock | own, 1024² albedo |
sandstonePale | cream-white capstone | own, 512² |
limestoneBleached | sun-bleached cream limestone for ruins | own, 1024² albedo |
stoneCarved | chisel-dressed bleached limestone: fine tooling, weathering pits, hairline cracks, no motif (statues, columns, carved trim) | own, 512² |
stoneAshlar | dressed sandstone block masonry | own, 512² |
mudBrick | sun-dried mud bricks with straw, eroded edges | own, 1024² albedo |
mudPlaster | eroding earthen render over brick | own, 1024² albedo |
terracotta | unglazed orange-red pottery | own, 256² |
tileGlazed | faded turquoise glazed tiles, crackled, chipped | own, 512², clear coat |
| Palms and plants | ||
palmBarkDate | date palm trunk: diamond rows of cut leaf-base scars | own, 512² (u round, v up) |
palmFrondDate | stiff blue-green date palm leaflet | own card 128×512 |
palmFrondDry | dead straw-brown leaflet | own card |
palmFanLeaf | fan palm segment | own card |
dates | glossy amber to orange-brown date clusters | own, 256², clear coat |
reedLeaf, reedPlume | reed blade, feathery tan-purple plume | own cards |
grassDry, grassGreen | straw desert tuft, green oasis tuft | own cards 256² |
flowerDesert | small yellow and purple desert blooms | own card |
cactusSkin | ribbed saguaro green with spine rows | own, 512² |
cactusPad | prickly pear pad with areoles | own, 256² |
agaveLeaf | one long blue-grey agave leaf with a terminal spine | own card 128×512 |
shrubLeaf, acaciaLeaf | grey-green shrub sprig, fine acacia leaflet spray | own cards |
tumbleweed | tiling alpha tangle of dry twigs (stylised looks cut it per look: painted and toon 0.62, lowpoly 0.55, pixel 0.58, so their blurred reads stay see-through) | own, 256² repeat |
| Wood | ||
twigDry | thin dry grey twig bark | own, 256² |
deadWood | sun-silvered cracked dead wood | own, 512² |
acaciaBark | dark fissured acacia bark | own, 512² |
woodWeathered | sun-dried grey-brown timber planks, deep cracks along the grain, rusty nail holes, sand in the joints | own, 512² tile |
| Camp | ||
rope, ironRusty | twisted rope, rusty iron | installed: tropicalMaterials |
canvas | sun-faded tent cloth | own, 256² |
rugWoven | faded red Bedouin woven rug | own, 512² |
leather | worn tan saddle leather | own, 256² |
brass | tarnished hammered brass, metallic | own, 256² |
bone | bleached bone | installed: Scale and Feather bone |
ash | campfire ash and charcoal | installed: Terra Firma ash |
| Water | ||
oasisWater | clear teal pool water: shallow aqua to deep teal by depth, slow ripples, Fresnel sky, sun glint | runtime on tropicalMaterials' tropicalWater |
UV conventions
- Cards fill 0..1, u across (midrib at u = 0.5), v = 0 at the base, v = 1 at the tip: one leaflet (
palmFrondDate,palmFrondDry), one fan segment, one reed blade or plume, one bloom, one shrub sprig, one acacia spray, one agave leaf. Tufts (grassDry,grassGreen): one clump, v = 0 at the ground.tumbleweedtiles (sphere shells). Vertex alpha = wind weight. - Tiles: about 1 uv unit = 1 m on props, u once round trunks (
palmBarkDate,cactusSkin,twigDry,deadWood,acaciaBark); ground surfaces repeat every 2-3 m when uv is in metres. Vertex RGB tints everything.
Looks
- real: tiles on tropicalMaterials'
tropicalSolidor the package'sdesertRock(world-height strata, desert varnish) anddesertSand(quartz glints, wetness); cards ontropicalFoliage(alpha cut, two-sided, light through the leaf, wind); water ontropicalWater. - painted / toon / lowpoly / pixel: runtime materials on
tropicalStylisedfrom the same textures, with cool lilac shadows. - terrain: each layer has a baked albedo per stylised look (
terrain_<layer>_<look>_albedo: painted 256², toon 128², lowpoly 64², pixel 256² of 4×4 blocks). The engine terrain hex-tiles its layers, which turns directional wind ripples into patches; set the surface material'shex_tilingto 0 for straight ripple fields (the terrain guide shows how).
Texture memory
196 textures, 36.6 MB of GPU memory (UASTC, 1 byte a texel, mipmaps included), inside the 48 MB web budget the tests hold it to: ground tiles and the two sandstones 17.5 MB, prop tiles and cards 16.4 MB, baked terrain looks 2.7 MB. DesertMaterialsBuild.textureMemory() recounts it.
What's in the package
DesertMaterials.modulethe resolver;DesertMaterialsTable.moduleits generated literal table;DesertLook.modulethe look switch;DesertLookSetting.componentthe synced switch.shaders/:desertRock(strata, varnish),desertSand(glints, wetness). The rest come from tropicalMaterials.materials/(46),desert.materialCollection(the 46 in materialLibraryKit's picker),textures/(196),guides/(2),tests/desertMaterials.testSuite.DesertMaterialsBuild.module(authoring):importTile(grade, flatten, procedural tiling wind ripples),bakeCard,writeMaterials,writeTable,bakeTerrainLooks,swatches,textureMemory. Build order: textures, then materials, then the table.
Depends on
Installed packages, at the versions package.yaml states: tropicalMaterials 1.0.2, materialLibraryKit 1.3.1, Terra Firma (groundMaterials) 1.0.8, Bedrock (stoneMaterials) 1.2.1, Heartwood (woodsMaterials) 1.0.1, Scale and Feather (organicMaterials) 1.0.7, Brick and Mortar (masonryMaterials) 2.0.0.
Known limits
- The look, the terrain tiles and the texture budget were judged in the desktop editor only. The author cannot start a web build (#20946), so how the five looks read in the browser, and the 48 MB budget there, is checked by whoever commissioned the package.
DesertLookSettingsyncs the look to every player, but a two-player test needs two accounts: two engines signed in to one account show up as one player (#14448).- Installing brings seven material packages (and their own dependencies), so the first install can take a few minutes (#21420); the ZeroMind listing text can trail the newest release by a while (#19258). A dependency removed from a nested package can come back on the next install (#23635).
- Running
zero tests run desertMaterialsin a shared editing room swaps the open scene for everyone in it (#23636); run it in a world of your own. - Re-importing or re-baking textures: moving a picture with the shell turns it into a texture asset where it lands (#23634), so keep each tile's
source.pngwhereimportTilewrote it. Frames are slow while the engine makes previews for new textures (#22778), and publishing before those previews finish makes the release change again once they land (#23611, #23686); wait for the previews before you push. Checking what changed is slow in a world this size (#23706).