Boxcars

Boxcars provides a lower-level, more raw view of replay data compared to rattletrap. While rattletrap performs convenience conversions and produces larger JSON output, Boxcars omits these to remain lightweight and focused on parsing.

To derive information that rattletrap provides automatically, you can use the following patterns in Boxcars:

• To derive object_name: Access replay.objects[x.object_id]
• To derive name: Access replay.names[x.name_id]
• To derive attribute name: Access replay.objects[attribute.object_id]

Boxcars is extensively fuzzed against malicious input. To run the fuzzing suite, you must first install cargo-fuzz. The recommended scenario to run is no-crc-body, which fuzzed all aspects of the replay without a CRC check.

# Install cargo-fuzz
cargo install cargo-fuzz

# Run the recommended fuzzing scenario
cargo +nightly fuzz run no-crc-body

You can run the built-in benchmarks using cargo bench. To see if compiling for your specific CPU architecture provides performance improvements, use the target-cpu=native flag.

cargo bench

# For CPU-specific optimizations:
RUSTFLAGS="-C target-cpu=native" cargo bench

To parse a Rocket League replay file and output its structure as JSON, use the ParserBuilder to configure the parsing requirements. By default, Boxcars ignores errors in the network data (the body) to ensure you can still access header information even after a game patch. To require both header and network data to be valid, use the .must_parse_network_data() method.

use boxcars::{ParseError, Replay};
use std::error;
use std::fs;
use std::io::{self, Read};

fn parse_rl(data: &[u8]) -> Result<Replay, ParseError> {
    boxcars::ParserBuilder::new(data)
        .must_parse_network_data()
        .parse()
}

fn run(filename: &str) -> Result<(), Box<dyn error::Error>> {
    let filename = "assets/replays/good/rumble.replay";
    let buffer = fs::read(filename)?;
    let replay = parse_rl(&buffer)?;
    serde_json::to_writer(&mut io::stdout(), &replay)?;
    Ok(())
}

A TickMark represents a significant game event (like a goal) that is placed in the replay slightly before the event actually occurs to allow for ramp-up time.

Example: A tickmark at frame 396 might represent a goal occurring at frame 441.

pub struct TickMark {
    pub description: String,
    pub frame: i32,
}

The network data uses several distinct ID types to track entities:

• ActorId: Identifies a specific entity (e.g., a car or ball). Note that IDs can be reused if an actor is destroyed and a new one spawns.
• ObjectId: A unique identifier for an object in the replay hierarchy.
• StreamId: A compressed version of an ObjectId used within the attribute stream to save space.

A Frame represents a single point in time in the replay. It contains:

• time: The timestamp in seconds.
• delta: The time elapsed since the previous frame.
• new_actors: A list of NewActor objects that appeared this frame.
• deleted_actors: A list of ActorIds that were destroyed.
• updated_actors: A list of UpdatedAttribute objects representing property changes (like position or rotation) for existing actors.