Crate boxcars

Boxcars

Boxcars is a Rocket League replay parser library written in Rust, designed to be fast and safe: 10-100x faster than established parsers. Boxcars is extensively fuzzed to ensure potentially malicious user input is handled gracefully.

A key feature of boxcars is the ability to dictate what sections of the replay to parse. A replay is broken up into two main parts: the header (where tidbits like goals and scores are stored) and the network body, which contains positional, rotational, and speed data (among other attributes). Since the network data fluctuates between Rocket League patches and accounts for 99.8% of the parsing time, one can tell boxcars to skip the network data or ignore errors from the network data.

• By skipping network data one can parse and aggregate thousands of replays in under a second to provide an immediate response to the user. Then a full parsing of the replay data can provide additional insights when given time.
• By ignoring network data errors, boxcars can still provide details about newly patched replays based on the header.

Boxcars will also check for replay corruption on error, but this can be configured to always check for corruption or never check.

Serialization support is provided through serde.

Below is an example to output the replay structure to json:

extern crate boxcars;
extern crate serde_json;
extern crate failure;

use std::fs::File;
use std::io::{self, Read};

fn run(filename: &str) -> Result<(), ::failure::Error> {
    let mut f = File::open(filename)?;
    let mut buffer = vec![];
    f.read_to_end(&mut buffer)?;
    let replay = boxcars::ParserBuilder::new(&buffer)
        .on_error_check_crc()
        .parse()?;

    serde_json::to_writer(&mut io::stdout(), &replay)?;
    Ok(())
}

Modules

attributes
crc

Structs

ActorId	An actor in the network data stream. Could identify a ball, car, etc. Ids are not unique across a replay (eg. an actor that is destroyed may have its id repurposed).
CacheProp	A mapping between an object (that's an attribute)'s index and what its id will be when encoded in the network data
ClassIndex	A mapping between an object's name and its index. Largely redundant
ClassNetCache	Contains useful information when decoding the network stream
DebugInfo	Debugging info stored in the replay if debugging is enabled.
Frame	Contains the time and any new information that occurred during a frame
KeyFrame	Keyframes as defined by the video compression section in the wikipedia article, are the main frames that are derived from in the following frame data. The key frames decoded will match up with the frames decoded from the network data.
NetworkFrames	The frames decoded from the network data
NewActor	Information for a new actor that appears in the game
ObjectId	A replay encodes a list of objects that appear in the network data. The index of an object in this list is used as a key in many places: reconstructing the attribute hierarchy and new actors in the network data.
ParserBuilder	The main entry point to parsing replays in boxcars. Allows one to customize parsing options, such as only parsing the header and forgoing crc (corruption) checks.
Replay	The structure that a rocket league replay is parsed into.
Rotation	An object's current rotation
StreamId	A StreamId is an attribute's object id in the network data. It is a more compressed form of the object id. Whereas the an object id might need to take up 9 bits, a stream id may only take up 6 bits.
TickMark	In Rocket league replays, there are tickmarks that typically represent a significant event in the game (eg. a goal). The tick mark is placed before the event happens so there is a ramp-up time. For instance, a tickmark could be at frame 396 for a goal at frame 441. At 30 fps, this would be 1.5 seconds of ramp up time.
Trajectory	Contains the optional location and rotation of an object when it spawns
UpdatedAttribute	Notifies that an actor has had one of their properties updated (most likely their rigid body state (location / rotation) has changed)
Vector	An object's current vector

Enums

Attribute
CrcCheck	Determines under what circumstances the parser should perform the crc check for replay corruption. Since the crc check is the most time consuming check for parsing (causing microseconds to turn into milliseconds), clients should choose under what circumstances a crc check is performed.
HeaderProp	All the interesting data are stored as properties in the header, properties such as:
NetworkParse	Determines how the parser should handle the network data, which is the most intensive and volatile section of the replay.
SpawnTrajectory	When a new actor spawns in rocket league it will either have a location, location and rotation, or none of the above