gravel

# groundMaterials: Terra Firma **Version 1.0.4. Depends on materialLibraryKit 1.3.1** (stated in the package's own dependency entry and installed with it automatically; nothing else is installed). 28 seamless, real-scale ground surfaces (grass, soil and mud, sand, gravel and lava rock, forest floor, moss, snow and ice, ash and desert crust, plus toon, hand-painted and pixel-art takes) for the materialLibraryKit material library, each of which is also a paint layer for the engine's own landscapes, with eight ready-made landscape mixes picked by one name. Every surface answers to one name and shows at **real size on any box, plane or model** with no UV setup: gravel stones are 1 to 4 cm, a 64 m field shows no repeating patch, and swapping a field from realistic grass to toon grass or pixel grass is a change of one name. **Texture memory: 64.0 MB for all 28** (GPU, mipmaps included), 73.7 MB with the reference pictures and board frame the gallery shows. ## Install and use Install **groundMaterials** from ZeroMind (search "groundMaterials" or "Terra Firma"). It lands at `/source/groundMaterials.package`, and **materialLibraryKit 1.3.1**, the shared material library it is built on, comes with it in the same install under `/source/deps/`. There is no setup code: every surface appears in the library's list, picker and swatch gallery on every player's machine. Then, in a brand-new world, run this from a script or the console (`execute`): ```luau local Materials = require("~materialLibraryKit.Materials") -- a 64 x 64 m field every player has local field = entity.spawn("field", { synced = true, components = { Model = { model = "cube" } } }) field.localPosition = { 0, -0.1, 12 } field.localScale = { 64, 0.2, 64 } assert(Materials.apply(field, "shortGrass")) -- every player sees it -- the same field in a cartoon world, or a retro one: only the name changes assert(Materials.apply(field, "toonGrass")) assert(Materials.apply(field, "pixelGrass")) -- every sand, and everything light enough for a phone for _, m in Materials.list({ collection = "ground", kind = "sand" }) do print(m.id, m.style, m.tileSize, m.textureKB) end for _, m in Materials.list({ collection = "ground", maxTextureKB = 1536 }) do print(m.id) end ``` `Materials.apply(object, name)` puts the surface on the object's Model, records it and shares it with every player (players who join later get it too); `Materials.get(name).material` is the material itself for any `Model`; `Materials.clear(field)` puts back what it wore. To remove the example: `Materials.clear(field)` then `entity.despawn(field.id)`. ## Painting a landscape Every surface is a layer for the engine's own landscapes (`@builtin::systems.terrainSystem`): its colour, its green-up normal map and its mask in the terrain's own layout (R metallic 0, G ambient occlusion, B **height**, A smoothness), tiled at its real size. Where two layers meet, the engine gives each contested pixel to the layer whose mask height stands proudest, so gravel stones stay whole on the path's edge and grass tufts poke through snow instead of the two cross-fading. In one call, raise a hill, pick a mix and lay a path: ```luau local GL = require("~groundMaterials.GroundLandscape") local hill = GL.build({ name = "myHill", folder = "landscapes", -- writes /source/landscapes/myHill.terrainData size = 96, resolution = 0.5, -- metres across, metres per cell mix = "alpine", heights = { 0, 24 }, -- the mix, and the height span its rules read shape = function(g, r) -- any terrain nodes: cone, ridge, fbm, erode... r = g.terrain.cone({ raster = r, at = { x = 0, z = 0 }, radius = 40, height = 24 }) return g.terrain.fbm({ raster = r, featureSize = 14, amplitude = 1.5 }) end, path = { { -48, -30 }, { -10, -14 }, { 20, -22 }, { 48, -36 } }, -- a dirt and gravel path }) GL.stand(hill) -- Terrain + GroundTerrain on a new entity ``` That hill gets short grass in the low ground, a dirt path with a gravel centre, scree and rock on the steep slopes, and packed then fresh snow on the top. To keep a landscape in a scene, put the same two components in the scene's `build.luau`: ```luau local e = entity.spawn("Hill") e.component.add("Terrain", { terrain = asset.resolve("landscapes.myHill", "terrainData") }) e.component.add("GroundTerrain", {}) ``` **GroundTerrain** is needed beside the engine's `Terrain`: the Terrain component shades every layer at roughness 0.95 to 1 ([zero#21004](https://github.com/OrigoZero/zero/issues/21004)), so wet mud, wet sand and ice would look as dull as ash. GroundTerrain rebuilds the same engine surface with each layer's own roughness and keeps it on whenever the Terrain rebuilds. It has `heightBlend` (default 8, how hard the proudest layer wins a join) and `sharpen` (default 1, narrower transitions). Inside a procgen graph of your own, `GL.paint(g, raster, mix, { heights, path })` writes the coverage layers and returns `(raster, layers, surfaces)` for `g.terrain.write`. A mix can also be your own list, bottom of the stack first: ```luau local myMix = { { surface = "drySand", rules = { { input = "everywhere" } } }, { surface = "gravel", rules = { { input = "slope", min = 20, feather = 4 } } }, { surface = "toonGrass", rules = { { hmin = 0.6, feather = 1 } } }, -- any surface, any style } ``` A rule is `terrain.mask`'s band: `input` height, slope (degrees), curvature, noise or `everywhere`; `min`/`max` in that unit; `hmin`/`hmax` as fractions of `heights`; `path` (metres either side of the path); `feather`, `jitter`, `jitterSize`, `featureSize`, `seed`. Later layers win where their rules say. A landscape carries at most 8 layers. ### The ready-made mixes `GL.mix(name)` returns a mix, `GL.mixSurfaces(name)` its surfaces. `rock` and `cliff` are the engine's own landscape pictures (`terrainSystem.demo.textures`), given a height-and-roughness mask by this package so they join the ground surfaces the same way. | Mix | Layers, bottom of the stack up | Path | |---|---|---| | `meadow` | `shortGrass` everywhere, `longGrass` in drifts, `dryGrass` on the tops, `dirt` on banks over 26° | dirt with a `gravel` centre | | `alpine` | `shortGrass` low, `gravel` scree on 24–38° slopes, `rock` over 36°, `packedSnow` above 62% of the height, `freshSnow` above 78% | dirt with a gravel centre | | `desert` | `drySand` everywhere, `desertCrust` in the lowest 20%, `gravel` pavement over 20°, `rock` over 38° | dirt | | `beach` | `beachSand` everywhere, `wetSand` in the lowest 12%, a `gravel` strandline, `drySand` dunes above 45%, `dryGrass` on dune tops | - | | `forest` | `forestFloor` everywhere, `leafLitter` in drifts, `moss` in hollows and patches, `rock` over 38° | dirt | | `swamp` | `mud` everywhere, `longGrass` on the rims, `moss` patches, `wetMud` in the lowest 30%, `swampMuck` in the lowest 15% | - | | `volcanic` | `ash` on the flats, `gravel` cinder drifts, `lavaRock` over 14°, `cliff` over 42° | - | | `tundra` | `dryGrass` everywhere, `moss` patches, `gravel` over 18°, `freshSnow` above 55%, `ice` in the lowest 8%, `rock` over 38° | - | ## The gallery The world this package comes from, "Terra Firma", opens straight into it. To open it in your own world: `zero scene load groundMaterials.GroundGallery` in the shell, or `startup_scene = "groundMaterials.GroundGallery"` in `.world_settings`. All 28 surfaces stand on one ring around the spawn, each in its own bay with a 2 x 2 m floor tile, a wall and a cube, sphere, shader ball and cylinder at real size, its reference picture framed on the wall beside it and a plaque naming it with its tags (the name is on the plaque's back too, so the ring reads from outside as well). The toolbar switches the lighting look for everyone (daylight, overcast, golden hour, moonlight, warm interior, studio), and **Materials** opens the picker, which puts any surface on whatever you click (in play) or have selected (in the editor), for every player. The gallery stands in a hollow of a 128 x 128 m landscape painted with the `alpine` mix, with snow-capped hills rising beyond the ring on every side, so every spawn spot looks out onto painted ground, and a dirt and gravel path climbing the tallest. To put the gallery in a scene of your own: `local g = entity.spawn("Gallery"); g.component.add("SwatchGallery", {}); g.component.add("GroundShowcase", {})`. ## The surfaces Every surface is tagged `category = ground`, with its `kind`, its `style`, `tileSize` (metres covered by one texture repeat), roughness and metallic ranges, `textureKB`, `animated = false`, and search words. Tags carry the same and more: the kind and style; a finish (`glossy` median roughness under 0.25, `satin` under 0.6, `rough`); a weight (`textures-tiny` under 128 KB, `textures-light` under 1.5 MB, `textures-medium` under 2.5 MB, `textures-heavy` up to 3 MB); `tile-<metres>m`; and on every surface `non-metallic`, `not-animated`, `landscape-layer` and `terrain`. The hand-painted grass is also tagged `hand-painted`. Examples: `Materials.list({ collection = "ground", kind = "grass" })`, `{ tag = "glossy" }`, `{ style = "toon" }`, `{ tag = "landscape-layer", style = "realistic" }`, `{ search = "beach" }`. Textures lists albedo / normal / mask sizes in pixels (`-` where the surface does not use that map). Roughness is measured from the baked mask (2nd to 98th percentile). Metallic is 0 for every surface. | Name | Surface | Kind, style | Tile (m) | Real sizes | Roughness | Textures (memory) | Tags: finish, weight, tile | |---|---|---|---|---|---|---|---| | `shortGrass` | Short grass | grass, realistic | 2 | mown lawn, blades 2 to 4 cm tall and 2 to 4 mm wide; 2 m repeat | 0.66–0.89 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `longGrass` | Long grass | grass, realistic | 2.5 | unmown meadow grass 20 to 40 cm tall, lying in tangled clumps, seen from above; 2.5 m repeat | 0.66–0.91 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2.5m` | | `dryGrass` | Dry grass | grass, realistic | 2 | sun-dried grass 5 to 15 cm, thin blades, patches of dusty soil; 2 m repeat | 0.79–0.95 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `dirt` | Dirt | dirt, realistic | 2 | dry compacted soil with crumbs and pebbles 2 to 15 mm; 2 m repeat | 0.86–0.95 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `mud` | Mud | mud, realistic | 2 | damp churned soil with boot and hoof marks 8 to 30 cm across; 2 m repeat | 0.55–0.81 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `wetMud` | Wet mud | mud, realistic | 2 | waterlogged mud with puddles 10 to 50 cm across; 2 m repeat | 0.1–0.51 | 1024 / 1024 / 512 (3.0 MB) | `glossy` `textures-heavy` `tile-2m` | | `clay` | Clay | clay, realistic | 2 | smooth damp clay with spade and tread marks, fine hairline drying cracks; 2 m repeat | 0.6–0.78 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `drySand` | Dry sand | sand, realistic | 2 | fine dry sand, grains 0.1 to 0.5 mm, wind ripples 8 to 12 cm apart; 2 m repeat | 0.89–0.96 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `wetSand` | Wet sand | sand, realistic | 2 | firm wet sand at low tide with backwash ripple marks 3 to 6 cm apart; 2 m repeat | 0.4–0.58 | 1024 / 1024 / 512 (3.0 MB) | `satin` `textures-heavy` `tile-2m` | | `beachSand` | Beach sand | sand, realistic | 2 | dry upper-beach sand with shell fragments 5 to 30 mm and old trampled footprints; 2 m repeat | 0.87–0.94 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `gravel` | Gravel | gravel, realistic | 1 | rounded and crushed stones 1 to 4 cm across with fine grit between; 1 m repeat | 0.61–0.81 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-1m` | | `lavaRock` | Lava rock | lava rock, realistic | 2 | cooled clinkery basalt lava with vesicles 2 to 20 mm and clinker lumps 5 to 25 cm; 2 m repeat | 0.63–0.87 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `forestFloor` | Forest floor | forest floor, realistic | 2 | conifer forest floor: needles 2 to 5 cm, twigs, cones 4 to 8 cm, humus; 2 m repeat | 0.73–0.84 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `leafLitter` | Leaf litter | leaves, realistic | 1.5 | fallen oak, beech and maple leaves 5 to 12 cm, overlapping; 1.5 m repeat | 0.63–0.83 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-1.5m` | | `moss` | Moss | moss, realistic | 1 | cushion moss in mounds 3 to 15 cm across, fronds 1 to 3 mm; 1 m repeat | 0.73–0.94 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-1m` | | `freshSnow` | Fresh snow | snow, realistic | 2 | fresh powder with soft wind drifts 20 to 60 cm across and crystal sparkle; 2 m repeat | 0.64–0.85 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `packedSnow` | Packed snow | snow, realistic | 2 | compacted trampled snow with boot prints 25 to 30 cm long and icy patches; 2 m repeat | 0.49–0.7 | 1024 / 1024 / 512 (3.0 MB) | `satin` `textures-heavy` `tile-2m` | | `ice` | Ice | ice, realistic | 2 | frozen pond surface with crack lines 1 to 3 mm and trapped bubbles 2 to 20 mm; 2 m repeat | 0.05–0.25 | 1024 / 1024 / 512 (3.0 MB) | `glossy` `textures-heavy` `tile-2m` | | `ash` | Volcanic ash | ash, realistic | 2 | fine volcanic ash with cinders 2 to 10 mm and soft wind-blown drifts; 2 m repeat | 0.92–0.96 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `desertCrust` | Desert crust | crust, realistic | 2 | dried-out mud crust cracked into plates 10 to 30 cm across, cracks 5 to 20 mm wide; 2 m repeat | 0.84–0.95 | 1024 / 1024 / 512 (3.0 MB) | `rough` `textures-heavy` `tile-2m` | | `swampMuck` | Swamp muck | swamp, realistic | 2 | black peaty muck with algae scum, duckweed patches and rotting leaves 3 to 10 cm; 2 m repeat | 0.15–0.6 | 1024 / 1024 / 512 (3.0 MB) | `satin` `textures-heavy` `tile-2m` | | `toonGrass` | Toon grass | grass, toon | 2 | flat cartoon grass with tufts about 10 cm; 2 m repeat | 0.9 | 256 / - / - (85 KB) | `rough` `textures-tiny` `tile-2m` | | `toonDirt` | Toon dirt | dirt, toon | 2 | flat cartoon earth with pebbles about 5 cm; 2 m repeat | 0.9 | 256 / - / - (85 KB) | `rough` `textures-tiny` `tile-2m` | | `toonSand` | Toon sand | sand, toon | 2 | flat cartoon sand with wavy ripple strokes about 15 cm apart; 2 m repeat | 0.9 | 256 / - / - (85 KB) | `rough` `textures-tiny` `tile-2m` | | `toonSnow` | Toon snow | snow, toon | 2 | flat cartoon snow with soft drift shapes about 40 cm; 2 m repeat | 0.9 | 256 / - / - (85 KB) | `rough` `textures-tiny` `tile-2m` | | `handPaintedGrass` | Hand-painted grass | grass, stylised | 2 | painterly grass with brush-stroke tufts 10 to 20 cm; 2 m repeat | 0.85 | 512 / 512 / 128 (704 KB) | `rough` `textures-light` `tile-2m` | | `pixelGrass` | Pixel-art grass | grass, pixel | 1 | 32 x 32 pixels per 1 m repeat (about 3 cm per pixel) | 0.9 | 32 / - / 32 (3 KB) | `rough` `textures-tiny` `tile-1m` | | `pixelDirt` | Pixel-art dirt | dirt, pixel | 1 | 32 x 32 pixels per 1 m repeat (about 3 cm per pixel) | 0.9 | 32 / - / 32 (3 KB) | `rough` `textures-tiny` `tile-1m` | ### Texture memory - **The whole collection: 64.0 MB** of GPU texture memory, mipmaps included (each texture counted once; no surface shares another's maps). - 21 realistic surfaces at 1024 / 1024 / 512 px: 3.0 MB each. - Hand-painted grass 512 / 512 / 128: 704 KB. The four toon surfaces 256 px colour only: 85 KB each. The two pixel-art surfaces 32 px: 3 KB each. - **Reference pictures: 9.3 MB** (28 at 512 px) plus 0.3 MB for the one frame all 28 boards share, loaded only where the gallery shows them. **Everything the gallery shows: 73.7 MB**, under a fifth of the library's 384 MiB budget for low-end devices. - **Within the web limits:** every surface samples at most 3 textures per draw (the web limit is 9) and no storage buffers, nothing is over 1024 px, and `Checks.budget` warns about none. Textures are UASTC (BC7 on desktop, ASTC on phones). - **Light on the GPU, browser included:** a pixel reads at most two of a curved object's three projections and at most two hex cells in each, and only pixels close enough to resolve single stones pay for the height-blended cell edges (three extra small reads); a typical distant pixel costs three to six texture reads. Measured on 2026-10-27 in Chrome on a Linux desktop, 840 x 632 window, with the gallery's tiles and the painted hills in view: about 50 fps (496 frames in 10 s, 20 ms average frame, 28 ms at the 90th percentile). - **On a landscape** the layers are copied into the landscape when it is baked: each layer's albedo, normal and mask are resampled to the slice edge (`layerResolution`, 512 by default in `GL.build`), 1.3 MB per map per layer at 512 px (5.3 MB at 1024). The gallery's 6-layer hill is 24 MB of slices plus 1.3 MB of height and control maps. ## How they were made - **Reference pictures first.** Each surface's reference picture (`references/<id>`, 512 px here) was generated from the prompt in its `GroundCatalog` entry before the material was made: a top-down patch of the ground under overcast light, at the size of one repeat ("the area shown is 200 cm across"). - **Realistic surfaces are drawn from their picture.** The picture is the colour; its height and roughness are read off the same picture, pixel for pixel, by the engine's `pbr_gen` service. `GroundRecipes` then makes picture and maps tile together (`GroundBaker.makePeriodic`: the band around each edge is replaced by the picture shifted half a repeat, joined along a minimum-difference cut, the same cut for every map), de-lights the colour (soft light falloff and cavity darkening divided out) and sets its mean to a measured ground albedo, draws the normal map from the height in real metres (green up, proud ground facing out) and the ambient occlusion from its cavities, and grades roughness into the surface's range, with the low ground glossiest on wet surfaces. The bake inputs live in the Terra Firma world (`~/groundSources`, not synced); `require("~groundMaterials.GroundRecipes").bakeAll()` rebakes from them. - **Stylised surfaces** are drawn from their picture too: made to tile, then flattened to a 5-colour palette (toon at 256 px, pixel art at 32 px with nearest filtering), or kept painterly with a soft normal map (hand-painted). - **Real size, no repeat.** `groundProjection` (after Brick and Mortar's masonryProjection and Bedrock's stoneTriplanar, MIT) places the texture by where each point stands on its object, in metres, so one repeat always covers the tile size, and **hex-tiles** it: the plane is cut into a honeycomb, each cell reads the texture through its own offset and turn (no turn for directional surfaces such as wind-rippled sand), and cells meet by their mask height. A slow brightness drift over 9 and 23 m breaks up large areas, a finer second read of the normal map keeps the ground crisp at arm's length and fades out before it could shimmer, and glossy surfaces widen their highlight by the detail a distant pixel averages away. Surfaces whose colour carries fine high-contrast detail (`ice`'s crack lines, the gaps in `leafLitter`) also read a slightly coarser level of their textures once a pixel covers more than one texel (the shader's `far_soften`), so they hold still at 30 m in bright sun while staying exactly as crisp up close. The pixel-art surfaces repeat plainly on purpose. - **Physically based.** Colour maps carry no light or shadow; metallic is 0 everywhere (the mask's metallic channel is 0); roughness follows the ground: ice 0.05–0.25, wet mud from 0.1 and wet sand 0.4–0.58 against dry dirt, dry sand, ash and desert crust at 0.84 and up. - **The periodic field toolkit** (`GroundBaker`) is Brick and Mortar's MasonryBaker (MIT lineage: Heartwood, Bedrock), with the ground additions above. ## Checked The package's test suite (33 tests) runs the library's own material checks on every surface and more; each test runs inside the library's `Sync.isolate()`, so nothing it does reaches other players. Run it with: ```luau asset.resolve("groundMaterials.tests.groundMaterials", "testSuite"):run() ``` - **The library's checks on all 28:** `Checks.budget` (web budget), `Checks.seams` (every texture's opposite edges match), `Checks.shimmer` (no shimmer at 30 m: the check renders under the world's own sun, so every surface was also measured under a bright sun of intensity 10, a fresh world's default, and 14; the highest is `lavaRock` at 4.5 and 4.8 against the limit of 6), `Checks.views` and `Checks.textureMemory`. - **Seamless 4 x 4 at real size:** a box face exactly 4 repeats wide, rendered straight on (albedo pass; lit for the toon set), judged at its true repeat lines with the library's seam statistics and thresholds. - **No repeat across 64 m:** a 64 m face of each realistic surface, rendered at 1024 px; the picture one tile along is no more alike than half or one and a half tiles along. A control (gravel with hex tiling off) proves the measure sees a plain repeat. - **Against the reference:** each colour map's mean brightness is within 40% of its reference picture's (realistic surfaces are set to measured albedos) or 10% (stylised). - **Physics:** wet shinier than dry, ice glossiest, every albedo plausible, metallic 0 in every map, and every realistic normal map leans the way its own height climbs (bumps face the right way). - **In use:** apply by one name, swap realistic → toon → pixel by one name, the shared channel, the picker, all 28 on one gallery ring with every sample shape beside its reference board. - **Landscapes:** every surface is a valid layer with a varying height channel and a smoothness matching its roughness; the eight mixes; a hill painted with `alpine` puts short grass at the foot, dirt or gravel on the path, rock or scree on the steep slope and snow on the summit; GroundTerrain shades with each layer's roughness. - **Package:** the dependency on materialLibraryKit 1.3.1, the gallery scene, one version everywhere, this README. ## Multiplayer - **Applied surfaces are shared.** `Materials.apply` goes through the library's shared `materials` channel, so a surface one player puts on an object every machine holds (a scene's own objects, the gallery's swatches, a `synced` object) shows on every machine, and players who join later get it. The picker applies the same way. Lighting looks are shared too. - **Landscapes are scene content.** A landscape stood by a scene's `build.luau` exists for every player; each machine builds its own GroundTerrain surface for it, which costs the network nothing. - **Script-made objects in edit mode stay local** unless spawned `synced`, as in the first example. ## Known limits Engine limits, each with its open issue on [OrigoZero/zero](https://github.com/OrigoZero/zero/issues): - **Terrain roughness without GroundTerrain** ([zero#21004](https://github.com/OrigoZero/zero/issues/21004)): the engine's Terrain shades every layer at roughness 0.95 to 1, so wet mud, wet sand and ice look as dull as ash. Add GroundTerrain beside it. - **No per-layer filtering or tiling on landscape layers** ([zero#21018](https://github.com/OrigoZero/zero/issues/21018)): the engine resamples layer textures smoothly and turns every layer's hex cells, so `pixelGrass` and `pixelDirt` paint a landscape soft rather than crisp, and `drySand`'s wind ripples turn from cell to cell there (on swatches they keep their direction). The toon surfaces paint a landscape with their colours but the engine's lit shading, not the cel bands. - **Reloading a scene can make its landscape float** ([zero#21023](https://github.com/OrigoZero/zero/issues/21023)): a scene reload saves the landscape's generated model into the scene, and the terrain then draws far above its heights. Discard that pending edit before reloading, or remove the saved model from the scene. - **A landscape bake can fail or pass on the same inputs** ([zero#21026](https://github.com/OrigoZero/zero/issues/21026)): whether `GL.build` finishes can depend on how busy the machine is. Run it again on a quieter machine if it fails. - **The gallery takes a long time to load** ([zero#21027](https://github.com/OrigoZero/zero/issues/21027)): 28 materials and one landscape make a slow first load, longest in a browser. - **The gallery's frame rate in a browser is held down by multiplayer sync** ([zero#20750](https://github.com/OrigoZero/zero/issues/20750)): the gallery measured about 50 fps in Chrome (see Texture memory), and the sync cost is part of every frame there. - **Two-player behaviour can't be tested inside one engine** ([zero#19114](https://github.com/OrigoZero/zero/issues/19114)): shared materials are checked through the library's shared channel. - **No `asset.materialCollection.*` namespace yet** ([zero#1889](https://github.com/OrigoZero/zero/issues/1889)): surfaces are reached through `Materials.*`. - **The engine's normal-map green convention is undocumented** ([zero#19414](https://github.com/OrigoZero/zero/issues/19414)): these maps are green-up, and the tests prove the direction. Limits of the package's own design (no engine issue): - **Curved surfaces blend projections** over a narrow band, which can show as a soft join on spheres and rounded models; box faces and planes take one projection. - **The test suite takes about two minutes:** its 33 tests render every surface's checks (87 to 132 s on the machines measured), so run it when nothing else is busy. - **GroundTerrain builds the landscape surface at run time** on each machine, from the layers the landscape carries; nothing is sent over the network for it. - **The bake inputs are not in the package:** the full-size pictures and the maps read off them stay with the machine that baked them (440 MB); the package carries the finished maps and 512 px references. ## Version history - **1.0.4 (2026-10-27)**: built against the engine's current built-in library, so installing it brings only this package and materialLibraryKit 1.3.1 (1.0.3 also copied old versions of three built-in components into the installing world). The test-suite limit no longer links an unrelated issue; it is listed as a limit of the package itself. Surfaces, shaders and landscapes are unchanged. - **1.0.3 (2026-10-27)**: documentation and housekeeping only; surfaces, shaders and landscapes are unchanged. Known limits name only open engine issues (the landscape-layers and material-binding limits are fixed in the engine and gone, and so is the blank-labels line, which had no matching issue), the browser frame rate is the one measured in Chrome (about 50 fps), and every text uses plain punctuation. - **1.0.2 (2026-10-25)**: the surface shader is several times cheaper per pixel with the same look: at most two projections and two hex cells per pixel, height-blended cell edges only where single stones can be seen, every loop unrolled. The gallery's ground page in a browser went from 3 to 8 fps to 15 to 21 fps on the machine measured then. Looks, tile sizes and no-repeat behaviour are unchanged (all 33 tests, side-by-side captures). - **1.0.1 (2026-10-25)**: `ice` and `leafLitter` no longer shimmer at 30 m in a bright sun (they did under a fresh world's default lighting, score 6.5 and 6.3 against 6; now 3.8 and 3.1), through the surface shader's new `far_soften`. The gallery's plaques carry each surface's name on their back as well, so the ring no longer shows blank panels from outside. - **1.0.0 (2026-10-25)**, on materialLibraryKit 1.3.1: 28 surfaces, their reference pictures, landscape layers and eight mixes, GroundTerrain, the gallery scene with its alpine hill, and the test suite (33 tests).