Timeline

namespace Griff.Runtime;

public sealed class Timeline

Rewind for play mode: keeps periodic snapshots of the running scene so you can step back in time, inspect or tweak, and resume from there. A snapshot holds what a scene file does and restores as the file would load, but is kept in a compact binary form made without garbage; taken of a game (Record), it also holds what the game keeps besides (see IKeepsState), and Restore puts the game itself back. Taking one is split in two so the game’s steps pay for as little of it as they can: between two steps, every entity’s values are copied out at once (its record), which is little more than reading them; then, on another thread (it reads nothing but the copies), each record is compared with the entity’s record in the last snapshot and kept as just the bytes that changed (next to nothing for an entity that didn’t change), with every tenth snapshot kept whole. Big scenes are snapshotted less often, so the snapshots stay within MemoryBudget and still reach as far back, and (with a CostPerStep) so copying them out doesn’t slow the game.

Properties

Bytes

public long Bytes { get; }

Memory the kept snapshots take, in bytes, once they’re settled (see Complete).

CaptureTime

public TimeSpan CaptureTime { get; }

The time copying a snapshot’s values out takes, on average: the part a step waits for.

CostPerStep

public TimeSpan CostPerStep { get; init; }

The most time a step may spend copying snapshots out (CaptureTime), on average (none unless set): a scene that takes longer is snapshotted less often, though at least every MostStepsForTime steps. The editor sets it so a big scene keeps its frame rate while it plays: a snapshot is copied out between two steps, so a slow one makes that frame late, and few enough of them don’t show. (Settling them, SettleTime, is done on another thread.)

Count

public int Count { get; }

Snapshots kept, the newest included while it’s still being settled.

MemoryBudget

public long MemoryBudget { get; init; }

The most memory the snapshots may take (256 MB unless set). Snapshots of a scene too big for the capacity’s worth to fit are taken less often, so the timeline still reaches back as far; past it, the oldest go.

RememberBudget

public TimeSpan RememberBudget { get; init; }

The most a step may spend copying the scene out for Remember, on average (a quarter millisecond unless set): a scene that takes longer isn’t remembered between snapshots, and KeepRemembered falls back to the newest snapshot.

SettleTime

public TimeSpan SettleTime { get; }

The time comparing a snapshot with the last and keeping what changed takes, on average, on another thread.

Spacing

public int Spacing { get; }

Steps between snapshots now: the steps it was made with, or more for a big scene (see MemoryBudget).

Times

public IEnumerable<double> Times { get; }

Game time of each snapshot, oldest first.

Methods

Clear

public void Clear()

Complete

public void Complete()

Waits for the newest snapshot to be settled, and keeps it.

IndexOfSequence

public int IndexOfSequence(long sequence)

The index of the snapshot SequenceAt named sequence, or -1 once it’s gone.

KeepRemembered

public ValueTuple<int, bool>? KeepRemembered(int position)

The snapshot holding the moment the step under way started from (see Remember): one already kept, or the remembered copy, kept now as the newest snapshot (anything after position, the moment the game went on from, goes first: it’s another future). Its index, and whether it’s exactly that moment; without one (a scene too big to remember every step), the snapshot at position, the last before it. Null if there’s none.

Record

public bool Record(Game game, bool force = false)

Record for a running game: each snapshot also keeps what the game keeps besides its scene (its systems, clock, random numbers, timers and scripts’ own fields; see IKeepsState), so Restore puts the game itself back.

Record

public bool Record(Scene scene, double time, bool force = false)

Call once per step of the game. Takes a snapshot every Spacing steps (or now, with force) and drops the oldest past capacity. True if it took one (which is then also the moment Remember keeps).

Remember

public void Remember(Game game)

Remember for a running game, with what it keeps besides its scene.

Remember

public void Remember(Scene scene, double time)

Remembers the scene as it is between two steps (after a step that took no snapshot), so that if the next step goes wrong (a script throws), KeepRemembered can keep it as a snapshot: the moment just before that step. It’s copied out as a snapshot is, without settling it or keeping it unless asked; a scene too big to copy out every step (see RememberBudget) isn’t.

RememberSnapshot

public void RememberSnapshot(int index)

The next step starts from snapshot index (the game was just put back there).

Restore

public Scene Restore(int index)

A fresh scene in the state of snapshot index.

Restore

public Scene Restore(int index, Game game)

Puts game back as it was at snapshot index (taken with Record): in a fresh scene in that snapshot’s state, with everything the game kept besides its scene as it was (its systems, clock, random numbers, timers, tweens, coroutines and scripts’ own fields), so it goes on from there just as it did. Returns the scene.

SequenceAt

public long SequenceAt(int index)

A number that names snapshot index for as long as it’s kept (indices move as the oldest go).

TimeAt

public double TimeAt(int index)

TruncateAfter

public void TruncateAfter(int index)

Forgets everything after index, so resuming from it starts a new future.

Fields

DefaultRememberBudget

public static readonly TimeSpan DefaultRememberBudget

A quarter millisecond: the RememberBudget unless set.

MostStepsForTime

public const int MostStepsForTime

The most steps CostPerStep spaces snapshots out to: 120, two seconds at 60 steps a second.