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	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: any value `<= 0.0` pauses this clock. `advance_scaled_microseconds` returns early, so boundary events stop while paused. UI consumers that read `clock.date_time()` are not gated here. Watch `clock_speed_changed` to bridge pause to tweens and animations.
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.
persistent_id	Property	Authored persistent identity for save/load. Empty by default; resolved lazily via `clock_id`. When non-empty, this is the second-highest-priority source for `clock_id` identity (after `clock_id_override` but before `resource_path` and the runtime counter). Assign once via `assign_persistent_id()` (editor action or script). Leave it stable — changing it silently breaks the link to existing saves. Unlike `resource_path` (which changes on file rename, project restructure, or cross-machine copy), a `persistent_id` is a UUID. It survives renames, restructuring, process restarts, and cross-machine use. Duplicating a resource copies its UUID; duplicate IDs are detected and can be regenerated. `ClockGroupSerializer` stores this alongside `clock_id` in per-clock save entries and detects duplicates within a host's clock group. Runtime-only clocks (no `.tres` file) may call `assign_persistent_id()` for durable persistence across process restarts. Clocks without a `persistent_id` fall back to the documented `clock_id` resolution chain.
clock_id_override	Property	Stable identity for save/load (legacy explicit override). Empty by default; resolved lazily via `clock_id`. Uses resource_path hash when loaded from a file, else a runtime counter. `ClockGroupSerializer` keys per-clock save data by this id, not array index. Two clones of the same `.tres` share an id automatically. Different `.tres` files always differ. Two `GameClock.new()` calls get distinct counter ids. Override `clock_id` for explicit cross-machine 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 (issue #424): 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