Log inGet started
World

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. look is real | painted | toon | lowpoly | pixel; nil or "auto" follows DesertLook.get(), an unknown look is real, 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 |o is built from the package's textures, |w is water) or fallback:. 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 what terrain.write's surfaces takes. 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 for real.
  • DM.footstep(surface) -> sand | softSand | gravel | rock | stone | mud | water | wood | grass | salt.
  • DesertLook (module): set, get, resolve, valid, onChanged, LOOKS; it is tropicalMaterials.TropicalLook. DesertLookSetting (component): a synced look field that calls DesertLook.set on 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", {}); looks and groups narrow 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.

SurfaceLooks likeComes from
Ground (all 14 are terrain layers)
sandDunewarm ochre-orange dune sand: broad swells with fine 10 cm wind ripples baked over them, quartz glints on meshesown, 1024² tile, 2.5 m
sandRippledcrisp asymmetric wind ripples about 10 cm apart, neutral ochre so a terrain can tint itown, 1024² tile, 2 m
sandMegaRipplecoarse granule ridges about 0.4-0.6 m apart, darker grit on the crestsown, 512², 2.5 m
sandSlipFacesmooth lee-face sand, faint avalanche streaks, no ripples, neutral ochreown, 512², 2.5 m
sandPalepale cream gypsum and quartz sand, soft ripplesown, 512², 2.5 m
sandReddeep rust-red iron-oxide sandown, 512², 2.5 m
sandPackedtrodden track: compacted sand, footprints, hoof marks, cart rutsown, 512², 2.5 m
gravelPlaindesert pavement: varnished dark pebbles over tan siltown, 512², 2 m
saltFlatwhite salt polygons with raised crusty rimsown, 512², 3 m
clayCrackeddry playa clay, curling mud-crack polygonsown, 512², 2 m
rockSandstonelayered orange sandstone bedrock (sandstoneLayered's textures)runtime on desertRock
rockVarnishedsandstone with black varnish streaks (sandstoneVarnished's textures)runtime on desertRock
mudWetdark glossy oasis mud with hoof prints and puddlesown, 512², glossy mask and clear coat
grassOasispatchy green grass over damp tan sandown, 512², 2 m
Rock, stone, built
sandstoneLayereddeep orange cross-bedded strata with cream bands; world-height strata on desertRockown, 1024² albedo
sandstoneVarnishedorange sandstone with black-brown varnish streaks running down; more streaks hang from ledges every 2.2 m on desertRockown, 1024² albedo
sandstonePalecream-white capstoneown, 512²
limestoneBleachedsun-bleached cream limestone for ruinsown, 1024² albedo
stoneCarvedchisel-dressed bleached limestone: fine tooling, weathering pits, hairline cracks, no motif (statues, columns, carved trim)own, 512²
stoneAshlardressed sandstone block masonryown, 512²
mudBricksun-dried mud bricks with straw, eroded edgesown, 1024² albedo
mudPlastereroding earthen render over brickown, 1024² albedo
terracottaunglazed orange-red potteryown, 256²
tileGlazedfaded turquoise glazed tiles, crackled, chippedown, 512², clear coat
Palms and plants
palmBarkDatedate palm trunk: diamond rows of cut leaf-base scarsown, 512² (u round, v up)
palmFrondDatestiff blue-green date palm leafletown card 128×512
palmFrondDrydead straw-brown leafletown card
palmFanLeaffan palm segmentown card
datesglossy amber to orange-brown date clustersown, 256², clear coat
reedLeaf, reedPlumereed blade, feathery tan-purple plumeown cards
grassDry, grassGreenstraw desert tuft, green oasis tuftown cards 256²
flowerDesertsmall yellow and purple desert bloomsown card
cactusSkinribbed saguaro green with spine rowsown, 512²
cactusPadprickly pear pad with areolesown, 256²
agaveLeafone long blue-grey agave leaf with a terminal spineown card 128×512
shrubLeaf, acaciaLeafgrey-green shrub sprig, fine acacia leaflet sprayown cards
tumbleweedtiling 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
twigDrythin dry grey twig barkown, 256²
deadWoodsun-silvered cracked dead woodown, 512²
acaciaBarkdark fissured acacia barkown, 512²
woodWeatheredsun-dried grey-brown timber planks, deep cracks along the grain, rusty nail holes, sand in the jointsown, 512² tile
Camp
rope, ironRustytwisted rope, rusty ironinstalled: tropicalMaterials
canvassun-faded tent clothown, 256²
rugWovenfaded red Bedouin woven rugown, 512²
leatherworn tan saddle leatherown, 256²
brasstarnished hammered brass, metallicown, 256²
bonebleached boneinstalled: Scale and Feather bone
ashcampfire ash and charcoalinstalled: Terra Firma ash
Water
oasisWaterclear teal pool water: shallow aqua to deep teal by depth, slow ripples, Fresnel sky, sun glintruntime 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. tumbleweed tiles (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' tropicalSolid or the package's desertRock (world-height strata, desert varnish) and desertSand (quartz glints, wetness); cards on tropicalFoliage (alpha cut, two-sided, light through the leaf, wind); water on tropicalWater.
  • painted / toon / lowpoly / pixel: runtime materials on tropicalStylised from 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's hex_tiling to 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.module the resolver; DesertMaterialsTable.module its generated literal table; DesertLook.module the look switch; DesertLookSetting.component the 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.
  • DesertLookSetting syncs 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 desertMaterials in 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.png where importTile wrote 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).