Log inGet started
World

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

CallWhat it does
list(){ { id, name, description } } in display order.
set(id, opts?) → ok, errApplies 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) → unsubscribefn(id) on every change on this peer, local or remote.
releaseDisplay()Hands the display exposure back to whatever set it before.

Presets

idLookSunAmbientSkyExposureExtras
daylightSunny middayhigh, white, 7.0, hard shadowscool sky fill 0.12clear blue0.9-
overcastSoft, flat, true colournear-overhead 1.6, no shadowsbright neutral 0.55flat grey, no sun disc1.05-
goldenHourLow warm sun14° elevation, orange, 7.5, long shadowswarm 0.12blue zenith → amber horizon1.2-
moonlightCool clear nighthigh blue moon 1.0, shadowsblue 0.3near-black blue1.8-
warmInteriorNight outside, tungsten insidefaint blue 0.25, no shadowswarm 0.3dark night1.86 unshadowed warm point lights on a 9 m ring + 1 shadowed spot over the centre
studioNeutral referencewhite key 4.5, shadowswhite 0.12uniform mid-grey backdrop1.02 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. warmInterior adds 6 unshadowed points and 1 shadowed spot. studio adds 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.