What Should Drive What?

Use this guide when you are deciding whether a system should read Calendar Time, Godot's normal frame/physics delta, or a game-owned fixed-step authority such as a deterministic replay or lockstep loop.

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?

If it is a world-calendar fact, use a GameClock.
If it is input, camera, UI, particles, audio, or visual polish, use Godot.
If your game already has a fixed simulation loop or replay step, let that loop drive game logic and drive Calendar Time manually from that same 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 that follows time of day
crops, machines, cooldowns, or objects that age by game time
NPC schedules such as "shop opens at 09:00"
weather or seasons tied to date/time
festivals and calendar event days
save/load of the world's current time
offline progress based on elapsed game time

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 open/close tweens, button hover, cursor blink
particles, flashes, hit sparks, and other presentation-only effects
audio playback and music timing
normal Godot physics unless your whole game intentionally couples physics to game-calendar time
AnimationPlayer playback for cosmetic animation

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 — a deterministic replay, lockstep networking step, test harness, offline batch progression, or a custom fixed-step loop — that loop should remain the source of truth for simulation order.

Calendar Time can still participate, but it should be driven by that loop:

time_host.drive_mode= TimeHost.DriveMode.MANUAL

func run_fixed_step()-> void:
    # Your game-owned systems decide when one step happens.
    run_gameplay_step()
    time_host.drive_microseconds(16_667)# one 60 Hz calendar step

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: using Engine.time_scale to speed up your calendar.

Engine.time_scale affects the whole engine: physics, animation, audio, and callbacks. Use TimeHost.time_scale.delta_multiplier or GameClock.speed_multiplier for game-calendar pacing.

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.