# 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](guide:world-environment).

## 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

```text
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

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `dayMinutes` | number (0.5 to 1440) | `24` | real minutes one game day lasts (24 means one game hour a minute) |
| `startHour` | number (0 to 24) | `8` | the hour of day 1 at the start |
| `sunrise` | number (0 to 12) | `6` | the dawn hour |
| `sunset` | number (12 to 24) | `19` | the dusk hour |
| `running` | boolean | `true` | the clock runs from the start |
| `driveLighting` | boolean | `true` | move the sun and the sky through `world.lighting`; its preset becomes `custom` |
| `updateSeconds` | number (0.2 to 30) | `2` | seconds between two lighting updates |

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.

```json
{ "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.