What Should Drive What?

Use this guide when deciding whether a system should read Calendar Time, Godot delta, or a game-owned fixed step.

Beginner rule

Ask one question first:

Is this a fact about the simulated world calendar, or is it just how the game feels on screen right now?

World-calendar fact → use a GameClock.
Input, camera, UI, particles, or audio → use Godot.
Fixed simulation or replay loop → drive Calendar Time manually from that step.

Use Calendar Time as the source of truth

Calendar Time should be the authority for systems that mean "what time is it in the game world?"

Common examples:

Date and time-of-day displays.
Day/night phase changes.
Sun, moon, or ambient lighting tied to time of day.
Crops, machines, cooldowns, or objects that age by game time.
NPC schedules such as shop hours.
Weather, seasons, festivals, and event days.
Save/load of world time and offline progress.

Example: lighting should usually read the clock. Sunset at 19:00 is a world rule, so the sun angle and color should derive from clock.current_date_time, clock.signal_bus.time_of_day_changed, or a Calendar Time lighting component. Godot still renders the light every frame, but Calendar Time decides what the light should represent.

Use Godot directly

Godot's delta, _process, _physics_process, tweens, animations, and audio should stay in charge of things that are about immediate presentation or engine behavior.

Common examples:

Player input responsiveness.
Camera smoothing and screen shake.
UI tweens, button hover, and cursor blink.
Particles, flashes, and presentation-only effects.
Audio playback and music timing.
Normal Godot physics unless you couple physics to calendar time.
Cosmetic AnimationPlayer playback.

Example: an inventory panel sliding open should not wait for the world clock. Use a Godot tween so it still feels responsive when game time is paused.

Drive Calendar Time from a game-owned fixed step

If your game owns a fixed or replayable simulation step, that loop stays the source of truth for order.

Calendar Time should be driven from that loop, not the other way around.

For the MANUAL mode API and fixed-step examples, see TimeScale & DriveMode.

This means:

Your fixed-step loop decides when systems run.
Calendar Time records the world calendar for that step.
Calendar events can influence systems, but the clock does not become the scheduler for the rest of your game.

Use this pattern for deterministic replay, lockstep multiplayer, offline batch progression, or tests that must advance one exact step at a time. An ECS may call the same manual API, but it is only one possible caller.

Quick decision table

System	Best source	Why
Date/time UI	`GameClock`	It displays world time.
Day/night lighting	`GameClock`	Lighting represents a calendar fact.
Crop growth	`GameClock`	Growth is based on elapsed game time.
NPC shop schedule	`GameClock`	Schedule is based on time of day/date.
Camera follow smoothing	Godot `delta`	It is presentation feel.
Inventory/menu animation	Godot tween/`delta`	UI should stay responsive when world time pauses.
Hit sparks / particles	Godot `delta`	Visual effect, not world calendar state.
Physics body integration	Godot physics tick	Godot owns normal physics stepping.
Game-owned fixed-step systems	Fixed-step sim tick	Your loop owns ordering and determinism.
Lockstep replay clock	Manual `drive_microseconds()`	Same integer input gives the same plugin timeline.

Common mistakes

Mistake: speeding up only the camera (or one actor) to "fast-forward".

Do not raise camera move speed to simulate a faster world. In production, change the root engine tick instead. That usually means Engine.time_scale (or your game-owned root step). Physics, presentation delta, and every GameClock on automatic drive then advance together.

Mistake: using one clock speed for both planet length and sim speed.

Different planets can use different calendars or clocks. A longer day is a calendar fact. Keep that on GameCalendar.time_scale or a per-clock rate. When you want the whole simulation faster, change the root engine tick. Relative day lengths stay the same. Everything still scales equally.

Mistake: using Engine.time_scale when you only meant the calendar.

Engine.time_scale scales the whole engine. Physics, animation, audio, and callbacks all change. If only world-calendar pacing should change, use TimeHost.time_scale.delta_multiplier or GameClock.speed_multiplier.

Mistake: letting Calendar Time drive your game's system order.

Calendar Time tells you what the calendar says. Your game-owned fixed-step loop should still decide which systems run and in what order. In deterministic games, set the host to MANUAL and drive it from that loop.

Mistake: driving UI polish from the game clock.

If a menu should animate while the game is paused, use Godot tweens or raw engine delta, not the clock.

Mistake: binding every demo actor to the calendar clock.

The shipped 2D demo keeps world facts on GameClock. Lighting, ageing, date events, and UI stay there. Presentation motion uses Godot delta. See Clock-Driven Animation Pattern for the optional "freeze with world time" recipe.

Multi-clock worlds vs root sim speed

Use multiple clocks when timelines are structurally different.

Example: Earth and a slow-day colony each get a GameClock. Day length lives in each calendar's unit schema. Shop hours and lighting follow that clock.

Use the root engine tick when the whole session should run faster or slower.

At 2× root tick, both planets' days still keep their relative lengths. Walk speeds, tweens, and clock advance all move together. That is the production fast-forward pattern.