# materialCollection (asset type) A materialCollection is one installable shelf of the materialLibraryKit material library: a `collection.yaml` that lists material assets and the tags that describe each one. The core (`materialLibraryKit`) discovers every collection in the world, on every peer, and merges their entries into the library that `Materials.list`, `Materials.apply`, the picker and the swatch gallery read. Installing a package that holds a collection is all a world does to get its materials into the library. ## Folder shape - `collection.yaml` — the entries. **Required.** - `README.md` — what the collection holds. **Required.** - `.metadata` — tags for search. **Required.** ## collection.yaml ```yaml title: "Metals" # shown in the picker and gallery version: "1.0.0" materials: - id: brushedSteel # unique library id (letters, digits, _ -) material: "~.materials.brushedSteel" # identity, VFS path, or ~. (this package) name: "Brushed steel" category: metal # free text, lower case kind: steel # sub-kind inside the category style: realistic # realistic | stylised | toon | pixel | scifi | fantasy tileSize: 1.0 # metres one texture repeat covers roughness: [0.25, 0.4] # min, max (one number means min = max) metallic: [1, 1] textureKB: 2730 # optional: estimated GPU texture memory; measured when omitted animated: false tags: [brushed, anisotropic-look] description: "Satin steel sheet." ``` Any field but `id`, `material`, `category` and `style` may be left out; the core fills defaults (see the materialLibraryKit README). `~.` means the package the collection file lives in, so a collection keeps working wherever its package is installed.

# 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.1.0. Collections (metals, woods, stone, fabrics, sci-fi panels, toon and pixel sets…) are separate packages that plug into this core. Installing one is all a world does: its materials appear in the list, the picker and the gallery on every player's machine, with no code. ## Install and use Install the package into your world from ZeroMind (search "materialLibraryKit", or install the published package `0d7f3e76-0699-44fd-b0ac-2cb37822b648`; the starter collection is `23d92c7c-345b-43bb-bb86-ab7c9d884ffa`). It lands at `/source/materialLibraryKit.package`. Then, from any script: ```luau local Materials = require("@root::materialLibraryKit.Materials") local ball = entity.spawn("ball", { components = { Model = { model = "sphere" } } }) ball.localPosition = { 0, 1, 3 } 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 ``` 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("@root::materialLibraryKit.<Module>")`; 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. 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.1.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. | | `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 }`. | | `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.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. 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: ```luau local Checks = require("@root::materialLibraryKit.Checks") Checks.assertGood("copper") ``` 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. 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 - **No `asset.materialCollection.*` namespace.** The engine reserves the type-scoped global namespace but does not build it yet (gh#1889). Collections are reached through `Materials.*` instead. - **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: the shared lighting and materials were checked live with two browser tabs. 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, so there is no issue number. - **Hidden browser tabs throttle.** A player whose tab is in the background catches up with lighting and material changes when the tab comes back. - **Placeholder name tags.** The engine's player name tag sometimes keeps reading `{PlayerName}` for another player. The gallery fills such a tag with "Visitor <peer>". Engine issue gh#19201. - **No in-engine second peer.** `multiplayer.loopback()` drives engine component sync, not custom message channels, so two-player behaviour cannot be tested from one engine. Engine issues gh#18688 and gh#19114. - **Normal-map convention undocumented.** 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. Engine issue gh#19414. - **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.

# 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.0.0. Collections (metals, woods, stone, fabrics, sci-fi panels, toon and pixel sets…) are separate packages that plug into this core. Installing one is all a world does: its materials appear in the list, the picker and the gallery on every player's machine, with no code. ## Install and use Install the package into your world from ZeroMind (search "materialLibraryKit", or install asset `fb19426f-3987-440e-a42d-d37b59588a34`). It lands at `/source/materialLibraryKit.package`. Then, from any script: ```luau local Materials = require("@root::materialLibraryKit.Materials") local ball = entity.spawn("ball", { components = { Model = { model = "sphere" } } }) ball.localPosition = { 0, 1, 3 } 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 ``` 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"). | | `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. | | `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. | | `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("@root::materialLibraryKit.<Module>")`; inside the package use `require("~.<Module>")`. **Materials** (the library) | Call | Does | |---|---| | `Materials.list(filter?)` | Entries matching `{ category, kind, style, collection, tag, animated, search, maxTextureKB, includeBroken }`. A string or a list of strings matches any of them. Sorted by category, kind, then name. | | `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. 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.0.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. | | `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 }`. | | `Gallery.onChanged(fn)` | Calls `fn(view)` after each rebuild. | | `Gallery.VIEWS`, `Gallery.PAGE_SIZE` | The exhibit names and the bays per ring. | | `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.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.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 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?)` | Warns when a material is over the web build's limits: 24 MiB of texture per material, 4096 px, uncompressed textures over 1024 px, formats browsers cannot filter. `nil` checks the whole library. | | `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. Checking what every player actually shows: `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: an 18% grey card, white (lit and unlit) and black references, a chrome ball, a glossy grey ball, roughness and metallic ramps, an albedo range strip, a UV orientation checker, a normal-map test pattern, a colour checker, a 21-stop grey wedge, a Siemens star, focus bars, a shadow ramp and an HDR emitter. 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: ```luau local Checks = require("@root::materialLibraryKit.Checks") Checks.assertGood("copper") ``` 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`. Every peer converges on the newest write, and a player who joins later is sent the room's state. Gallery swatches are local, temporary entities rebuilt on every peer, so they cost the network nothing. A page of the gallery is about 215 entities: 16 bays, each with 7 models and 4 one-line labels. In the editor build it measured about 5 ms of GPU time per frame and about 1 ms of label upkeep. ## Known limits - **No `asset.materialCollection.*` namespace.** The engine reserves the type-scoped global namespace but does not build it yet (gh#1889). Collections are reached through `Materials.*` instead. - **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: the shared lighting and materials were checked live with two browser tabs. 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, so there is no issue number. - **Hidden browser tabs throttle.** A player whose tab is in the background catches up with lighting and material changes when the tab comes back. - **Placeholder name tags.** The engine's player name tag sometimes keeps reading `{PlayerName}` for another player. The gallery fills such a tag with "Visitor <peer>". No GitHub issue number found; reported through ZeroMind (bug report, 2026-10-18). - **No in-engine second peer.** `multiplayer.loopback()` drives engine component sync, not custom message channels, so two-player behaviour cannot be tested from one engine. No GitHub issue number found; reported through ZeroMind feedback. - **Normal-map convention undocumented.** 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. No GitHub issue number found; reported through ZeroMind feedback. - **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.

# 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.