GameObject Time Machine

This guide dives into every tunable option exposed by the GameObjectTimeMachine singleton so you can balance fidelity, memory, and designer workflow when building rewindable gameplay. In most cases you don't need to touch the inspector settings at all. Instead, everything is configured through the Crystal Save Settings or via manager classes such as the Time Travel Manager, RaceController, or NavmeshGhostManager.

How the Settings Are Applied

• Add it to a bootstrap scene manually for deterministic initialization.

• Inspector fields on the component mirror the data held in SnapshotRecorderSettings (Recording Settings) plus runtime controls such as playback behavior and ghost mode toggles.

• You can tweak the same values through code at runtime via GameObjectTimeMachine.Instance.Settings if you need per-level overrides or a custom options menu.

The following tables explain what every property does, when you want to turn it on, and when to steer clear of it.

Recording Settings (SnapshotRecorderSettings)

Setting	What it does	Use it when…	Avoid when…
Max Snapshots Per Object (maxSnapshotsPerObject)	Caps how many snapshots each tracked object keeps in memory.	You only need a short rewind window or have lots of tracked objects and want predictable RAM use.	You rely on long-form replays or deep debugging history—pruning will trim old data once the cap is hit.
Auto Prune (autoPrune)	Automatically removes the oldest snapshots when the cap is reached.	Designers should never see a "timeline full" error and you prefer the system to self-manage memory.	You intend to export or inspect full timelines offline—automatic pruning could delete data before you analyze it.
Use Delta Compression (useDeltaCompression)	Stores only the fields that changed between snapshots.	Most changes are incremental (movement, rotation) and you want the smallest save footprint.	Your custom components expect complete state dumps every frame—diff-based storage may omit context your tooling assumes.
Minimum Snapshot Interval (minSnapshotInterval)	Enforces a minimum time (seconds) between captured snapshots; 0 captures every frame.	Gameplay only needs updates a few times per second and you are fighting CPU or GC spikes.	High-speed action or physics debugging requires frame-accurate playback.
Max Memory Budget (MB) (maxMemoryBudgetMB)	Global memory ceiling for all snapshots; 0 disables the cap.	You ship to memory-constrained platforms or run large automated test suites simultaneously.	You already throttle per-object snapshots tightly and prefer not to sacrifice history when the budget is exceeded.
Record Unchanged Snapshots (recordUnchangedSnapshots)	Forces a snapshot even if nothing changed.	You need regularly spaced keyframes (for interpolation or syncing with external systems).	Memory is tight and you rely on delta compression to avoid redundant data.
Auto Tag Events (autoTagEvents)	Inserts tags at important lifecycle events (scene load, save, collisions, etc.).	Designers scrub timelines looking for big events and you want breadcrumbs automatically.	You prefer a pristine timeline for cinematic playback and already add manual tags.
Position/Rotation/Scale Change Thresholds	Ignore micro-movements until change exceeds these thresholds.	Floating-point jitter or animation noise is cluttering the timeline.	You are tracking precise puzzles (e.g., millimeter adjustments) and cannot lose fidelity.

Runtime Control Flags

Setting	What it does	Use it when…	Avoid when…
Recording Enabled (recordingEnabled)	Master switch that blocks or allows all recording; also exposed via SetRecordingEnabled/PauseRecording/ResumeRecording.	You need to temporarily pause capture during cutscenes, loading, or heavy simulation steps.	Animators expect to keep recording during timeline scrubs—remember to re-enable it afterwards.
Continuous Time Mode	Keeps timestamps advancing seamlessly even after pauses; initialized from the latest snapshot when enabled.	You pause/resume recording frequently but want interpolation to stay smooth without visible gaps.	You intentionally rely on real Time.time offsets (for syncing with external logs) and gaps are acceptable.
Time Scale Control (SetTimeScaleControl)	Optionally couples Time.timeScale to playback speed during timeline replays.	You want cinematics or debugging playback to respect slow-motion/fast-forward speeds automatically.	Other systems manage Time.timeScale and shouldn’t be overridden (e.g., multiplayer rollback or physics experiments).
Debug Flags (enableDebugLogs, showMemoryStats)	Emits verbose logs and memory counters to help diagnostics.	You are profiling snapshot churn, branch creation, or verifying new integrations.	Shipping builds where log spam or UI overlays are undesirable.

