Day-Night Cycle

A day-night cycle is one clock for the whole world. Real seconds turn into hours, and the hour decides how bright it is and whether it is night, dawn, day or dusk. Scheduled events fire once each time the clock passes their hour, even in a big step or during sleep. The player can pause and sleep until sunrise.

Also called: Time of day, World clock, Day and night.

A plump hedgehog in a yellow oilskin coat stands on a stone jetty at the turn from night to morning: the sky is deep blue on one side and apricot gold on the other, half the village lamps are still glowing and a baker's shutter swings open. — Dabbledawn Quay, an invented harbour village game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Day-Night Cycle" to my game.

What it should do: A world that changes with the hour feels alive: shops open and close, danger comes with the dark, and the player plans around the time. One clock drives all of it, so light, events and sleep can never disagree.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> day
  day: Day
  dusk: Dusk
  night: Night
  dawn: Dawn
  day --> dusk: the sun goes down
  dusk --> night: sunset
  night --> dawn: sunrise or sleep
  dawn --> day: the light is full
```

Use these starting values:
- dayLength: 600 seconds
- sunrise: 6 hour
- sunset: 20 hour
- twilight: 1.5 hours

Watch out for these common mistakes:
- Events skipped by a big step: Tell your AI: fire an event when the clock passes its hour, looking at where it was and where it is now, and let sleep move the clock the same way a tick does.
- Counting the day at the wrong moment: Tell your AI: count a day at midnight only, and have sleep count it like any other pass of midnight.
- Dawn and dusk longer than the day: Tell your AI: cut the twilight to half of the daylight hours when the day is too short for both.
- A long stall: Tell your AI: limit one step to a day, so a stall moves the clock by at most 24 hours and the game carries on from there.
- The clock runs behind a menu: Tell your AI: pause the clock while a menu is open, and ignore sleep while it is paused.
- Landing exactly on an hour: Tell your AI: an event fires when its hour is after the old time and at or before the new one. That covers landing on it exactly, and an event at the starting hour waits until tomorrow.
- Light that jumps: Tell your AI: ease the light across the whole twilight instead of switching it.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

A world that changes with the hour feels alive: shops open and close, danger comes with the dark, and the player plans around the time. One clock drives all of it, so light, events and sleep can never disagree.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Day → Dusk: the sun goes down
Dusk → Night: sunset
Night → Dawn: sunrise or sleep
Dawn → Day: the light is full

Good starting values

Value	Start with	What it changes
dayLength	600 seconds	Real time for a whole day. Ten minutes is long enough to get things done in daylight and short enough that the player sees dusk fall in one sitting.
sunrise	6 hour	The hour dawn starts. Before it, and after sunset, it is night.
sunset	20 hour	The hour night starts. A long summer evening or a short winter one is just a different number here.
twilight	1.5 hours	How long dawn and dusk each last. Long enough for the light to fade in slowly, short enough that most of the day is plain daylight.

What usually goes wrong

Events skipped by a big step

If an event only fires when the clock shows exactly its hour, a lag spike or a night's sleep jumps over it and the market never opens.

Fix: Tell your AI: fire an event when the clock passes its hour, looking at where it was and where it is now, and let sleep move the clock the same way a tick does.

Counting the day at the wrong moment

Counting a new day at sunrise makes sleeping before midnight and after midnight count differently, and a player can gain or lose a day.

Fix: Tell your AI: count a day at midnight only, and have sleep count it like any other pass of midnight.

Dawn and dusk longer than the day

A short day with long twilights makes dawn and dusk overlap, and the light jumps or goes below zero.

Fix: Tell your AI: cut the twilight to half of the daylight hours when the day is too short for both.

A long stall

After a loading screen or a window put in the background, the next step can be minutes long and carry the clock through whole days.

Fix: Tell your AI: limit one step to a day, so a stall moves the clock by at most 24 hours and the game carries on from there.

The clock runs behind a menu

If the clock keeps going while a menu is open, the player comes back to a different time of day, or a night they did not choose.

Fix: Tell your AI: pause the clock while a menu is open, and ignore sleep while it is paused.

Landing exactly on an hour

An event on the starting hour fires at once, or never, and one that the clock lands on exactly can be counted twice.

Fix: Tell your AI: an event fires when its hour is after the old time and at or before the new one. That covers landing on it exactly, and an event at the starting hour waits until tomorrow.

Light that jumps

Switching the light at the edge of dawn or dusk makes the screen blink from dark to bright.

Fix: Tell your AI: ease the light across the whole twilight instead of switching it.

How to check it works

A day lasts 600 seconds and it is 8 o'clock. 25 seconds pass: It is 9 o'clock.
It is half past 11 at night. One hour passes: It is half past midnight and the day count is one higher.
Sunrise at 6, sunset at 20 and 1.5 hours of twilight. You look at 3, 6, 7.5, 18.5 and 20 o'clock: They are night, dawn, day, dusk and night.
The default day. You look at 2 in the morning, noon and 9 in the evening: The light is 0, 1 and 0.
The default day. You follow the light from 6 to 7.5 o'clock: It rises without jumps and is exactly half at 6:45.
A market that opens at 8 and the clock at 7:30. The clock moves past 8, then on: The market opens exactly once.
Events at 8, 19:30 and midnight, and the clock at 7. One step moves the clock 18 hours: All three fire, in the order the clock passed them.
A paused clock at 7:54, just before an event at 8. Five hours of real time go by, then the clock resumes: The time stays 7:54 and the event fires only after the clock runs again.
It is 10 at night. The player sleeps: It is 6 in the morning, the day count is one higher and the midnight event has fired.
It is 3 in the morning. The player sleeps: It is 6 in the morning and the day count is the same.
It is noon. The player tries to sleep: Nothing changes.
A day of 60 seconds, and another of 3600 seconds. 2.5 seconds pass in the first and 150 in the second: The clock moves one hour in both.

Works well with

Hunger and Thirst: Sleeping through the night should cost food and drink for the hours that passed, or the player sleeps to dodge hunger. Let the clock move first, then drain the meters by the same amount of time.
Enemy Patrol and Chase: Nights are the easy place to hide danger. Change the guards' sight with the light value, not with a hard switch at sunset. Read the part of the day first, then pick how far guards see and how many patrol.
Daily Rewards: Mixing the two lets a player collect twice in a row by sleeping, or lose a reward to a long night. Decide whether a day for rewards is the game's midnight or the player's real calendar day.

Common questions

how do i add a day and night cycle to my game

Keep one clock in hours and work out the light and the part of the day from it, never separately. Ten real minutes per day is a good start. Ease the light across dawn and dusk instead of switching it.

how do i make events happen at a certain time of day

Fire an event when the clock passes its hour, comparing the old time with the new one, not when the clock shows exactly that hour. Then a lag spike or a night's sleep cannot skip it. Tell your AI to fire it once per pass.

what happens to events when the player sleeps

They should still happen. Sleeping is just a big step of the clock, so move the clock the normal way and let everything scheduled in between fire in order. Count the day at midnight so sleep before or after midnight gives the same result.

what do i tell my ai to add a day and night cycle

Paste this: Add a day-night cycle. One clock in hours, 600 real seconds per day, sunrise at 6 and sunset at 20 with 1.5 hours of dawn and dusk. Work out light and the part of the day from the hour. Fire scheduled events when the clock passes their hour, even in a big step. Count a day at midnight, pause the clock in menus, and let the player sleep only at night, jumping to sunrise.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

25 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it