Godot Game Loop Time Trial

Architectural Thinking: The "Validation-Chain" Pattern

A Master implementation treats Time Trials as a State-Validated Sequence. Recording a time is easy; ensuring the player didn't cheat via shortcuts requires a strictly ordered CheckpointManager.

Core Responsibilities

• TimeTrialManager: The central clock. Validates checkpoint order and handles "Best Lap" logic.
• GhostRecorder: Captures high-frequency transform data. Uses delta-time timestamps for frame-independent playback.
• Checkpoint: Spatial triggers that notify the Manager.

Expert Code Patterns

1. Robust Checkpoint Validation

Prevent "Shortcut Cheating" by requiring checkpoints to be cleared in numerical order.

Wire Area body_entered (physics) → TimeTrialManager.pass_checkpoint(index). The manager owns usec timing — see script.

2. Space-Efficient Ghosting

Sample at a fixed rate (e.g. 10 Hz). Lerp position; slerp Quaternion rotation (ghost_recorder.gd / ghost_replayer.gd). Never Euler-lerp ghost heading.

Master Decision Matrix: Data Storage

NEVER Do

• NEVER use OS.get_ticks_msec() for ultra-precise race timing — Millisecond resolution is too coarse for high-end racing games. Use Time.get_ticks_usec() for microsecond precision.
• NEVER rely exclusively on _process() for finish line triggers — Visual frames can skip during lag. Always evaluate physical overlaps in _physics_process() to guarantee detection within the fixed physics step.
• NEVER evaluate Area3D overlaps immediately after instantiation — The physics server requires at least one physics frame to synchronize. await get_tree().physics_frame before checking for players.
• NEVER scale a CollisionShape3D on a checkpoint non-uniformly — This breaks the underlying SAT collision math. Always scale the internal shape resource (e.g., BoxShape3D.size) instead.
• NEVER use TCP (reliable) for syncing positions in multiplayer racing — Congestion algorithms cause huge spikes. Use ENetMultiplayerPeer with TRANSFER_MODE_UNRELIABLE for high-frequency position updates.
• NEVER trust client-side finish line/lap crossing — Always validate triggers on the authoritative server using multiplayer.is_server() to prevent cheating.
• NEVER use standard float equality (==) for record lap times — Use is_equal_approx() to account for precision loss in accumulated time variables.
• NEVER hardcode input checks without flushing the buffer — For frame-perfect boost/stop responses, call Input.flush_buffered_events() to ensure the engine has processed the latest raw input.
• NEVER allocate new Vector3 arrays inside fast path-following loops — This triggers the garbage collector. Use PackedVector3Array to maintain a contiguous memory block.
• NEVER use dynamic string paths ($"../Checkpoint") in tight loops — Lookups are slow. Use @onready to cache node references during initialization.
• NEVER record the whole player object for ghosts — Only record core transforms (position/rotation). Recording the whole object is memory-intensive and unnecessary for visual ghosts.
• NEVER give the ghost collision — It should be a purely visual indicator (e.g., semi-transparent) to avoid disrupting the player's line.
• NEVER neglect checkpoint sequencing — Don't just check if the player hit the finish line. Verify they passed every intermediate checkpoint in the correct order.
• NEVER use Area3D without monitoring optimization — Checkpoints should only look for the Player physics layer to minimize the number of physics overlap calculations.
• NEVER use standard lerp for ghost rotation — Use slerp() or Quaternion.slerp() to avoid gimbal lock and ensure smooth rotation interpolation.

---

Available Scripts

MANDATORY: Follow the golden path order. Read each listed script before coding that stage.

Golden path (MANDATORY)

1. time_trial_manager.gd — microsecond (Time.get_ticks_usec) or physics-frame clock; pass_checkpoint only from physics overlaps / Area signals
2. Checkpoint Areas — ordered indices into the manager (physics frame, not _process)
3. ghost_recorder.gd — samples {t, p, q} with Quaternion rotation
4. ghost_replayer.gd — position lerp + Quaternion slerp (never Euler lerp)
5. time_trial_leaderboard_bridge.gd — integer usec/msec → UI strings

Script index

time_trial_patterns.gd

10 Expert patterns: Microsecond timing, server-authoritative validation, rubber-banding AI, and frame-perfect input flushing.

time_trial_manager.gd

Central clock. Accumulates Time.get_ticks_usec() (or physics-frame counts). Finish checks must come from physics overlaps.

ghost_recorder.gd

Captures transform samples with Quaternion "q" fields for slerp-safe playback.

ghost_replayer.gd

MANDATORY with recorder. Replays samples via position lerp + Quaternion.slerp.

time_trial_playback_buffer.gd

Jitter-buffer for smooth ghost playback during network streaming.

time_trial_leaderboard_bridge.gd

Formatting utility for converting raw time data to human-readable strings.

---

Expert Time Trial Patterns

1. Delta-Compression for Ghosts

Store a keyframe only when position/rotation changes beyond a threshold. Persist with FileAccess.open_compressed() + ZSTD; prefer binary floats over JSON.

2. The Leaderboard Bridge

Store records as int usec/msec. Format with %02d:%02d.%03d for stable UI (e.g. 01:24.450).