rattletrap-4.0.0: README.markdown

# [Rattletrap][]

[![Version badge][]][version]
[![Windows build badge][]][windows build]
[![Build badge][]][build]

Rattletrap parses and generates [Rocket League][] replays.

## Install

Get Rattletrap by downloading and unpacking [the latest release][] for your
platform.

To build Rattletrap from source, install [Stack][]. Then run
`stack --resolver nightly install rattletrap`.

## Replays

Rocket League saves your replays in a folder that depends on your operating
system.

- Windows:
  - `%UserProfile%/Documents/My Games/Rocket League/TAGame/Demos`
  - For example: `C:/Users/Taylor/Documents/My Games/Rocket League/TAGame/Demos`
- macOS:
  - `$HOME/Library/Application Support/Rocket League/TAGame/Demos`
  - For example: `/Users/taylor/Library/Application Support/Rocket League/TAGame/Demos`
- Linux:
  - `$HOME/.local/share/Rocket League/TAGame/Demos`
  - For example: `/home/taylor/.local/share/Rocket League/TAGame/Demos`

## Interface

Rattletrap is a command line application.

``` sh
> rattletrap --help
rattletrap version 4.0.0
  -c             --compact                minify JSON output
  -h             --help                   show the help
  -i FILE|URL    --input=FILE|URL         input file or URL
  -m MODE        --mode=MODE              decode or encode
  -o FILE        --output=FILE            output file
  -v             --version                show the version
```

By default Rattletrap will try to determine the appropriate mode (either decode
or encode) based on the file extensions of the input or output. You can
override this behavior by passing `--mode` (or `-m`) with either `decode` or
`encode`.

Input extension | Output extension | Mode
--- | --- | ---
`.replay` | anything | `decode` (parse)
`.json` | anything | `encode` (generate)
anything | `.replay` | `encode` (generate)
anything | `.json` | `decode` (parse)
anything | anything | `decode` (parse)

## Parse

Rattletrap can parse (decode) Rocket League replays and output them as JSON.

``` sh
> rattletrap --input http://example.com/input.replay --output output.json
# or
> rattletrap -i input.replay > output.json
# or
> rattletrap < input.replay > output.json
```

The input argument can either be a local path or a URL.

By default the JSON is pretty-printed. To minify the JSON, pass `--compact` (or
`-c`) to Rattletrap. Even when the JSON is minified, it's extremely large. The
output can be up to 100 times larger than the input. For example, a 1.5 MB
replay turns into 31 MB of minified JSON or 159 MB of pretty-printed JSON.

## Generate

Rattletrap can also generate (encode) Rocket League replays from JSON files.

``` sh
> rattletrap --input http://example.com/input.json --output output.replay
# or
> rattletrap -i input.json > output.replay
# or
> rattletrap --mode encode < input.json > output.replay
```

The input argument can either be a local path or a URL.

If the JSON was generated by Rattletrap, the output replay will be bit-for-bit
identical to the input replay.

## Modify

By inserting another program between parsing and generating, Rattletrap can be
used to modify replays.

``` sh
> rattletrap -i input.replay |
  modify-replay-json |
  rattletrap -o output.replay
```

[Rattletrap]: https://github.com/tfausak/rattletrap
[Version badge]: https://img.shields.io/hackage/v/rattletrap.svg?label=version
[version]: https://www.stackage.org/nightly/package/rattletrap
[Windows build badge]: https://img.shields.io/appveyor/ci/taylorfausak/rattletrap/master.svg?logo=appveyor
[windows build]: https://ci.appveyor.com/project/TaylorFausak/rattletrap
[Build badge]: https://img.shields.io/travis/tfausak/rattletrap/master.svg
[build]: https://travis-ci.org/tfausak/rattletrap
[Rocket League]: https://www.rocketleaguegame.com
[the latest release]: https://github.com/tfausak/rattletrap/releases/latest
[Stack]: https://docs.haskellstack.org/en/stable/README/