Expand description
§Boxcars
Boxcars is a Rocket League replay parser library written in Rust.
§Features
- ✔ Safe: Stable Rust with no unsafe
- ✔ Fast: Parse a hundred replays per second per CPU core
- ✔ Fuzzed: Extensively fuzzed against potential malicious input
- ✔ Ergonomic: Serialization support is provided through serde
See where Boxcars in used:
- Inside the rrrocket CLI app to turn Rocket League Replays into JSON
- Compiled to WebAssembly and embedded in a web page
- Underpins the python analyzer of the popular calculated.gg site
§Quick Start
Below is an example to output the replay structure to json:
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(())
}
The above example will parse both the header and network data of a replay file, and return an error if there is an issue either header or network data. Since the network data will often change with each Rocket League patch, the default behavior is to ignore any errors from the network data and still be able to return header information.
§Variations
If you’re only interested the header (where tidbits like goals and scores are stored) then you can achieve an 1000x speedup by directing boxcars to only parse the header.
- 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.
Modules§
Structs§
- 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).
- A mapping between an object (that’s an attribute)’s index and what its id will be when encoded in the network data
- A mapping between an object’s name and its index. Largely redundant
- Contains useful information when decoding the network stream
- Debugging info stored in the replay if debugging is enabled.
- Contains the time and any new information that occurred during a frame
- 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.
- The frames decoded from the network data
- Information for a new actor that appears in the game
- 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.
- 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.
- The structure that a rocket league replay is parsed into.
- An object’s current rotation
- A
StreamIdis 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. - 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.
- Contains the optional location and rotation of an object when it spawns
- Notifies that an actor has had one of their properties updated (most likely their rigid body state (location / rotation) has changed)
- An object’s current vector
Enums§
- The attributes for updated actors in the network data.
- Determines under what circumstances the parser should perform the crc check for replay corruption. Since the crc check is the most time consuming part when parsing the header, clients should choose under what circumstances a crc check is performed.
- All the interesting data are stored as properties in the header, properties such as:
- Determines how the parser should handle the network data, which is the most intensive and volatile section of the replay.
- When a new actor spawns in rocket league it will either have a location, location and rotation, or none of the above