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:

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

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

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

Lamps: the WorldLamp component's style

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)

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

Weather: worldClockKit.weather

Sky: worldClockKit.sky

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

local Catalog = require("worldClockKit.catalog")
print(Catalog.forFamily("horror").skies)   -- { "eternalNight", "overcast" }

Diagnostics and sound

Events: Clock.on(name, fn) / Kit.on(name, fn)

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

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.

• Shared time is the owner's, to one network latency (OrigoZero/zero#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). 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). 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). 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.

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.