# PlayWrites The kit's writes to the scene's own entities during play (the sun, ambient light and sky of a lighting look, a material another player picked), made from a component's update so the engine never counts them as "tuned in play" and Stop just works. `PlayWrites.run(key, fn)` runs `fn` at once outside play and queues it during play; the `MaterialLibraryPlayWriter` component, which the module adds to a temporary entity of its own, makes the queued writes each frame. Lighting and Materials call it; a collection never needs to.

# materialLibraryKit The shared core of a material library: tagged materials from every installed collection, `Materials.apply` / `Materials.list`, a calibration shelf, a swatch gallery, shared lighting presets, an on-screen picker, and checking tools. Version 1.3.0. 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. ## Version history **1.3.0 (current, 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: If you installed 1.3.0 before 18:00 UTC on 2026-10-21, install it again: it was published several times that day while it was being finished, and only the last of those is the 1.3.0 described here. ```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. `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.3.0"`. | **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. **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 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'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. - **Installed textures can draw plain white on the desktop app (gh#20193).** On the desktop app, the textures of a freshly installed package do not load, so a collection's textured materials can show plain white. The calibration shelf is procedural and has no textures; textured collections (woods, metals) are. - **No second player inside one engine (gh#19114).** One engine is one peer, so two-player behaviour cannot be tested from a single editor. The kit's tests send the late-join snapshot through the engine's loopback transport, and live checks use a second client (a browser tab or another device on the world's play page). `Sync.askRoom(seconds)` asks every peer what it actually shows. - **No `asset.materialCollection.*` namespace (gh#1889).** The engine reserves the type-scoped global namespace but does not build it yet. Collections are reached through `Materials.*` instead. - **Normal-map convention undocumented (gh#19414).** The engine reads a normal map's green channel as image-up (OpenGL/glTF). The calibration `normalTest` shows it; `flip_y = 1` on that material shows the DirectX convention for comparison. - **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.