GameClock

GameClock — the runtime clock consumers reference. A self-contained Resource holding the microsecond count, calendar, signal bus, serializer, and age service. date_time() is derived from the count via the calendar, so it is never stored and never stale.

Source: addons/calendar_time/game_time/state/game_clock.gd

Syntax

class GameClock extends Resource

Members

Name	Kind	Summary
ProjectionRange	Field	`ProjectionRange` is preloaded here to bound safe date projection.
current_microseconds	Property	The canonical clock value: an exact integer count of elapsed game-microseconds. Source of truth. Everything else (date_time, game_seconds) is derived from it. Not @export — it's runtime state, not authored data; saves go through TimeSnapshot.
speed_multiplier	Property	How fast this clock runs relative to the host's pacing rate. 1.0 is normal speed; higher values fast-forward this clock's timeline, and 0 (or any value at or below 0) pauses it. This is the per-clock rate: the final advance is engine delta × host time scale × this multiplier. It never touches `Engine.time_scale`. Watch `clock_speed_changed` to pause tweens/animations. Host-wide rate is `TimeHost.time_scale.delta_multiplier`; this field is the per-clock rate and the only field that affects this clock's advancement. While paused (`<= 0.0`) boundary events stop firing; UI that reads `clock.date_time()` directly is unaffected.
calendar	Property	The calendar that gives this clock its shape of time: months, days, event days, and the unit schema (seconds per minute / hour / day). Assign a `GameCalendar` resource. The bundled Four Seasons calendar is a good starting point; duplicate it to customize.
time_scale	Property	Advanced — per-clock pacing read by animation systems (flipper, emote bob, etc.). This does not change how fast this clock advances (see `speed_multiplier`); it is only a rate that animation consumers poll. The host propagates its own time scale here automatically, so you normally leave this unset.
epoch	Property	Optional start date for the clock's timeline. `date_time()` counts elapsed time forward from this date, so it becomes the in-game "day one". Leave it at the default to start from the calendar's own epoch.
persistent_id	Property	A stable UUID that identifies this clock in save files. Leave empty for a first clock; the system derives an id automatically. Assign one for clocks that must keep their saves across file renames or restructuring. Use the editor action "Calendar Time: Assign Persistent ID" (it assigns only when missing and saves the resource). Keep it stable: changing it breaks the link to existing saves. Duplicating a clock `.tres` copies the UUID; use "Regenerate Persistent ID" on the duplicate. Advanced — most projects never set this by hand.
clock_id_override	Property	Advanced — an explicit id for this clock used in save files. Leave it empty for automatic identity. Set it only when you need a fixed, readable id that survives file renames (for example, cross-project references). Most projects never touch this; the editor's persistent-ID actions are the supported way to manage identity.
signal_bus	Property	The clock event bus. Created eagerly so a consumer can subscribe the moment it holds the clock — before the host has finished _ready. The clock itself emits all clock-boundary events on this bus from `advance_microseconds`.
age_service	Property	The age service bound to this clock's time. Optional. Setter wires `age_service.clock = self` so the counter subscribes to this bus. Not @export — Godot cannot resolve a custom Resource @export here. Assign from the clock `.tres` or at runtime; the setter still wires `clock = self`.
time_snapshot_serializer	Property	The clock's own time serializer (constructed in _init; self-wired).
age_registry	Property	The clock's own age registry. Each `GameClock` carries its own `AgeStateRegistry` so age state is hermetically scoped to the clock: `AgeService`s and `AgeComponent`s attached to this clock read/write here. No process singleton — two clocks can run side-by-side without seeing each other's age states. Constructed in `_init`; lifetime matches the clock resource.
clock_id	Property	Stable id used by ClockGroupSerializer for save/load identity. Lazy-derives from `clock_id_override` → `persistent_id` → resource_path → a monotonic counter (see `_derive_clock_id` for the exact priority chain). Once resolved, the value is cached — re-deriving only happens if `persistent_id` or `clock_id_override` is reassigned, which clears the cache. Priority chain: 1. `clock_id_override` (explicit designer label) — durable across sessions. 2. `persistent_id` (authored UUID) — durable across renames, restarts, machines. 3. `resource_path` hash — durable when the same `.tres` is shipped. 4. Runtime counter — session-local; not durable across process restarts.
assign_persistent_id	Method
regenerate_persistent_id	Method
advance_microseconds	Method
advance_through_microseconds	Method
advance_scaled_microseconds	Method
progress_time	Method
advance_to_next_day	Method
publish_current_state	Method
publish_state_loaded	Method
get_time_snapshot_serializer	Method
to_dict	Method
from_dict	Method
date_time	Method
game_seconds	Method