Swatchbook: Material Library, Picker and Calibration Kit
README.md
Lighting
Live-switchable lighting presets for the materialLibraryKit swatch gallery. One call changes the sun, ambient, sky, display exposure, the sky reflection the chrome balls mirror and the preset-only lights, for every player in the room. The gallery UI, the picker and any scene that wants a known light to judge materials under call it.
local Lighting = require("~materialLibraryKit.Lighting") -- from a world
-- local Lighting = require("~.Lighting") -- inside the package
Lighting.attach() -- find or build the rig (idempotent; call on every scene load)
Lighting.applyCurrent("daylight") -- show the room's preset, or daylight if nobody chose one yet
Lighting.set("goldenHour", { blend = 1.5 }) -- everyone switches, easing over 1.5 s
for _, p in Lighting.list() do print(p.id, p.name, p.description) end
local stop = Lighting.onChanged(function(id) print("lighting is now", id) end)
API
| Call | What it does |
|---|---|
list() | { { id, name, description } } in display order. |
set(id, opts?) → ok, err | Applies the preset here and writes it to the Sync channel lighting (key preset) so every peer, including late joiners, applies it too. opts.localOnly skips the broadcast. opts.blend (seconds) eases sun, ambient, sky colours and exposure. Unknown id → false, "unknown lighting preset …". |
current() | The preset id this peer shows (falls back to the synced one, then daylight). |
attach(root?) | Ensures the rig exists and returns its entity ids. Reuses the scene's own directional Light, ambient Light and ProceduralSky, found by component (never by name), and spawns whatever is missing as local, temporary entities under MLK_Lighting (parented to root when given). Idempotent and cheap (~0.1 ms). |
applyCurrent(fallback?) | attach(), then apply the synced preset (or fallback) on this peer only. Call this from a scene or component when it loads. |
onChanged(fn) → unsubscribe | fn(id) on every change on this peer, local or remote. |
releaseDisplay() | Hands the display exposure back to whatever set it before. |
Presets
| id | Look | Sun | Ambient | Sky | Exposure | Extras |
|---|---|---|---|---|---|---|
daylight | Sunny midday | high, white, 7.0, hard shadows | cool sky fill 0.12 | clear blue | 0.9 | - |
overcast | Soft, flat, true colour | near-overhead 1.6, no shadows | bright neutral 0.55 | flat grey, no sun disc | 1.05 | - |
goldenHour | Low warm sun | 14° elevation, orange, 7.5, long shadows | warm 0.12 | blue zenith → amber horizon | 1.2 | - |
moonlight | Cool clear night | high blue moon 1.0, shadows | blue 0.3 | near-black blue | 1.8 | - |
warmInterior | Night outside, tungsten inside | faint blue 0.25, no shadows | warm 0.3 | dark night | 1.8 | 6 unshadowed warm point lights on a 9 m ring + 1 shadowed spot over the centre |
studio | Neutral reference | white key 4.5, shadows | white 0.12 | uniform mid-grey backdrop | 1.0 | 2 unshadowed distant lights (fill, rim) |
The sky is the scene's ProceduralSky with syncSunToLight = false, so the preset owns the sun and the sky is drawn from it. A preset switch recaptures the environment's sky slot (environment.captureSky) four frames later, so metals reflect the new sky.
Cost
- No per-frame work. A blend runs one task for its duration and then exits.
- A switch costs about 1 ms of Lua, once.
- GPU cost: one shadowed sun in every preset.
warmInterioradds 6 unshadowed points and 1 shadowed spot.studioadds 2 distant lights with no shadow maps. - Preset-only lights are switched off with
setActive(false), which takes their rows out of the renderer. - There is no fog. A height-fog pass costs a full-screen pass every frame and dimmed the sky reflection.
Multiplayer
The preset id is the only synced state. Every peer builds its own rig locally from the id, so nothing heavy replicates. Sync resolves concurrent writes newest-wins and hands late joiners a snapshot.