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
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	Authoritative per-clock runtime speed multiplier. Applied by `advance_scaled_microseconds()` when TimeHost or ClockGroup drives this clock. This is the only field that affects clock advancement rate. Host-wide rate is `TimeHost.time_scale.delta_multiplier`. Per-clock rate is `GameClock.speed_multiplier`. Final formula: clock_delta = engine_delta × host_multiplier × clock_multiplier Pause/resume semantics: any value `<= 0.0` pauses this clock. `advance_scaled_microseconds` returns early, so clock-boundary events stop firing while paused. UI/animation consumers that read `clock.date_time()` directly are intentionally not gated here — if a game wants to also freeze presentation, it does that with its own time-scale or by watching `clock_speed_changed` and pausing its own tween/animation systems. The `clock_speed_changed` signal is emitted on every actual change (including pause and resume), so observers can bridge the clock's pause to their own runtime state without polling.
calendar	Property	The calendar that defines the shape of time (months, days, event days) and the date math + rate (calendar.get_scale()). Authored on the clock resource.
time_scale	Property	Per-clock time scale for animation consumers (flipper, emote bob, etc.). Animation systems poll `clock.time_scale.delta_multiplier` to convert real-time intervals into game-time intervals. This field does NOT affect clock advancement — `advance_scaled_microseconds()` reads `speed_multiplier` only. Leave unset when no per-clock animation consumer needs the rate. TimeHost propagates its own `time_scale` to this field so animation consumers get a consistent rate without each one reaching for the host.
epoch	Property	Optional reference date used as the zero-point for date_time derivation. date_time() returns calendar.advance_date_time(epoch, elapsed_seconds). Leave unset to use DateTime.new(), the calendar epoch fallback.
clock_id_override	Property	Stable identity for save/load. Optional — empty by default; resolved lazily via `clock_id` to a hash of resource_path (when the resource is loaded from a file) plus a deterministic runtime counter fallback. Used by `ClockGroupSerializer` to key per-clock save data instead of array index, so reordering the host's clocks between save and load doesn't cross-pollinate state. Two clones of the same `.tres` get the same id automatically (no user typing required). Different `.tres` files always get different ids. Two `GameClock.new()` calls (no resource_path) get distinct ids from a monotonic counter. Override `clock_id = "..."` for explicit stable cross-machine identity (e.g. to dedupe clocks that share a resource_path across multiple instances).
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 clock's bus. Not @export — the Godot parser fails to resolve a custom-Resource @export on a Resource when the two classes live in the same plugin folder (forward-reference parse order). The game assigns this from the clock .tres (plain property write) or at runtime; the setter still wires `clock = self` so the counter subscribes correctly.
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` → 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 `clock_id_override` is reassigned, which clears the cache.
path	Property
seed	Property
seed_str	Property
h	Property
advance_microseconds	Method
bus	Property
old_dt	Property
new_dt	Property
seconds_advanced	Property
days_between	Property
new_event	Property
old_event	Property
advance_scaled_microseconds	Method
progress_time	Method
advance_to_next_day	Method
old_dt	Property
target_dt	Property
delta_seconds	Property
publish_current_state	Method
dt	Property
publish_state_loaded	Method
get_time_snapshot_serializer	Method
to_dict	Method
from_dict	Method
date_time	Method
game_seconds	Method