TimeHost | Calendar Time Docs

Source note:This page rendered plugin-owned docs or generated metadata inside unified Astro docs shell.

TimeHost — Node; the engine→game bridge. Drives every clock in the clocks array each frame via the chosen drive_mode. Composes the save/load facade (ClockGroupSerializer) and one DayNightCycleService per clock in _ready. No clock ownership, no primary-clock concept. Drive modes (see DriveMode enum, docs/notes/timescale-and-drive-modes.md):

PROCESS (default): _process(delta) advances every clock from engine delta × time_scale.delta_multiplier with fractional-µs carry.
PHYSICS_PROCESS: _physics_process(delta) does the same on the physics tick. Use for games whose game-time calibration is locked to the physics frame rate (e.g. 60 Hz physics).
MANUAL: no automatic advancement. The game / test calls host.drive_microseconds(int) or host.drive_seconds(float) itself. Manual is the deterministic / replay / lockstep seam.

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

Syntax

class TimeHost extends Node

Members

Name	Kind	Summary
`clocks`	Property	Drive mode for automatic clock advancement. The default `PROCESS` is beginner-friendly and matches prior behaviour. `MANUAL` is the documented deterministic / replay path — see `docs/notes/timescale-and-drive-modes.md`. The clocks this host drives every frame. Designer-fillable: drag `clock.tres` files into this array. Runtime/static-registry auto-attach is legacy-compatible opt-in via `auto_attach_unbound_clocks`. Assigning or replacing this array at runtime (after `_enter_tree`) rebuilds the internal `ClockGroup` so driving, save/load, and the group serializer stay in sync (issue #193).
`auto_attach_unbound_clocks`	Property	Auto-attach any `GameClock` resource that was constructed at runtime (no Inspector binding) to this host in `_enter_tree`. Default `false` (issue #131): a production TimeHost only drives the clocks explicitly listed in the `clocks` array. This prevents runtime-created clocks (save previews, level transitions, test fixtures, editor-only scenes) from being silently attached to the host and driving it. The flag remains for backwards compatibility with the 1.x "drop a clock.tres anywhere and it just works" experience — set it to `true` in scenes that rely on that flow (the `getting-started` guide documents both paths). The static registry still tracks every GameClock for tooling (test setup uses `TestSetup.clear_all_clocks_for_tests()` to hermetic-isolate suites); this flag controls auto-attach, not the registry itself, and the registry now prunes on `NOTIFICATION_PREDELETE` so freed clocks don't leak into future hosts.
`time_scale`	Property	The time scale (delta_multiplier bridge from real seconds to game seconds, multiplied into the engine delta in PROCESS / PHYSICS_PROCESS drive modes). Distinct from `GameCalendar.time_scale`, which is the calendar's unit schema (seconds_per_minute / hour / day), not the rate. See `docs/notes/timescale-and-drive-modes.md`. Reassigning `time_scale` resets the pending fractional µs carry — the carry is computed under the current multiplier, so leftover carry from the previous multiplier would be applied under the new multiplier and produce a non-deterministic first tick (issue #101).
`drive_mode`	Property	Drive mode. PROCESS is the beginner default and matches prior `auto_increment_time = true` behaviour. MANUAL is deterministic. `auto_increment_time` is preserved as a backward-compatible alias — `auto_increment_time = true` ≡ `drive_mode = PROCESS`, `auto_increment_time = false` ≡ `drive_mode = MANUAL`.
`auto_increment_time`	Property	Backward-compatible boolean alias for `drive_mode`. `auto_increment_time = true` ≡ `drive_mode = PROCESS`, `auto_increment_time = false` ≡ `drive_mode = MANUAL`. Reads as the equivalent boolean for any pre-rename scenes / tests.
`group_serializer`	Property	The save/load facade. Composes time + age per clock and namespaces under the internal group's `save_key`. See `ClockGroupSerializer`.
`day_night_cycle_services`	Property	Day-night cycle services — one per clock, composed by the host in `_ready`. Each DNC reads `times_of_day` from its own clock's calendar (the calendar is the schema; TODs are part of the schema).
`dnc`	Property
`get_clock_group`	Method
`get_group_serializer`	Method
`load_state`	Method
`drive_microseconds`	Method
`drive_seconds`	Method
`multiplier`	Property
`delta_microseconds`	Property
`scale`	Property

Source

addons/calendar_time/game_time/state/time_host.gd

Plugin docs root:gdscript/plugins/calendar_time_dev/docs