# materialLibraryKit
The shared material library and picker for Zero worlds. It gives a creator one place where every installed material collection lands, tagged by category, kind, style, real-world tile size, finish and texture cost: `Materials.list` finds materials by those tags, `Materials.apply(target, id)` puts one on anything with a `Model` by its name and shares the choice with every player, the on-screen picker lets players browse and apply materials, and the walk-round swatch gallery, a 20-piece calibration shelf, six shared lighting looks and checking tools (seams, shimmer, web texture budget) come with it. **To install:** search ZeroMind for "materialLibraryKit" and install the package, or install any collection built on it (stoneMaterials, starterMaterials and others), which brings it along; then `local Materials = require("~materialLibraryKit.Materials")` from any script. An install brings the library and nothing else. Version 1.4.3.
Collections (metals, woods, stone, fabrics, sci-fi panels, toon and pixel sets…) are separate packages that plug into this core. Once a collection is installed, its materials appear in the list, the picker and the gallery on every player's machine, with no code. Installing it is all a world has to do.
**Two guides come with the package** (open them with `man`, the editor's Docs panel, or search the guides for them):
- **"How to add materials to your game"** (`addMaterialsToYourGame`): what the library and a collection are, how to install collections, find, apply and swap materials for every player, let players pick, and make your own material collection and plug it in.
- **"Dress your game level with materials"** (`dressYourLevelWithMaterials`): a worked example that builds a small level in an empty world (a floor, walls, a door, a few props), dresses it with woodsMaterials and metalsMaterials, and changes its whole look, from a timber cabin to a rusty factory, with one change.
## Version history
**1.4.3 (current, 2026-11-03)**
- **Texture memory is measured for collections that name their textures package-relatively.** A material whose slots name `~.textures.X` (the spelling a collection uses so it also renders when installed as a library) measured 0 KB in `Materials.measureTextures`, `Checks.textureMemory` and the web-budget check, because the name was looked up as written. It is now resolved against the material's own package, and a texture shipped without its source image is sized from its compiled payload's header (`texRef:info()`). Found through Terra Firma's and Scale and Feather's own texture-memory tests, which now pass.
- **Two tests no longer depend on frame timing.** The carried-copy test waits for the hello it checks (up to 3 s) instead of a fixed 0.2 s, and the cleared-world lighting test takes the rig's root first, as a whole-world clear does, instead of its parts one at a time (on a slow frame the settle check could see the root still standing with its lights gone and put them back). Both pass on a heavily loaded engine too. Nothing else changed.
**1.4.2 (2026-10-31)**
- **Known limits name the guide search gap:** the two guides cannot be found through ZeroMind library search yet (#22181), and the entry says where to find them once the package is installed. Nothing else changed.
**1.4.1 (2026-10-31)**
- **After Stop, the library reports what the scene shows.** Stop puts the scene back as it was when play started, but the library kept what was picked during play: a box given toon steel in play went back to its walnut board while `Materials.applied` still said toon steel, and a box re-dressed in play still reported the play material. Now the shared state goes back with the scene: when play starts `Sync` keeps what every channel holds, and on Stop it puts that back and shows every key play changed as it was, then asks the edit room for anything it changed meanwhile. Applied materials, the lighting look (or the scene's own lighting, when no look was set before play) and the gallery exhibit all match the screen again. A model already wearing the material it is given is left untouched, so this records no scene edit.
- New in `Sync`: `Sync.inPlaySession()` and `Sync.onPlaySession(fn)`, the play-session counterparts of `isolated` and `onIsolation`.
- The version history no longer names a closed issue.
- Tests: 41 (core 14, sync 14, tools 4, starter 9).
**1.4.0 (2026-10-31)**
- **Two guides ship in the package:** "How to add materials to your game" (`addMaterialsToYourGame`) and "Dress your game level with materials" (`dressYourLevelWithMaterials`). Every step in both was run word for word in a new world.
- **One calibration shelf, whatever a collection was published against.** An install keeps the older library a collection was published against under `/source/deps/<world>/versions/<commit>/`, and the library used to find that copy's calibration shelf too: with metalsMaterials installed it listed two shelves and 20 duplicate-id problems. A collection under `versions/` is now left out whenever the current copy of the same collection is installed (when only pinned copies are there, the newest is used). The published woods and metals collections installed together now give one shelf and no problems, and their own test suites pass against 1.4.0.
- No call, tag, lighting look, gallery view, calibration material or picker style changed. Tests: 40 (core 14, sync 13, tools 4, starter 9).
**1.3.4 (2026-10-30)**
- **No long dashes.** Every text file the kit ships (its code, READMEs, yaml and the Swatchbook scene) uses plain hyphens instead of em and en dashes, so a world that installs the kit carries none. No behaviour change: the library, picker, gallery, lighting looks, checks and tests are as in 1.3.1.
**1.3.1 (2026-10-24)**
- **A clean install: no copies of engine parts.** 1.3.0 recorded every engine part it uses at the engine version it was built with, so installing it (by itself or with a collection) also laid private copies of about a dozen of the engine's own standard parts under `/source/deps/`: `Model`, `Asset`, `PlayerSpawn`, `PlayerPrototype`, `SkinnedModel`, `ProceduralSky`, the `pbr`, `unlit` and sky shaders and the asset inspector. The gallery's swatches then used the copied `Model` instead of the engine's own. 1.3.1 names every engine part by its plain name with no engine version, so an install brings the kit and nothing else, and the gallery, the lighting looks, the picker and the Swatchbook scene use the engine's own parts. No calls, tags or behaviour changed.
- **Known limits list only open problems:** the desktop problem where freshly installed textures drew plain white is fixed and no longer listed.
**1.3.0 (2026-10-21)**
- **Tests stay out of the live room.** New in `Sync`: `Sync.isolate()`, `Sync.endIsolation()`, `Sync.isolated()` and `Sync.onIsolation(fn)`. Every test of the kit runs inside an isolation: what a test writes for every player goes out tagged for that test alone, a player who joins meanwhile is sent the room's real state, and when the test ends the lighting look, the gallery and the applied materials are shown as the room has them. Collections should isolate their own tests the same way (see "Make your own collection").
- **The tests pass every time**, with the core installed by itself or with a collection. The lighting check after a look change only repairs lights that are there and never builds a rig of its own, so a test runner clearing the world between tests gets nothing back in the next test, and the checks' test counts only the probe entities the checks spawn.
- **A player who joins late sees the room's lighting look, not just its name.** On a machine still loading, a look could be written into a light the engine had not registered yet, and the scene's own sun and sky then arrived with their saved daylight. After every look change the kit checks for 20 s that the screen really draws it and applies it again when not. `Lighting.isShown()` answers the same question, and each player's room report carries `shown`.
- **Stop just works after using the lighting looks.** During play the engine counts a field written by a caller (the console, a tool, an agent, or a callback or background task one of them started) as "tuned in play" and asks to throw it away on Stop. The kit's writes to the scene's sun, ambient light and sky, and the materials it puts on scene objects, are made from a component's update during play (`PlayWrites` and its `MaterialLibraryPlayWriter` component, added for you), which the engine never counts.
- **Players arrive to a clean gallery.** The engine can hand one running copy of the kit from one world to the next (it keeps a module by its asset and version). `Sync` checks the bound world before it sends, takes in or reads anything; in a new world it drops what it held, asks the new room for its state and carries on there, so one world's state never reaches another world's players.
- A material applied to a shared entity that has not reached a player yet (one who just joined) is tried again there for 10 s.
- The README's first example spawns a shared ball, so every player really has it, and shows how to take it away again.
- The version is stated the same way in every place: package settings and description, this README, the asset listing, `Materials.VERSION`, `Checks.VERSION` and the calibration shelf. A test checks all of them.
- Built against the engine library of 2026-10-21 (`@builtin` 5b09a32). Two plain strings the publish check read as asset references no longer look like references.
- Tests: 38 (core 13, sync 13, tools 4, starter 8).
**1.2.1 (2026-10-20)**
- The core's own tests use only the core (the calibration shelf and engine materials), so they pass with the core installed by itself.
- The late-join test waits for the answer carrying its own write instead of taking the first message.
**1.2.0 (2026-10-20)**
- It installs again: the collection type no longer ships a `template/` folder, which a fresh install refused; `asset.create("materialCollection", name)` makes a new collection through the type's `onCreate`.
- Reach the core by its package name, `~materialLibraryKit`, wherever it was installed.
- `Materials.apply` and the picker find a swatch's `Model` whichever copy of the engine's `Model` component it carries.
- The gallery's style view shows a notice board when no installed material has that style, and the picker says the same.
- Late-join tests send the room's state through the engine's loopback transport.
**1.1.0 (2026-10-18)**
- Picker taps work with mouse and touch, take the point from the event, and say in the status line why a tap targeted nothing.
- Every library entry carries `displayName`, `subKind` and `sampledTextures`; `Checks.budget` judges the sampled-texture and storage-buffer limits.
- The calibration shelf grows to 20, adding a glossy black ball, a matte 18% grey ball and a 1.0 emitter.
- `Materials.list` refuses unknown filter keys and takes lists for its name keys.
- Lighting finds its extra lights by name on every look, so none can be left switched on.
- Some of these (the new entry fields, the three calibration materials and their tests) went in after 1.1.0 was first published, without a new number.
**1.0.0 (2026-10-18)**
- First release: tagged collections, `Materials.apply` / `Materials.list`, the calibration shelf, the swatch gallery and Swatchbook scene, shared lighting looks, the picker (grid, list, quick), the toolbar, material checks and tests.
## Install and use
Install the package into your world from ZeroMind: search "materialLibraryKit", or install the published package `0d7f3e76-0699-44fd-b0ac-2cb37822b648`. Installed by itself it lands at `/source/materialLibraryKit.package`. When it comes with a collection (starterMaterials, for example) it lands under `/source/deps/`. Either way, scripts reach it by its package name with `~materialLibraryKit`. Then, from any script or the console:
An install brings the kit and nothing else: no copies of the engine's own parts. If you installed 1.3.0, update; 1.3.0 also laid private copies of about a dozen engine parts under `/source/deps/` (see the version history).
```luau
local Materials = require("~materialLibraryKit.Materials")
-- synced: the ball exists for every player, so every player sees its material
local ball = entity.spawn("ball", { synced = true, components = { Model = { model = "sphere" } } })
ball.localPosition = { 0, 1, 3 }
assert(Materials.apply(ball, "chromeBall")) -- every player sees it
for _, m in Materials.list({ category = "calibration", style = "realistic" }) do
print(m.id, m.kind, m.tileSize, m.textureKB)
end
```
`Materials.apply` returns `ok, err`; the `assert` stops with the reason instead of leaving the ball grey. When you are done with the ball, take it away again for every player:
```luau
Materials.clear(ball)
entity.despawn(ball.id)
```
To see every installed material, load the showcase scene, or drop the gallery into a scene of your own:
```luau
zero scene load materialLibraryKit.Swatchbook -- in the shell
entity.spawn("Gallery").component.add("SwatchGallery", {}) -- or in a scene's build.luau
```
The gallery stands around the origin, so put the player's spawn there. The Swatchbook scene does.
## The tags
Every library entry carries these fields. A collection writes them in its `collection.yaml`; the fields marked *filled* get a default when left out.
| Field | Meaning |
|---|---|
| `id` | Unique library id (letters, digits, `_`, `-`). If two collections use the same id, the second is reachable as `collection/id`. |
| `name` | Display name. *Filled* from the id ("chromeBall" becomes "Chrome Ball"). Every entry carries it as `displayName` (and as `name`). |
| `material` | The material asset: an identity (`@builtin::materials.gold`), a VFS path, or `~.a.b` for `<this package>/a/b.material`. |
| `category` | What it is: metal, wood, stone, fabric, calibration… Free text, lower-cased. |
| `kind` | The sub-kind within the category: steel, oak, grey card… *Filled* with the category. Every entry carries it as `subKind` (and as `kind`). |
| `style` | Style family, one of `realistic`, `stylised`, `toon`, `pixel`, `scifi`, `fantasy`. |
| `tileSize` | Metres one texture repeat covers. The gallery's floor tiles and walls use it, so each shows at real-world scale. *Filled* 1. |
| `roughness`, `metallic` | `[min, max]`, or a single number. *Filled* from the material's own values. |
| `textureKB` | GPU texture memory in KB. *Filled* by measuring the material's textures. |
| `sampledTextures` | How many textures the material samples per draw: every texture slot its shader declares (an unbound slot still samples its default). Always measured; a collection does not write it. `Checks.budget` holds it to at most 9. |
| `animated` | Whether the surface moves over time. *Filled* false. |
| `unlit` | A self-lit or reference-chart shader. *Filled* when the shader has no roughness or metallic. |
| `singleRepeat` | The material must be drawn once per face (UV 0..1), as a parallax march that discards outside one repeat does. *Filled* false. |
| `tags`, `description` | Free words for search and the picker's tooltips. |
## Every call
From a world use `require("~materialLibraryKit.<Module>")`, which finds the core wherever it was installed; inside the package use `require("~.<Module>")`.
**Materials** (the library)
| Call | Does |
|---|---|
| `Materials.list(filter?)` | Entries matching `{ category, kind, style, collection, tag (or tags), animated, search, maxTextureKB, includeBroken }`, sorted by category, kind, then name. For the name keys (`category`, `kind`, `style`, `collection`, `tag`/`tags`) a string or a non-empty list of strings matches any of them: `Materials.list({ tag = { "checker", "pattern" } })`. An unknown key, or a value of the wrong kind, raises an error naming it and the keys it knows, so a typo never returns the whole library. |
| `Materials.get(id)` | One entry, or nil. |
| `Materials.apply(target, id, opts?)` | Puts the material on the target's Model (or every Model under it) for every player. In an editor play session the choice lasts until Stop, which puts it back to what it was when play started, along with the scene. `target` is an entity, an id or a name. `opts.localOnly` keeps it on this peer. A player who has not built the entity yet (a shared entity still reaching someone who just joined) tries again for 10 s, and `reapply` catches up anything built later. Every player sees it only on an entity every player has: a shared (`synced`) entity, the scene's own entities, or the gallery's swatches. Returns `ok, err`. |
| `Materials.clear(target, opts?)` | Restores what the entity wore before, for every player. |
| `Materials.applied(target)` | The library id applied through the library, or nil. |
| `Materials.reapply()` | Re-applies shared assignments to entities built at runtime. Returns the count. |
| `Materials.keyOf(target)` | How peers name an entity: `id:<id>` for a synced entity; `id:<synced ancestor>/<path below it>` for a part of one (a piece of a player's body); `path:<name path>` for local ones. |
| `Materials.categories()`, `Materials.styles()`, `Materials.STYLES` | What the library holds, and the six style families. |
| `Materials.collections()` | `{ name, title, version, path, count, problem? }` per installed collection. |
| `Materials.problems()` | Entries breaking the tag contract: unknown style, missing material, duplicate id. |
| `Materials.refresh()` | Rescans every collection. Returns the material count. `list` already scans on first use, and new collections arrive by themselves. |
| `Materials.onChanged(fn)` | Calls `fn("library")` when collections change and `fn("applied", key, id)` when a material is applied. Returns an unsubscribe function. |
| `Materials.findMaterial(name)` | A material AssetRef by identity, path or guid, found without a computed resolve, so published worlds can call it. |
| `Materials.measureTextures(material)` | Total bytes, plus one row per textured slot: `{ slot, texture, width, height, compression, bytes, mips }`. |
| `Materials.VERSION` | `"1.4.3"`. |
**Gallery** (the swatch gallery: every material on a sphere, a cube, a 2 × 2 m floor tile and a wall section at real-world scale, plus a shader ball and a cylinder, with a label plaque)
| Call | Does |
|---|---|
| `Gallery.setView(view, opts?)` | Switches the exhibit for every player. `"all"` (by category, paged 16 per ring, `{ page }`), `"closeup"` (`{ id }`: near, plus a 40 m runway), `"compare"` (`{ a, b }`), `"style"` (`{ style, page }`). `opts.localOnly` keeps it on this peer. A style no installed material has stands a notice board in front of the spawn saying so (and listing the installed styles) instead of an empty ring. |
| `Gallery.build()`, `Gallery.clear()`, `Gallery.isBuilt()` | Stand, remove, or check the current exhibit. |
| `Gallery.view()`, `Gallery.pages()`, `Gallery.stats()` | The current exhibit, its page count, and `{ entities, bays, pages, radius, empty }` (`empty` is true while that notice stands). |
| `Gallery.onChanged(fn)` | Calls `fn(view)` after each rebuild. |
| `Gallery.VIEWS`, `Gallery.PAGE_SIZE` | The exhibit names and the bays per ring. |
| `Gallery.tour(settle?, measure?)`, `Gallery.tourResult()`, `Gallery.requestTour(settle?, measure?)` | Measure this peer's frame rate on an empty floor, every page, the close-up and the compare (local only; the exhibit is restored after). `requestTour` asks every other player's machine to run it; their results arrive in `Sync.heard()[peer].report.tour`. |
| `Gallery.placePlayer(body, delay?)`, `Gallery.freeSpot(mine?)`, `Gallery.SPOTS` | Stand a player on one of four spots 5 m from the centre, facing outward into their own quarter of the ring, so no player stands between another's camera and the signs. The Swatchbook scene calls it for each player. |
| `Gallery.fillNameTags()` | Replace placeholder `{PlayerName}` tags with "Visitor <peer>". The gallery component runs it every 2 s. |
**SwatchGallery** component: `view`, `lighting` (a preset id, or empty to leave the scene's lighting alone) and `showHud`. It builds the gallery, applies the shared lighting and shows the toolbar.
**Lighting** (presets every player sees: `daylight`, `overcast`, `goldenHour`, `moonlight`, `warmInterior`, `studio`)
| Call | Does |
|---|---|
| `Lighting.list()` | `{ id, name, description }` in display order. |
| `Lighting.set(id, opts?)` | Switches for everyone. `opts.localOnly` keeps it local; `opts.blend` eases the change over that many seconds. |
| `Lighting.current()` | The active preset id. |
| `Lighting.isShown()` | Whether this machine's screen really draws the current preset (the scene's sun is the rig's, and the sun, ambient light and sky carry the preset's values). For 20 s after each change the kit re-applies a preset that is not shown, so a player still loading gets it; within that window a hand edit to the scene's sun or sky is put back. It only repairs lights that are there and never builds a rig of its own. |
| `Lighting.attach(root?)` | Finds the scene's sun, ambient light and sky, or builds its own. |
| `Lighting.applyCurrent(fallback?)` | Attaches and shows the room's preset. This is what a scene calls on load. |
| `Lighting.onChanged(fn)`, `Lighting.releaseDisplay()` | Subscribe to changes; hand the exposure back to the scene. |
**Picker** (styles `grid` with thumbnails, `list` with search, and `quick` for gamepad or phone)
| Call | Does |
|---|---|
| `Picker.open({ style? })`, `Picker.close()`, `Picker.toggle()`, `Picker.isOpen()` | Show and hide the picker. |
| `Picker.styles()`, `Picker.style()`, `Picker.setStyle(s)` | Switch the look. |
| `Picker.target()`, `Picker.setTarget(e)` | The entity a pick goes on: the editor selection in edit mode, a clicked or tapped object in play. |
| `Picker.pick(id)`, `Picker.onPicked(fn)`, `Picker.visible()` | Apply a material; get told about each pick; list the ids the filters show. |
| `Picker.pointerPixels()`, `Picker.lastTap()` | Where the pointer is in scene pixels; what the last tap saw (its point, the ray, each surface it crossed and why it was taken or skipped). A tap that targets nothing also says why in the picker's status line. |
| `Picker.pickAt(x, y)` | What a tap at scene pixel (x, y) targets: the nearest drawn surface with a Model, skipping players' bodies and the gallery's boards and frames. |
In play, a click or a touch tap on any swatch (or any object with a Model) targets it; presses on the toolbar and the picker stay in the UI. In Quick, ←/→ or the D-pad browses, Q/E or LB/RB changes category, ↑/↓ changes style, and Enter or A applies.
**Hud** (the gallery toolbar): `Hud.show()`, `Hud.hide()`, `Hud.isShown()`, and `Hud.onCallback(id)` to run a toolbar action by its id.
**Checks** (for a collection's own tests; tool code, so never require it from a component or scene entrypoint)
| Call | Does |
|---|---|
| `Checks.views(id, opts?)` | Renders the material on a sphere, a tile and a shader ball in the final, albedo, roughness, metallic and normal passes. Writes a PNG and returns per-cell luma stats. |
| `Checks.seams(id, opts?)` | Tiles the material 4 × 4, renders it from the top, and compares tile boundaries with tile interiors. Also checks each texture's opposite edges. Returns `{ seamless, score, ... }`. |
| `Checks.shimmer(id, opts?)` | Near (about 1.5 m) and far (about 30 m, grazing) images, plus a shimmer score from a half-pixel camera shift. |
| `Checks.textureMemory(id)` | Bytes per slot, cross-checked against what the renderer actually holds. |
| `Checks.budget(id or nil, opts?)` | Judges a material against the engine's per-material limits and the web budget. `bindings.verdict` is `"pass"` or `"fail"` for at most 9 sampled textures and 1 storage buffer, with the counts (`sampledTextures`, `storageBuffers`) and the shader's slots; every slot the shader declares counts, since an unbound slot still samples its default. The size checks warn on 24 MiB of texture per material, 4096 px, uncompressed textures over 1024 px, and formats browsers cannot filter. `ok` is false when any of these fail. `nil` checks the whole library; `opts.limits` overrides any limit. |
| `Checks.run(id, opts?)`, `Checks.assertGood(id)` | Everything at once; `assertGood` raises a readable failure, for test suites. |
The same six run as tools: `zero materialChecks run chromeBall`, or `tools.use("materialChecks", "budget", "gold")`.
**Sync** (shared state the other modules ride on): `Sync.channel(name, onRemote)`, `Sync.set(ch, key, value)`, `Sync.get(ch, key)`, `Sync.resync()`. Writes are newest-wins on every peer, and a player who joins later receives a snapshot; a peer also re-sends its state whenever another peer appears.
Keeping tests out of the live room: `Sync.isolate()` starts an isolation on this peer and `Sync.endIsolation()` ends it, `Sync.isolated()` says whether one runs, and `Sync.onIsolation(fn)` calls `fn("begin")` / `fn("end")` for state a module shows that no shared key restores. While isolated, every write meant for every player goes out tagged for that isolation alone, so no other player takes it in; the room's own writes keep arriving into its saved state, and a player who joins is sent that real state. Ending it brings the room's state back and shows it again (lighting look, gallery exhibit and whether it stood, applied materials), with whatever the room changed meanwhile. A test suite calls the pair in `beforeEach` / `afterEach`.
A copy of `Sync` keeps its state for the world that is bound: the engine can hand one running copy from one world to the next, so before it sends, takes in or reads anything it checks the world, and in a new one it drops everything it held and asks the new room for its state. One world's shared state never reaches another world's players.
Play sessions in the editor: Stop puts the scene back as it was when play started, and `Sync` puts the shared state back with it. When play starts it keeps what every channel holds; on Stop it restores that, shows every key play changed as it was (a material picked during play comes off, a lighting look picked during play gives way to the look from before play, or to the scene's own lighting when none was set), and asks the edit room for its state. `Sync.inPlaySession()` says whether one runs, and `Sync.onPlaySession(fn)` calls `fn("begin")` / `fn("end")` for state a module shows that no shared key restores. Published players are always in play, so for them nothing is rolled back.
**PlayWrites** (for the kit's own modules): `PlayWrites.run(key, fn)` runs a write to the scene's entities at once outside play, and during play from the `MaterialLibraryPlayWriter` component's update (added to a temporary `MLK_PlayWriter` entity when first needed), so the engine never counts it as tuning and Stop just works. Lighting and Materials use it; a collection does not need to.
Checking what every player actually shows (and how fast it runs): `Sync.perf()` is this peer's frame rate over the last second, `Sync.report()` is this peer's own report (the lighting preset and sun, and per shared entity the material wanted and the one on its Model), `Sync.heard()` is the latest report each other peer broadcast (after every change and every 15 s), `Sync.askRoom(seconds)` asks the room and waits for answers, `Sync.peers()` lists the peers, and `Sync.reporter(name, fn)` adds a section of your own.
**materialCollection** assets: `ref:entries()`, `ref:document()`, `ref:inspect()`. The engine builds no `asset.materialCollection.*` namespace for the type, so collections are reached through `Materials.*`.
## The calibration shelf
The core ships the `calibration` collection, 20 references:
- Cards: an 18% grey card (`grey18`), a lit white card (`whiteCard`), an unlit white (`whiteReference`) and a lit black card (`blackCard`).
- Balls: a chrome ball (`chromeBall`), a glossy 18% grey ball (`greyGlossy`), a glossy black dielectric ball (`blackGlossy`: albedo 0.04, roughness 0.05, not metallic) and a matte diffuse 18% grey ball (`matteGrey`: roughness 1).
- Ramps: roughness 0 to 1 (`roughnessRamp`), metallic 0 to 1 (`metallicRamp`), PBR albedo 4% to 90% (`albedoRange`) and a shadow ramp (`darkRamp`).
- Charts: a UV orientation checker (`uvChecker`), a normal-map test pattern (`normalTest`), a colour checker (`colorChecker`), a 21-stop grey wedge (`greyWedge`), a Siemens star (`siemensStar`) and focus bars (`focusBars`).
- Emitters: one at a plain 1.0 reference brightness (`emitterUnit`) and an HDR one at 16x (`emitterReference`).
The engine reads a normal map's green channel as image-up (the OpenGL and glTF convention). The `normalTest` chart shows it; `flip_y = 1` on that material shows the DirectX convention for comparison.
The engine's own `postReference` materials are reused where they fit. Every calibration material is procedural and costs no texture memory.
## Make your own collection
A collection is a package holding one `<name>.materialCollection` folder. Here are two materials of your own:
```
myMetals.package/
package.yaml name: myMetals / version: "1.0.0"
README.md
materials/copper.material/mat.yaml
materials/blueSteel.material/mat.yaml
metals.materialCollection/
collection.yaml
README.md
.metadata { "tags": ["materials", "metal"] }
```
`materials/copper.material/mat.yaml` (`blueSteel` is the same with its own colour and roughness):
```yaml
shader: "@builtin::shaders.pbr"
properties:
base_color: [0.95, 0.64, 0.54, 1]
roughness: 0.3
metallic: 1
```
`metals.materialCollection/collection.yaml`:
```yaml
title: "My metals"
version: "1.0.0"
materials:
- id: copper
material: "~.materials.copper"
category: metal
kind: copper
style: realistic
tileSize: 1.0
tags: [warm, polished]
- id: blueSteel
material: "~.materials.blueSteel"
category: metal
kind: steel
style: scifi
tileSize: 0.5
```
That is the whole collection. Once it is installed, `Materials.list({ collection = "metals" })` returns both, and the picker and gallery show them on every player's machine. Check them in your collection's tests, isolated from the live room so a test run never changes what players see:
```luau
local Test = asset.containing(__FILE__).modules.shared
local Checks = require("~materialLibraryKit.Checks")
local Sync = require("~materialLibraryKit.Sync")
Test.describe("myMetals", function()
Test.beforeEach(function() Sync.isolate() end) -- nothing a test writes reaches the room
Test.afterEach(function() Sync.endIsolation() end) -- and the room's state is shown again after it
Test.it("copper passes every check", function()
Checks.assertGood("copper")
end)
end)
return true
```
The `starterMaterials` package is a worked example that only tags materials living elsewhere (the engine's own) without copying them.
## Multiplayer and the web
Applied materials, the gallery exhibit and the lighting preset are shared through `Sync`. The lighting rig is local to each machine; every look finds its own extra lights (studio fill and rim, warm practicals) by name, keeps exactly one of each and switches them to that look, so a player who joins, or a reload, cannot leave one switched on. Every peer converges on the newest write, and a player who joins later is sent the room's state: the test suite sends that snapshot through the engine's loopback transport and checks that the material, the lighting look and the gallery view all take it. Running the tests changes nothing other players see: each test runs inside `Sync.isolate()`, which keeps what it writes off the room and answers players who join from the room's real state, and the suite checks that the room's state and messages are untouched afterwards. Gallery swatches are local, temporary entities rebuilt on every peer, so they cost the network nothing. A full page of the gallery is about 183 entities: 16 bays, each with 7 models and 2 text blocks (name, facts). In a browser tab every page and view measured 47-60 fps (`Gallery.requestTour` measures any player's machine).
## Known limits
Engine problems are listed by their GitHub issue number (OrigoZero/zero) and only while they are open.
- **A live two-player check needs a second client.** One engine is one peer, and an engine cannot start a browser engine itself (#20946), so the second player is a browser tab or another device on the world's play page. Two engines signed in to the same account collide as one player (#14448), so the second client signs in with another account. The kit's tests send the late-join snapshot through the engine's loopback transport, and `Sync.askRoom(seconds)` asks every peer what it actually shows.
- **The gallery's frame rate in a browser (#20750).** The core's own gallery pages measured 47-60 fps in a browser tab, but a bigger page runs slower on the web than on the desktop: metalsMaterials measured about 30 fps on its 28-bay page, with most of each frame spent on the engine's multiplayer updates.
- **Installs with several dependencies are slow (#21420).** A collection brings the library with it, and a collection with many textures takes a while to install. Let it finish.
- **The two guides cannot be found through ZeroMind library search yet (#22181).** Searching ZeroMind for "how to add materials to my game" or "dress my game level with materials" brings up material collections, not the guides `addMaterialsToYourGame` and `dressYourLevelWithMaterials`. They come with the package: once it is installed they are in its `guides` folder (`materialLibraryKit.package/guides/<name>.guide/guide.md`, under `/source/deps/` when a collection brought the library), and the agent in the editor opens them by name.
- **The ZeroMind description can lag one release behind (#19258).** Right after a release the search card can still show the previous version's text; the package itself (`package.yaml`, this README) is the release.
- **The editor and players are in different rooms.** The engine keys rooms `{world}/{profile}/{mode}/{scene}`, so an editor in play never shares state with players of the published world. Two players of the published world do. To watch players from the editor, join their room with `multiplayer.joinRoom("<world>/runtime/play/<scene guid>")` and read `Sync.heard()`. This is the engine's design, not a bug.
- **Hidden browser tabs throttle.** A player whose tab is in the background catches up with lighting and material changes when the tab comes back.
- **The parallax bricks.** The starter collection's `bricksParallax` and `bricksFlat` cost about 26.7 MiB of texture each, which is over the per-material web budget. `Checks.budget` reports it, and the gallery label shows the cost. They are the engine's own materials, so the collection tags them rather than fixing them.
# traversalKit: climbing and rooftop movement for any character
A nimble character who scales walls, hangs off ledges, shimmies round corners, vaults fences at a run, balances along roof ridges and runs up walls to reach a higher edge: the movement a stealth game in a feudal castle town needs, and just as useful for platformers and adventures. Built on **climbKit** (mantle, wall climb, ledge hang and shimmy) and the engine's own CharacterController, IK and animation; works on keyboard, gamepad and touch, for players and NPCs, in multiplayer.
## Paste this into an empty world
Install traversalKit from ZeroMind (search **traversalKit**). If the new world has no `scenes/main.scene` yet, make one with a player first: in the editor's Scenes panel choose New scene with a player and set it as the startup scene (an agent runs `zero scene create --startup main player`). Then open `scenes/main.scene/build.luau` and add these lines at the end of `content()`, just before its `end` (the scene already has ground, light and a player `body`), then press play:
```luau
local K = require("traversalKit.kit")
K.equip(body) -- climbing, ledges, vaults, ridges, ropes, IK, sounds
local wall = entity.spawn("Wall") -- an ordinary box: it climbs by rule, nothing marked
wall.component.add("Model", { model = "cube" })
wall.component.add("BoxCollider", {})
wall.localPosition = { 0, 3, -6 }
wall.localScale = { 6, 6, 1 }
```
Walk into the wall and keep pushing: you climb it and pull up over the top. Walk off the top and pull back toward it: you catch the edge and hang; push left or right to shimmy round the corners, push toward the wall to pull up. The example guide (*Build a small climbing level from an empty world*) builds a whole course with vaults, ridges, ropes, a timer and a guard that climbs after you.
## Installs with it
Installing traversalKit brings everything it needs; nothing else has to be installed by hand:
| Package | Version | What traversalKit uses it for |
|---|---|---|
| climbKit (Ledgework) | 1.1.35 | mantle, wall climb, hang, shimmy, corners, climb rules |
| juiceKit | 1.2.12 | screen feedback: shakes, landing squash, dust on catches, slips and hard landings |
| navKit | 1.5.4 | NPC routes (ClimbFollower) and climb links for navKit's `climber` style |
| soundstage | 2.1.3 | the sound pool the hold sounds play through (footsteps and impacts too) |
| aiKit | 1.3.19 | the `climbingGuard` preset `ClimbNav` defines: aiKit's guard that climbs after a player (aiKit brings MatchFlow and SecondWind with it) |
The engine's own CharacterController, IKLimb and animation graph come with every world. For keyboard, gamepad and touch control schemes add **controlsKit** (checked with 1.4.4). aiKit and traversalKit must share one navKit: install aiKit and navKit at versions that agree (aiKit 1.3.19 with navKit 1.5.4), or a guard plans on a second navKit copy that knows nothing of the climb links.
## What it does
- **Climb up, down and sideways** on walls, cliffs, posts and trees; **grab a ledge, hang, shimmy, go round corners, pull up and mantle over** (climbKit).
- **Vault** a waist-high fence or wall at a run without breaking stride.
- **Balance** along a narrow ridge or beam: a wobble you steer out of, a slip down the roof you can catch at the eave.
- **Helped catches**: a jump is steered onto the ledge or post it is heading for; letting go catches the ledge below on the way down, a thin lip as well as a deep shelf (above a shelf the drop is carried out past its edge, so the shelf is caught as a hang instead of landed on); step off an edge and pull back toward it to hang from it (arcade catches it for you). The catch ends in a steady hang on every help level: keeping the stick pulled back holds it, and you pull up only when you ease off and push toward the wall again (or press jump). The help level decides how far out and how late a catch still works, with a scrabbling grab that slows the fall while the hands reach back: arcade 1.8 m and 1.3 s, standard 1.5 m and 1.0 s, strict 0.9 m and 0.7 s.
- **Ridges and beams**: a small push gives a wobble you recover from; a long one tips you off, and the ridge or beam is caught as a hang (arcade by itself, standard and strict with a jump press).
- **Lips, eaves and dead ends**: climbing up under a thin lip (a string course, a sill) climbs up over it onto the wall above, and pushing up from a hang on a lip does the same. Pushed straight up under an eave it cannot get past, the climber edges sideways toward where the eave opens; in a true dead end (no way up, round, over or to either side) it lets go after a second rather than pinning the player to the wall.
- **Ladders and ropes**; **wall run-ups** of a few steps to a higher edge.
- **Hands control back cleanly**: every move hands the CharacterController back its walking and jumping when it lands.
## No tagging needed
Surfaces climb **by rule**: steep enough, tall enough, and not smooth. On the arcade and standard help levels that is every solid wall a level already has, an ordinary unmarked box included; strict wants something that gives a real hold (stone, brick, wood, bark, rock, cliff, terrain or a rough material). Glass, ice, metal and polished surfaces never climb. An existing town or mountain with sensible colliders just works. To mark something on purpose and say what hold it is, add a `ClimbSurface` (`K.mark(entity, "ladder")`) or set it never climbable (`K.mark(entity, "stone", false)`). `K.explain(entity, hit)` says why a surface did or did not pass.
## Swap while it runs
| Setting | Choices |
|---|---|
| Movement feel (`feel`) | `nimble`, `armoured`, `ordinary`, `acrobat` |
| Hold kind (`ClimbSurface.kind`) | `stone`, `timber`, `tiles`, `rope`, `ladder`, `tree`, `cliff`, `bamboo`: each handles, sounds and is held differently |
| Help (`assist`) | `arcade`, `standard`, `strict` |
Every feel, hold kind and help level carries `tags` ("heavy", "stealth", "roof", "slippery", "easy", "speedrun" and more), and each list filters by them: `require("traversalKit.feels").withTag("heavy")`, `require("traversalKit.holds").withTag("slippery")`, `require("traversalKit.assists").withTag("easy")`.
`K.setFeel(body, "armoured")`, `K.setAssist(body, "arcade")`, a `TraverseZone` volume, or the `TraverseHud` buttons. The **gallery scene** (`scenes/gallery` in the High Ground world) shows all of them side by side.
## For game code
`K.state(body).mode` is `grounded`, `airborne`, `falling`, `climbing`, `ladder`, `rope`, `hanging`, `mantling`, `vaulting`, `wallrunning`, `balancing` or `slipping`, on every peer. Events fire on every peer: `onGrab`, `onRelease`, `onPullUp`, `onVault`, `onWallRun`, `onWobble`, `onRecover`, `onSlip`, `onCatch`, `onLand`, `onModeChanged`.
`onGrab` and `onCatch` say what was taken hold of: `kind` is the hold kind under the hands (also on a catch made while dropping onto a lip or shelf below); `ledgeId` is the entity of the ledge being hung from (or of the wall or hold being climbed; "" for a rope or a jump catch with nothing in hand) and `topY` the height of its edge. `onLand` and the `grounded` mode come only from real ground under the feet: letting go of a hang reports `airborne` and then `falling`, never a landing in mid air.
```luau
K.on(body, "onCatch", function(e)
if e.ledgeId ~= "" and entity(e.ledgeId).name == "BellTowerLip" then print("caught the bell tower at", e.topY) end
end)
K.on(body, "onGrab", function(e) print("grabbed", e.kind) end)
K.on(body, "onPullUp", function(e) print("up and over a", e.height, "m edge") end)
```
## NPCs
`K.spawnFollower({ position = p, feel = "armoured" })` makes an NPC that follows the nearest player (or a `target`) with navKit paths on foot and climbs, mantles, vaults and runs up walls after them.
Any navKit NPC can climb too: `K.linkClimbableWalls({ center = { x, y, z }, radius = 40 })` tells navKit about every wall traversalKit climbs, as a `ladder` link from its foot to a top a character can stand on. An ordinary **aiKit** guard on navKit's `climber` style then plans its chase up the wall. The `ClimbNav` component does both in one step: put it on the entity holding a navKit `multiLevel` map and it defines aiKit's `climbingGuard` preset (aiKit's `guard`, moving on navKit's `climber` style) and links the walls once the map has baked; then give the guard `aiKit.Brain` with `preset = "climbingGuard"`. The High Ground gallery has one.
## Touch
With controlsKit, a floating stick suits climbing best (it appears under the thumb; a gentle push climbs slowly, sideways on a ledge shimmies): `require("controlsKit.controls").setStick("floating", "left")`. While you hang or climb, the camera swings round behind the climber at corners, so up on the stick always points up the wall.
## Multiplayer
Each body's own peer runs its moves; the body's position replicates with the engine's interpolation (smooth, not snapping), `mode` and the events are synced, and `ClimbRig` draws every climber's animation, hand and foot placement and facing on every peer from that synced state. Feedback goes through juiceKit, which shows it to everyone.
## What it ships
| Part | |
|---|---|
| `kit.module` | the one interface: `equip`, `mark`, `setFeel`, `setAssist`, `state`, `on`, `spawnFollower`, `explain` |
| `Traverser.component` | the moves, synced mode and events |
| `ClimbRig.component` | animations, hand and foot IK (hanging hands rest on top of the lip), facing, sounds, soft fading dust puffs and feedback for every move, on every peer |
| `ClimbCamera.component` | camera framing per move (pull back and look up on walls, lower on ridges, a speed kick on vaults and wall runs), keeping the player's own zoom and the orbit rig's own distance (from its rings), so it never settles closer just because the rig's collision sweep pulled in. The camera stays out of walls, roofs and anything with a collider and aims for at least 2.9 m from the climber (a standing climber then fills at most about half the screen height, and on walls, ladders and ropes typically 25 to 35 %): when the way straight back is blocked it looks round and above the climber for a clear spot instead of closing in. From 1.0.24, when nothing near behind has room and the climber is not holding on, it looks all the way round and higher, and as a last resort looks down from high above, before settling anywhere under 1.2 m (on a hold it stays close to behind, because the stick is read against the camera there). Where there is truly no room (a body dropping past a roof's edge under a taller wall, the foot of a ladder under a deck) it can still come within about 0.3 to 0.7 m for up to half a second; on Ridge Run on 18 November that happened two or three times a run, never on a hold, and never with the camera inside a collider. From 1.0.22 it runs after the orbit rig each frame (`executionOrder` 50), so the spot it picks is where the camera really is; during a pull-up it looks for room from just above the ledge and, with none at 2.9 m, holds where it was; and with no room anywhere it never settles nearer than the rig's own spot. Trees and other drawn-only scenery never push it in: what is drawn between the camera and the climber with no collider (branches of a forest's instanced trees, which no raycast sees and which are read back from the renderer as the climber moves 15 m, and ordinary drawn-only meshes) is not drawn, the near plane moving out to 0.6 m before the climber. Under a lip or shelf the aim point drops so the camera keeps its distance. The rope being climbed (`Traverser.heldRope`) is left out of the camera's collision checks while held and for 1.5 s after letting go (a top-out still has the body against it), and the aim test skips everything on the rig's `cameraIgnore` list, so a rope running through the aim column no longer leaves the aim in a beam overhead and the camera in the climber's head (fixed at Ridge Run's rope 2 top-out in 1.0.20). The near plane clears what is drawn before the climber from where the camera really is as well as from where it was placed, since the orbit rig can hold the camera further out (1.0.20). Two read-only fields help debugging: `treeBoxes` and `clipNote`. The climber is never hidden: up to 1.0.20 the camera switched the climber's model off as a last resort when it had no room, through a setting every player shares and that only that camera's memory switched back on, so after a reload or a new play session a climber could stay invisible for good. From 1.0.21 the camera never hides the climber, and switches back on a climber model it finds switched off. When the lens comes within 0.5 m of the ground under it (a slope rising behind on a trail), the rig pitches up over it, at most three-quarters of the way to its top ring, and eases back to the player's own pitch once clear (1.0.21 also pitched up for a climber nearer than 1.2 m, which on a wall ended looking straight down on the head; 1.0.22 does not). For small props that should vanish while in the way (crates, lanterns, banners), add **viewClear** (Dockhands world) on their group, as Ridge Run does for its checkpoint banners; do not put holds the player climbs in such a group |
| `ClimbSurface.component` | mark a hold on purpose, choose its kind |
| `ClimbFollower.component` | NPC that follows players up walls |
| `ClimbNav.component` | the `climbingGuard` aiKit preset and the navKit wall links for it |
| `TraverseZone.component` | volume that switches feel / help |
| `TraverseHud.component` | mode readout and feel / help switchers (touch, mouse, F / G) |
| `holds.module`, `feels.module`, `assists.module`, `rules.module` | the catalogues and the climb rule |
| `holdSounds.module`, `sounds/` | grab, hand, foot and slip sounds per hold kind, plus vault, landing, wobble and pull-up |
| `anims/` | 15 humanoid climbing clips and the module that keys them |
| `docs/` | the two guides below |
| `tests/` | probes for the rule, holds and moves |
Guides (open with the `guides` tool): **How to make my character climb walls and ledges** and **Build a small climbing level from an empty world**.
## Limits
- Up is world +Y (no climbing in `GravityField` frames), like climbKit.
- The 15 climbing clips are made with the engine's animation generator (anim_gen) and made in place by `anims/clipImport.module`; hands and feet are placed by IK on top of them. Drop in your own clips under the same names to change them.
- One climb rule tuning is active per peer: the local player's assist level.
- Hanging just under a deep eave (the Ridge Run cabin), the hands rest on the roof but the forearms pass through the eave board.
- Slow machines: a long frame is climbed in steps of at most 1/30 s, and a body a long frame pushed into the ground or a post beside the wall is moved free, so climbing keeps working at low frame rates (Ridge Run finishes on keyboard with frames averaging 150 to 200 ms and spikes of several seconds). Frames longer than 0.1 s are still counted as 0.1 s, so below 10 frames a second everything, climbing included, runs slower than real time.
- A climber pinned where it cannot rise (a true dead end, a pocket under a low eave) lets go after one second of the stick asking for a way nothing gives, in any direction but down or away (`onClimbEnd` reason `no way up`). A player who wants to stay there eases off the stick. From climbKit 1.1.27 a climb or a hang whose stick is held (not down or away from the wall) while the body moves less than 5 cm for 2 s lets go the same way, including a hang pushed sideways at a ledge's dead end; after any `no way up` let-go (from a climb or a hang) that wall is not climbed again for 3 s, so the player is not put straight back into it. From climbKit 1.1.31 a stick held down or away at the foot of a wall that sticks out below (a plinth, a foundation) lets go after 0.5 s of going no lower when the ground is within 2.5 m (`onClimbEnd` reason `blocked below`). A rope topped out from is not taken again for 4 s, nor ever from a standing height near its top (1.0.21). From 1.0.22 a light push (about 15 % of the stick or a short touch drag) gets a climber off a rope's top: at Ridge Run's rope 1, 1.0 s with the gamepad stick at 35 % and 1.1 s with a 45 px touch drag, where 1.0.21 wanted half the stick and a person measured 1.7 s on gamepad and up to 9 s on touch. Also from 1.0.22, a player pushing with no headway on the ground for half a second gets help: into a climbable wall at a slant the climb starts (a missed jump into the alley under Ridge Run's second house: out in 0.6 to 3.9 s at any angle from 50 to 80 degrees off straight in, where a person stood 24 s), and against a wall that gives nothing the push turns along it to the side that is open and has ground under it, further each time it is stuck again; never away from a ladder or rope being walked into. On 18 November 2026 (traversalKit 1.0.24, climbKit 1.1.35) a scripted route driver ran Ridge Run through real simulated input on a heavily loaded desktop (5 to 30 frames a second): keyboard finished start to finish twice (2:41 and 2:56) and gamepad once (3:07), every checkpoint, no falls, and a watcher saw no stall, no rope or ladder loop, the camera never inside a collider and the climber never hidden. Other runs that day did not finish, all at the jumps to the post and the ledge: at that frame rate the driver's jumps fell short, and from the alley under the second house the driver could not find its way back, though a steady push into the house's stone wall climbs out onto the ledge in about 5 s (most push angles; the first 2 s are the wait before a push into a wall starts a climb). One finding was real and is fixed in Ridge Run 0.1.9: the stone bases of the second and third houses stopped above a dip in the ground, so a climber there grabbed the stone, found no wall at the feet and let go, over and over; and the cabin's corner fill left a pocket and a shelf under the eave. Touch was driven once and stopped in that alley; a full touch run and the second gamepad run are not proven on this version. A scripted driver steers differently from a person, so stalls that depend on how a person arrives are not proven gone.
- Ropes top out on any push but down within their last 35 cm: onto a floor about level with the feet up to 1.3 m away (a deck or roof beside the rope's top), the way pushed first and then round the rope, or else onto a ledge above the feet, the way pushed and then all the way round (1.0.24; before, a roof behind the climber was never tried, and a push the wrong way held them at the top).
- Arrivals (1.0.24): after any pull-up (a wall, a ladder, a post, a rope's top, a ledge), for 1.5 s, and until the stick is let go or a jump is asked for, walking stops short of a drop deeper than 0.9 m, so the push that carried the climber up no longer walks them straight off a small top and back onto the hold. A ladder being climbed is on climbKit's `ignoreLedges` list (climbKit 1.1.35), so its own rails are never taken for the top: before, Ridge Run's second ladder stood the climber on a 14 cm slab 0.9 m above the deck. A narrow top only counts as a beam to balance along when it runs on for 1.2 m, so a post cap is somewhere to stand. Measured with a sweep (every feel, every help level, the stick held at -90 to 180 degrees from the moment of the pull-up): ladder 1, ladder 2 and the post cap stand the climber on top every time; the only exceptions were the climber walking on along the roof to a corner and stopping there, or onto the rope that hangs beside ladder 2's deck.
- Hand-back (1.0.24 and climbKit 1.1.35): the engine's CharacterController now speeds up and brakes toward the stick (`acceleration`, `braking`) from a walk of its own that it resets while switched off, so a vault or pull-up handed back only the input restarted from standing. Both kits now hand the move's own speed across with one frame of `acceleration` 0, and the controller's own feel is back the next frame.
- Facing (1.0.24): a body with no `Locomotion` faces `transform.forward` (the engine's default front, Locomotion's own default `{0, 0, -1}`); ClimbRig and climbKit both assumed the old `+Z` and turned such a body's back to the wall. A floor at the feet wins over a beam overhead (the rope's own anchor). This needs climbKit 1.1.29 or later (`tryMantle` options).
## Reused versus new
traversalKit is the new layer; most of what it does runs on published parts and the engine.
| | Code (Luau lines) | Share |
|---|---|---|
| climbKit 1.1.35, juiceKit 1.2.12, navKit 1.5.4, soundstage 2.1.3, aiKit 1.3.19 | 28,510 | 84% |
| traversalKit itself | 5,391 | 16% |
Also reused, not counted: the engine's CharacterController, IKLimb and animation graph. The High Ground world as a whole is about 97% installed code (236,116 lines across 11 installed packages and the 16 packages they depend on) against 3% made for it (7,960 lines: traversalKit 5,391, Ridge Run 1,233, scenes and world components 1,336), counted on 18 November 2026. `reuse-review.md` in the High Ground world rates every installed part 1 to 5 and lists what was built new.
# animatedMaterials: Flux and Flicker
**Animated and special surfaces for the Swatchbook material library (materialLibraryKit): flowing water and lava, conveyor belts and treadmills that travel at a stated speed in metres per second, wind-blown cloth, pulsing lights, dissolves, holograms, spreading frost, drying wet surfaces, a spreading burn and world-aligned rock, ground, masonry and metal; every live setting is changed per object with one call that every player sees.**
Version 1.0.16. Depends on materialLibraryKit 1.3.4 (Swatchbook) and nothing else; installing this package brings the library along and no other collection. A fresh install also writes six of the engine's own shader parts into the new world under `deps/` (`pbr`, `unlit`, `pbr_shading`, `shadows`, `shadow_bias`, `engine_bindings`): the package's shaders include the engine's PBR shading module and some materials draw with its `pbr` and `unlit` shaders, and the engine pins every built-in asset content names at the version it was built against, so the materials look the same in every world whatever engine library that world is on. Once installed, all 28 materials are in the library's list, picker and swatch gallery on every player's machine, with no setup code.
## Install, then flowing lava and a dissolving crate
Install **animatedMaterials** from ZeroMind (search "animatedMaterials" or "Flux and Flicker"). Then, in an empty world, from the console or any script:
```luau
local Materials = require("~materialLibraryKit.Materials")
local Live = require("~animatedMaterials.Live")
-- flowing lava on a 4 m plane; synced, so every player has the plane and sees the lava
local lava = entity.spawn("lavaPool", { synced = true, components = { Model = { model = "plane" } } })
lava.localScale = { 4, 1, 4 }
lava.localPosition = { 0, 0.02, 0 } -- 2 cm up, clear of the ground it would flicker through
assert(Materials.apply(lava, "lavaCrusted"))
assert(Live.set(lava, "flowSpeed", 0.3)) -- metres per second, this plane only
assert(Live.set(lava, "flowDirection", 90)) -- degrees on the surface: now it runs along +V
-- the dissolve on a crate, driven from 0 (whole) to 1 (gone) over 3 s of game time
local crate = entity.spawn("crate", { synced = true, components = { Model = { model = "cube" } } })
crate.localPosition = { 3, 0.5, 0 }
assert(Materials.apply(crate, "dissolveEmber"))
assert(Live.set(crate, "amount", 0))
assert(Live.set(crate, "amount", 1, { over = 3 }))
```
`Materials.apply` and `Live.set` return `ok, err`; the `assert` stops with the reason instead of leaving a grey or still object. Swap the look by changing one word: `"lavaToon"`, `"dissolveArcane"`, `"dissolveDigital"`. `Live.get(crate, "amount")` reads what an object shows now, `Live.settings("lavaCrusted")` lists what a material takes with its ranges, `Live.reset(crate)` puts its settings back to the material's defaults, and `Materials.clear(crate)` then `entity.despawn(crate.id)` takes it away again.
## One way to change any animated material: `Live`
Every animated or special material has its live settings (listed below), and they are all changed the same way:
| Call | Does |
|---|---|
| `Live.set(object, setting, value, opts?)` | Sets one setting of one object, clamped to its range, for every player. `opts.over = seconds` eases to it on the game's clock; `opts.localOnly = true` keeps it on this machine. Returns `ok, err` (an unknown setting is refused with the list the material takes). |
| `Live.get(object, setting)` | The value the object shows now (its own, else the material's default); nil for an object that wears no material of this collection, and while the material library has not loaded yet. |
| `Live.all(object)` | Every setting of the object, `{ [name] = value }`. |
| `Live.reset(object, setting?)` | Back to the material's default, one setting or all, for every player. |
| `Live.settings(materialId)` | `{ name, min, max, default, unit, description }` for each setting. |
| `Live.onChanged(fn)` | `fn(object, setting, record)` whenever a setting changes here or arrives from another player. Returns an unsubscribe function. |
- **Per object.** A setting is written as the object's own named values (`am.<setting>`), which the material binds in its `values:` block, so twenty crates wearing one material each show their own amount, and an object never given a setting shows the material's default. A setting on a parent reaches the meshes under it.
- **Every player, late joiners too.** Settings go through materialLibraryKit's `Sync` (newest write wins), keyed the way `Materials.apply` keys objects: a shared (`synced`) entity, the scene's own entities and the gallery's swatches. A player who joins later is sent the room's state and their objects take it.
- **No jumps.** Changing a speed or a direction never makes the surface jump: each setter also states where the surface stood at that moment on the shared clock, and a ramp (`over`) integrates the motion as the speed or direction changes.
- **The game's own clock.** Every material moves by `AnimClock`: in play it advances with gameplay time, so `engine.timeScale` slows it and a pause freezes it; in edit mode it runs on real time, so the surfaces move while you author. A machine that joins asks the room for the clock and takes it before it ever speaks for the room; one machine per mode (edit or play), the lowest peer id among those already keeping the time, restates it every 5 s, and a small drift is eased in rather than jumped, so a stripe or a wave stands in the same place on every screen. Only the newest copy of `AnimClock` on a machine answers, so an edited module that reloaded on every machine never sends its old, stopped clock. A setting made on a machine in the instant before its clock takes the room's time (a script that runs as a player joins, or as the module reloads) is moved onto the room's time when it does, so its ramp still runs its full length. Ramps (`over`) run on the same clock: they slow, pause and finish together everywhere.
## Texture memory
**6 MB for all 28 materials** (GPU memory, mipmaps included; UASTC, which the engine turns into BC7 on desktop and ASTC on phones). 22 of the 28 are procedural and bind no texture at all. The six that do (`wetPaving`, `wetAsphalt`, `worldRock`, `worldGround`, `worldMasonry`, `worldMetal`) bind 3 textures each at 512 px (albedo, normal, and a mask packing ambient occlusion, roughness, height and metal), 1 MB per material. **The 28 reference pictures** the gallery hangs add 9.3 MB (512 px each, 341 KB), **15.3 MB with them**. Every material passes the library's web check (`Checks.budget`): at most 3 sampled textures (the web limit is 9), no storage buffer (the limit is 1), nothing over 512 px.
## The materials
Every material is tagged `animatedMaterials`, its category (`animated` for the ones that move by themselves, `special` for the amount-driven and world-aligned ones), what kind it is, `family-<family>`, `animated` with what moves or `not-animated`, `live-settings` with each setting and its range (`live-flowSpeed 0..3 m/s`) or `no-live-settings`, its tile size (`tile-<metres>m`, the metres one repeat covers, 1 unit = 1 m), how it is mapped (`mapping-uv`, `mapping-object` for the belts and effects, `mapping-world` with `world-aligned` and `triplanar`), its style (`style-realistic`, `style-toon`, `style-scifi`, `style-fantasy`), `emissive` and `self-lit` where it glows, how many textures it binds and their cost (`0-textures`, `textures-none`; `3-textures`, `textures-medium`), `seamless`, `metallic` or `non-metallic`, and search words. The library keeps its tags in lower case. Each kind comes in at least two looks, so a world swaps the look by changing one name.
The live settings are changed with `Live.set` on one object (above). A setting marked m/s, Hz or lines/s is a speed: the surface travels at it and never jumps when it changes. Tile is the real size of one repeat; the belts and the effects map in metres along the object's own axes, the world-aligned set by world position.
| Material | Name | Kind | Category | Style | Tile | Live settings (range, default) | Textures (memory) |
|---|---|---|---|---|---|---|---|
| `riverClear` | Clear mountain river | river | animated | realistic | 2 m | `flowSpeed` 0..3 m/s (0.8), `flowDirection` 0..360 deg (0) | none (0 KB) |
| `riverMurky` | Murky lowland river | river | animated | realistic | 2 m | `flowSpeed` 0..3 m/s (0.6), `flowDirection` 0..360 deg (0) | none (0 KB) |
| `waterToon` | Toon water | river | animated | toon | 2 m | `flowSpeed` 0..3 m/s (0.8), `flowDirection` 0..360 deg (0) | none (0 KB) |
| `lavaCrusted` | Crusted flowing lava | lava | animated | realistic | 2 m | `flowSpeed` 0..0.5 m/s (0.12), `flowDirection` 0..360 deg (0), `glow` 0..4 x (1) | none (0 KB) |
| `lavaToon` | Toon lava | lava | animated | toon | 2 m | `flowSpeed` 0..0.5 m/s (0.12), `flowDirection` 0..360 deg (0), `glow` 0..4 x (1) | none (0 KB) |
| `beltRubber` | Rubber conveyor belt | conveyor belt | animated | realistic | 1 m | `beltSpeed` -5..5 m/s (0.5) | none (0 KB) |
| `beltSlats` | Steel slat conveyor | conveyor belt | animated | realistic | 0.15 m | `beltSpeed` -5..5 m/s (0.5) | none (0 KB) |
| `treadmill` | Treadmill belt | treadmill | animated | realistic | 1.4 m | `beltSpeed` -5..5 m/s (2.5) | none (0 KB) |
| `treadmillNeon` | Sci-fi glow treadmill | treadmill | animated | scifi | 0.5 m | `beltSpeed` -5..5 m/s (1.5) | none (0 KB) |
| `flagCotton` | Printed cotton flag | flag | animated | realistic | 1.5 m | `windStrength` 0..25 m/s (8), `windDirection` 0..360 deg (0) | none (0 KB) |
| `bannerCanvas` | Heavy canvas banner | banner | animated | realistic | 2 m | `windStrength` 0..25 m/s (8), `windDirection` 0..360 deg (0) | none (0 KB) |
| `pulseBreath` | Breathing light panel | light panel | animated | scifi | 1 m | `pulseRate` 0..4 Hz (0.25), `glow` 0..30 x (6) | none (0 KB) |
| `pulseAlarm` | Alarm strobe lens | alarm light | animated | realistic | 0.6 m | `pulseRate` 0..4 Hz (2), `glow` 0..30 x (9) | none (0 KB) |
| `dissolveEmber` | Ember dissolve (wooden crate) | dissolve | special | realistic | 1 m | `amount` 0..1 (0.45), `edgeGlow` 0..20 x (7), `edgeWidth` 0.005..0.2 m (0.03) | none (0 KB) |
| `dissolveArcane` | Arcane dissolve (carved stone) | dissolve | special | fantasy | 1 m | `amount` 0..1 (0.45), `edgeGlow` 0..20 x (7), `edgeWidth` 0.005..0.2 m (0.06) | none (0 KB) |
| `dissolveDigital` | Digital dissolve (sci-fi panel) | dissolve | special | scifi | 0.5 m | `amount` 0..1 (0.45), `edgeGlow` 0..20 x (10), `edgeWidth` 0.005..0.2 m (0.07) | none (0 KB) |
| `holoBlue` | Blue hologram | hologram | animated | scifi | 1 m | `flicker` 0..1 (0.25), `glitch` 0..1 (0.15), `glow` 0..8 x (1.3), `scanSpeed` -20..20 lines/s (12) | none (0 KB) |
| `holoGlitchRed` | Glitching red hologram | hologram | animated | scifi | 1 m | `flicker` 0..1 (0.75), `glitch` 0..1 (0.8), `glow` 0..8 x (1), `scanSpeed` -20..20 lines/s (9) | none (0 KB) |
| `frostWindow` | Frosting window glass | frost | special | realistic | 1 m | `amount` 0..1 (0.5) | none (0 KB) |
| `frostToon` | Toon frost creep | frost | special | toon | 1 m | `amount` 0..1 (0.5) | none (0 KB) |
| `wetPaving` | Wet flagstone paving | wet paving | special | realistic | 2 m | `wetness` 0..1 (0.7) | 3 (1024 KB) |
| `wetAsphalt` | Wet road asphalt | wet asphalt | special | realistic | 3 m | `wetness` 0..1 (0.7) | 3 (1024 KB) |
| `burnWood` | Burning wooden planks | burn | special | realistic | 1 m | `amount` 0..1 (0.5), `emberGlow` 0..10 x (4) | none (0 KB) |
| `burnToon` | Toon burning planks | burn | special | toon | 1 m | `amount` 0..1 (0.5), `emberGlow` 0..10 x (3) | none (0 KB) |
| `worldRock` | World-aligned cliff rock | rock | special | realistic | 4 m | none (world-aligned, still) | 3 (1024 KB) |
| `worldGround` | World-aligned forest floor | ground | special | realistic | 2 m | none (world-aligned, still) | 3 (1024 KB) |
| `worldMasonry` | World-aligned brick | brick | special | realistic | 0.9 m | none (world-aligned, still) | 3 (1024 KB) |
| `worldMetal` | World-aligned chipped painted metal | painted metal | special | realistic | 1 m | none (world-aligned, still) | 3 (1024 KB) |
- `riverClear`: animatedmaterials, animated, river, family-water, flowing, travels in m/s, rippling, live-settings, live-flowspeed 0..3 m/s, live-flowdirection 0..360 deg, tile-2m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, water, stream, creek, brook, clear, mountain, pebbles, shallow, transparent, caustics, nature
- `riverMurky`: animatedmaterials, animated, river, family-water, flowing, travels in m/s, rippling, drifting scum, live-settings, live-flowspeed 0..3 m/s, live-flowdirection 0..360 deg, tile-2m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, water, murky, muddy, silty, swamp, lowland, canal, brown, green, scum, foam, nature
- `waterToon`: animatedmaterials, animated, river, family-water, flowing, travels in m/s, sparkling, live-settings, live-flowspeed 0..3 m/s, live-flowdirection 0..360 deg, tile-2m, mapping-uv, style-toon, toon, 0-textures, textures-none, seamless, non-metallic, water, cartoon, cel shaded, stylised, sea, teal, blue, foam, sparkle
- `lavaCrusted`: animatedmaterials, animated, lava, family-lava, flowing, travels in m/s, glowing, crust tearing, live-settings, live-flowspeed 0..0.5 m/s, live-flowdirection 0..360 deg, live-glow 0..4 x, tile-2m, mapping-uv, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, magma, molten, volcano, volcanic, fire, crust, basalt, hot
- `lavaToon`: animatedmaterials, animated, lava, family-lava, flowing, travels in m/s, glowing, live-settings, live-flowspeed 0..0.5 m/s, live-flowdirection 0..360 deg, live-glow 0..4 x, tile-2m, mapping-uv, style-toon, toon, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, cartoon, cel shaded, stylised, magma, volcano, fire, orange
- `beltRubber`: animatedmaterials, animated, conveyor belt, family-belt, scrolling, travels in m/s, live-settings, live-beltspeed -5..5 m/s, tile-1m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, conveyor, belt, rubber, factory, warehouse, industrial, black, moving surface
- `beltSlats`: animatedmaterials, animated, conveyor belt, family-belt, scrolling, travels in m/s, live-settings, live-beltspeed -5..5 m/s, tile-0.15m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, metallic, conveyor, slats, steel, metal, chain conveyor, factory, airport, baggage, moving surface
- `treadmill`: animatedmaterials, animated, treadmill, family-belt, scrolling, travels in m/s, live-settings, live-beltspeed -5..5 m/s, tile-1.4m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, running machine, gym, fitness, belt, black, moving surface
- `treadmillNeon`: animatedmaterials, animated, treadmill, family-belt, scrolling, travels in m/s, glowing, live-settings, live-beltspeed -5..5 m/s, tile-0.5m, mapping-object, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, metallic, moving walkway, travelator, sci-fi, neon, cyan, glow, spaceship, conveyor, moving surface
- `flagCotton`: animatedmaterials, animated, flag, family-cloth, fluttering, waving in the wind, vertex animation, live-settings, live-windstrength 0..25 m/s, live-winddirection 0..360 deg, tile-1.5m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, cotton, fabric, cloth, wind, waving, banner, printed, pole, teal, orange, star
- `bannerCanvas`: animatedmaterials, animated, banner, family-cloth, billowing, swaying in the wind, vertex animation, live-settings, live-windstrength 0..25 m/s, live-winddirection 0..360 deg, tile-2m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, canvas, sail, sailcloth, heavy fabric, cloth, wind, medieval, tent, stitched, hem
- `pulseBreath`: animatedmaterials, animated, light panel, family-pulse, pulsing, breathing, glowing, live-settings, live-pulserate 0..4 hz, live-glow 0..30 x, tile-1m, mapping-uv, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, metallic, pulse, sleep light, glow, standby, led, frosted, acrylic, sci-fi, wall light, indicator
- `pulseAlarm`: animatedmaterials, animated, alarm light, family-pulse, flashing, strobing, glowing, live-settings, live-pulserate 0..4 hz, live-glow 0..30 x, tile-0.6m, mapping-uv, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, alarm, strobe, warning light, beacon, siren, red, flash, emergency, lens, industrial, lockdown
- `dissolveEmber`: animatedmaterials, special, dissolve, family-dissolve, animated, driven by amount, dissolves away, flickering embers, live-settings, live-amount 0..1, live-edgeglow 0..20 x, live-edgewidth 0.005..0.2 m, tile-1m, mapping-object, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, burn away, disintegrate, ember, fire, crate, wood, destroy, vanish, char
- `dissolveArcane`: animatedmaterials, special, dissolve, family-dissolve, animated, driven by amount, dissolves away, pulsing runes, live-settings, live-amount 0..1, live-edgeglow 0..20 x, live-edgewidth 0.005..0.2 m, tile-1m, mapping-object, style-fantasy, fantasy, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, arcane, magic, spell, runes, stone, teleport, vanish, disintegrate, violet, cyan
- `dissolveDigital`: animatedmaterials, special, dissolve, family-dissolve, animated, driven by amount, dissolves away, flickering voxels, live-settings, live-amount 0..1, live-edgeglow 0..20 x, live-edgewidth 0.005..0.2 m, tile-0.5m, mapping-object, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, metallic, digital, de-rez, voxel, pixel, hologram, teleport, sci-fi, cyan, glitch, disintegrate
- `holoBlue`: animatedmaterials, animated, hologram, family-hologram, scanlines climbing, flickering, glitching, live-settings, live-flicker 0..1, live-glitch 0..1, live-glow 0..8 x, live-scanspeed -20..20 lines/s, tile-1m, mapping-world, world-aligned, triplanar, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, holo, projection, sci-fi, blue, cyan, scanlines, transparent, additive, glow, ghost, futuristic
- `holoGlitchRed`: animatedmaterials, animated, hologram, family-hologram, glitching, flickering hard, scanlines climbing, colour split, live-settings, live-flicker 0..1, live-glitch 0..1, live-glow 0..8 x, live-scanspeed -20..20 lines/s, tile-1m, mapping-world, world-aligned, triplanar, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, glitch, corrupted, red, error, warning, sci-fi, scanlines, chromatic aberration, transparent, additive, cyberpunk, hacked
- `frostWindow`: animatedmaterials, special, frost, family-frost, not-animated, live-settings, live-amount 0..1, tile-1m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, ice, window, glass, winter, frozen, cold, crystals, freeze, transparent
- `frostToon`: animatedmaterials, special, frost, family-frost, animated, driven by amount, frost sweeps diagonally across, twinkling sparkles, live-settings, live-amount 0..1, tile-1m, mapping-object, style-toon, toon, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, ice, freeze, cartoon, stylised, winter, cold, snow, sparkle, frozen
- `wetPaving`: animatedmaterials, special, wet paving, family-wet, not-animated, live-settings, live-wetness 0..1, tile-2m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, wet, rain, puddle, puddles, flagstone, paving, stone, street, courtyard, drying, damp, glossy
- `wetAsphalt`: animatedmaterials, special, wet asphalt, family-wet, not-animated, live-settings, live-wetness 0..1, tile-3m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, wet, rain, puddle, puddles, asphalt, road, tarmac, street, drying, damp, glossy, reflective
- `burnWood`: animatedmaterials, special, burn, family-burn, animated, driven by amount, spreading burn, flickering embers, live-settings, live-amount 0..1, live-emberglow 0..10 x, tile-1m, mapping-object, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, fire, scorch, char, charred, wood, planks, ember, smoulder, destruction
- `burnToon`: animatedmaterials, special, burn, family-burn, animated, driven by amount, spreading burn, live-settings, live-amount 0..1, live-emberglow 0..10 x, tile-1m, mapping-object, style-toon, toon, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, fire, scorch, char, cartoon, cel, wood, planks, ember
- `worldRock`: animatedmaterials, special, rock, family-world, not-animated, no-live-settings, tile-4m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, world aligned, world space, no uv, cliff, stone, boulder, mountain, blockout
- `worldGround`: animatedmaterials, special, ground, family-world, not-animated, no-live-settings, tile-2m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, world aligned, world space, no uv, forest floor, dirt, pine needles, soil, terrain, blockout
- `worldMasonry`: animatedmaterials, special, brick, family-world, not-animated, no-live-settings, tile-0.9m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, world aligned, world space, no uv, masonry, wall, running bond, red brick, building, blockout
- `worldMetal`: animatedmaterials, special, painted metal, family-world, not-animated, no-live-settings, tile-1m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, metallic, world aligned, world space, no uv, metal, chipped paint, green, steel, industrial, machine, blockout
## Pairing a conveyor with a moving surface
The belt materials (`beltRubber`, `beltSlats`, `treadmill`, `treadmillNeon`) map by metres along the object's own axes and travel along the object's own **+x**, the frame a collider's `surfaceVelocity` is stated in. Add the package's `Conveyor` component to the belt and it gives the collider `surfaceVelocity = (beltSpeed, 0, 0)` every time the belt's live speed changes, so a crate resting on it moves exactly with the stripes:
```luau
local Materials = require("~materialLibraryKit.Materials")
local Live = require("~animatedMaterials.Live")
local belt = entity.spawn("belt", { synced = true, components = { Model = { model = "cube" } } })
belt.localPosition = { 0, 0.6, 0 }
belt.localScale = { 5, 0.12, 0.9 } -- runs along its own x; turn it to aim it
belt.component.add("BoxCollider", { friction = 1 })
belt.component.add("Conveyor", {})
assert(Materials.apply(belt, "beltRubber"))
assert(Live.set(belt, "beltSpeed", 1.2)) -- m/s: the stripes and the crate both move at 1.2
local crate = entity.spawn("crate", { synced = true, components = { Model = { model = "cube" } } })
crate.localPosition = { -2, 1.2, 0 }
crate.localScale = { 0.5, 0.5, 0.5 }
crate.component.add("BoxCollider", { friction = 1 })
crate.component.add("Physics", { kind = "dynamic", mass = 20 })
```
Physics runs in play, so the crate rides in play; the stripes move in edit mode too. A negative speed runs the belt backwards. Without the component, state the same yourself: `collider.surfaceVelocity = { Live.get(belt, "beltSpeed"), 0, 0 }`.
An engine whose colliders have no `surfaceVelocity` field refuses that write (the web build has shipped without it: "Component<BoxCollider> has no declared field 'surfaceVelocity'"). The `Conveyor` then says so once in the log and carries what rests on the belt itself: the belt's collider is made frictionless while it carries (its own friction comes back when the component is removed), and at every physics step (once a frame on an engine without a physics step hook) each dynamic body whose middle stands over the belt is handed the belt's speed along it, plus a pull that closes any distance it has fallen behind, on the shared game clock. It finds the bodies by an overlap query and by the belt's contacts, and reads the belt's box from its oriented bounds, else its collider's size, else its scale. Measured on the desktop with that mode forced (`_forceCarry`), crates rode 0.499, 0.499, 2.496 and 1.497 m/s on belts at 0.5, 0.5, 2.5 and 1.5 m/s, and within about 1.3% at 1.2, -0.8, 3.0 and 2.0 m/s; the demo yard's crate rode its 0.5 m/s belt at 0.499 (step hook) and 0.504 (once a frame); with the collider's own `surfaceVelocity`, within 0.7%. `conveyor:_mode()` says which way a belt moves its load (`"surface"` or `"carry"`), and `conveyor:_carryStats()` what carrying found (the hook, the bodies near the belt and riding it, the last error a physics call gave).
## The gallery and the demo yard
This world opens on the library's swatch gallery, showing this collection alone on a stand in front of the spawn: all 28 bays on four curved rows, each row higher than the one before so its floor shows over the plaques in front, the amount-driven and world-aligned ones in the two front rows under the SPECIAL banner and the moving ones in the two back rows under ANIMATED. Players arrive on a 4 m deck facing the stand, and the camera tilts 6.5 degrees up from there, so one look shows every bay with its name and facts (checked from the play camera at 16:9 with a 60 degree vertical view). Each bay shows its material on a sphere, a cube, a shader ball and a cylinder, a floor tile and a wall at real size (the belts and world-aligned materials map in metres themselves), its reference picture in a dark frame, and a label on one shared grid that reads from the deck: the name, then three short rows (what it is; style and tile size; whether it moves by itself, by an amount or not at all, and how many textures it binds), each set about 0.38 m tall. The live settings and texture memory are in the picker and this README. The cloth bays also fly a small flag on a pole, and the lava bays stand a soft orange light. Everything moves, in edit mode too. The toolbar switches the library's six lighting looks for everyone (Daylight, Overcast, Golden hour, Moonlight, Warm interior, Studio), and **Materials** opens the picker.
Behind the deck, one turn away and down a ramp, stands the demo yard, built on every machine by the `AnimYard` component (local pieces, nothing saved into the scene file): on the left a lava channel between world-aligned rock banks, a rubber conveyor carrying a metal crate (the `Conveyor` component moves it with the stripes, in play), a cotton flag on a 4 m pole and a blue hologram sign over a pedestal; on the right a crate dissolving out and back in, a window frosting over and clearing, and a wet paving patch drying and soaked again. The cycles run on the shared clock through `Live`, so every player sees the same moment. Players come from the scene's player prototype, each on their own spot along the deck. The library's ring is still there as `layout = "ring"` (the default), for a scene that wants it.
In a scene of your own, in its `content()`:
```luau
local AnimGallery = require("~animatedMaterials.AnimGallery")
entity.spawn("Gallery").component.add("AnimShowcase", { driveGallery = true, lighting = "daylight", layout = "stand" })
for _, s in AnimGallery.standYardSpots() do -- the yard's two halves, behind the deck, facing it
local yard = entity.spawn("AnimYard_" .. s.part)
yard.localPosition = s.position
yard.localRotation = { 0, math.sin(math.rad(s.yaw) / 2), 0, math.cos(math.rad(s.yaw) / 2) }
yard.component.add("AnimYard", { part = s.part })
end
-- stand each arriving player on the deck: AnimGallery.standSpot(i) gives the i-th spot and its yaw
```
## How they were made
- **Reference pictures first.** Every material has `references/<id>`, a picture generated from the prompt in its entry before its shader was written. Each material was then compared beside its picture in its gallery bay under the Daylight look and the dark Moonlight look, by reviewers who wrote down what each bay showed, and changed where they differed (the review notes are in this world's `design/review`).
- **One definition.** `AnimEntries` gathers the families under `families/`; `AnimCatalog.build()` writes every `mat.yaml` (shader, properties, textures and the `values:` block binding each live property to `am.<setting>`) and the collection with its tags and measured texture memory; `AnimCatalog.writeBoards()` writes the reference boards.
- **Searched and reused.** The library core (materialLibraryKit 1.3.1) and its gallery, picker, lighting looks and checks; the startup asset type and catalog pattern of retroMaterials and toonMaterials (MIT); the gallery dressing forked from retroMaterials' RetroShowcase (MIT); Rune and Ember's `fantasyLava` shader forked as `animLava` (MIT); Hull and Hologram's `scifiHolo` forked as `animHolo` (MIT); the world-aligned and wet surfaces' textures forked from stoneMaterials, groundMaterials, masonryMaterials and metalsMaterials (MIT), repacked at 512 px. Looking Glass's water, the engine's `water_material`, `triplanar`, `animated_color` and `foliage` were read for ideas; none of them is a dependency, and no other package comes along with an install.
- **Shaders.** `animWater`, `animLava`, `animBelt`, `animCloth`, `animPulse`, `animHolo`, `animDissolve`, `animBurn`, `animFrost`, `animWet`, `animWorld`, plus `animBoard` for the reference boards and the shared WGSL module `animCommon` (periodic noise, Voronoi, object-metre mapping). Every procedural field is periodic over one repeat, so it tiles with no seam.
## Tests
```luau
asset.resolve("animatedMaterials.tests.animatedMaterials", "testSuite"):run()
```
Eight short tests, each wait a frame or two (the ramp test waits on the shared clock for half a second, at most 5 s on a slow machine); the whole run takes under a minute on a quiet desktop engine, longer while other work loads it: every material in the library and fully tagged; a live setting changes one object only (clamped, an unknown setting refused, reset); a speed or direction change never makes the surface jump; a ramp runs on the shared clock; a setting from another player (as a late joiner's snapshot arrives) lands on the object; the shared clock moves in edit mode and drives every material; the `Conveyor` gives its collider the belt's speed; every material inside the web limits. Each runs inside the library's `Sync.isolate()`, so nothing reaches other players; probes stand far from the gallery and are removed. The library's slower render checks run as tools: `zero materialChecks run <id>`.
## Multiplayer
Applied materials and the lighting look go through the library's `Sync`; live settings through the same `Sync` on their own channel; the clock through two small messages (a joiner asks; the machine keeping the room's time in that mode answers and restates it every 5 s). Every player sees the same settings on the same objects, a player who joins late included. The gallery's swatches and the yard's pieces are local and built the same on every machine under the same names, so a setting made on one of them reaches every player too. A ramp costs one message, not one per frame. `Live` also answers the library's room report: `require("~materialLibraryKit.Sync").askRoom()` returns, for every player, the section `animatedMaterials` with what that player's objects actually show (each setting it holds, whether the object is built there, and the values read back off it), so another player's screen can be checked from yours. Checked with two players: a setting made before the second player joined, a lava pool's speed and direction, and a dissolve ramp all read the same on both, the ramp at the same point of the shared clock.
## Gallery frame rate
- **Desktop engine:** about 72 fps in play (frames drawn over 10 s), in the desktop editor on this release with the whole 28-bay stand (460 local pieces) and the demo yard (40) standing and moving, measured by the author.
- **Web (browser):** about 29 fps, the median over 60 s in play at the arrival point by the stand, in Chrome on the owner's desktop, with all 28 bays and both halves of the yard up, measured by the world's owner on 1.0.9. The cost is the engine's per-frame upkeep of the gallery's many objects in the browser ([#20750](https://github.com/OrigoZero/zero/issues/20750)). Materials on ordinary scene objects in your own world do not carry the gallery's cost.
## How it works
- **Cloth mesh.** Free flutter needs a finely divided mesh whose vertex colour marks the free part; the package ships one (`animatedMaterials.meshes.flagCloth`, 1.5 x 1 m). On a cube or a sphere the shape holds and the wind moves only the shading.
- **Long-running speeds.** Flow and belt offsets are kept in metres in 32-bit floats; after many hours at full speed a step can reach a few millimetres a frame. A `Live.set` of the same speed restates the offset close to zero.
- **World-aligned and amount-driven tiling.** The world-aligned set maps by world position (an object moved slides under its pattern); the dissolve, frost and burn patterns are sized by the object, so they scale with it.
## Known limits
Engine issues are listed by their number at github.com/OrigoZero/zero.
- **Gallery frame rate on the web ([#20750](https://github.com/OrigoZero/zero/issues/20750)).** About 29 fps in the browser (the owner's measurement on 1.0.9), against about 72 on the desktop. The gallery is about 460 local pieces (plus the yard's 40) with 28 procedural shaders, and the engine's per-frame upkeep of that many objects is what costs the frame there. In your own world, with the materials on ordinary scene objects, that does not apply.
- **Checked in the browser by the owner, not the author ([#20946](https://github.com/OrigoZero/zero/issues/20946)).** The author cannot start a browser engine; this release was prepared and checked on the desktop engine, and the web frame rate and the web boot were checked by the world's owner on 1.0.9.
- **The library's material checks tools in the browser ([#7789](https://github.com/OrigoZero/zero/issues/7789)).** In the browser, the material library's `materialChecks` tools log "module '.shared' not found" as they load: each tool loads its helper with a relative `require(".shared")` that the web build does not resolve. Those tools are part of materialLibraryKit (Swatchbook), not of this package, so this package cannot fix them; the materials, the gallery, `Live` and the library's `Checks` module are not affected, and the tools work on the desktop engine.
- **Reloading the scene can save runtime things ([#21023](https://github.com/OrigoZero/zero/issues/21023)).** The gallery's swatches and the yard's pieces are temporary and rebuilt each time; check the scene file before committing after a reload.
- **A push can report a timeout and still land ([#21025](https://github.com/OrigoZero/zero/issues/21025)).** Check the world's commits before pushing again.
- **Flat labels read from the front only ([#21224](https://github.com/OrigoZero/zero/issues/21224)).** The gallery's plaques face the deck, and the yard's signs face the deck from below it, so each reads correctly from where visitors stand; walked round to the back, a label reads mirrored.
- **A copy of a shared object does not report itself as shared ([#21477](https://github.com/OrigoZero/zero/issues/21477)).** On a machine that holds another machine's copy of a `synced` object, the engine answers `e.synced()` false, so the material library's `Materials.keyOf` names that object by its name path there and by its id on the machine that spawned it. What you see: every screen shows the right value either way. Before 1.0.9 a setting made from one machine could read back with `Live.get` as the material's default on another; `Live` now reads both keys and takes the newest, so it reads back the same on every machine. Give shared objects unique names, since the name path is what a copy is known by.
- **A 3D text label keeps its old text ([#7781](https://github.com/OrigoZero/zero/issues/7781)).** `AnimShowcase` never rewrites a label: when an entry changes (a new tile size, a new setting) it removes the bay's labels and spawns them again with the new text. Do the same with labels of your own.
- **Plaques blank for a moment after a test run ([#15118](https://github.com/OrigoZero/zero/issues/15118)).** The renderer reset at the end of a run destroys every 3D text label's picture; the gallery remakes its own within a few seconds.
- **A test run in a live world can remove objects the world's own scripts made ([#21495](https://github.com/OrigoZero/zero/issues/21495)).** The test suite's own probes are temporary, stand far away and are removed, but the engine's test runner can take other objects that scripts spawned. The gallery and the yard rebuild themselves: in this world, with the yard's pieces removed it stood again within 6 s, and with half the gallery's pieces removed all 28 bays stood again within 15 s; after a whole suite run here both were still standing. Objects your own scripts spawned may not come back, so run the suite in a world nobody is playing.
- **A test run can release what the yard draws with ([#21873](https://github.com/OrigoZero/zero/issues/21873)).** The renderer reset at the end of a run can release the meshes and materials the demo yard made for itself (its poles, frames and plain boxes) while its objects stay, so for a moment the yard draws only the pieces that wear package materials. The yard checks every second whether what it draws with is still there and, when something is gone, builds itself again; the gallery stand rebuilds its own the same way.
- **Labels in the debug views ([#21451](https://github.com/OrigoZero/zero/issues/21451)).** The engine's own 3D text draws magenta in the albedo, roughness and metallic capture views; keep the plaques out of frame when judging a material in those views.
- **Wind-blown cloth in a render feature pass ([#21428](https://github.com/OrigoZero/zero/issues/21428)).** The cloth moves its vertices in the material's clip-space hook, by each flag's own wind values. A render feature that redraws the scene's meshes in its own geometry pass (an outline, a custom depth or mask pass) moves the vertices the same way whatever value the material holds, so in that pass a flag does not follow its own wind strength and direction.
- **A gallery board's picture can drop out ([#21868](https://github.com/OrigoZero/zero/issues/21868)).** Each bay's reference board shows its picture through the board material, and the engine can release that picture while the board still wears it; the board then draws plain white, and which board it hits varies (seen on the clear river one while the dissolve, burn and masonry boards showed fine). It stays white until the gallery is built again (reload the world, or switch the gallery's view). The materials themselves, their previews in the picker and list, and objects in your own world are not affected.
- **Shader previews ([#21617](https://github.com/OrigoZero/zero/issues/21617), [#21618](https://github.com/OrigoZero/zero/issues/21618)).** The engine's preview pictures fail for shaders that include the package's own shader module (`animCommon`), so some shaders show no preview; the shaders compile and draw. The materials' own previews (the pictures the library's picker and list show) are rendered files and always show. The gallery's reference boards are another matter: see #21868 above.
## Version history
- **1.0.16 (2026-10-30):** release of this round's work: late joiners and play see the newest setting on every object (1.0.12), the demo yard rebuilds itself after a test run (1.0.13), materialLibraryKit 1.3.4 with no long dashes and the current engine library (1.0.14), a README that says what a fresh install writes (1.0.15). The package description says what it is and how to install and use it. Materials, settings, tags and tests are unchanged.
- **1.0.15 (2026-10-30):** README only: it says plainly what a fresh install writes (the package, materialLibraryKit and six pinned engine shader parts under `deps/`) and why. Checked by a fresh install of 1.0.14 into a new empty world on the current engine library, which also carried no long dashes. Materials, settings, tags and tests are unchanged.
- **1.0.14 (2026-10-30):** depends on materialLibraryKit 1.3.4, the kit's release with no long dashes in any text file, so a fresh install carries none. The world is on the current built-in library. Materials, settings, tags and tests are unchanged.
- **1.0.13 (2026-10-30):** the demo yard builds itself again when a test run's renderer reset releases the meshes and materials it made ([#21873](https://github.com/OrigoZero/zero/issues/21873)): it used to rebuild only when its objects went missing, so after a run it could stand there drawing nothing but the flag. Materials, settings, tags and tests are unchanged.
- **1.0.12 (2026-10-30):** a player who joins late, and a machine entering play, sees the newest setting on every object. One object can hold its settings under its id and under its name path (set from the machine that spawned it and from one holding its copy), and a late joiner's snapshot or the replay on entering play wrote whichever record came last, so belts, flags, holograms and pulses could fall back to old values; `Live` now writes the newest of them, whichever key arrives. The collection's version agrees with the package's. Known limits drop the closed #21492, and the shader preview entry points at #21868 above it. Materials, settings, tags and tests are unchanged.
- **1.0.11 (2026-10-30):** README only. Known limits name [#21868](https://github.com/OrigoZero/zero/issues/21868), a gallery board's reference picture dropping out to plain white, and the shader preview entry says what the materials' own previews and the gallery boards really show. The world's cover shows the stand and the demo yard together. Materials, settings, tags and tests are unchanged.
- **1.0.10 (2026-10-30):** the browser frame rate is the owner's new measurement, about 29 fps (median over 60 s in Chrome at the stand), in place of the 1.0.6 figure. The `Conveyor` asks its collider whether it declares `surfaceVelocity` before writing it, so a browser engine without the field no longer logs "BoxCollider has no declared field surfaceVelocity"; it carries the load itself there as before. Materials, settings, tags and tests are unchanged.
- **1.0.9 (2026-10-30):** `Live.get` and `Live.all` read a setting back the same on every machine: a setting made from a machine holding a copy of a shared object was stored under the object's name path rather than its id ([#21477](https://github.com/OrigoZero/zero/issues/21477)), so other machines showed it but read the default; `Live` now reads both and takes the newest. Checked with three windows, a late joiner included, both ways. The README splits how-it-works notes from the known limits, cites #21617 and #21618 for shader previews, and says that an install also pins six engine shader parts. Stays on materialLibraryKit 1.3.1: the library's 1.3.3 is in its world's history but not yet its published version, so a fresh install could not get it. Materials, settings, tags and tests are unchanged.
- **1.0.8 (2026-10-28):** the first example's lava plane stands 2 cm above the ground, so in an empty world it shows whole instead of flickering through the ground (checked at a 2 cm lift on a ground at height 0: a clean crust with glowing cracks). The demo yard's signs are turned to read from the deck, where they read mirrored before. The known limits cite [#7789](https://github.com/OrigoZero/zero/issues/7789) for the library's material checks tools in the browser and add a second engine reading a setting back as the default ([#21477](https://github.com/OrigoZero/zero/issues/21477)). The world's listing describes the stand and the yard behind the deck. Materials, settings, tags, tests and texture memory are unchanged.
- **1.0.7 (2026-10-28):** the whole gallery in one look from the spawn. The world's gallery stood its 28 bays on the library's ring round the spawn, so a visitor saw about 7 of them and had to turn round for the rest; `AnimShowcase` now takes `layout = "stand"` (the library's ring stays the default), which moves every bay onto four curved, stepped rows in front of a 4 m deck the visitors arrive on (`AnimGallery.STAND`, `stand`, `standSpot`, `standYardSpots`), with the demo yard behind the deck, one turn away. The plaques carry the name and three short rows instead of four long ones, so every row is set about 0.38 m tall instead of about 0.27 m; the two longest names wrap to three smaller lines. The README gives the owner's browser frame rate on 1.0.6 and says this release is not yet measured in a browser, points the long waits and the tests at [#21492](https://github.com/OrigoZero/zero/issues/21492) (it cited a different issue), and says plainly that the library's material checks tools log "module '.shared' not found" in the browser and that this package cannot fix them. 1.0.6 was already published, so this round ships as 1.0.7. Materials, settings, tags, tests and texture memory are unchanged.
- **1.0.6 (2026-10-28):** a ramp started as a machine joins keeps its length. A setting made in the instant before a machine's clock took the room's time was stamped on the machine's own clock, so when the clock then jumped to the room's (hundreds of seconds on), a ramp such as the README's 3 s dissolve read finished at once. `AnimClock` now tells `Live` how far it moved when it takes the room's time (`AnimClock.onSettle`), and `Live` moves the settings it stamped before then by that much and sends them out again. Checked with a simulated room 500 s ahead: the dissolve read 0.495 at 1.5 s and 1.0 at 3.5 s. Materials, settings, tags and texture memory are unchanged.
- **1.0.5 (2026-10-28):** the yard's crate rides in the browser, and a late joiner's clock holds steady. The `Conveyor`'s carrying fallback took a body's pivot for its middle, and the demo yard's crate has its pivot at its base, below the belt's top face, so it was never counted as riding and stood still while the stripes moved; it now tests each body's middle (its bounds' centre), finds bodies by the belt's contacts as well as an overlap query, reads the belt's box from its collider or scale where oriented bounds are missing, carries once a frame where there is no physics step hook, starts a body put back at the start of the belt afresh, and reports what it found (`_carryStats`). `AnimClock`: an edited module reloads on every machine, and the message handlers the older copies had registered still answered a joiner with their own stopped clocks, while more than one machine could restate its clock, so a late joiner's clock jumped between readings hundreds of seconds apart (and the yard's cycles with it). Now only the newest copy on a machine speaks or listens, a joiner takes the room's clock before it ever speaks for the room, one machine per mode keeps the time, and a small drift is eased in. Materials, settings, tags and texture memory are unchanged.
- **1.0.4 (2026-10-28):** the belts carry their load in the browser and the web boot is quiet. The web build's colliders have no `surfaceVelocity` field, so the `Conveyor`'s write was refused and it logged "has no declared field 'surfaceVelocity'" hundreds of times a minute while the crates stood still; it now says so once and carries what rests on the belt itself, keeping pace with the stripes (measured within 1.3% of the belt's speed with that mode forced on the desktop). `AnimClock` asked for the material library with a `require` before the library had registered, which logged "names no package" at boot even inside `pcall`; every place that waits for the library now asks `asset.resolve` first and requires it only once it is there. The README gives the owner's web frame rate measured on 1.0.3 (about 27 fps). Materials, settings, tags and texture memory are unchanged; the conveyor test accepts either way of moving the load.
- **1.0.3 (2026-10-28):** works when the web build starts this package before the material library. In the browser the gallery dressing (`AnimShowcase`) and the yard (`AnimYard`) failed at boot with "no package named materialLibraryKit exists", and `Live` started without its shared channel and never tried again, so the `Conveyor` repeated "attempt to index nil with 'entries'" every frame. All three now bind the library when it is there and start the moment it is; until then `Live.get` answers nil and `Live.set` and `Live.reset` return false with the reason. The scene places each arriving player once the library is there. `Live` answers the library's room report (`Sync.askRoom`, section `animatedMaterials`), which checked two players side by side. The README gives the owner's web frame rate. Materials, settings, tags, tests and texture memory are unchanged.
- **1.0.2 (2026-10-28):** fixes after a side-by-side review of every bay beside its reference picture in Daylight and Moonlight. `lavaToon` takes its crust highlight from a real dome lit by the scene instead of a lighter colour painted into the crust, so the lava glows only by its own emission; `dissolveArcane` glows violet-blue to cyan like its picture; `frostWindow` grows thinner, finer fern crystals over a crisp, granular frost edge on darker glass instead of soft blotches. `Live`: a ramp on `flowDirection` now curves the flow smoothly (the travelled path is the integral of the velocity), where before the surface swung sideways while the direction turned. The README's known limits cite the issue that describes each one. Settings, tags, tests and texture memory are unchanged.
- **1.0.1 (2026-10-28):** first public release. The gallery holds its ring: when the library rebuilt its own "all" view while the materials were still registering (as a world loads, or after switching worlds), `AnimShowcase` took that for a player's choice and left the library's 3-page layout standing; it now steps back only when someone picks another kind of exhibit, and takes the "all" view back with this collection's 28-bay ring. Materials, settings, tags, tests and texture memory are unchanged from 1.0.0.
- **1.0.0 (2026-10-28):** the release candidate, proven by a fresh install in a scratch world and never made public: 28 animated and special materials in 11 families, their reference pictures, the shaders (`animWater`, `animLava`, `animBelt`, `animCloth`, `animPulse`, `animHolo`, `animDissolve`, `animBurn`, `animFrost`, `animWet`, `animWorld`, `animBoard` and the shared `animCommon` module), `Live`, `AnimClock`, the `Conveyor` component, the flag mesh, the gallery dressing (`AnimShowcase`, `AnimGallery`), the demo yard (`AnimYard`), the eight tests and this showcase world.