Module clip 

Replay clipping: trim a boxcars::Replay down to a small, self-contained window of frames that still processes through the full ReplayProcessor pipeline unchanged.

Why this works

ReplayProcessor only consumes already-decoded boxcars::Frames plus a few static tables (net_version, objects, names). It never touches the replay bitstream. A ReplayClip therefore needs only those tables and a list of frames.

The catch is that the processor is fully incremental: the meaning of frame N depends on every actor spawned and every attribute set in frames 0..N. Naively slicing out frames[N..M] would reference actors that were never created. To fix this, a clip begins with a synthetic keyframe: a single frame that re-spawns every actor that is alive at the start of the window and re-emits each of its current attributes (reconstructed from ActorStateModeler). When the clip is processed, that keyframe seeds the processor’s world to exactly the state it had at the window boundary, after which the real frames replay normally.

Boundary artifacts and lead-in

The synthetic keyframe reproduces persistent actor state perfectly, but the processor’s per-frame updaters (touch detection, dodge detection, etc.) are delta-based and have no history before the keyframe. To keep the region you actually want to assert on clean, request a few frames of lead-in before it (see clip_replay_around). The differential tests quantify how much lead-in is needed for a faithful reproduction.

Structs

ClipProvenance

Where a ReplayClip came from in its source replay, for provenance and for mapping source frame indices back onto clip frame indices.

ReplayClip

A self-contained, serializable slice of a replay that can be processed by the full subtr-actor pipeline.

Constants

CLIP_VERSION

Current ReplayClip schema version. Bump on breaking layout changes.

Functions

clip_replay_around

Extract a clip centered on a region of interest [region_start, region_end], padded with lead_in warm-up frames before it and tail frames after.

clip_replay_around_times

clip_replay_around, but with the region of interest given in replay seconds instead of frame indices. Most event assertions are written against event times (which clips preserve from the source replay), so this is the usual entry point when migrating a full-replay test onto a clip.

clip_replay_range

Extract a clip spanning the inclusive source frame range [real_start, real_end].

frame_index_at_time

Index of the first frame whose time is at or after time (the last frame if every frame is earlier).