Skip to main content

Rocket League replay parsing and analysis.

Project description

Build Status PyPI version codecov Build status Language grade: Python Total alerts


Various tools for decompiling / analyzing Rocket League replays.


  • Python 3.6.7+ or 3.7+
  • Windows, Mac or Linux


Install from pip:

pip install carball

Clone for development

git clone
cd carball/
git clone
cd carball/

Examples / Usage

Decompile and analyze a replay:

import carball

analysis_manager = carball.analyze_replay_file('9EB5E5814D73F55B51A1BD9664D4CBF3.replay', 
proto_game = analysis_manager.get_protobuf_data()

# you can see more example of using the analysis manager below

Just decompile a replay to a JSON object:

import carball

_json = carball.decompile_replay('9EB5E5814D73F55B51A1BD9664D4CBF3.replay', 

Analyze a JSON game object:

import carball
import os
import gzip
from import Game
from carball.analysis.analysis_manager import AnalysisManager
# _json is a JSON game object (from decompile_replay)
game = Game()

analysis_manager = AnalysisManager(game)

# write proto out to a file
# read api/*.proto for info on the object properties
with open(os.path.join('output.pts'), 'wb') as fo:
# write pandas dataframe out as a gzipped numpy array
with'output.gzip'), 'wb') as fo:
# return the proto object in python
proto_object = analysis_manager.get_protobuf_data()

# return the pandas data frame in python
dataframe = analysis_manager.get_data_frame()

Command Line

Carball comes with a command line tool to analyze replays. To use carball from the command line:

carball -i 9EB5E5814D73F55B51A1BD9664D4CBF3.replay --json analysis.json

To get the analysis in both json and protobuf and also the compressed replay frame data frame:

carball -i 9EB5E5814D73F55B51A1BD9664D4CBF3.replay --json analysis.json --proto analysis.pts --gzip frames.gzip

Command Line Arguments

usage: carball [-h] -i INPUT [--proto PROTO] [--json JSON] [--gzip GZIP] [-sd]
               [-v] [-s]

Rocket League replay parsing and analysis.

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        Path to replay file that will be analyzed. Carball
                        expects a raw replay file unless --skip-decompile is
  --proto PROTO         The result of the analysis will be saved to this file
                        in protocol buffers format.
  --json JSON           The result of the analysis will be saved to this file
                        in json file format. This is not the decompiled replay
                        json from rattletrap.
  --gzip GZIP           The pandas dataframe will be saved to this file in a
                        compressed gzip format.
  -sd, --skip-decompile
                        If set, carball will treat the input file as a json
                        file that Rattletrap outputs.
  -v, --verbose         Set the logging level to INFO. To set the logging
                        level to DEBUG use -vv.
  -s, --silent          Disable logging altogether.


pipeline is in Parserformat.png

If you want to add a new stat it is best to do it in the advanced stats section of the pipeline. You should look at:

Stat base classes

Where you add a new stat

If you want to see the output format of the stats created you can look here

Compile the proto files by running in this directory setup.bat (Windows) or (Linux/mac)

Build Status codecov


Linux set python3.6 as python:

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.6 1

This assumes you already have 3.6 installed.

Linux Error (Potential): PermissionError: [Errno 13] Permission denied: 'carball/rattletrap/rattletrap-6.2.2-linux' Fix: chmod +x "carball/rattletrap/rattletrap-6.2.2-linux"


For testing you must run pytest. For ides you can configure them to use the pytest runner.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for carball, version 0.6.36
Filename, size File type Python version Upload date Hashes
Filename, size carball-0.6.36.tar.gz (5.1 MB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page