Playback Resume & Branching Behaviour

These options define how the timeline behaves once you stop playback and resume recording.

Playback Resume Mode

Mode	Behaviour	Best for	Avoid when…
Overwrite Mode	Resumes recording from the current scrub position, overwriting future snapshots.	Quick edits, QA workflows that mimic linear video timelines.	Designers expect to keep the original future intact as an alternative branch.
Auto Branch Mode	Spawns a new branch when you resume so the original future stays intact.	Narrative prototyping, QA comparisons, or any time you want “what-if” paths.	Memory budgets are strict and you cannot afford extra branches.
Continue From End	Jumps the object back to the last snapshot before recording, preserving continuity without branches.	Cinematics that must flow forward or gameplay with strict causality.	You explicitly want mid-timeline forks for alternate outcomes.

Auto Branch Behaviour

Controls what happens if auto-branching triggers while you are already on an alternative branch.

Option	Behaviour	Use it when…	Avoid when…
Overwrite Current Branch	Keeps a single alternative timeline and overwrites its future when resuming.	You want one clean “Alt” track to iterate on repeatedly.	Testers need to preserve multiple variations for comparison.
Continue Current Branch	Teleports back to the branch’s end before recording so the branch always grows forward.	Non-destructive polishing of a single alternative path.	You intentionally want to rewrite the future of the current branch from the scrub point.
Unlimited Branches	Creates Alt1, Alt2, Alt3… on every resume, preserving history.	Ghost racing, QA explorations, or puzzle design that benefits from archiving each iteration.	Memory budgets are tight or the UI becomes cluttered with branches.
Max Two Branches	Maintains Original + Alt1 only; Alt1 overwrites itself after the fork point.	Lightweight “good vs bad outcome” storytelling without branch sprawl.	You need more than one alternative at a time.

Branch Copy Mode

Defines how new branches inherit data when they are created.

Mode	Behaviour	Ideal scenario	Avoid when…
From Original	Copies snapshots from the Original branch up to the fork point.	Clean divergences where each branch represents a fresh what-if starting from the canonical timeline.	You want each branch to include previous alternative edits.
Accumulative	Copies from the parent branch, snowballing prior changes into descendants.	Ghost racing or investigative debugging where you track how each iteration changed the state.	Old mistakes shouldn’t contaminate future experiments.
Empty	Starts with no snapshots at all; records fresh from the branch point.	Memory-sensitive scenarios or branches that should capture only post-fork content.	You need immediate playback at the fork moment without re-recording baseline data.

Ghost Mode & Recording During Playback

allowRecordingDuringPlayback unlocks “ghost mode” where playback and recording happen simultaneously on different branches.

• When active, starting playback creates a fresh branch (ghostRecordingBranchName) while the current branch plays back, letting players race against previous attempts.

• Ghost mode only engages if your auto-branch behaviour supports multiple branches (Unlimited or Max Two). Otherwise the system falls back to the standard “stop recording before playback” flow.

• Disable the flag for most production builds so artists do not accidentally create hidden branches while scrubbing playback. Enable it deliberately for ghost racing, TAS tooling, or QA scenarios where simultaneous record/playback is the point.

Practical Tuning Tips

• Start with conservative limits (maxSnapshotsPerObject, minSnapshotInterval) in large scenes, then relax them on hero characters that need cinematic replays.

• Combine Continue From End with Continuous Time to keep animation curves smooth when designers constantly pause to inspect frames.

• Pair Unlimited Branches with Accumulative copy mode for time-trial ghost systems; each new attempt inherits the best-so-far run and you can compare branches quickly.

• Keep autoTagEvents on while iterating so you can spot save/load events instantly, then disable it for marketing captures to avoid tag clutter.

Armed with these guidelines you can pick the right knobs for prototyping, QA, and shipped builds without guessing how the Time Machine will behave under pressure.