# precip Rain, snow and blown sand: one fixed 2,400-drop mesh drawn with the `wck_precip` shader by three temporary entities parked on the camera, so the cost never grows with the world.

# weather The shared weather: `Weather.set(name, { fade })` fades everyone's world into it; reads the blended numbers, storm/rain/snow state, and the lightning schedule every peer computes identically. Fires weatherChanged, stormStarted, stormEnded and lightning.

# state The single source of truth. The scene's `WorldClock` registers here as the host; its owner is the authority. Holds the shared timeline (`State.now()`), the clock, weather and sky records, and routes a change from a non-owner to the owner over `multiplayer.send`. With no host it runs on a local record (tests, previews). `State.isAuthority()` tells game code whether this machine should make shared-world changes.

# director Turns clock, weather and look into the scene each frame on every peer: the sun/moon light, ambient, the kit's sky material, height fog, the engine's surface weather (wet ground, snow cover), precipitation, lightning and ambience. `Director.evaluate(t)` is pure and testable; `apply` writes only what changed.

# sky The shared sky look: `Sky.set(name)` cross-fades the whole look for everyone; `Sky.lightLevel()`, `Sky.isDark()` and `Sky.environment()` read what the kit computed this frame.

# signals The kit's event bus. `on(name, fn)` / `once` subscribe and return a connection with `:Disconnect()`; `emit` calls every handler, each isolated so a failing handler never stops the clock. `Signals.NAMES` lists every event. Reached through `Clock.on` and `Kit.on`.

# lamps The six lamp styles (streetLamp, hangingLantern, wallTorch, neonSign, glowingWindows, stringLights) as part lists, the builder `WorldLamp` uses, neon tube lettering, and `spawn` / `list` / `setMode` / `define` for code.

