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:

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:

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.

Every call

From a world use require("@root::materialLibraryKit.<Module>"); inside the package use require("~.<Module>").

Materials (the library)

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)

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)

Picker (styles grid with thumbnails, list with search, and quick for gamepad or phone)

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)

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):

shader: "@builtin::shaders.pbr"
properties:
  base_color: [0.95, 0.64, 0.54, 1]
  roughness: 0.3
  metallic: 1

metals.materialCollection/collection.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:

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.