TimeSnapshot

TimeSnapshot — the in-memory save DTO for a GameClock's current state. Pure data: an identifier, a canonical integer microsecond count, and the DateTime derived from it. The save serializer writes the clock's current_microseconds here, calls to_dict() for storage, and on load reads from_dict() back into the clock.

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

Syntax

class TimeSnapshot extends RefCounted

Members

Name	Kind	Summary
serialization_id	Property	Identifier in serialized saves. Set during construction or by the serializer. 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).
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.
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.
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
saved_version	Property
saved_identity	Property
current_identity	Property
to_dict	Method
dict	Property
SCHEMA_VERSION	Field	Increment this when an on-disk key changes shape. v2 stored the timestamp ID under the key "id"; v3 stores it under "serialization_id". v4 adds schema_version and calendar_identity to the payload.
SCHEMA_VERSION_KEY	Field	Schema v4 key for the version number itself.
SERIALIZATION_ID	Field	Schema v3 key. Written by to_dict().
DATE_TIME	Field
GAME_MICROSECONDS	Field	Schema v3 canonical clock: exact integer game-microseconds.
CALENDAR_IDENTITY	Field	Schema v4 calendar identity. A deterministic fingerprint of the calendar configuration used to interpret elapsed microseconds. Mismatch on load produces a warning but does not block loading.
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	Read-only key carried over from v1/v2. from_dict() auto-migrates it to SERIALIZATION_ID when no SERIALIZATION_ID is present. See MIGRATION.md §5.
get_keys	Method