Skip to content

Time and Clocks ​

Reuse Time, WorldHost, and TimerWheel, separating duration measurement, simulation order, and display time without another synonymous clock service.

Executive summary ​

Use monotonic time for durations and timeouts, ticks for simulation order, and wall time for readable records. Cross-process authority uses epochs, sequences, and durable records rather than comparing machine clocks.

1. Current implementation ​

ComponentResponsibility
apollo::base::TimeMonotonic readings, wall time, and formatting helpers
WorldHostFixed steps, injected monotonic source, bounded catch-up, and dropped_ticks
WorldTickContexttick_index, delta_seconds, and local monotonic instant
apollo::base::TimerWheelSingle-writer wheel advanced by caller-supplied monotonic milliseconds

The example GameClockService is an assembly demonstration, not a delivered framework clock facade.

2. Three time domains ​

TimePurposeRestriction
steadyDurations, timeouts, backoff, budget refillNot a comparable cross-machine timestamp or deterministic gameplay input
tickInput attribution, simulation order, replayInterpreted within its process/activity; independent World ticks are not comparable
wallLogs, audits, presentation, reportsNot timeout arithmetic or authority ordering

Do not format a steady-clock epoch value as a real wall-clock date.

3. Fixed steps ​

WorldHost defaults to 10 Hz. WorldApp defaults tickRateMs to 50, or 20 Hz. These are defaults at different configuration entry points, not two simultaneous simulation schedules.

WorldHost catches up at most 5 steps per call and records excess backlog as dropped_ticks, avoiding unbounded catch-up. Constructor injection supports deterministic clock tests. State the actual tick configuration in capacity evidence.

4. Pause and execution boundaries ​

Distinguish paused simulation, stopped admission, and process shutdown. Heartbeats, admission, drain, and async completion during a pause require explicit application policy. Stopping ticks alone does not establish availability.

Script commits, input consumption, and background completion run at the owning logic boundary. Completion timing cannot change a finished tick's decisions.

5. Client time ​

Client timestamps support presentation, interpolation, and defined experience policies. Server authority determines execution order. Client-reported time does not grant write authority or permission to rewrite history.

6. Cross-World ordering ​

Worlds keep independent clocks. Transfers use process incarnation, player authority epoch, transfer identity, and conditional directory commit. Timeout triggers reconciliation; it does not prove absent destination commit or authorize source writes automatically.

7. Logs and persistence ​

Logs include wall/tick context. Journal sequences, settlement IDs, and authority epochs provide recovery and idempotency. Readable timestamps cannot replace them. Local ticks may restart; business order across restart needs durable evidence.

8. Timers ​

The owning thread calls TimerWheel.advance(now_ms). The wheel does not read OS time or create threads. Defaults are 10 ms precision, 64 slots per level, and 5 levels; hosts choose appropriate configuration.

Schedule/cancel and callbacks follow single-writer ownership. Callbacks can schedule/cancel other work but cannot reenter advance. Object destruction must cancel related work or validate object generations before callbacks touch an expired Instance.

The current API uses monotonic milliseconds, not World tick IDs. Hosts must choose and convert explicitly and validate pause/catch-up semantics.

10. Acceptance ​

Validate injected clocks, zero-instant startup, fixed steps, catch-up limits, dropped ticks, backwards input, and cancellation. Test reconnect, drain, and transfer with independent clocks instead of using similar local timestamps as protocol evidence.

Released under the MIT License