Crate boxcars

Source

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§

attributes
crc

Structs§

ActiveActor
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).
AppliedDamage
CacheProp: A mapping between an object (that’s an attribute)’s index and what its id will be when encoded in the network data
CamSettings
ClassIndex: A mapping between an object’s name and its index. Largely redundant
ClassNetCache: Contains useful information when decoding the network stream
ClubColors
DamageState
DebugInfo: Debugging info stored in the replay if debugging is enabled.
Demolish
DemolishExtended
DemolishFx
Explosion
ExtendedExplosion
Frame: Contains the time and any new information that occurred during a frame
FrameContext
Impulse
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.
Loadout
LoadoutsOnline
LogoData
MusicStinger
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.
Pickup
PickupInfo
PickupNew
PrivateMatchSettings
Product
Ps4Id
PsyNetId
Quaternion
RepStatTitle
Replay: The structure that a rocket league replay is parsed into.
ReplicatedBoost
Reservation
RigidBody
Rotation: An object’s current rotation
StatEvent
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.
SwitchId
TeamLoadout
TeamPaint
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
UniqueId
UpdatedAttribute: Notifies that an actor has had one of their properties updated (most likely their rigid body state (location / rotation) has changed)
Vector3f
Vector3i: An object’s current vector
Welded

Enums§

Attribute: The attributes for updated actors in the network data.
AttributeError
CrcCheck: 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.
FrameError
HeaderProp: All the interesting data are stored as properties in the header, properties such as:
NetworkError
NetworkParse: Determines how the parser should handle the network data, which is the most intensive and volatile section of the replay.
ParseError
ProductValue
RemoteId
SpawnTrajectory: When a new actor spawns in rocket league it will either have a location, location and rotation, or none of the above

Crate boxcarsCopy item path