# worldClockKit **worldClockKit gives your world a shared day/night clock that every player sees at the same hour, with a sun, moon and stars that cross the sky and lighting that follows them; eight sky looks; eight weathers that fade in, from clear skies up to a thunderstorm whose lightning and thunder every player sees and hears at the same moment; six lamp styles that switch themselves on at dusk and off at dawn; four on-screen clocks; and rain, wind, night and thunder sound through Soundstage.** To start in a new world, install worldClockKit (Soundstage comes with it), then in your scene's build.luau add `entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 10 })` and press play. Version 1.3.0 · depends on **Soundstage** (installed with it) · multiplayer from the start · runs in the browser. ## Install and use Install the package (it brings Soundstage with it). Then add one clock to your scene and use the calls from any script. In your scene's `build.luau` (inside `content()`), or once from the editor: ```lua -- the clock: ONE per scene, on a synced entity so every player shares it local clock = entity.spawnSynced("WorldClock") clock.component.add("WorldClock", { dayLengthMinutes = 10, startHour = 7, sky = "realistic" }) -- a lamp that lights itself at dusk local lamp = entity.spawn("Lamp") lamp.localPosition = { 4, 0, -3 } lamp.component.add("WorldLamp", { style = "streetLamp" }) ``` In any script (a scene entrypoint, a component, a tool): ```lua local Kit = require("worldClockKit.kit") local Clock, Weather, Sky = Kit.Clock, Kit.Weather, Kit.Sky function onLoad() Kit.Displays.show("digital", { anchor = "topRight" }) -- a clock on screen Clock.on("dusk", function(e) print("Evening of day " .. e.day) end) Clock.on("newDay", function(e) print("Day " .. e.day .. " begins") end) Weather.set("storm") -- fades in over a few seconds, for everyone Sky.set("pastel") -- swap the whole look; nothing else changes end ``` That is all a world needs: the sky, the sun and moon, the scene's lighting, fog, wet ground, rain, lightning, thunder and the ambience all follow from the clock. The scene's own directional and ambient lights are driven if it has them; if not, the kit brings its own. ## What you get - **A world clock everybody shares.** `dayLengthMinutes` sets how long a day is in real minutes. Every player sees the same hour, sun, weather and lightning, including someone who joins mid-afternoon. A day counter, four seasons (summer days run longer, winter days shorter), and pause / set time. - **A sky that moves.** The sun rises in the east, crosses high in the south and sets in the west; the moon follows with its phase on an eight-day cycle; stars come out after dusk. The light, the ambient fill and the fog follow it: warm low dawn, white noon (capped so it never blows out), orange dusk, and a blue moonlit night that is dark but still readable. - **Weather that fades.** `Weather.set("rain")` blends over a few seconds. Rain and snow fall around the camera, the ground goes wet and shiny or white (the engine's own surface weather, which keeps the ground under a roof dry), fog thickens, clouds roll in and darken the sky, and storms throw lightning with thunder that arrives after the sound's travel time. - **Lamps that switch themselves.** On at dusk, off at dawn, and early when a storm darkens the sky. Each lamp waits a moment of its own so a street lights up one lamp after another; windows and bulbs light one by one; the neon sign stutters on; torches and lanterns flicker. - **Events** for dawn, noon, dusk, midnight, a new day, each hour, phase and season changes, weather changes, storms starting and ending, and every lightning strike. - **Sound** from Soundstage's rain, wind and night recordings, plus the kit's own thunder (three takes by distance) and sandstorm bed. Beds and thunder play through voices the kit owns, checked every frame and rebuilt whenever a play session took them away, so storms always sound like rain and wind, in every session and whatever the weather was before. Beds fade over 1.5 s; both follow Soundstage's ambience and sound-effects volumes. ## Styles Every style is one setting away. Read them in code with `Kit.Catalog` (below); the family tags are realistic, cartoon, cozy, sci-fi, pixel, horror, fantasy and minimal, plus finer ones. ### Sky looks: `Sky.set(name)` or the WorldClock's `sky` field | name | look | tags | | --- | --- | --- | | `realistic` | Natural sky: deep blue noon, orange dawn and dusk, stars and moon | realistic, natural, survival, farming, open-world | | `toon` | Saturated bands, bold sun disc, hard-edged puffy clouds | cartoon, stylised, kids, platformer, bright | | `pastel` | Peach mornings, lavender evenings, lilac night | cozy, cute, farming, hangout, soft | | `alien` | Teal and magenta sky, two suns rising one after the other, a huge green moon | sci-fi, alien, space, exotic, fantasy | | `eternalNight` | The sun never rises: a cold moon and a sky full of stars | horror, spooky, night, mystery, halloween | | `lockedSunset` | Golden hour forever, the sun just above the horizon | cozy, romantic, hangout, vaporwave, chill | | `overcast` | A low grey lid of cloud all day, flat light | moody, realistic, horror, drama, northern | | `pixel` | Chunky pixel gradient, ordered dither, square sun | pixel, retro, 8-bit, arcade, platformer | Locked looks (`eternalNight`, `lockedSunset`) hold the sky and light still while the clock, days and events carry on. ### Weather: `Weather.set(name)` or the WorldClock's `weather` field | name | what happens | | --- | --- | | `clear` | Blue sky, a few wisps of cloud | | `cloudy` | Broken grey cloud, softer light, a breeze | | `rain` | Steady rain, wet shining ground, low cloud, rain ambience | | `storm` | Heavy driven rain, near-black cloud, lightning flashes and thunder, lamps on early | | `snow` | Drifting flakes, the ground turns white | | `blizzard` | Snow driven sideways, thick white-out fog, howling wind | | `fog` | Thick still fog that swallows the distance | | `sandstorm` | A wall of blown orange sand, the sun a dull disc, roaring sand wind | ### Lamps: the `WorldLamp` component's `style` | name | what it is | tags | | --- | --- | --- | | `streetLamp` | Cast-iron post with a curved arm and a sodium lantern that warms up | realistic, urban, victorian, horror, city | | `hangingLantern` | Wooden gallows post with a brass candle lantern | cozy, fantasy, medieval, farming, rustic | | `wallTorch` | A burning torch in an iron bracket on a stone wall | medieval, fantasy, horror, dungeon, survival | | `neonSign` | Pink and cyan tube lettering on a dark board (`text` sets the words) | sci-fi, cyberpunk, urban, synthwave, retro | | `glowingWindows` | A cottage front whose windows light one by one | cozy, realistic, urban, horror, hangout, village | | `stringLights` | Coloured festoon bulbs sagging between two posts | cozy, festive, hangout, party, farming | `WorldLamp` fields: `style`, `mode` (`auto` follows the sky; `on` / `off` force it), `brightness`, `text` (the neon sign's words; letters A-Z, digits and spaces draw as tubes, anything else as a plain label). ### Clock displays: `Kit.Displays.show(style, opts)` | name | what it is | | --- | --- | | `digital` | A panel with the time in big digits, the day, the season and the weather | | `analog` | A round dial with hour and minute hands and the day | | `arc` | A horizon arc the sun travels along by day and the moon by night | | `minimal` | Just the time, small, in a corner | ## Calls All of these work from any player; a change made by someone who is not the clock's owner is sent to the owner and reaches everybody from there. ### `Kit`: `require("worldClockKit.kit")` `Kit.Clock`, `Kit.Weather`, `Kit.Sky`, `Kit.Lamps`, `Kit.Displays`, `Kit.Catalog`, `Kit.on(event, fn)`, `Kit.EVENTS`, `Kit.VERSION`. Each module is also reachable on its own: `require("worldClockKit.clock")`, `.weather`, `.sky`, `.lamps`, `.displays`, `.catalog`. ### Clock: `worldClockKit.clock` | call | returns / does | | --- | --- | | `Clock.hour()` | Hour of the day, 0 to <24 with fractions | | `Clock.minute()` | Minute within the hour, 0-59 | | `Clock.day()` | Day counter, from 1 | | `Clock.totalHours()` | Game hours since day 1, 00:00 | | `Clock.dayProgress()` | 0 at midnight to 1 | | `Clock.format(twelveHour?)` | `"14:05"` or `"2:05 PM"` | | `Clock.season()` | `{ name, index, dayOfSeason, progress, year, daysPerSeason }` (spring, summer, autumn, winter) | | `Clock.sunTimes()` | Sunrise and sunset hours today | | `Clock.solarHour(h?)` | The hour mapped so sunrise is 6 and sunset 18 | | `Clock.phase()` / `Clock.phaseAt(h)` | `"night"`, `"dawn"`, `"day"` or `"dusk"` | | `Clock.isNight()`, `Clock.isDay()` | Booleans | | `Clock.daylight()` | 0 (night) to 1 (full day), from the sun's height | | `Clock.sunDirection()`, `Clock.moonDirection()` | Unit vectors `{x, y, z}` toward each | | `Clock.sunDirectionAt(solarHour)` | The same for any solar hour (x, y, z) | | `Clock.moonPhase()` | 0 new, 0.5 full | | `Clock.dayLengthMinutes()`, `Clock.isPaused()` | Current settings | | `Clock.setTime(hour, day?)` | Set the hour (stays on today unless `day` is given) | | `Clock.setDay(day)` | Jump to a day, keeping the hour | | `Clock.advance(hours)` | Move forward (or back) | | `Clock.pause()`, `Clock.resume()` | Stop and restart the clock (the weather keeps fading) | | `Clock.setDayLength(minutes)` | Change the speed, keeping the hour | | `Clock.on(event, fn)`, `Clock.once(event, fn)` | Subscribe; returns a connection with `:Disconnect()` | ### Weather: `worldClockKit.weather` | call | returns / does | | --- | --- | | `Weather.set(name, { fade = seconds }?)` | Change it for everyone; fades over `weatherFade` (6 s) unless given; `fade = 0` snaps | | `Weather.current()`, `Weather.previous()` | The weather now (or fading in), and the one fading out | | `Weather.blend()` | How far the fade has got, 0-1 | | `Weather.params()` / `Weather.paramsAt(t)` | The numbers now: `cloudCover, cloudDark, rain, snow, sand, wind, fog, wetness, snowCover, lightning` (strikes/min)`, sunDim, darkness, tint, rainBed, windBed, sandBed` | | `Weather.isStorm()`, `Weather.isRaining()`, `Weather.isSnowing()` | Booleans | | `Weather.list()` | Every preset name | | `Weather.define(name, def)` | Add a preset (any channels above, plus `label`, `tags`, `description`) | | `Weather.strike({ at = {x, z}, strength }?)` | Call down one lightning strike for everyone | | `Weather.strikesBetween(t0, t1)` | The scheduled strikes in shared seconds (what every peer computes) | | `Weather.stormCenter()`, `Weather.stormRadius()` | Where lightning lands (the WorldClock's position, `stormRadius`) | ### Sky: `worldClockKit.sky` | call | returns / does | | --- | --- | | `Sky.set(name, { fade = seconds }?)` | Switch the look for everyone (3 s cross-fade) | | `Sky.current()`, `Sky.looks()` | The look now; every look | | `Sky.define(name, def)` | Add a look: `night`, `dawn`, `day`, `dusk` palettes plus style knobs (see `worldClockKit.skies`) | | `Sky.lightLevel()` | How lit the world is, 0-1, clouds included | | `Sky.isDark()` | Whether lamps should be on | | `Sky.environment()` | Everything the kit computed this frame: light, ambient, fog, palette, sun and moon | ### Lamps: `worldClockKit.lamps` `Lamps.styles()`, `Lamps.has(name)`, `Lamps.get(name)`, `Lamps.describe(name)`, `Lamps.spawn(style, { position, yaw, mode, parent })`, `Lamps.list()` (live lamps `{ id, style, mode, on }`), `Lamps.setMode("on" | "off" | "auto")` (every lamp), `Lamps.define(name, def)` (parts, lights, warmup, flicker), `Lamps.canTube(word)`. ### Displays: `worldClockKit.displays` `Displays.show(style, { anchor, scale, twelveHour })` returns a handle; `Displays.hide(handle)`, `Displays.hideAll()`, `Displays.styles()`, `Displays.describe(style)`. Anchors: `topLeft`, `topRight`, `bottomLeft`, `bottomRight`, `topCenter`. ### Catalog: `worldClockKit.catalog` | call | returns | | --- | --- | | `Catalog.kinds()` | `{ "skies", "weathers", "lamps", "clocks" }` | | `Catalog.list(kind, tag?, namesOnly?)` | Entries `{ kind, name, label, tags, description }`, optionally only those tagged | | `Catalog.find(text)` | Every style whose name, label, tags or description mention it | | `Catalog.get(kind, name)` | One entry | | `Catalog.tags()`, `Catalog.FAMILIES` | Every tag in use; the style families | | `Catalog.forFamily(tag)` | `{ skies = {...}, weathers = {...}, lamps = {...}, clocks = {...} }` for a game's style | | `Catalog.text()` | The whole catalog as text | ```lua local Catalog = require("worldClockKit.catalog") print(Catalog.forFamily("horror").skies) -- { "eternalNight", "overcast" } ``` ### Diagnostics and sound | call | returns / does | | --- | --- | | `require("worldClockKit.probe").ask(seconds?)` | Every player's report side by side, with `agree` and `problems` (see With several players) | | `Probe.report()` | This machine's report: hour, weather, look, lamps lit, `perf`, `notes` | | `Probe.drawState()` | This machine's frame rate (`fps, avgMs, p95Ms, worstMs`), platform, sky type and fallback, whether rain/snow/sand draw, its screens and cameras | | `Probe.note(key, value)`, `Probe.notes()` | Attach a fact of your own to what this machine reports | | `require("worldClockKit.director").frameStats()` | `{ fps, avgMs, p95Ms, worstMs, samples }` over the last ~300 frames | | `Director.skyFallback()` | Whether the engine's sky is standing in until the kit's sky shader compiles | | `require("worldClockKit.audio").onThunder(fn)` | `fn({ name, volume, played })` after every thunderclap | | `Audio.playing()` | The level each weather bed is asked for: bed name → 0-1 | | `Audio.sounding()` | What each bed sounds like on this machine: bed name → `{ level, voice, audible }`, `audible` being the engine mixer's own verdict | ### Events: `Clock.on(name, fn)` / `Kit.on(name, fn)` | event | payload | | --- | --- | | `dawn`, `noon`, `dusk`, `midnight` | `{ hour, day, time }` | | `newDay` | `{ hour, day, time }` (the new day) | | `hour` | `{ hour, day, time, hourOfDay }` | | `phase` | `{ phase }`: night, dawn, day, dusk | | `season` | `{ season }` | | `timeSet` | `{ from, to }`: the clock jumped (setTime, a joiner catching up) | | `weatherChanged` | `{ from, to, fade }` | | `stormStarted`, `stormEnded` | `{ weather }` | | `lightning` | `{ t, position = {x, 0, z}, distance, strength, variant }` | | `skyChanged` | `{ from, to }` | Events fire on every player's machine at the same moment, so use them for what each player sees and hears. For a change to the shared world (spawning a crop, ending a round), act only on one machine, for example the clock owner: `require("worldClockKit.state").isAuthority()`. ## Settings: the `WorldClock` component | field | default | meaning | | --- | --- | --- | | `dayLengthMinutes` | 20 | Real minutes per game day | | `startHour`, `startDay` | 8, 1 | Where the clock starts each session | | `daysPerSeason` | 7 | Game days per season | | `startSeason` | spring | The season of day 1 | | `seasonalDaylight` | 1.5 | Hours sunrise/sunset move across the year (0 = always 6:00-18:00) | | `sky` | realistic | The look | | `weather` | clear | The weather | | `weatherFade` | 6 | Seconds a weather change takes | | `paused` | false | Clock stopped | | `skyMode` | kit | `kit` draws the kit's sky; `engine` keeps the scene's own `ProceduralSky` and drives its hour; `off` leaves the sky alone | | `drivesLighting` | true | Drive the sun/moon and ambient light | | `precipitation` | true | Draw rain, snow and sand | | `sound` | true | Weather ambience and thunder through Soundstage | | `lightning` | true | Storms throw lightning | | `stormRadius` | 160 | How far from the WorldClock entity lightning lands (m) | | `autoWeather` | false | Change weather by itself on a shared forecast | | `forecastMinutes` | 4 | Minutes between forecast changes | | `forecast` | clear,clear,cloudy,rain,clear,storm | What the forecast draws from (repeat one to make it likelier) | | `persist` | false | Save day, hour, weather and look between sessions (world data) | ## With several players - **One source of truth.** The `WorldClock` sits on a synced entity. Its owner (the first player in, handed on when they leave) publishes a shared timeline twice a second along with three small records: the clock anchor, the weather fade and the sky look. Every player computes the hour, the sun, the fade and the lightning from those, so nothing drifts and nothing per-frame crosses the network. - **Late joiners** receive the records and the latest shared time, snap to it, and see exactly what everyone else sees: the same hour, the same half-faded storm. - **Lightning** is a schedule every machine derives from the same seed and the same shared time, so each strike flashes and thunders for everybody at the same moment (to within one network latency) without a message per strike. `Weather.strike()` sends one message that every machine plays. - **Anyone can change things.** `Weather.set`, `Sky.set`, `Clock.setTime` and the rest go straight to the record when called on the owner's machine and are forwarded to the owner from anyone else. - **Lamps** decide on/off from the shared sky on each machine, so every player sees the same lamps lit. - **Checking it.** `require("worldClockKit.probe").ask()` asks every player's machine what it computes: the hour at one agreed instant, the weather and its fade, the sky look, the lightning schedule, the strikes it showed, and how many lamps are lit. It returns the answers side by side with `agree` and a list of `problems`. Run it from a script or the console while two players are in the world. ## Living beside the engine's own sky and weather The kit uses the engine's height fog (`@builtin::systems.atmosphere`) and surface weather (`@builtin::systems.weather`) rather than its own, and drives the scene's existing directional and ambient lights. A scene that already has a `ProceduralSky` can keep it with `skyMode = "engine"` (the kit then sets its hour and leaves its look alone), or let the kit draw the sky with `skyMode = "kit"`. With `drivesLighting = false` and `skyMode = "off"` the kit only keeps time, weather, events and lamps. ## Performance Built for the browser at 30+ fps: the sky is one fullscreen pass; rain, snow and sand are one fixed 2,400-drop mesh wrapped around the camera (cost does not grow with the world); the kit writes a light or material value only when it changed; lamps write only while they fade. Each lamp style casts one or two shadowless point lights. When the clock starts, the kit draws rain, snow, sand and the lightning bolt once, invisibly, so the first storm does not stall while their GPU pipelines are built. Measured in a Chrome editor tab during a storm: 26-60 fps depending on what else shared the GPU; on desktop 43-67 fps. **Never a black sky.** Until the kit's sky shader has compiled, the kit shows the engine's own procedural sky in the kit's current colours, then switches over (`require("worldClockKit.director").skyFallback()` reads which is showing). **Lighting your own scenery.** The kit drives the scene's lights; your meshes need lit materials to follow them. A Model tint (`Model:setTint`) blends a flat colour over the lit result, so a heavily tinted floor looks the same at midnight as at noon. Colour scenery with a material's `base_color` instead (the gallery's `gallery/materials` are examples). ## Known limits Each is a platform limit the kit works around, linked to the open issue that tracks it in the engine's repository, [OrigoZero/zero](https://github.com/OrigoZero/zero). - **Shared time is the owner's, to one network latency** ([OrigoZero/zero#18604](https://github.com/OrigoZero/zero/issues/18604), no network-wide clock). Peers follow the owner's published timeline. Measured with two players 43 ms apart: the hour, weather fade and lightning schedule were identical at the same shared instant; a scheduled strike showed within 30-55 ms on the joining player, and a strike called with `Weather.strike()` (which travels to the owner and back) within about 0.2 s. - **Clock displays do not show in the browser editor's play mode** ([OrigoZero/zero#19380](https://github.com/OrigoZero/zero/issues/19380)). The browser editor keeps its own camera on screen in play, and that camera does not draw game UI. Displays show in the desktop editor and on the player page; the kit's sky, weather and lamps are unaffected. - **The sky shader can sit uncompiled after a branch switch and reload** ([OrigoZero/zero#19396](https://github.com/OrigoZero/zero/issues/19396)). The kit shows the engine's sky in its own colours until it compiles, so the sky is never black, but the kit's own look (clouds, toon bands, pixel dither, two suns) waits for the compile. - **The published player page lost its render device while loading** in Chrome on a machine also running the desktop editor ([OrigoZero/zero#19397](https://github.com/OrigoZero/zero/issues/19397)). Not reproduced elsewhere; the same world runs in the browser editor on that machine. ## By design - **One WorldClock per scene.** A second one stands by and logs why. - **Precipitation follows the camera.** It is drawn in a 26 m box around whoever is looking; distant rain is suggested by fog and cloud rather than drawn. - **Neon lettering** draws A-Z, digits, spaces and `!` as tubes; any other text falls back to a plain label. - **Browser audio** starts on the first click or key, as with all browser sound (see Soundstage). - **The clock follows real time.** Pausing the engine does not stop it; to stop time in your game, call `Clock.pause()`. ## What changed in 1.3.0 - Each known limit links the GitHub issue that tracks it in [OrigoZero/zero](https://github.com/OrigoZero/zero). ## What changed in 1.2.0 - Rain, wind, night and sandstorm beds play through the kit's own voices, rebuilt each play session. Before, a new session that followed a rainy one could go silent in a storm until clear weather had lasted about four seconds (Soundstage's ambience kept a voice from the session before). - New call: `Audio.sounding()`. - No long dashes left in the docs. ## What changed in 1.1.0 - Dawn holds its warm palette from just before sunrise to about an hour after (it used to blend into day by sunrise), and the dawn palettes are warmer through the whole sky, the sun and the fill light, not only at the horizon. Dusk, noon and night are unchanged. - Thunder is heard in every play session (it played only in the first). - Lamp parts use lit materials instead of tints, so lamp posts, arms and frames darken at night like the rest of the scene. - New calls: `Audio.onThunder`, `Director.frameStats`, `Director.skyFallback`, `Probe.drawState`, `Probe.note`, `Probe.notes`. The sky falls back to the engine's sky until the kit's shader compiles; rain, snow, sand and the bolt warm up at load. ## Tests `worldClockKitTests` covers every public call: the clock and its events, seasons, sun and moon; weather fades, storms and the lightning schedule; every sky look's night and noon levels; lamps, lettering and spawning; displays; the catalog; this README's version; and the multiplayer model (forwarded requests, timeline correction, a late joiner). Run it with `tools.use("tests", "run", { suite = "worldClockKitTests" })`. ## This world The world this package lives in is its gallery: a plaza with all six lamps, labels, a live time board, and controls to switch the sky look and weather and scrub the hour. Press play to watch a two-minute day go by. Version 1.3.0.