TimeSnapshot — the in-memory save DTO for the runtime clock. Pure data: an identifier, a canonical integer microsecond count, and the DateTime derived from it. TimeSnapshot owns NO events, NO mutation API, and NO runtime/transition state. The runtime clock is the GameClock; events live on the GameClock's TimeSignalBus; time-of-day transition state belongs to DayNightCycleService. This type exists only so a game can persist and restore the exact clock instant. The host's TimeSnapshotSerializer uses this as its serialization shape: it writes the clock's current_microseconds into a TimeSnapshot, calls to_dict(), and on load reads from_dict() back into the clock. RefCounted, not Resource. TimeSnapshot never appears in the Inspector — it's an internal save-DTO constructed on save and consumed on load. There's no scene authoring, no .tres authoring, no inspector display. RefCounted (the lightweight base class) is the right fit; Resource (which extends RefCounted and adds inspector + asset serialization) would be over-spec.
Source: addons/calendar_time/game_time/state/time_snapshot.gd
Syntax
class TimeSnapshot extends RefCountedMembers
| Name | Kind | Summary |
|---|---|---|
serialization_id | Property | Identifier in serialized saves. Set during construction or by the serializer; not scene-authored. See Keys.SERIALIZATION_ID for the on-disk key name (the literal string `"time_state"` is the legacy 1.x dict-key identifier preserved for save migration — see `MIGRATION.md` §5 + `docs/internal/time-model.md`). |
calendar | Property | Optional calendar, used only by from_dict() to recompute date_time from a legacy game_seconds save that has no serialized DateTime. Not required for v3 saves (which serialize the DateTime directly). |
date_time | Property | The DateTime captured in the save. On v3 saves this is serialized directly; on legacy saves it is recomputed from game_seconds via the calendar. |
epoch | Property | Optional epoch reference. When set, this is the reference DateTime the clock was using at save time — saved alongside the canonical µs so `date_time()` (which is computed as `calendar.advance_date_time(epoch, ...)`) reconstructs the same calendar date after load. Without persisting the epoch, a clock with a custom epoch (e.g. year 1000 fantasy setting) would silently revert to the default epoch on load and produce wrong dates (issue #96). |
game_microseconds | Property | Canonical elapsed game time, stored as an exact integer count of game-microseconds. This is the source of truth that is persisted; everything else (game_seconds, derived dates) is computed from it. See docs/internal/time-model.md. |
game_seconds | Property | The elapsed game time in seconds — a float view of (and write-through to) the canonical game_microseconds. Convenience for callers that think in seconds. |
validate | Method | |
issues | Property | |
from_dict | Method | |
data | Property | |
to_dict | Method | |
dict | Property | |
SCHEMA_VERSION | Field | Bumped when an on-disk key changes shape. v2 stored the timestamp ID under the key "id"; v3 stores it under "serialization_id". |
SERIALIZATION_ID | Field | Schema v3 key. Written by to_dict(). |
DATE_TIME | Field | |
GAME_MICROSECONDS | Field | Schema v3 canonical clock: exact integer game-microseconds. |
GAME_TICKS | Field | Legacy clock keys. Read-only — from_dict() auto-migrates them to GAME_MICROSECONDS (seconds→µs, or whole-second ticks→µs). See MIGRATION.md §5. |
GAME_SECONDS | Field | |
EPOCH | Field | Schema v3+ epoch key. Persisted when the source clock had a non-default epoch. Optional — older saves (and clocks that never set a custom epoch) load with the default DateTime. |
LEGACY_ID | Field | Legacy v1/v2 key. Read-only — from_dict() auto-migrates it to SERIALIZATION_ID when no SERIALIZATION_ID is present. See MIGRATION.md §5. |
get_keys | Method |
Source
addons/calendar_time/game_time/state/time_snapshot.gd
Plugin docs root:gdscript/plugins/calendar_time_dev/docs