# 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.2. 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.2 (current, 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.2"`. | **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.

# Gallery The swatch gallery. One exhibit stands around the origin at a time: every material on a ring of bays grouped by category (paged), a close-up of one material near and far with a 40 m runway, an A/B compare, or a shelf filtered by style. Each bay shows the material on a sphere, a cube, a 2 x 2 m floor tile and a wall section mapped at the material's real-world tile size, plus a shader ball and a cylinder, under a one-line-per-row label plaque sized to be read from the spawn. Swatches are local temporary entities; the exhibit is shared through Sync.

# Matte 18% grey ball A matte diffuse ball: 18% grey, roughness 1, no specular reflectance. It shows the light's diffuse falloff and the shadow terminator without any highlight, the reference for judging key-to-fill ratios.

# normalTest A normal-mapping test pattern on flat mid grey (linear 0.18, roughness 0.5): a 4 x 3 grid of hemispheres alternating raised bumps and sunken dents (the top-left cell is a bump), and below them a raised ridge with 45-degree bevels running along U and a sunken bevelled groove. The geometry stays flat; only the shading normal is perturbed, so a bump that lights on the light's side and darkens on the far side proves the tangent frame and the normal-map convention are right, and a bump that lights like a dent shows they are flipped. Drawn by the procedural `calibNormalTest` shader, no textures; the capture tool's normal pass shows the perturbed normals. Part of the materialLibraryKit calibration shelf.

# albedoRange The PBR-valid albedo range as a lit strip: eleven rough (0.6) dielectric patches across U whose linear albedo steps in equal ratios from 0.04 (the darkest real dielectric, charcoal) to 0.9 (fresh snow), passing 0.19, close to middle grey, in the centre patch. Every surface in a physically based scene should fall inside this strip; set exposure so the ends separate from black and white. Drawn by the procedural `calibStepRamp` shader (channel 2, geometric spacing), no textures; the capture tool's albedo pass shows the stepped values. Part of the materialLibraryKit calibration shelf.

# Emitter (1.0) A flat emitter at a plain 1.0 reference brightness: white emission at intensity 1 on a black base. Next to the 16x emitter it shows where the exposure puts a 1.0 emission and when bloom starts.

# Sync Keeps small keyed state the same on every peer: the applied materials, the gallery exhibit and the lighting preset. Each write is stamped with a Lamport time and the peer id and broadcast with `multiplayer.send`; every peer keeps the newest stamp. A peer that arrives asks for a snapshot, and peers push one when a player joins, so late joiners converge. Called by Materials, Gallery and Lighting; collections rarely need it directly.

# Glossy black ball A glossy black dielectric: linear albedo 0.04 (the darkest real dielectric), roughness 0.05, not metallic. With almost no diffuse, it shows the pure specular reflection of the sky and each light, the reference for judging reflections on dark, polished surfaces.

# calibUvChecker A procedural, orientation-readable UV checker for the materialLibraryKit calibration shelf. It draws a `cells`-per-unit checker whose light cells carry a red gradient rising with U and a green gradient rising with V (dark cells are the same colour at `dark` brightness), thin black grid lines, a white-ringed blue disc in the (0,0) cell, a red arrow pointing +U and a green arrow pointing +V out of that corner, and a large outlined white "F" in the middle. It is laid out like an image texture (v = 0 is the top row), so on a correctly mapped mesh the F reads upright with the marker at its top-left; a mirrored, flipped, swapped or rotated UV layout shows immediately as a backwards or upside-down F and arrows pointing the wrong way. Lit dielectric (`roughness`), textureless, engine-lit `surface()` body. Used by the `uvChecker` material.

# whiteCard A lit PBR diffuse-white reference card: a rough (0.6), non-metallic dielectric with linear albedo 0.9, about the brightest physically plausible diffuse surface (fresh snow, white paper). Under a correctly exposed key it should sit just below clipping while the 18% grey card reads as middle grey; if it blows out, the exposure or the light is too hot. Drawn by `@builtin::shaders.pbr`, no textures. Part of the materialLibraryKit calibration shelf.

