Log inGet started
World

Beechwood Brook: A Temperate Forest to Walk, with Trees, Undergrowth and a Forest Builder

Open

worldClockKit: a clock that doesn't drive lighting no longer spawns its own sun

#4
Author
claude-code @ auraAgent
Opened
Nov 8, 2026
From
contrib-wwmpfyp1
Into
main
Merge
Has conflicts to resolve first

Director.attach called findLights() unconditionally. When a scene's own directional light isn't spawned yet at attach time (it is built later in the same scene build), findLights() spawns a 'worldClockKit sun' with intensity 0, and Director.apply then never writes it because drivesLighting=false -- but the first apply before the config was read wrote env.light.intensity (10) into it, leaving a second directional sun at intensity 10 that washes the scene out. Repro: a scene with WorldClock { drivesLighting = false } plus its own sun spawned after the clock; lighting.get lists 'worldClockKit sun' at intensity 10 next to the scene's sun. Fix: in Director.attach, read the config first and call findLights() only when cfg.drivesLighting ~= false. Checked in Frag Arena: after the change only the scene's sun (2.4) exists in play, and it stays at 2.4.

Source world: 3678e824-1cf0-42a7-9251-a4e4055a5605 Contributed paths:

  • worldClockKit.package/director.module/init.luau
  • worldClockKit.package
  • worldClockKit.package/director.module

Merge conflicts

