Metadata-Version: 2.4
Name: analyzerl-boxcars
Version: 0.1.0
Summary: Python API for the AnalyzeRL Boxcars Rocket League replay parser.
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: polars>=1.0
Requires-Dist: polars-runtime-32>=1.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# AnalyzeRL Boxcars
## Labelling and analyzing Rocket League replay data

AnalyzeRL Boxcars is a Rust package mounting the detection of events and player actions onto frame-wise Rocket League replay data parsed by the powerful [boxcars](https://github.com/nickbabcock/boxcars) library.

## Requirements
- Rocket League `.replay` files
- The compiled Windows or Linux x86-64 binary from the repository's [Releases](https://github.com/owensingh38/analyzerl_boxcars/releases) page when using the CLI directly
- Python 3.10 or newer when using the Python API
- Rust 1.85 or newer only when building the binary from source

## Parsing Pipeline
- Collect replay objects from boxcars
- Arrange frame-by-frame match dataframe
- Mount EventModel and obtain interpretable frame-level events in a match

## Installation
Download `analyzerl_boxcars.exe` from the assets attached to the latest repository [release](https://github.com/owensingh38/analyzerl_boxcars/releases). Building locally is optional:

```powershell
cargo build --release
```

Install the Python package when using the Python API:

```powershell
python -m pip install analyzerl-boxcars
```

The Windows and Linux x86-64 wheels include the matching Rust binary, so Python API users do not need to download it separately.

The examples below use the downloaded release binary:

```powershell
$analyzerl = "C:\path\to\analyzerl_boxcars.exe"
$replay = "C:\path\to\match.replay"
```

Python examples use the binary bundled with `AnalyzeRLBoxcars`:

```python
from pathlib import Path

from analyzerl_boxcars import AnalyzeRLBoxcars

analyzer = AnalyzeRLBoxcars(
    n_workers=1,
)
replay = Path(r"C:\path\to\match.replay")
```

## Usage
### Parse Without Writing Files
**CLI**

The CLI parses silently when `--export` is omitted:

```powershell
& $analyzerl $replay
```

**Python**

The Python API returns the frame-wise Polars dataframe directly:

```python
frames = analyzer.parse_replay(replay, event_tagging=False)
```

### Export Frame Data to CSV
**CLI**

```powershell
& $analyzerl $replay --export "C:\path\to\match.csv"
```

**Python**

```python
analyzer.parse_replay(
    replay,
    event_tagging=False,
    export="csv",
    export_dir=Path(r"C:\path\to\exports"),
)
```

### Export Frame Data to Parquet
**CLI**

```powershell
& $analyzerl $replay --export "C:\path\to\match.parquet"
```

**Python**

```python
analyzer.parse_replay(
    replay,
    event_tagging=False,
    export="parquet",
    export_dir=Path(r"C:\path\to\exports"),
)
```

### Stream or Return Frame Data
**CLI**

The CLI streams Parquet bytes to stdout and writes status text to stderr:

```powershell
& $analyzerl $replay --event-tagging true --export stdout
```

**Python**

The Python API uses the same stdout transport internally and returns a Polars dataframe without writing a file:

```python
frames = analyzer.parse_replay(replay, event_tagging=True)
```

### Mount the Event Model
**CLI**

```powershell
& $analyzerl $replay --event-tagging true --export "C:\path\to\match.parquet"
```

**Python**

```python
labelled_frames = analyzer.parse_replay(replay, event_tagging=True)
```

### Apply the Event Model to Frame Data
Frame data parsed with `event_tagging=False` retains the replay-native signals needed to mount the same event model later. Existing event columns are overwritten.

**CLI**

```powershell
& $analyzerl "C:\path\to\frames.parquet" --apply-event-model --export "C:\path\to\labelled.parquet"
```

**Python**

```python
from analyzerl_boxcars import EventModel, apply_event_model

labelled_frames = apply_event_model(frames)
labelled_frames = EventModel().apply(frames)
```

The Python API streams Parquet between Polars and the bundled Rust binary in memory; it does not create an intermediate file.

### Calculate Stats From a Replay
**CLI**

```powershell
& $analyzerl $replay --calc-stats --export "C:\path\to\stats.csv"
```

**Python**

```python
stats = analyzer.calculate_stats(replay)
```

### Calculate Stats From Frame Data
Both CSV and Parquet frame exports are valid stats inputs.

**CLI**

```powershell
& $analyzerl "C:\path\to\frames.csv" --calc-stats --export "C:\path\to\stats.csv"
& $analyzerl "C:\path\to\frames.parquet" --calc-stats --export "C:\path\to\stats.parquet"
```

**Python**

```python
csv_stats = analyzer.calculate_stats(Path(r"C:\path\to\frames.csv"))
parquet_stats = analyzer.calculate_stats(Path(r"C:\path\to\frames.parquet"))
```

### Export Stats
**CLI**

The CLI infers CSV or Parquet from the output extension:

```powershell
& $analyzerl $replay --calc-stats --export "C:\path\to\stats.parquet"
```

**Python**

The Python API selects the format with `export` and writes through the Rust binary:

```python
analyzer.calculate_stats(
    replay,
    export="parquet",
    export_dir=Path(r"C:\path\to\exports"),
)
```

The CLI supports `.csv` and `.parquet` export paths. The special `stdout` target always emits Parquet bytes. Python calls with `export=False` return a Polars dataframe; calls with `export="csv"` or `export="parquet"` write files and return `None`.

## Output
The parser returns a frame-wise dataframe with replay, frame, ball, team, event, and player column groups. Player columns are kept together as the final column group so wide exports remain easier to scan.

When `--calc-stats` is supplied, the CLI returns one row per `replay_id` and `player_id` instead of frame-level rows. Stats are calculated only from columns already present in the labelled frame-wise dataframe.

When an export path is supplied, the CLI prints:

```text
Parsed {replay_id}
```

## Documentation
Full documentation coming soon.

## License
AnalyzeRL Boxcars is closed-source, proprietary software. Copyright (c) 2026 Project Signal. All Rights Reserved. No permission is granted to use, copy, modify, or distribute the software except under a separate written agreement expressly authorized by Project Signal. See the [proprietary license](LICENSE) for complete terms.
