Time of day in your world (world.daynight) #

Readable offline: gripforge docs world-daynight, or the MCP tool gripforge_docs (topic world-daynight). The kit is also summarised in the family guide Environment of your world.

What it is for #

world.daynight is the clock of the world. It advances with the simulation time, publishes the hour, the day and the phase (dawn, day, dusk, night) and emits an event when they change. With world.lighting installed, it also moves the sun and the sky with the hour: a warm low sun at dawn and dusk, a white high sun at noon, a faint blue moon at night. The game decides what the time means (shops closing, enemies out at night); the kit only keeps the time.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "world.daynight" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "world.daynight",
                              config: { "dayMinutes": 12, "startHour": 7 } }

The kit requires game.engine. world.lighting is optional.

First example #

<!-- test: kits/game_engine/host/tests/world_daynight.rs::the_clock_turns_the_day_and_drives_the_lighting --> With dayMinutes 0.5 (a day lasts 30 seconds), startHour 23 and updateSeconds 0.5, the world starts in the night phase. After 90 ticks the day counter is 2, world.clock.text() answers 00:12, and world.lighting has switched to its custom preset with the night sun colour: the clock moved the sun through the lighting kit.

Settings and defaults #

Set driveLighting to false to keep your own look.

Services, events, variables #

• world.clock (service): hour() (0 to 24), day(), phase(), text() (such as 08:05), set(hour, day?), advance(hours), pause(on?), running(), speed(mult?) (a multiplier on the pace) and sky() (the sun and sky values of the moment). The clock is saved with the game.
• world.phase (event): { phase, hour, day }, the phase changed.
• world.hour (event): { hour, day }, a new hour began.
• world.day (event): { day }, a new day began, at midnight.
• world.hour, world.day, world.phase and world.time (variables): the hour, the day, the phase and the text of the time.
• set_time { hour, day? } and wait_hours { hours } (script actions): set the clock, or advance it (sleeping, waiting).
• phase_is { phase } and time_between { from, to } (script conditions): time_between holds for the hour in [from, to) and wraps past midnight when from is greater than to.
• clock (HUD view): the time, the day count and the phase.

Hooks and modding #

daynight.phase { phase, from, hour, day } is asked before the clock leaves the phase from for phase (time passing, set, advance, set_time, wait_hours; not at the start, not after a load). A tap may change hour: the clock jumps there, to the next day when that hour is not later than the current one, and the phase of that hour is announced without asking again. Cancelled, the clock goes back to where it was, and stops if time was passing; world.clock.pause(false) starts it again.

{ "id": "no_night", "hook": "daynight.phase", "match": { "phase": "night" }, "set": { "hour": 5.75 } }

A mod may override every setting above.

Engines #

The clock runs in the Rust kit host, on the web player and the native player. The HUD view is a web UI view.

When it does not do what you expect #

• The sun does not move: world.lighting is not installed, or driveLighting is false.
• The lighting preset changed to custom: the clock drives the individual fields; this is expected.
• The clock stopped: a daynight.phase tap cancelled a phase change while time was passing; call world.clock.pause(false).
• A phase hook is not asked at the start: the first publication and a load are never asked.

Limits #

No calendar beyond the day counter, no seasons and no weather: time of day only. Weather is the subject of world.weather.

Versions #

Kit 1.1.0. 1.1.0 added the daynight.phase hook and declared the settings moddable. The service world.clock is at 1.0.0.