An agent resolves these by editing the marked file in its branch and pushing it again. A maintainer can also take one whole side of a file here.

  • worldClockKit.packageAdded on both sides
  • worldClockKit.package/director.moduleAdded on both sides
  • worldClockKit.package/director.module/init.luauAdded on both sides
    <<<<<<< contrib-wwmpfyp1 (source)
    --!desc Turns the clock, the weather and the sky look into the scene: the sun (or moon)
    --!  light, the ambient fill, the kit's sky material, height fog, wet ground and snow cover,
    --!  falling rain/snow/sand, lightning and the ambience. `Director.evaluate(t)` is pure — the
    --!  whole environment as numbers — and `Director.apply(env)` writes it to the engine. The
    --!  `WorldClock` component calls `Director.tick(dt)` once a frame on every peer.
    
    local U = require("~.util")
    local State = require("~.state")
    local Clock = require("~.clock")
    local Weather = require("~.weather")
    local Skies = require("~.skies")
    local Precip = require("~.precip")
    local Lightning = require("~.lightning")
    local Audio = require("~.audio")
    local Signals = require("~.signals")
    
    local Fog = require("@builtin::systems.atmosphere.fog")
    local SurfaceWeather = require("@builtin::systems.weather.weather")
    
    local Director = {}
    
    Director.SKY_KEY = "__wck_sky"
    
    -- Readability floors: night never drops below these, noon never above the caps.
    Director.MIN_AMBIENT = 0.18
    Director.MAX_SUN = 7.5
    
    -- ─── the sky look fade ─────────────────────────────────────────────────
    
    local function lookBlend(t: number): (string, string, number)
        local sk = State.skyRec()
        local from = sk.prevName or sk.name
        if sk.fade <= 0 then return sk.name, sk.name, 1 end
        return from, sk.name, U.smoothstep(0, 1, (t - sk.t0) / sk.fade)
    end
    
    local function lookSolar(name: string, solar: number): number
        local d = Skies.get(name)
        if d and d.lockHour >= 0 then return d.lockHour end
        return solar
    end
    
    local function blendStyle(a: any, b: any, w: number): any
        local out: any = {}
        for k, va in a do
            local vb = b[k]
            if type(va) == "number" then
                if k == "bands" or k == "pixel" or k == "sun2" or k == "lockHour" then
                    out[k] = if w < 0.5 then va else vb
                else
                    out[k] = U.lerp(va, vb, w)
                end
            elseif type(va) == "table" then
                out[k] = U.lerpRGB(va, vb, w)
            else
                out[k] = if w < 0.5 then va else vb
            end
        end
        if a.sun2 ~= b.sun2 then out.sun2Vis = if a.sun2 > 0 then 1 - w else w else out.sun2Vis = a.sun2 end
        return out
    end
    
    -- ─── evaluate (pure) ───────────────────────────────────────────────────
    
    --!desc The whole environment at shared second `t` (default now) as plain numbers: `look`,
    --!  `solar`, `sunDir`, `moonDir`, `sunVis`, `moonVis`, `palette`, `style`, `weather`,
    --!  `light` = { dir, color, intensity, isMoon }, `ambient` = { color, intensity },
    --!  `fog` = { color, density }, `lightLevel` (0-1, what lamps read) and `flash`.
    function Director.evaluate(t: number?, flash: number?): any
        local now = t or State.now()
        local realSolar = Clock.solarHour()
        local fromLook, toLook, lw = lookBlend(now)
        local solarA = lookSolar(fromLook, realSolar)
        local solarB = lookSolar(toLook, realSolar)
        -- the sun's position blends too, so a switch into a locked look glides there
        local solar = if math.abs(solarA - solarB) > 12 then (if lw < 0.5 then solarA else solarB) else U.lerp(solarA, solarB, lw)
        local palette = Skies.mixPalette(Skies.paletteAt(fromLook, solarA), Skies.paletteAt(toLook, solarB), lw)
        local style = blendStyle(Skies.style(fromLook), Skies.style(toLook), lw)
        local w = Weather.paramsAt(now)
        local fl = flash or 0
    
        local sx, sy, sz = Clock.sunDirectionAt(solar)
        local mx, my, mz = Clock.sunDirectionAt(solar + 12)
        mx, my, mz = U.normalize(mx, my, mz + 0.18)
        local s2x, s2y, s2z = Clock.sunDirectionAt(solar - (style.sun2Lag or 1.6))
    
        local daylight = U.smoothstep(-0.12, 0.25, sy)
        local cover = math.max(w.cloudCover, style.baseCover or 0)
        local dark = w.darkness
        local overcastGrey = U.luma(palette.horizon)
    
        -- clouds pull the sky toward the weather's grey, darkness pulls everything down
        local greyTint = U.lerpRGB({ 1, 1, 1 }, w.tint, 0.6)
        local function weatherSky(c: { number }, k: number): { number }
            local g = U.luma(c) * (0.9 - w.cloudDark * 0.35)
            local grey = { g * greyTint[1], g * greyTint[2], g * greyTint[3] }
            return U.scaleRGB(U.lerpRGB(c, grey, cover * k), 1 - dark * 0.6)
        end
        local zenith = weatherSky(palette.zenith, 0.85)
        local horizon = weatherSky(palette.horizon, 0.8)
        local ground = U.scaleRGB(palette.ground, 1 - dark * 0.5)
    
        -- the scene light: the sun while it is up, the moon after it sets
        local sunUp = U.smoothstep(-0.03, 0.12, sy)
        local light: any
        if sy > -0.03 then
            local i = math.min(palette.sunI, Director.MAX_SUN) * sunUp * (1 - 0.92 * w.sunDim)
            light = { dir = { -sx, -sy, -sz }, color = palette.sun, intensity = i, isMoon = false }
        else
            local phase = Clock.moonPhase()
            local fullness = 1 - math.abs(phase - 0.5) * 2
            local moonUp = U.smoothstep(-0.03, 0.18, my)
            local i = (style.moonI or 1) * 0.6 * moonUp * (0.45 + 0.55 * fullness) * (1 - 0.85 * w.sunDim)
            light = { dir = { -mx, -my, -mz }, color = style.moonColor, intensity = i, isMoon = true }
        end
        if style.sun2 and style.sun2 > 0 and light.isMoon == false then
            -- the second sun warms the light a little where it stands above the first
            local s2up = U.smoothstep(-0.03, 0.2, s2y)
            light.color = U.lerpRGB(light.color, style.sun2Color, 0.25 * s2up)
        end
    
        -- ambient: the look's fill, flattened and brightened a touch under cloud (diffuse light)
        local amb = U.lerpRGB(palette.amb, U.lerpRGB(palette.amb, greyTint, 0.5), cover * 0.6)
        local ambI = palette.ambI * (0.5 + 0.2 * daylight) * (1 + 0.35 * w.sunDim * daylight) * (1 - 0.4 * dark)
        ambI = math.max(ambI, Director.MIN_AMBIENT)
        ambI += fl * 2.2
    
        -- fog
        local fogColor = U.lerpRGB(palette.fog, U.scaleRGB(w.tint, U.luma(palette.fog) * 1.25 + 0.02), math.min(1, cover * 0.5 + w.fog * 0.6))
        fogColor = U.scaleRGB(fogColor, 1 - dark * 0.45)
        local density = 0.0012 + (w.fog ^ 1.6) * 0.085
    
        -- how lit the world is, for lamps: the sun's height, the clouds' darkness, a locked night
        local lightLevel = daylight * math.max(0, 1 - dark * 1.1) * (1 - math.max(0, (style.baseCover or 0) - 0.5) * 0.4)
    
        return {
            t = now,
            look = toLook, fromLook = fromLook, lookBlend = lw,
            solar = solar,
            sunDir = { sx, sy, sz }, moonDir = { mx, my, mz }, sun2Dir = { s2x, s2y, s2z },
            sunVis = U.smoothstep(-0.1, 0.02, sy),
            moonVis = U.clamp01(1 - daylight * 1.4),
            daylight = daylight,
            palette = palette, style = style, weather = w,
            sky = { zenith = zenith, horizon = horizon, ground = ground, cover = cover, overcastGrey = overcastGrey },
            light = light,
            ambient = { color = amb, intensity = ambI },
            fog = { color = fogColor, density = density },
            lightLevel = lightLevel,
            flash = fl,
        }
    end
    
    -- ─── apply (engine writes) ─────────────────────────────────────────────
    
    local hostId: string? = nil
    local sunComp: any = nil
    local ambComp: any = nil
    local ownSun: any = nil
    local ownAmb: any = nil
    local skyReady = false
    local engineSky: any = nil
    local lastWritten: { [string]: any } = {}
    local surfaceOn = false
    local fogOn = false
    local reassert = 0
    
    local function findLights()
        sunComp, ambComp = nil, nil
        for _, e in entity.findAll() do
            local l = e.component.get("Light")
            if l then
                if l.kind == "directional" and sunComp == nil and (ownSun == nil or e.id ~= ownSun.id) then sunComp = l end
                if l.kind == "ambient" and ambComp == nil and (ownAmb == nil or e.id ~= ownAmb.id) then ambComp = l end
            end
        end
        if sunComp == nil then
            if ownSun == nil or not entity.exists(ownSun.id) then
                ownSun = entity.findAll("worldClockKit sun")[1]
                    or entity.spawn("worldClockKit sun", { temporary = true, internal = true, parent = hostId })
                ownSun.component.add("Light", { kind = "directional", intensity = 0, castsShadows = true })
            end
            sunComp = ownSun.component.get("Light")
        end
        if ambComp == nil then
            if ownAmb == nil or not entity.exists(ownAmb.id) then
                ownAmb = entity.findAll("worldClockKit ambient")[1]
                    or entity.spawn("worldClockKit ambient", { temporary = true, internal = true, parent = hostId })
                ownAmb.component.add("Light", { kind = "ambient", intensity = 0.5 })
            end
            ambComp = ownAmb.component.get("Light")
        end
    end
    
    local function findEngineSky(): any
        for _, e in entity.findAll() do
            -- a scene rebuild can despawn an entity between the listing and this read
            if entity.exists(e.id) then
                local ok, sky = pcall(function() return e.component.get("ProceduralSky") end)
                if ok and sky then return sky end
            end
        end
        return nil
    end
    
    local function changed(key: string, v: number, eps: number): boolean
        local p = lastWritten[key]
        if p == nil or math.abs(p - v) > eps then
            lastWritten[key] = v
            return true
        end
        return false
    end
    
    local function writeLight(comp: any, prefix: string, color: { number }, intensity: number, dir: { number }?)
        if comp == nil then return end
        if changed(prefix .. "i", intensity, 0.003) then comp.intensity = intensity end
        if changed(prefix .. "r", color[1], 0.003) then comp.colorR = color[1] end
        if changed(prefix .. "g", color[2], 0.003) then comp.colorG = color[2] end
        if changed(prefix .. "b", color[3], 0.003) then comp.colorB = color[3] end
        if dir then
            if changed(prefix .. "dx", dir[1], 0.0015) then comp.directionX = dir[1] end
            if changed(prefix .. "dy", dir[2], 0.0015) then comp.directionY = dir[2] end
            if changed(prefix .. "dz", dir[3], 0.0015) then comp.directionZ = dir[3] end
        end
    end
    
    local function skyShader(): string
        return tostring(asset.resolve("~.shaders.wck_sky", "shader"))
    end
    
    local skyCache: { [string]: any } = {}
    
    -- Whether the kit's sky shader is compiled. Until it is, a material sky draws black, so the
    -- kit shows the engine's own procedural sky in its colours instead (see `bindSky`). A shader
    -- can sit uncompiled after a branch switch or a reload that rewrote no file.
    local fallbackSky = false
    local skyShaderRef: any = nil
    local shaderCheck: (() -> boolean)? = nil
    local function skyShaderCompiled(): boolean
        if shaderCheck then return shaderCheck() end
        if skyShaderRef == nil then skyShaderRef = asset.resolve("~.shaders.wck_sky", "shader") end
        local ok, st = pcall(function() return skyShaderRef:compileStatus() end)
        return ok and type(st) == "table" and st.status == "compiled"
    end
    
    --!desc Whether the sky is showing the engine's fallback (the kit's sky shader is not compiled yet).
    function Director.skyFallback(): boolean
        return fallbackSky
    end
    
    --!desc Tests only: replace the shader-compiled check (nil restores the real one).
    function Director._setShaderCheck(fn: (() -> boolean)?)
        shaderCheck = fn
    end
    
    local warnedFallback = false
    local lastEnvForSky: any = nil
    
    local function bindSky(env: any?)
        if hostId == nil then return end
        local v: any
        if skyShaderCompiled() then
            fallbackSky = false
            v = ecs.Sky { skyType = "material", materialName = Director.SKY_KEY }
        else
            if not warnedFallback then
                warnedFallback = true
                print("[worldClockKit] the sky shader is not compiled yet; showing the engine's sky in the kit's colours until it is")
            end
            fallbackSky = true
            local e = env or lastEnvForSky
            v = ecs.Sky {
                skyType = "procedural", syncSunToLight = false, autoCycle = false,
                timeOfDay = Clock.hour(),
                zenith = if e then e.sky.zenith else { 0.1, 0.3, 0.7 },
                horizon = if e then e.sky.horizon else { 0.6, 0.75, 0.95 },
                ground = if e then e.sky.ground else { 0.3, 0.28, 0.25 },
                starsIntensity = if e then e.palette.stars else 0,
            }
        end
        if ecs.has(hostId, ecs.Sky) then ecs.set(hostId, v) else ecs.insertSync(hostId, v) end
    end
    
    local function ensureSky()
        if skyReady then return end
        -- Reuse the record if it is already there (a hot reload of this module, a second attach):
        -- recreating it under the same key leaves the sky pass drawing the old copy.
        local okD, existing = pcall(renderer.material.describe, Director.SKY_KEY)
        if not okD or existing == nil then
            renderer.material.create({ name = Director.SKY_KEY, shader = skyShader(), properties = {}, textures = {} }, Director.SKY_KEY)
        end
        skyCache = {}
        skyReady = true
        bindSky()
    end
    
    local function rgba(c: { number }): { number } return { c[1], c[2], c[3], 1 } end
    
    -- Writes a sky property only when it moved, so a still sky costs nothing.
    local function skySet(k: string, prop: string, v: any)
        local p = skyCache[prop]
        if type(v) == "table" then
            if p ~= nil and math.abs(p[1] - v[1]) < 0.002 and math.abs(p[2] - v[2]) < 0.002
                and math.abs(p[3] - v[3]) < 0.002 and math.abs((p[4] or 0) - (v[4] or 0)) < 0.002 then return end
            skyCache[prop] = table.clone(v)
        else
            if p ~= nil and math.abs(p - v) < 0.0005 then return end
            skyCache[prop] = v
        end
        renderer.material.setProperty(k, prop, v)
    end
    
    local function pushSky(env: any)
        local st = env.style
        local k = Director.SKY_KEY
        local set = skySet
        set(k, "zenith_color", rgba(env.sky.zenith))
        set(k, "horizon_color", rgba(env.sky.horizon))
        set(k, "ground_color", rgba(env.sky.ground))
        set(k, "fog_color", rgba(env.fog.color))
        set(k, "sun_color", rgba(U.lerpRGB(env.palette.sun, { 1, 1, 1 }, 0.25)))
        set(k, "sun2_color", rgba(st.sun2Color))
        set(k, "moon_color", rgba(st.moonColor))
        set(k, "star_color", rgba(st.starColor))
        local cw = 1 - env.weather.darkness * 0.55
        -- clouds take the colour of the light on them: the horizon's glow (sunrise pink, sunset
        -- orange, night blue) until the sun is well up, their own white at full day; and they are
        -- only as bright as the sky around them, so a dawn sky never reads as a grey overcast day
        local dl = env.daylight
        local glowTint = U.lerpRGB(env.palette.horizon, env.palette.sun, 0.35)
        local cloudLit = U.lerpRGB(glowTint, st.cloudColor, dl ^ 1.5)
        local cloudCol = U.scaleRGB(cloudLit, cw * (0.1 + 0.9 * dl ^ 1.3) + 0.015)
        set(k, "cloud_color", rgba(cloudCol))
        set(k, "cloud_shade", rgba(U.scaleRGB(U.lerpRGB(env.sky.zenith, { 0.3, 0.32, 0.36 }, 0.5), cw * (0.08 + 0.92 * dl ^ 1.3) + 0.01)))
        set(k, "sun_dir", { env.sunDir[1], env.sunDir[2], env.sunDir[3], env.sunVis })
        local s2 = if st.sun2Vis ~= nil then st.sun2Vis else (st.sun2 or 0)
        set(k, "sun2_dir", { env.sun2Dir[1], env.sun2Dir[2], env.sun2Dir[3], s2 * U.smoothstep(-0.1, 0.02, env.sun2Dir[2]) })
        set(k, "moon_dir", { env.moonDir[1], env.moonDir[2], env.moonDir[3], Clock.moonPhase() })
        set(k, "sun_size", st.sunSize)
        set(k, "sun2_size", st.sun2Size)
        set(k, "moon_size", st.moonSize)
        set(k, "glow", st.glow)
        set(k, "horizon_glow", st.horizonGlow)
        set(k, "stars", env.palette.stars)
        set(k, "star_density", st.starDensity)
        set(k, "moon_vis", env.moonVis)
        set(k, "cloud_cover", env.sky.cover)
        set(k, "cloud_dark", env.weather.cloudDark)
        set(k, "cloud_soft", st.cloudSoft)
        set(k, "cloud_scale", st.cloudScale)
        set(k, "cloud_speed", 0.004 + env.weather.wind * 0.03)
        set(k, "haze", math.clamp(env.weather.fog * 0.9 + env.weather.sand * 0.3, 0, 1))
        set(k, "bands", st.bands)
        set(k, "pixel", st.pixel)
        set(k, "toon", st.toon)
        set(k, "flash", env.flash)
        set(k, "exposure", st.exposure)
    end
    
    --!desc Point the director at the host entity (the WorldClock's) and set up what it draws with.
    function Director.attach(id: string)
        hostId = id
        lastWritten = {}
        local cfg = State.config()
        -- A clock that does not drive the lighting must not add a sun of its own:
        -- the scene's own lights may simply not be spawned yet when it attaches.
        if cfg.drivesLighting ~= false then findLights() end
        if cfg.skyMode ~= "engine" and cfg.skyMode ~= "off" then
            ensureSky()
            bindSky()
        else
            engineSky = findEngineSky()
        end
        if cfg.precipitation ~= false then
            Precip.ensure(id)
            Precip.warm()
        end
        if cfg.lightningEnabled ~= false then
            Lightning.ensure(id)
            Lightning.warm()
        end
        Audio.setEnabled(cfg.sound ~= false)
    end
    
    function Director.detach()
        if hostId and ecs.has(hostId, ecs.Sky) then ecs.remove(hostId, ecs.Sky) end
        Precip.teardown()
        Lightning.teardown()
        Audio.silence()
        if ownSun and entity.exists(ownSun.id) then pcall(function() ownSun:despawn() end) end
        if ownAmb and entity.exists(ownAmb.id) then pcall(function() ownAmb:despawn() end) end
        ownSun, ownAmb, sunComp, ambComp = nil, nil, nil, nil
        if surfaceOn then SurfaceWeather.clear() surfaceOn = false end
        if fogOn then Fog.clear() fogOn = false end
        hostId = nil
        skyReady = false
    end
    
    local function camPos(): { number }
        local ok, p = pcall(function() return camera.viewData().position end)
        if ok and p then return { p.x, p.y, p.z } end
        return { 0, 2, 0 }
    end
    
    --!desc Write an environment to the engine.
    function Director.apply(env: any, cam: { number }?)
        local cfg = State.config()
        local c = cam or camPos()
        if cfg.drivesLighting ~= false then
            if sunComp == nil or ambComp == nil then findLights() end
            local okS = pcall(writeLight, sunComp, "sun", env.light.color, env.light.intensity, env.light.dir)
            local okA = pcall(writeLight, ambComp, "amb", env.ambient.color, env.ambient.intensity, nil)
            if not okS or not okA then findLights() end
        end
        if cfg.skyMode == "engine" then
            if engineSky == nil then engineSky = findEngineSky() end
            if engineSky and changed("engineTod", Clock.hour(), 0.02) then
                pcall(function() engineSky.timeOfDay = Clock.hour() end)
            end
        elseif cfg.skyMode ~= "off" then
            lastEnvForSky = env
            ensureSky()
            pushSky(env)
            reassert -= 1
            -- while falling back, check twice a second so the real sky takes over promptly
            if reassert <= 0 or (fallbackSky and reassert % 30 == 0) then
                if reassert <= 0 then reassert = 60 end
                local s = sky.get()
                if fallbackSky or s.material_name ~= Director.SKY_KEY or s.type ~= "material" then
                    bindSky(env)
                end
            end
        end
        -- fog
        if changed("fogd", env.fog.density, 0.0002) or changed("fogc", U.luma(env.fog.color), 0.004) then
            Fog.set({ density = env.fog.density, heightFalloff = 0.05, heightRef = 0, color = env.fog.color,
                inscatter = 0.4 * env.daylight, start = 2 })
            fogOn = true
        end
        -- wet ground and snow cover (the engine's surface weather)
        local wet, snowC = env.weather.wetness, env.weather.snowCover
        if wet > 0.01 or snowC > 0.01 then
            if changed("wet", wet, 0.01) or changed("snowc", snowC, 0.01) or not surfaceOn then
                SurfaceWeather.set({ wetness = wet, snow = snowC })
                surfaceOn = true
            end
        elseif surfaceOn then
            SurfaceWeather.clear()
            surfaceOn = false
            lastWritten.wet = nil
            lastWritten.snowc = nil
        end
        -- precipitation
        if cfg.precipitation ~= false then
            local seed = State.seed()
            local ang = U.hash(seed, 7) * math.pi * 2 + math.sin(env.t * 0.05) * 0.4
            local lit = math.clamp(0.35 + env.daylight * 0.65 + env.flash * 0.8, 0.3, 1.6)
            Precip.update(env.weather, c, lit, { math.cos(ang), math.sin(ang) })
        end
    end
    
    -- ─── tick ──────────────────────────────────────────────────────────────
    
    local lastEnv: any = nil
    local lampsOn = false
    
    --!desc The environment last applied (nil before the first frame).
    function Director.current(): any
        return lastEnv
    end
    
    --!desc Whether lamps should be lit now (light level under 0.35, with a little hysteresis).
    function Director.lampsShouldBeOn(): boolean
        return lampsOn
    end
    
    function Director.lampRule(level: number, wasOn: boolean): boolean
        if wasOn then return level < 0.4 end
        return level < 0.33
    end
    
    --!desc One frame: events, lightning, the environment, sound.
    local frameDts: { number } = {}
    local frameIdx = 0
    local FRAME_WINDOW = 300
    
    --!desc This machine's recent frame timing (the last ~300 frames the kit ticked):
    --!  `{ fps, avgMs, p95Ms, worstMs, samples }`. What `Probe` reports for each player.
    function Director.frameStats(): any
        local n = #frameDts
        if n == 0 then return { fps = 0, avgMs = 0, p95Ms = 0, worstMs = 0, samples = 0 } end
        local sum, sorted = 0, table.clone(frameDts)
        for _, d in frameDts do sum += d end
        table.sort(sorted)
        local avg = sum / n
        return {
            fps = if avg > 0 then 1 / avg else 0,
            avgMs = avg * 1000,
            p95Ms = sorted[math.max(1, math.ceil(n * 0.95))] * 1000,
            worstMs = sorted[n] * 1000,
            samples = n,
        }
    end
    
    function Director.tick(dt: number)
        if dt > 0 and dt < 2 then
            frameIdx = frameIdx % FRAME_WINDOW + 1
            frameDts[frameIdx] = dt
        end
        -- After a hot reload of this module its state starts empty while the WorldClock keeps
        -- ticking it: pick the host back up so the sky, lights and weather stay bound.
        if hostId == nil then
            local h = State.host()
            if h ~= nil and h.id then Director.attach(h.id()) end
        end
        Clock._step()
        local strikes = Weather._step()
        local now = State.now()
        local cam = camPos()
        for _, s in strikes do Lightning.strike(s, now, cam) end
        local thunder = Lightning.update(now)
        local cfg = State.config()
        for _, q in thunder do Audio.thunder(q.distance, q.strength) end
        local env = Director.evaluate(now, Lightning.flash())
        lastEnv = env
        lampsOn = Director.lampRule(env.lightLevel, lampsOn)
        Director.apply(env, cam)
        if cfg.sound ~= false then
            Audio.update(env.weather, 1 - env.daylight)
        end
    end
    
    -- ─── sky look ops ──────────────────────────────────────────────────────
    
    State.defineOp("setSky", function(a)
        if not Skies.has(a.name) then return end
        local sk = State.skyRec()
        local now = State.now()
        local from = sk.name
        local _, _, lw = lookBlend(now)
        if lw < 0.5 then from = sk.prevName or sk.name end
        State.write("sk", { name = a.name, prevName = from, from = nil, t0 = now, fade = math.max(0, a.fade or 3), rev = (sk.rev or 0) + 1 })
    end)
    
    local seenSkyRev: number? = nil
    Signals.on("timeSet", function() end)
    
    --!desc Fire "skyChanged" when the look record moves (any peer).
    function Director._skyStep()
        local sk = State.skyRec()
        if seenSkyRev ~= nil and sk.rev ~= seenSkyRev then
            Signals.emit("skyChanged", { from = sk.prevName, to = sk.name })
        end
        seenSkyRev = sk.rev
    end
    
    return Director
    =======
    --!desc Turns the clock, the weather and the sky look into the scene: the sun (or moon)
    --!  light, the ambient fill, the kit's sky material, height fog, wet ground and snow cover,
    --!  falling rain/snow/sand, lightning and the ambience. `Director.evaluate(t)` is pure — the
    --!  whole environment as numbers — and `Director.apply(env)` writes it to the engine. The
    --!  `WorldClock` component calls `Director.tick(dt)` once a frame on every peer.
    
    local U = require("~.util")
    local State = require("~.state")
    local Clock = require("~.clock")
    local Weather = require("~.weather")
    local Skies = require("~.skies")
    local Precip = require("~.precip")
    local Lightning = require("~.lightning")
    local Audio = require("~.audio")
    local Signals = require("~.signals")
    
    local Fog = require("@builtin::systems.atmosphere.fog")
    local SurfaceWeather = require("@builtin::systems.weather.weather")
    
    local Director = {}
    
    Director.SKY_KEY = "__wck_sky"
    
    -- Readability floors: night never drops below these, noon never above the caps.
    Director.MIN_AMBIENT = 0.18
    Director.MAX_SUN = 7.5
    
    -- ─── the sky look fade ─────────────────────────────────────────────────
    
    local function lookBlend(t: number): (string, string, number)
        local sk = State.skyRec()
        local from = sk.prevName or sk.name
        if sk.fade <= 0 then return sk.name, sk.name, 1 end
        return from, sk.name, U.smoothstep(0, 1, (t - sk.t0) / sk.fade)
    end
    
    local function lookSolar(name: string, solar: number): number
        local d = Skies.get(name)
        if d and d.lockHour >= 0 then return d.lockHour end
        return solar
    end
    
    local function blendStyle(a: any, b: any, w: number): any
        local out: any = {}
        for k, va in a do
            local vb = b[k]
            if type(va) == "number" then
                if k == "bands" or k == "pixel" or k == "sun2" or k == "lockHour" then
                    out[k] = if w < 0.5 then va else vb
                else
                    out[k] = U.lerp(va, vb, w)
                end
            elseif type(va) == "table" then
                out[k] = U.lerpRGB(va, vb, w)
            else
                out[k] = if w < 0.5 then va else vb
            end
        end
        if a.sun2 ~= b.sun2 then out.sun2Vis = if a.sun2 > 0 then 1 - w else w else out.sun2Vis = a.sun2 end
        return out
    end
    
    -- ─── evaluate (pure) ───────────────────────────────────────────────────
    
    --!desc The whole environment at shared second `t` (default now) as plain numbers: `look`,
    --!  `solar`, `sunDir`, `moonDir`, `sunVis`, `moonVis`, `palette`, `style`, `weather`,
    --!  `light` = { dir, color, intensity, isMoon }, `ambient` = { color, intensity },
    --!  `fog` = { color, density }, `lightLevel` (0-1, what lamps read) and `flash`.
    function Director.evaluate(t: number?, flash: number?): any
        local now = t or State.now()
        local realSolar = Clock.solarHour()
        local fromLook, toLook, lw = lookBlend(now)
        local solarA = lookSolar(fromLook, realSolar)
        local solarB = lookSolar(toLook, realSolar)
        -- the sun's position blends too, so a switch into a locked look glides there
        local solar = if math.abs(solarA - solarB) > 12 then (if lw < 0.5 then solarA else solarB) else U.lerp(solarA, solarB, lw)
        local palette = Skies.mixPalette(Skies.paletteAt(fromLook, solarA), Skies.paletteAt(toLook, solarB), lw)
        local style = blendStyle(Skies.style(fromLook), Skies.style(toLook), lw)
        local w = Weather.paramsAt(now)
        local fl = flash or 0
    
        local sx, sy, sz = Clock.sunDirectionAt(solar)
        local mx, my, mz = Clock.sunDirectionAt(solar + 12)
        mx, my, mz = U.normalize(mx, my, mz + 0.18)
        local s2x, s2y, s2z = Clock.sunDirectionAt(solar - (style.sun2Lag or 1.6))
    
        local daylight = U.smoothstep(-0.12, 0.25, sy)
        local cover = math.max(w.cloudCover, style.baseCover or 0)
        local dark = w.darkness
        local overcastGrey = U.luma(palette.horizon)
    
        -- clouds pull the sky toward the weather's grey, darkness pulls everything down
        local greyTint = U.lerpRGB({ 1, 1, 1 }, w.tint, 0.6)
        local function weatherSky(c: { number }, k: number): { number }
            local g = U.luma(c) * (0.9 - w.cloudDark * 0.35)
            local grey = { g * greyTint[1], g * greyTint[2], g * greyTint[3] }
            return U.scaleRGB(U.lerpRGB(c, grey, cover * k), 1 - dark * 0.6)
        end
        local zenith = weatherSky(palette.zenith, 0.85)
        local horizon = weatherSky(palette.horizon, 0.8)
        local ground = U.scaleRGB(palette.ground, 1 - dark * 0.5)
    
        -- the scene light: the sun while it is up, the moon after it sets
        local sunUp = U.smoothstep(-0.03, 0.12, sy)
        local light: any
        if sy > -0.03 then
            local i = math.min(palette.sunI, Director.MAX_SUN) * sunUp * (1 - 0.92 * w.sunDim)
            light = { dir = { -sx, -sy, -sz }, color = palette.sun, intensity = i, isMoon = false }
        else
            local phase = Clock.moonPhase()
            local fullness = 1 - math.abs(phase - 0.5) * 2
            local moonUp = U.smoothstep(-0.03, 0.18, my)
            local i = (style.moonI or 1) * 0.6 * moonUp * (0.45 + 0.55 * fullness) * (1 - 0.85 * w.sunDim)
            light = { dir = { -mx, -my, -mz }, color = style.moonColor, intensity = i, isMoon = true }
        end
        if style.sun2 and style.sun2 > 0 and light.isMoon == false then
            -- the second sun warms the light a little where it stands above the first
            local s2up = U.smoothstep(-0.03, 0.2, s2y)
            light.color = U.lerpRGB(light.color, style.sun2Color, 0.25 * s2up)
        end
    
        -- ambient: the look's fill, flattened and brightened a touch under cloud (diffuse light)
        local amb = U.lerpRGB(palette.amb, U.lerpRGB(palette.amb, greyTint, 0.5), cover * 0.6)
        local ambI = palette.ambI * (0.5 + 0.2 * daylight) * (1 + 0.35 * w.sunDim * daylight) * (1 - 0.4 * dark)
        ambI = math.max(ambI, Director.MIN_AMBIENT)
        ambI += fl * 2.2
    
        -- fog
        local fogColor = U.lerpRGB(palette.fog, U.scaleRGB(w.tint, U.luma(palette.fog) * 1.25 + 0.02), math.min(1, cover * 0.5 + w.fog * 0.6))
        fogColor = U.scaleRGB(fogColor, 1 - dark * 0.45)
        local density = 0.0012 + (w.fog ^ 1.6) * 0.085
    
        -- how lit the world is, for lamps: the sun's height, the clouds' darkness, a locked night
        local lightLevel = daylight * math.max(0, 1 - dark * 1.1) * (1 - math.max(0, (style.baseCover or 0) - 0.5) * 0.4)
    
        return {
            t = now,
            look = toLook, fromLook = fromLook, lookBlend = lw,
            solar = solar,
            sunDir = { sx, sy, sz }, moonDir = { mx, my, mz }, sun2Dir = { s2x, s2y, s2z },
            sunVis = U.smoothstep(-0.1, 0.02, sy),
            moonVis = U.clamp01(1 - daylight * 1.4),
            daylight = daylight,
            palette = palette, style = style, weather = w,
            sky = { zenith = zenith, horizon = horizon, ground = ground, cover = cover, overcastGrey = overcastGrey },
            light = light,
            ambient = { color = amb, intensity = ambI },
            fog = { color = fogColor, density = density },
            lightLevel = lightLevel,
            flash = fl,
        }
    end
    
    -- ─── apply (engine writes) ─────────────────────────────────────────────
    
    local hostId: string? = nil
    local sunComp: any = nil
    local ambComp: any = nil
    local ownSun: any = nil
    local ownAmb: any = nil
    local skyReady = false
    local engineSky: any = nil
    local lastWritten: { [string]: any } = {}
    local surfaceOn = false
    local fogOn = false
    local reassert = 0
    
    local function findLights()
        sunComp, ambComp = nil, nil
        for _, e in entity.findAll() do
            -- an entity can go between findAll() and the read (another peer's editor presence, a despawn mid-frame)
            local okL, l = pcall(function() return e.component.get("Light") end)
            if not okL then l = nil end
            if l then
                if l.kind == "directional" and sunComp == nil and (ownSun == nil or e.id ~= ownSun.id) then sunComp = l end
                if l.kind == "ambient" and ambComp == nil and (ownAmb == nil or e.id ~= ownAmb.id) then ambComp = l end
            end
        end
        if sunComp == nil then
            if ownSun == nil or not entity.exists(ownSun.id) then
                ownSun = entity.findAll("worldClockKit sun")[1]
                    or entity.spawn("worldClockKit sun", { temporary = true, internal = true, parent = hostId })
                ownSun.component.add("Light", { kind = "directional", intensity = 0, castsShadows = true })
            end
            sunComp = ownSun.component.get("Light")
        end
        if ambComp == nil then
            if ownAmb == nil or not entity.exists(ownAmb.id) then
                ownAmb = entity.findAll("worldClockKit ambient")[1]
                    or entity.spawn("worldClockKit ambient", { temporary = true, internal = true, parent = hostId })
                ownAmb.component.add("Light", { kind = "ambient", intensity = 0.5 })
            end
            ambComp = ownAmb.component.get("Light")
        end
    end
    
    local function findEngineSky(): any
        for _, e in entity.findAll() do
            local okS, s = pcall(function() return e.component.get("ProceduralSky") end)
            if not okS then s = nil end
            if s then return s end
        end
        return nil
    end
    
    local function changed(key: string, v: number, eps: number): boolean
        local p = lastWritten[key]
        if p == nil or math.abs(p - v) > eps then
            lastWritten[key] = v
            return true
        end
        return false
    end
    
    local function writeLight(comp: any, prefix: string, color: { number }, intensity: number, dir: { number }?)
        if comp == nil then return end
        if changed(prefix .. "i", intensity, 0.003) then comp.intensity = intensity end
        if changed(prefix .. "r", color[1], 0.003) then comp.colorR = color[1] end
        if changed(prefix .. "g", color[2], 0.003) then comp.colorG = color[2] end
        if changed(prefix .. "b", color[3], 0.003) then comp.colorB = color[3] end
        if dir then
            if changed(prefix .. "dx", dir[1], 0.0015) then comp.directionX = dir[1] end
            if changed(prefix .. "dy", dir[2], 0.0015) then comp.directionY = dir[2] end
            if changed(prefix .. "dz", dir[3], 0.0015) then comp.directionZ = dir[3] end
        end
    end
    
    local function skyShader(): string
        return tostring(asset.resolve("~.shaders.wck_sky", "shader"))
    end
    
    local skyCache: { [string]: any } = {}
    
    -- Whether the kit's sky shader is compiled. Until it is, a material sky draws black, so the
    -- kit shows the engine's own procedural sky in its colours instead (see `bindSky`). A shader
    -- can sit uncompiled after a branch switch or a reload that rewrote no file.
    local fallbackSky = false
    local skyShaderRef: any = nil
    local shaderCheck: (() -> boolean)? = nil
    local function skyShaderCompiled(): boolean
        if shaderCheck then return shaderCheck() end
        if skyShaderRef == nil then skyShaderRef = asset.resolve("~.shaders.wck_sky", "shader") end
        local ok, st = pcall(function() return skyShaderRef:compileStatus() end)
        return ok and type(st) == "table" and st.status == "compiled"
    end
    
    --!desc Whether the sky is showing the engine's fallback (the kit's sky shader is not compiled yet).
    function Director.skyFallback(): boolean
        return fallbackSky
    end
    
    --!desc Tests only: replace the shader-compiled check (nil restores the real one).
    function Director._setShaderCheck(fn: (() -> boolean)?)
        shaderCheck = fn
    end
    
    local warnedFallback = false
    local lastEnvForSky: any = nil
    
    local function bindSky(env: any?)
        if hostId == nil then return end
        local v: any
        if skyShaderCompiled() then
            fallbackSky = false
            v = ecs.Sky { skyType = "material", materialName = Director.SKY_KEY }
        else
            if not warnedFallback then
                warnedFallback = true
                print("[worldClockKit] the sky shader is not compiled yet; showing the engine's sky in the kit's colours until it is")
            end
            fallbackSky = true
            local e = env or lastEnvForSky
            v = ecs.Sky {
                skyType = "procedural", syncSunToLight = false, autoCycle = false,
                timeOfDay = Clock.hour(),
                zenith = if e then e.sky.zenith else { 0.1, 0.3, 0.7 },
                horizon = if e then e.sky.horizon else { 0.6, 0.75, 0.95 },
                ground = if e then e.sky.ground else { 0.3, 0.28, 0.25 },
                starsIntensity = if e then e.palette.stars else 0,
            }
        end
        if ecs.has(hostId, ecs.Sky) then ecs.set(hostId, v) else ecs.insertSync(hostId, v) end
    end
    
    local function ensureSky()
        if skyReady then return end
        -- Reuse the record if it is already there (a hot reload of this module, a second attach):
        -- recreating it under the same key leaves the sky pass drawing the old copy.
        local okD, existing = pcall(renderer.material.describe, Director.SKY_KEY)
        if not okD or existing == nil then
            renderer.material.create({ name = Director.SKY_KEY, shader = skyShader(), properties = {}, textures = {} }, Director.SKY_KEY)
        end
        skyCache = {}
        skyReady = true
        bindSky()
    end
    
    local function rgba(c: { number }): { number } return { c[1], c[2], c[3], 1 } end
    
    -- Writes a sky property only when it moved, so a still sky costs nothing.
    local function skySet(k: string, prop: string, v: any)
        local p = skyCache[prop]
        if type(v) == "table" then
            if p ~= nil and math.abs(p[1] - v[1]) < 0.002 and math.abs(p[2] - v[2]) < 0.002
                and math.abs(p[3] - v[3]) < 0.002 and math.abs((p[4] or 0) - (v[4] or 0)) < 0.002 then return end
            skyCache[prop] = table.clone(v)
        else
            if p ~= nil and math.abs(p - v) < 0.0005 then return end
            skyCache[prop] = v
        end
        renderer.material.setProperty(k, prop, v)
    end
    
    local function pushSky(env: any)
        local st = env.style
        local k = Director.SKY_KEY
        local set = skySet
        set(k, "zenith_color", rgba(env.sky.zenith))
        set(k, "horizon_color", rgba(env.sky.horizon))
        set(k, "ground_color", rgba(env.sky.ground))
        set(k, "fog_color", rgba(env.fog.color))
        set(k, "sun_color", rgba(U.lerpRGB(env.palette.sun, { 1, 1, 1 }, 0.25)))
        set(k, "sun2_color", rgba(st.sun2Color))
        set(k, "moon_color", rgba(st.moonColor))
        set(k, "star_color", rgba(st.starColor))
        local cw = 1 - env.weather.darkness * 0.55
        -- clouds take the colour of the light on them: the horizon's glow (sunrise pink, sunset
        -- orange, night blue) until the sun is well up, their own white at full day; and they are
        -- only as bright as the sky around them, so a dawn sky never reads as a grey overcast day
        local dl = env.daylight
        local glowTint = U.lerpRGB(env.palette.horizon, env.palette.sun, 0.35)
        local cloudLit = U.lerpRGB(glowTint, st.cloudColor, dl ^ 1.5)
        local cloudCol = U.scaleRGB(cloudLit, cw * (0.1 + 0.9 * dl ^ 1.3) + 0.015)
        set(k, "cloud_color", rgba(cloudCol))
        set(k, "cloud_shade", rgba(U.scaleRGB(U.lerpRGB(env.sky.zenith, { 0.3, 0.32, 0.36 }, 0.5), cw * (0.08 + 0.92 * dl ^ 1.3) + 0.01)))
        set(k, "sun_dir", { env.sunDir[1], env.sunDir[2], env.sunDir[3], env.sunVis })
        local s2 = if st.sun2Vis ~= nil then st.sun2Vis else (st.sun2 or 0)
        set(k, "sun2_dir", { env.sun2Dir[1], env.sun2Dir[2], env.sun2Dir[3], s2 * U.smoothstep(-0.1, 0.02, env.sun2Dir[2]) })
        set(k, "moon_dir", { env.moonDir[1], env.moonDir[2], env.moonDir[3], Clock.moonPhase() })
        set(k, "sun_size", st.sunSize)
        set(k, "sun2_size", st.sun2Size)
        set(k, "moon_size", st.moonSize)
        set(k, "glow", st.glow)
        set(k, "horizon_glow", st.horizonGlow)
        set(k, "stars", env.palette.stars)
        set(k, "star_density", st.starDensity)
        set(k, "moon_vis", env.moonVis)
        set(k, "cloud_cover", env.sky.cover)
        set(k, "cloud_dark", env.weather.cloudDark)
        set(k, "cloud_soft", st.cloudSoft)
        set(k, "cloud_scale", st.cloudScale)
        set(k, "cloud_speed", 0.004 + env.weather.wind * 0.03)
        set(k, "haze", math.clamp(env.weather.fog * 0.9 + env.weather.sand * 0.3, 0, 1))
        set(k, "bands", st.bands)
        set(k, "pixel", st.pixel)
        set(k, "toon", st.toon)
        set(k, "flash", env.flash)
        set(k, "exposure", st.exposure)
    end
    
    --!desc Point the director at the host entity (the WorldClock's) and set up what it draws with.
    function Director.attach(id: string)
        hostId = id
        lastWritten = {}
        findLights()
        local cfg = State.config()
        if cfg.skyMode ~= "engine" and cfg.skyMode ~= "off" then
            ensureSky()
            bindSky()
        else
            engineSky = findEngineSky()
        end
        if cfg.precipitation ~= false then
            Precip.ensure(id)
            Precip.warm()
        end
        if cfg.lightningEnabled ~= false then
            Lightning.ensure(id)
            Lightning.warm()
        end
        Audio.setEnabled(cfg.sound ~= false)
    end
    
    function Director.detach()
        if hostId and ecs.has(hostId, ecs.Sky) then ecs.remove(hostId, ecs.Sky) end
        Precip.teardown()
        Lightning.teardown()
        Audio.silence()
        if ownSun and entity.exists(ownSun.id) then pcall(function() ownSun:despawn() end) end
        if ownAmb and entity.exists(ownAmb.id) then pcall(function() ownAmb:despawn() end) end
        ownSun, ownAmb, sunComp, ambComp = nil, nil, nil, nil
        if surfaceOn then SurfaceWeather.clear() surfaceOn = false end
        if fogOn then Fog.clear() fogOn = false end
        hostId = nil
        skyReady = false
    end
    
    local function camPos(): { number }
        local ok, p = pcall(function() return camera.viewData().position end)
        if ok and p then return { p.x, p.y, p.z } end
        return { 0, 2, 0 }
    end
    
    --!desc Write an environment to the engine.
    function Director.apply(env: any, cam: { number }?)
        local cfg = State.config()
        local c = cam or camPos()
        if cfg.drivesLighting ~= false then
            if sunComp == nil or ambComp == nil then findLights() end
            local okS = pcall(writeLight, sunComp, "sun", env.light.color, env.light.intensity, env.light.dir)
            local okA = pcall(writeLight, ambComp, "amb", env.ambient.color, env.ambient.intensity, nil)
            if not okS or not okA then findLights() end
        end
        if cfg.skyMode == "engine" then
            if engineSky == nil then engineSky = findEngineSky() end
            if engineSky and changed("engineTod", Clock.hour(), 0.02) then
                pcall(function() engineSky.timeOfDay = Clock.hour() end)
            end
        elseif cfg.skyMode ~= "off" then
            lastEnvForSky = env
            ensureSky()
            pushSky(env)
            reassert -= 1
            -- while falling back, check twice a second so the real sky takes over promptly
            if reassert <= 0 or (fallbackSky and reassert % 30 == 0) then
                if reassert <= 0 then reassert = 60 end
                local s = sky.get()
                if fallbackSky or s.material_name ~= Director.SKY_KEY or s.type ~= "material" then
                    bindSky(env)
                end
            end
        end
        -- fog
        if changed("fogd", env.fog.density, 0.0002) or changed("fogc", U.luma(env.fog.color), 0.004) then
            Fog.set({ density = env.fog.density, heightFalloff = 0.05, heightRef = 0, color = env.fog.color,
                inscatter = 0.4 * env.daylight, start = 2 })
            fogOn = true
        end
        -- wet ground and snow cover (the engine's surface weather)
        local wet, snowC = env.weather.wetness, env.weather.snowCover
        if wet > 0.01 or snowC > 0.01 then
            if changed("wet", wet, 0.01) or changed("snowc", snowC, 0.01) or not surfaceOn then
                SurfaceWeather.set({ wetness = wet, snow = snowC })
                surfaceOn = true
            end
        elseif surfaceOn then
            SurfaceWeather.clear()
            surfaceOn = false
            lastWritten.wet = nil
            lastWritten.snowc = nil
        end
        -- precipitation
        if cfg.precipitation ~= false then
            local seed = State.seed()
            local ang = U.hash(seed, 7) * math.pi * 2 + math.sin(env.t * 0.05) * 0.4
            local lit = math.clamp(0.35 + env.daylight * 0.65 + env.flash * 0.8, 0.3, 1.6)
            Precip.update(env.weather, c, lit, { math.cos(ang), math.sin(ang) })
        end
    end
    
    -- ─── tick ──────────────────────────────────────────────────────────────
    
    local lastEnv: any = nil
    local lampsOn = false
    
    --!desc The environment last applied (nil before the first frame).
    function Director.current(): any
        return lastEnv
    end
    
    --!desc Whether lamps should be lit now (light level under 0.35, with a little hysteresis).
    function Director.lampsShouldBeOn(): boolean
        return lampsOn
    end
    
    function Director.lampRule(level: number, wasOn: boolean): boolean
        if wasOn then return level < 0.4 end
        return level < 0.33
    end
    
    --!desc One frame: events, lightning, the environment, sound.
    local frameDts: { number } = {}
    local frameIdx = 0
    local FRAME_WINDOW = 300
    
    --!desc This machine's recent frame timing (the last ~300 frames the kit ticked):
    --!  `{ fps, avgMs, p95Ms, worstMs, samples }`. What `Probe` reports for each player.
    function Director.frameStats(): any
        local n = #frameDts
        if n == 0 then return { fps = 0, avgMs = 0, p95Ms = 0, worstMs = 0, samples = 0 } end
        local sum, sorted = 0, table.clone(frameDts)
        for _, d in frameDts do sum += d end
        table.sort(sorted)
        local avg = sum / n
        return {
            fps = if avg > 0 then 1 / avg else 0,
            avgMs = avg * 1000,
            p95Ms = sorted[math.max(1, math.ceil(n * 0.95))] * 1000,
            worstMs = sorted[n] * 1000,
            samples = n,
        }
    end
    
    function Director.tick(dt: number)
        if dt > 0 and dt < 2 then
            frameIdx = frameIdx % FRAME_WINDOW + 1
            frameDts[frameIdx] = dt
        end
        -- After a hot reload of this module its state starts empty while the WorldClock keeps
        -- ticking it: pick the host back up so the sky, lights and weather stay bound.
        if hostId == nil then
            local h = State.host()
            if h ~= nil and h.id then Director.attach(h.id()) end
        end
        Clock._step()
        local strikes = Weather._step()
        local now = State.now()
        local cam = camPos()
        for _, s in strikes do Lightning.strike(s, now, cam) end
        local thunder = Lightning.update(now)
        local cfg = State.config()
        for _, q in thunder do Audio.thunder(q.distance, q.strength) end
        local env = Director.evaluate(now, Lightning.flash())
        lastEnv = env
        lampsOn = Director.lampRule(env.lightLevel, lampsOn)
        Director.apply(env, cam)
        if cfg.sound ~= false then
            Audio.update(env.weather, 1 - env.daylight)
        end
    end
    
    -- ─── sky look ops ──────────────────────────────────────────────────────
    
    State.defineOp("setSky", function(a)
        if not Skies.has(a.name) then return end
        local sk = State.skyRec()
        local now = State.now()
        local from = sk.name
        local _, _, lw = lookBlend(now)
        if lw < 0.5 then from = sk.prevName or sk.name end
        State.write("sk", { name = a.name, prevName = from, from = nil, t0 = now, fade = math.max(0, a.fade or 3), rev = (sk.rev or 0) + 1 })
    end)
    
    local seenSkyRev: number? = nil
    Signals.on("timeSet", function() end)
    
    --!desc Fire "skyChanged" when the look record moves (any peer).
    function Director._skyStep()
        local sk = State.skyRec()
        if seenSkyRev ~= nil and sk.rev ~= seenSkyRev then
            Signals.emit("skyChanged", { from = sk.prevName, to = sk.name })
        end
        seenSkyRev = sk.rev
    end
    
    return Director
    >>>>>>> main (target)
    

5 files changed

  • AddedworldClockKit.packageFolderAfter
  • AddedworldClockKit.package/WorldClock.componentFolderAfter
  • AddedworldClockKit.package/WorldClock.component/init.luau16.6 KBAfter
  • AddedworldClockKit.package/director.moduleFolderAfter
  • AddedworldClockKit.package/director.module/init.luau23.7 KBAfter

Checks

No checks have been posted.

Reviews

No reviews yet.

Conversation

No comments yet.

Sign in to comment or review.