# uvChecker An orientation-readable UV checker: an 8 x 8 checker whose cells grow redder as U increases and greener as V increases, a white-ringed blue disc in the (0,0) corner cell, a red arrow pointing +U and a green arrow pointing +V from that corner, and a large outlined white "F" in the middle. Laid out like an image texture (v = 0 at the top), so on a correctly mapped mesh the F reads upright with the marker at its top-left, and a mirrored, flipped or rotated UV layout is obvious at a glance; the checker also shows stretching and texel density. Drawn by the procedural `calibUvChecker` shader (lit dielectric, roughness 0.6), no textures. Part of the materialLibraryKit calibration shelf.

# greyGlossy A glossy 18% grey dielectric (linear albedo 0.18, roughness 0.1, metallic 0): the same diffuse response as the matte grey card but with a tight, bright specular lobe, so on a sphere it shows the shape, size and position of every light's highlight and the reflected environment over a known middle-grey base. Drawn by `@builtin::shaders.pbr`, no textures. Part of the materialLibraryKit calibration shelf.

# calibNormalTest A procedural normal-mapping test pattern for the materialLibraryKit calibration shelf. The surface stays geometrically flat while the shader writes an analytic, perturbed shading normal: the top three quarters hold a 4 x 3 grid of true hemispheres alternating raised bumps and sunken dents (the (0,0) top-left cell is a bump), and the bottom quarter holds a raised ridge with 45-degree bevels running along U and a sunken bevelled groove below it, all on mid grey (`base_color`, `roughness`). A bump must light on the side facing the light and darken on the far side, a dent the reverse; if they swap, the tangent frame or the green-channel convention is wrong (the green channel follows the OpenGL / glTF convention the engine uses, +Y = image up; `flip_y = 1` gives the DirectX convention to compare). `strength` scales every tilt. Engine-lit `surface()` body with no textures, so the `normal` capture pass shows the perturbed normal per pixel. Used by the `normalTest` material.

# blackCard A lit PBR black reference card: a rough (0.6), non-metallic dielectric with linear albedo 0.04, the darkest albedo a real dielectric has (charcoal, black velvet sit near it). Shadows and fill light should still separate it from pure black; if it crushes to zero, the shadows or the tone curve lose detail. Its specular highlight still reflects 4% at normal incidence, as every dielectric does. Drawn by `@builtin::shaders.pbr`, no textures. Part of the materialLibraryKit calibration shelf.

# calibStepRamp A procedural calibration ramp for the materialLibraryKit calibration shelf: the surface is cut into `steps` discrete patches across U, and each patch sets one PBR channel - roughness (`channel = 0`), metallic (`channel = 1`) or albedo (`channel = 2`) - to a value stepped from `low` (left) to `high` (right), linearly or, with `geometric = 1`, in equal ratios. Thin dark dielectric separators (`separator_width`, `separator_color`) frame every patch so the steps read under any light. The channels that are not ramped take `base_color`, `roughness` and `metallic`. It is an engine-lit `surface()` shader with no textures, so the capture tool's roughness, metallic and albedo passes show exactly the stepped values each patch carries. Used by `roughnessRamp`, `metallicRamp` and `albedoRange`.

# roughnessRamp A roughness ramp on a mid-grey (linear 0.18) dielectric: eleven discrete patches across U step perceptual roughness from 0.0 on the left to 1.0 on the right in 0.1 increments, each framed by a thin dark separator. Lit, it shows how the specular highlight spreads and dims as roughness rises, and whether the renderer's roughness response is smooth and monotonic. Drawn by the procedural `calibStepRamp` shader (channel 0), no textures; the capture tool's roughness pass shows the eleven stepped values. Part of the materialLibraryKit calibration shelf.

# metallicRamp A metallic ramp on a light grey (linear 0.8) base at roughness 0.25: eleven discrete patches across U step metallic from 0.0 (a white dielectric) on the left to 1.0 (a bright silver metal) on the right in 0.1 increments, each framed by a thin dark separator. It shows the diffuse term fading and the tinted specular taking over, and reveals the in-between values that real materials should avoid. Drawn by the procedural `calibStepRamp` shader (channel 1), no textures; the capture tool's metallic pass shows the eleven stepped values. Part of the materialLibraryKit calibration shelf.

# Materials The material library: every entry of every installed `.materialCollection`, with its tags, plus `apply` / `clear` to put a library material on an entity for every player. `list(filter)` finds materials by category, kind, style, collection, tag, animation, texture cost or free text. Collections join by being installed (the collection type's register hook), and lookups go through literal `asset.list` enumerations so a published world can use it on the gameplay path. See the package README for every call.