Advanced Host Integration

This guide shows the recommended ownership split when a host game integrates Calendar Time and needs save/restore compatibility across calendar-configuration changes.

Ownership split

Host simulation clock / pacing / pause / speed
    → Game-owned bridge (e.g. a ClockBridge node)
    → Calendar Time GameClock
    → plugin configuration fingerprint + lossless clock snapshot

Calendar Time owns:

• the calendar model (GameCalendar, years, months, TimeScale, time-of-day stages).
• the calendar instant (GameClock microseconds, epoch, DateTime).
• lossless clock serialization (GameClock.to_dict / from_dict).
• the canonical, versioned compatibility descriptor and fingerprint ([CalendarConfiguration]).

The host game owns:

• simulation tick cadence and wall-clock pacing policy.
• pause / speed policy.
• the game save envelope and any non-calendar state.
• composing the plugin fingerprint into its overall save schema.

Validating restore compatibility before mutation

A saved calendar instant is only meaningful when the authored calendar has not materially changed since the save was written. Use the plugin fingerprint to check compatibility before touching the live clock:

var saved_fingerprint:String = saved_state["calendar_config_fingerprint"]
if not CalendarConfiguration.is_compatible_with(saved_fingerprint, game_clock.calendar):
    push_error("Calendar configuration mismatch — refusing to restore saved clock.")
    return

# Only now is it safe to mutate the live clock.
game_clock.from_dict(saved_state["game_clock"])

This keeps the live clock untouched when the saved calendar is incompatible, instead of partially mutating it.

What the fingerprint covers

The fingerprint is stable for a given authored calendar. It changes only when a field shifts how an instant maps to dates or events. See [CalendarConfiguration] for the full semantic policy:

• Included (semantic): start date, week length, month structure, month names, time-of-day names and timings, event days.
• Excluded (display-only / runtime pacing): TimeScale.delta_multiplier, EventDay.icon, EventDay.accent_color.

Multi-clock hosts

When a host runs more than one clock, persist one fingerprint per clock alongside each clock's saved microsecond count. The fingerprint is per-calendar, not per-clock, so clocks sharing a authored calendar share a fingerprint.

Related

• Multi-clock Save Identity — clock_id resolution and atomic restore semantics.
• TimeScale and DriveMode — what the time scale owns and what it does not.