0008: Keyframes
Status: Accepted. Item 1 extended by decision 0016 (a keyframe also starts the pregame) and decision 0026 (keyframes list lasting effects). How keyframes are checked is defined by decision 0037.
Context
The prototype is a pure event stream. To show the board at turn 9, a reader or viewer has to replay every event from the start of the game. Viewers need to jump straight to any turn (T1, T2, T3, ...). Recorders can also miss events (a source fails to report something, or recording starts late), and in a pure event stream every later state is then wrong with no way to recover.
Decision
- A keyframe is recorded at the start of every turn, before any of that turn's untap step actions. It is a full snapshot of game state from the perspective player's point of view: every object in every zone (hidden objects by instance ID only, following decision 0001), life totals and other player counters, permanents' tapped status, counters, and attachments, and the stack.
- Keyframes are checkable. The state produced by replaying events from one keyframe MUST equal the next keyframe. A mismatch makes the file invalid, unless an incompleteness marker covers the gap.
- Keyframes resync incomplete recordings. When a source misses events, the gap is marked as incomplete (principle 5) and the next keyframe restores the true state from the source.
Which state fields a keyframe contains, and its exact syntax, are defined in the spec.
Rules basis
Checked against the Comprehensive Rules effective 2026-09-25.
- 500.1: a turn consists of five phases in a fixed order, every turn. The start of a turn is a fixed, well-defined point for a keyframe.
- 502.1 to 502.3: the untap step's actions (phasing, day/night, untapping) are the first things that happen in a turn, so a keyframe taken before them shows the board exactly as the previous turn left it.
- 103.8: the starting player takes the first turn after the pregame procedure, so the turn 1 keyframe shows the hands kept after mulligans.
Alternatives rejected
- No keyframes. Rejected: jumping to a turn means replaying the whole game, and one missed event corrupts everything after it.
- Keyframes at every step or phase. Rejected: much longer files for little benefit. Turn-level jumps are what viewers need, and stack snapshots (decision 0007) cover the moments within a turn.
- Optional keyframes. Rejected: viewers could not rely on jumping to a turn, and resyncing would only work for some writers.
Consequences
- Files grow by one state block per turn.
- The spec must define the keyframe grammar and its state fields, and conformance fixtures must include a keyframe that does not match the events.