{"id":13734826,"url":"https://github.com/nickbabcock/boxcars","last_synced_at":"2025-05-16T03:04:11.907Z","repository":{"id":11076151,"uuid":"68257211","full_name":"nickbabcock/boxcars","owner":"nickbabcock","description":"Rocket League Replay parser in Rust","archived":false,"fork":false,"pushed_at":"2025-04-05T13:15:18.000Z","size":90268,"stargazers_count":113,"open_issues_count":2,"forks_count":17,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-08T13:11:12.443Z","etag":null,"topics":["rocket-league","rust","serde"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/boxcars","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickbabcock.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-15T01:22:30.000Z","updated_at":"2025-04-05T13:15:23.000Z","dependencies_parsed_at":"2023-02-17T00:15:41.684Z","dependency_job_id":"4d508191-e4b2-4e8f-b952-d6a526ed5d6a","html_url":"https://github.com/nickbabcock/boxcars","commit_stats":{"total_commits":690,"total_committers":8,"mean_commits":86.25,"dds":"0.024637681159420333","last_synced_commit":"6aa706cf6d98cf577d02d8001495e9afd73b2221"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickbabcock%2Fboxcars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickbabcock%2Fboxcars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickbabcock%2Fboxcars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickbabcock%2Fboxcars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickbabcock","download_url":"https://codeload.github.com/nickbabcock/boxcars/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459088,"owners_count":22074605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rocket-league","rust","serde"],"created_at":"2024-08-03T03:01:00.292Z","updated_at":"2025-05-16T03:04:06.888Z","avatar_url":"https://github.com/nickbabcock.png","language":"Rust","funding_links":[],"categories":["Libraries"],"sub_categories":["Data parsing and analysis"],"readme":"# Boxcars\n\n![ci](https://github.com/nickbabcock/boxcars/workflows/ci/badge.svg) [![](https://docs.rs/boxcars/badge.svg)](https://docs.rs/boxcars) [![Version](https://img.shields.io/crates/v/boxcars.svg?style=flat-square)](https://crates.io/crates/boxcars)\n\nBoxcars is a [Rocket League](http://www.rocketleaguegame.com/) replay parser library written in\nRust.\n\n## Features\n\n- ✔ Safe: Stable Rust with no unsafe\n- ✔ Fast: Parse over a hundred replays per second per CPU core\n- ✔ Fuzzed: Extensively fuzzed against potential malicious input\n- ✔ Ergonomic: Serialization support is provided through [serde](https://github.com/serde-rs/serde)\n\nSee where Boxcars in used:\n\n- Inside the [rrrocket CLI app](https://github.com/nickbabcock/rrrocket) to turn Rocket League Replays into JSON\n- Compiled to [WebAssembly and embedded in a web page](https://rl.nickb.dev/)\n- Underpins the python analyzer of the [popular calculated.gg site](https://calculated.gg/)\n- Powers the [`subtr-actor`](https://github.com/rlrml/subtr-actor) library that offers an ergonomic interface to processing replay data\n\n## Quick Start\n\nBelow is an example to output the replay structure to json:\n\n```rust\nuse boxcars::{ParseError, Replay};\nuse std::error;\nuse std::fs;\nuse std::io::{self, Read};\n\nfn parse_rl(data: \u0026[u8]) -\u003e Result\u003cReplay, ParseError\u003e {\n    boxcars::ParserBuilder::new(data)\n        .must_parse_network_data()\n        .parse()\n}\n\nfn run(filename: \u0026str) -\u003e Result\u003c(), Box\u003cdyn error::Error\u003e\u003e {\n    let filename = \"assets/replays/good/rumble.replay\";\n    let buffer = fs::read(filename)?;\n    let replay = parse_rl(\u0026buffer)?;\n    serde_json::to_writer(\u0026mut io::stdout(), \u0026replay)?;\n    Ok(())\n}\n```\n\nThe above example will parse both the header and network data of a replay file, and return an\nerror if there is an issue either header or network data.  Since the network data will often\nchange with each Rocket League patch, the default behavior is to ignore any errors from the\nnetwork data and still be able to return header information.\n\n## Variations\n\nIf you're only interested the header (where tidbits like goals and scores are stored) then you\ncan achieve an 1000x speedup by directing boxcars to only parse the header.\n\n- By skipping network data one can parse and aggregate thousands of replays in\nunder a second to provide an immediate response to the user. Then a full\nparsing of the replay data can provide additional insights when given time.\n- By ignoring network data errors, boxcars can still provide details about\nnewly patched replays based on the header.\n\nBoxcars will also check for replay corruption on error, but this can be configured to always\ncheck for corruption or never check.\n\n## Benchmarks\n\nTo run the boxcar benchmarks:\n\n```\ncargo bench\n\n# Or if you want to see if compiling for the\n# given cpu eeks out tangible improvements:\n# RUSTFLAGS=\"-C target-cpu=native\" cargo bench\n```\n\nSince Boxcars allows you to pick and choose what to parse, below is a table\nwith the following options and the estimated elapsed time.\n\n| Header | Corruption Check | Body | Output JSON | Elapsed | Throughput |\n| -      | -                | -    | -           | -       | -          |\n| ✔      |                  |      |             | 32 µs |            |\n| ✔      | ✔                | ✔    |             | 5.1 ms | 290 MiB/s  |\n| ✔      |                  | ✔    |             | 4.8 ms | 315 MiB/s  |\n| ✔      | ✔                | ✔    | ✔           | 31 ms |  600 MiB/s ^1  |\n\n^1: JSON serialization throughput includes the amount of JSON produced\n\n## Special Thanks\n\nBoxcars doesn't exist in a vacuum! If boxcars doesn't fit your needs, check out one of these other high quality Rocket League Replay parsers:\n\n[rattletrap](https://github.com/tfausak/rattletrap) | [Bakkes' replay parser](https://github.com/Bakkes/CPPRP) | [RocketLeagueReplayParser](https://github.com/jjbott/RocketLeagueReplayParser) | [RocketRP](https://github.com/Drogebot/RocketRP)\n\n## Difference between rattletrap and boxcars\n\n- Rattletrap is a binary that ingests rocket league replays and outputs JSON, while boxcars is a lower level parsing library. Boxcars underpins Rrrocket, a cli binary that outputs JSON similar to Rattletrap\n- Rattletrap can roundtrip replays (convert them into JSON and then write them out back to a replay losslessly). Boxcars is focussed on parsing replays.\n- In part due to allowing roundtrip parsing, rattletrap JSON output is 2x larger than boxcars (rrrocket) even when accounting for output minification.\n\nBelow are some differences in the model:\n\nrattletrap:\n\n```json\n\"properties\": {\n  \"value\": {\n    \"BuildID\": {\n      \"kind\": \"IntProperty\",\n      \"size\": \"4\",\n      \"value\": {\n        \"int\": 1401925076\n      }\n    },\n  }\n}\n```\n\nboxcars:\n\n```json\n\"properties\": {\n  \"BuildID\": 1401925076\n}\n```\n\n---\n\nrattletrap:\n\n```json\n\"actor_id\": {\n  \"limit\": 2047,\n  \"value\": 1\n},\n```\n\nboxcars:\n\n```json\n\"actor_id\": 1\n```\n\n---\n\nrattletrap:\n\n```json\n\"value\": {\n  \"spawned\": {\n    \"class_name\": \"TAGame.GameEvent_Soccar_TA\",\n    \"flag\": true,\n    \"initialization\": {\n      \"location\": {\n        \"bias\": 2,\n        \"size\": {\n          \"limit\": 21,\n          \"value\": 0\n        },\n        \"x\": 0,\n        \"y\": 0,\n        \"z\": 0\n      }\n    },\n    \"name\": \"GRI_TA_1\",\n    \"name_index\": 0,\n    \"object_id\": 85,\n    \"object_name\": \"Archetypes.GameEvent.GameEvent_Soccar\"\n  }\n}\n```\n\nboxcars:\n\n```json\n\"actor_id\": 1,\n\"name_id\": 1,\n\"object_id\": 85,\n\"initial_trajectory\": {\n  \"location\": {\n    \"x\": 0,\n    \"y\": 0,\n    \"z\": 0\n  },\n  \"rotation\": null\n}\n```\n\nWhile rattletrap provides convenience conversions, boxcars omit them in favor of a more raw view of the replay:\n\n- to derive `object_name`: `replay.objects[x.object_id]`\n- to derive `name`: `replay.names[x.name_id]`\n\n---\n\nAttribute updates:\n\nrattletrap:\n\n```json\n{\n  \"actor_id\": {\n    \"limit\": 2047,\n    \"value\": 7\n  },\n  \"value\": {\n    \"updated\": [\n      {\n        \"id\": {\n          \"limit\": 98,\n          \"value\": 34\n        },\n        \"name\": \"Engine.PlayerReplicationInfo:PlayerName\",\n        \"value\": {\n          \"string\": \"Nadir\"\n        }\n      }\n    ]\n  }\n}\n```\n\nboxcars:\n\n```json\n{\n  \"actor_id\": 7,\n  \"stream_id\": 34,\n  \"object_id\": 161,\n  \"attribute\": {\n    \"String\": \"Nadir\"\n  }\n}\n```\n\nTo derive rattletrap's `name` for the attribute use `replay.objects[attribute.object_id]`\n\n## Fuzzing\n\nBoxcars contains a fuzzing suite. If you'd like to run it, first install [cargo-fuzz](https://github.com/rust-fuzz/cargo-fuzz)\n\n```\ncargo install cargo-fuzz\n```\n\nThere are several scenarios to fuzz (`cargo fuzz list`), and the best one to run is `no-crc-body`, due to all aspects of the replay being fuzzed without a crc check:\n\n```\ncargo +nightly fuzz run no-crc-body\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickbabcock%2Fboxcars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickbabcock%2Fboxcars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickbabcock%2Fboxcars/lists"}