Sprocket-carball

Sprocket-carball is an open-source project that combines multiple tools for decompiling Rocket League replays and then analysing them. It is a fork of SaltieRL's carball project, which appears to no longer be maintained.

Install

Install from pip:

pip install sprocket_carball

Examples / Usage

One of the main data structures used in carball is the pandas.DataFrame, to learn more, see its wiki page.

Decompile and analyze a replay:

importcarballanalysis_manager=carball.analyze_replay_file('9EB5E5814D73F55B51A1BD9664D4CBF3.replay', output_path='9EB5E5814D73F55B51A1BD9664D4CBF3.json', overwrite=True)
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:

importcarball_json=carball.decompile_replay('9EB5E5814D73F55B51A1BD9664D4CBF3.replay', output_path='9EB5E5814D73F55B51A1BD9664D4CBF3.json', overwrite=True)

Analyze a JSON game object:

importcarballimportgzipfromcarball.json_parser.gameimportGamefromcarball.analysis.analysis_managerimportAnalysisManager# _json is a JSON game object (from decompile_replay)game=Game()
game.initialize(loaded_json=_json)
analysis_manager=AnalysisManager(game)
analysis_manager.create_analysis()
# return the proto object in pythonproto_object=analysis_manager.get_protobuf_data()
# return the proto object as a json objectjson_oject=analysis_manager.get_json_data()
# return the pandas data frame in pythondataframe=analysis_manager.get_data_frame()

You may want to save carball analysis results for later use:

# write proto out to a file# read api/*.proto for info on the object propertieswithopen('output.pts', 'wb') asfo:
analysis_manager.write_proto_out_to_file(fo)
# write pandas dataframe out as a gzipped numpy arraywithgzip.open('output.gzip', 'wb') asfo:
analysis_manager.write_pandas_out_to_file(fo)

Read the saved analysis files:

importgzipfromcarball.analysis.utils.pandas_managerimportPandasManagerfromcarball.analysis.utils.proto_managerimportProtobufManager# read proto from filewithopen('output.pts', 'rb') asf:
proto_object=ProtobufManager.read_proto_out_from_file(f)
# read pandas dataframe from gzipped numpy array filewithgzip.open('output.gzip', 'rb') asf:
dataframe=PandasManager.read_numpy_from_memory(f)

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
provided.
--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.
--gzip GZIP The pandas dataframe will be saved to this file in a
compressed gzip format.
-v, --verbose Set the logging level to INFO. To set the logging
level to DEBUG use -vv.
-s, --silent Disable logging altogether.

Pipeline

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 setup.sh (Linux/mac)