# 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](https://github.com/SaltieRL/carball) project, which
appears to no longer be maintained.
## Requirements
- Python 3.6.7+ (3.7 and 3.8 included)
- Windows, Mac or Linux
## Install
#### Install from pip:
`pip install sprocket_carball`
#### Clone for development
##### Windows
```
git clone https://github.com/SprocketBot/carball
cd carball/
python init.py
```
##### Linux
```
git clone https://github.com/SprocketBot/carball
cd carball/
./_travis/install-protoc.sh
python init.py
```
Alternatively,
```
git clone https://github.com/SprocketBot/carball
cd carball/
./utils/install_protobuf.sh
python init.py
sudo python setup.py install
```
Finally, to publish the package on PyPI
```
python setup.py sdist
twine upload dist/*
```
To actually *use* the package as writ (until we get the protobuf version that we
use for generating the pb2 files updated), you'll need to set this environment
variable:
```
export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python
```
##### Mac
In MacOS Catalina, zsh replaced bash as the default shell, which may cause permission issues when trying to run `install-protoc.sh` in the above fashion. Simply invoking bash should resolve this issue, like so:
```
git clone https://github.com/SprocketBot/carball
cd carball/
bash ./_travis/install-protoc.sh
python init.py
```
Apple's decision to replace bash as the default shell may foreshadow the removal of bash in a future version of MacOS. In such a case, Homebrew users can [install protoc](http://google.github.io/proto-lens/installing-protoc.html) by replacing `bash ./travis/install-protoc.sh` with `brew install protobuf`.
## Examples / Usage
One of the main data structures used in carball is the pandas.DataFrame, to learn more, see [its wiki page](https://github.com/SaltieRL/carball/wiki/data_frame).
Decompile and analyze a replay:
```Python
import carball
analysis_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:
```Python
import carball
_json = carball.decompile_replay('9EB5E5814D73F55B51A1BD9664D4CBF3.replay',
output_path='9EB5E5814D73F55B51A1BD9664D4CBF3.json',
overwrite=True)
```
Analyze a JSON game object:
```Python
import carball
import gzip
from carball.json_parser.game import Game
from carball.analysis.analysis_manager import AnalysisManager
# _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 python
proto_object = analysis_manager.get_protobuf_data()
# return the proto object as a json object
json_oject = analysis_manager.get_json_data()
# return the pandas data frame in python
dataframe = analysis_manager.get_data_frame()
```
You may want to save carball analysis results for later use:
```python
# write proto out to a file
# read api/*.proto for info on the object properties
with open('output.pts', 'wb') as fo:
analysis_manager.write_proto_out_to_file(fo)
# write pandas dataframe out as a gzipped numpy array
with gzip.open('output.gzip', 'wb') as fo:
analysis_manager.write_pandas_out_to_file(fo)
```
Read the saved analysis files:
```python
import gzip
from carball.analysis.utils.pandas_manager import PandasManager
from carball.analysis.utils.proto_manager import ProtobufManager
# read proto from file
with open('output.pts', 'rb') as f:
proto_object = ProtobufManager.read_proto_out_from_file(f)
# read pandas dataframe from gzipped numpy array file
with gzip.open('output.gzip', 'rb') as f:
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:
```bash
carball -i 9EB5E5814D73F55B51A1BD9664D4CBF3.replay --json analysis.json
```
To get the analysis in both json and protobuf and also the compressed replay frame data frame:
```bash
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](carball/analysis/stats/stats.py)
[Where you add a new stat](carball/analysis/stats/stats_list.py)
If you want to see the output format of the stats created you can look [here](api)
Compile the proto files by running in this directory
`setup.bat` (Windows) or `setup.sh` (Linux/mac)
[](https://travis-ci.org/SaltieRL/carball)
[](https://codecov.io/gh/SaltieRL/carball)
Raw data
{
"_id": null,
"home_page": "https://github.com/SprocketBot/carball",
"name": "sprocket-carball",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "rocket-league",
"author": "Sprocket Dev Team",
"author_email": "asaxplayinghorse@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f9/8f/9e97ba1f687da14b935bae399448f2fbad56407cbc74f0eb35095b5a0ad7/sprocket_carball-0.8.7.tar.gz",
"platform": null,
"description": "# Sprocket-carball\nSprocket-carball is an open-source project that combines multiple tools for\ndecompiling Rocket League replays and then analysing them. It is a fork of\n[SaltieRL's carball](https://github.com/SaltieRL/carball) project, which \nappears to no longer be maintained. \n\n## Requirements\n\n- Python 3.6.7+ (3.7 and 3.8 included)\n- Windows, Mac or Linux\n\n## Install\n\n#### Install from pip:\n\n`pip install sprocket_carball`\n\n#### Clone for development\n\n##### Windows\n```\ngit clone https://github.com/SprocketBot/carball\ncd carball/\npython init.py\n```\n\n##### Linux\n```\ngit clone https://github.com/SprocketBot/carball\ncd carball/\n./_travis/install-protoc.sh\npython init.py\n```\n\nAlternatively, \n\n```\ngit clone https://github.com/SprocketBot/carball\ncd carball/\n./utils/install_protobuf.sh\npython init.py\nsudo python setup.py install\n```\n\nFinally, to publish the package on PyPI\n\n```\npython setup.py sdist\ntwine upload dist/*\n```\n\nTo actually *use* the package as writ (until we get the protobuf version that we\nuse for generating the pb2 files updated), you'll need to set this environment\nvariable:\n\n```\nexport PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python\n```\n\n\n##### Mac\nIn MacOS Catalina, zsh replaced bash as the default shell, which may cause permission issues when trying to run `install-protoc.sh` in the above fashion. Simply invoking bash should resolve this issue, like so:\n```\ngit clone https://github.com/SprocketBot/carball\ncd carball/\nbash ./_travis/install-protoc.sh\npython init.py\n```\nApple's decision to replace bash as the default shell may foreshadow the removal of bash in a future version of MacOS. In such a case, Homebrew users can [install protoc](http://google.github.io/proto-lens/installing-protoc.html) by replacing `bash ./travis/install-protoc.sh` with `brew install protobuf`.\n\n\n## Examples / Usage\nOne of the main data structures used in carball is the pandas.DataFrame, to learn more, see [its wiki page](https://github.com/SaltieRL/carball/wiki/data_frame).\n\nDecompile and analyze a replay:\n```Python\nimport carball\n\nanalysis_manager = carball.analyze_replay_file('9EB5E5814D73F55B51A1BD9664D4CBF3.replay', \n output_path='9EB5E5814D73F55B51A1BD9664D4CBF3.json', \n overwrite=True)\nproto_game = analysis_manager.get_protobuf_data()\n\n# you can see more example of using the analysis manager below\n\n```\n\nJust decompile a replay to a JSON object:\n\n```Python\nimport carball\n\n_json = carball.decompile_replay('9EB5E5814D73F55B51A1BD9664D4CBF3.replay', \n output_path='9EB5E5814D73F55B51A1BD9664D4CBF3.json', \n overwrite=True)\n```\n\nAnalyze a JSON game object:\n```Python\nimport carball\nimport gzip\nfrom carball.json_parser.game import Game\nfrom carball.analysis.analysis_manager import AnalysisManager\n\n# _json is a JSON game object (from decompile_replay)\ngame = Game()\ngame.initialize(loaded_json=_json)\n\nanalysis_manager = AnalysisManager(game)\nanalysis_manager.create_analysis()\n \n# return the proto object in python\nproto_object = analysis_manager.get_protobuf_data()\n\n# return the proto object as a json object\njson_oject = analysis_manager.get_json_data()\n\n# return the pandas data frame in python\ndataframe = analysis_manager.get_data_frame()\n```\n\nYou may want to save carball analysis results for later use:\n\n```python\n# write proto out to a file\n# read api/*.proto for info on the object properties\nwith open('output.pts', 'wb') as fo:\n analysis_manager.write_proto_out_to_file(fo)\n \n# write pandas dataframe out as a gzipped numpy array\nwith gzip.open('output.gzip', 'wb') as fo:\n analysis_manager.write_pandas_out_to_file(fo)\n```\n\nRead the saved analysis files:\n\n```python\nimport gzip\nfrom carball.analysis.utils.pandas_manager import PandasManager\nfrom carball.analysis.utils.proto_manager import ProtobufManager\n\n# read proto from file\nwith open('output.pts', 'rb') as f:\n proto_object = ProtobufManager.read_proto_out_from_file(f)\n\n# read pandas dataframe from gzipped numpy array file\nwith gzip.open('output.gzip', 'rb') as f:\n dataframe = PandasManager.read_numpy_from_memory(f)\n```\n\n### Command Line\n\nCarball comes with a command line tool to analyze replays. To use carball from the command line:\n\n```bash\ncarball -i 9EB5E5814D73F55B51A1BD9664D4CBF3.replay --json analysis.json\n```\n\nTo get the analysis in both json and protobuf and also the compressed replay frame data frame:\n\n```bash\ncarball -i 9EB5E5814D73F55B51A1BD9664D4CBF3.replay --json analysis.json --proto analysis.pts --gzip frames.gzip\n```\n\n#### Command Line Arguments\n\n```\nusage: carball [-h] -i INPUT [--proto PROTO] [--json JSON] [--gzip GZIP] [-sd]\n [-v] [-s]\n\nRocket League replay parsing and analysis.\n\noptional arguments:\n -h, --help show this help message and exit\n -i INPUT, --input INPUT\n Path to replay file that will be analyzed. Carball\n expects a raw replay file unless --skip-decompile is\n provided.\n --proto PROTO The result of the analysis will be saved to this file\n in protocol buffers format.\n --json JSON The result of the analysis will be saved to this file\n in json file format.\n --gzip GZIP The pandas dataframe will be saved to this file in a\n compressed gzip format.\n -v, --verbose Set the logging level to INFO. To set the logging\n level to DEBUG use -vv.\n -s, --silent Disable logging altogether.\n```\n\n## Pipeline\n\n\nIf you want to add a new stat it is best to do it in the advanced stats section of the pipeline.\nYou should look at:\n\n[Stat base classes](carball/analysis/stats/stats.py)\n\n[Where you add a new stat](carball/analysis/stats/stats_list.py)\n\nIf you want to see the output format of the stats created you can look [here](api)\n\nCompile the proto files by running in this directory\n`setup.bat` (Windows) or `setup.sh` (Linux/mac)\n\n[](https://travis-ci.org/SaltieRL/carball)\n[](https://codecov.io/gh/SaltieRL/carball)\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Rocket League replay parsing and analysis.",
"version": "0.8.7",
"split_keywords": [
"rocket-league"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f98f9e97ba1f687da14b935bae399448f2fbad56407cbc74f0eb35095b5a0ad7",
"md5": "a17a5ef9801d3707d5efbd83bb8bf7a1",
"sha256": "4e8a02b75263d78df1b9ba7d17e64b42dc414ce3a562f410457d4229b9223129"
},
"downloads": -1,
"filename": "sprocket_carball-0.8.7.tar.gz",
"has_sig": false,
"md5_digest": "a17a5ef9801d3707d5efbd83bb8bf7a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 165102,
"upload_time": "2023-04-18T19:44:23",
"upload_time_iso_8601": "2023-04-18T19:44:23.398129Z",
"url": "https://files.pythonhosted.org/packages/f9/8f/9e97ba1f687da14b935bae399448f2fbad56407cbc74f0eb35095b5a0ad7/sprocket_carball-0.8.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-18 19:44:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "SprocketBot",
"github_project": "carball",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"appveyor": true,
"requirements": [],
"lcname": "sprocket-carball"
}
JSON
