### Running an example script

Source: https://github.com/manucabral/rlstatsapi/blob/main/examples/README.md

This command shows how to run any of the example Python scripts.

```bash
python examples/<file>.py
```

--------------------------------

### Quick Setup

Source: https://github.com/manucabral/rlstatsapi/blob/main/CONTRIBUTING.md

Commands to set up a virtual environment, activate it, and install the project locally.

```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
# source .venv/bin/activate

pip install -e .
```

--------------------------------

### Verify Installation

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/installation.md

Verify the installation by checking the library's version.

```bash
python -c "import rlstatsapi; print(rlstatsapi.__version__)"
```

--------------------------------

### Install from GitHub

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/installation.md

Install the rlstatsapi library directly from its GitHub repository using pip.

```bash
pip install git+https://github.com/manucabral/RocketLeagueStatsAPI.git
```

--------------------------------

### Detect match start and end

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/recipes.md

This example shows how to detect multiple match-related events like 'MatchCreated', 'RoundStarted', 'MatchEnded', and 'MatchDestroyed'.

```python
import asyncio
from rlstatsapi import StatsClient


async def main() -> None:
    async with StatsClient() as client:
        client.on_many(
            ["MatchCreated", "RoundStarted", "MatchEnded", "MatchDestroyed"],
            lambda msg: print(msg.event),
        )
        await asyncio.Event().wait()
```

--------------------------------

### Run event_names_only.py example

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/examples.md

This command demonstrates how to run the `event_names_only.py` script from the repository root.

```bash
python examples/event_names_only.py
```

--------------------------------

### CLI quick checks

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/quickstart.md

Provides command-line interface commands for quick checks.

```bash
rlstatsapi status
```

```bash
rlstatsapi listen --event GoalScored
```

--------------------------------

### Install from PyPI

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/installation.md

Install the rlstatsapi library using pip from the Python Package Index.

```bash
pip install rlstatsapi
```

--------------------------------

### Basic listener

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/quickstart.md

Prints incoming events from the local Rocket League exporter.

```python
import asyncio
from rlstatsapi import StatsClient


async def main() -> None:
    async with StatsClient() as client:
        client.on_any(lambda msg: print(msg.event, msg.data))
        await asyncio.Event().wait()


asyncio.run(main())
```

--------------------------------

### Filter specific events

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/quickstart.md

Filters and prints specific events from the client.

```python
async with StatsClient() as client:
    async for message in client.events("GoalScored", "MatchEnded"):
        print(message.event, message.data)
```

--------------------------------

### Typed payload pattern (Pylance-friendly)

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/quickstart.md

Demonstrates a typed payload pattern for Pylance compatibility.

```python
from rlstatsapi.models import EventMessage
from rlstatsapi.types import GoalScoredPayload, cast_event_data


def on_goal(msg: EventMessage) -> None:
    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
    scorer = data.get("Scorer", {})
    print(scorer.get("Name"))
```

--------------------------------

### Register one handler for several events

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/quickstart.md

Registers a single handler for multiple events.

```python
client.on_many(["MatchCreated", "MatchEnded"], lambda msg: print(msg.event))
```

--------------------------------

### Python Configuration

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/configuration.md

Example of configuring rlstatsapi using Python.

```python
from rlstatsapi import configure_stats_api

configure_stats_api(enabled=True, port=49123, packet_send_rate=30)
```

--------------------------------

### Example Usage

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Example of how to use the EventMessage and cast_event_data for handling goal events.

```python
from rlstatsapi.models import EventMessage
from rlstatsapi.types import GoalScoredPayload, cast_event_data


def on_goal(msg: EventMessage) -> None:
    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
    scorer = data.get("Scorer", {})
    print(f"{scorer.get('Name')}" scored!)
```

--------------------------------

### CLI Configuration

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/configuration.md

Examples of configuring rlstatsapi using the command-line interface.

```bash
rlstatsapi enable --port 49123 --rate 30
rlstatsapi disable
rlstatsapi status
```

--------------------------------

### Install from GitHub

Source: https://github.com/manucabral/rlstatsapi/blob/main/README.md

Install the rlstatsapi package using pip directly from GitHub.

```bash
pip install git+https://github.com/manucabral/rlstatsapi.git
```

--------------------------------

### Log goals only

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/recipes.md

This example demonstrates how to listen for and log 'GoalScored' events.

```python
import asyncio
from rlstatsapi import StatsClient
from rlstatsapi.types import GoalScoredPayload, cast_event_data


def on_goal(msg) -> None:
    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
    scorer = data.get("Scorer", {})
    print("Goal by:", scorer.get("Name"))


async def main() -> None:
    async with StatsClient() as client:
        client.on("GoalScored", on_goal)
        await asyncio.Event().wait()
```

--------------------------------

### Typing example

Source: https://github.com/manucabral/rlstatsapi/blob/main/README.md

Example demonstrating how to use `cast_event_data` for type-safe event data handling.

```python
from rlstatsapi.models import EventMessage
from rlstatsapi.types import GoalScoredPayload, cast_event_data


def on_goal(msg: EventMessage) -> None:
    data: GoalScoredPayload = cast_event_data("GoalScored", msg.data)
    print(data.get("Scorer", {}).get("Name"))
```

--------------------------------

### Keep your client port in sync with the config file

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/recipes.md

This example demonstrates how to configure the Stats API, including the port and packet send rate, and then initialize the StatsClient with the configured port.

```python
from rlstatsapi import StatsClient, configure_stats_api

status = configure_stats_api(enabled=True, port=49123, packet_send_rate=30)
client = StatsClient(port=status.port or 49123)
```

--------------------------------

### CountdownBegin Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the pre-kickoff countdown starts.

```json
{
  "event": "CountdownBegin",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### MatchInitialized Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the match finishes loading and is ready to start.

```json
{
  "event": "MatchInitialized",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### Write all changed payloads to a file

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/recipes.md

This command-line example executes a script that writes all changed event payloads to a text file.

```bash
python examples/all_events_to_txt.py
```

--------------------------------

### CLI status command

Source: https://github.com/manucabral/rlstatsapi/blob/main/README.md

Get the current status of the rlstatsapi service.

```bash
rlstatsapi status
```

--------------------------------

### ReplayCreated Event

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when an in-match replay starts (e.g. goal replay saved as replay).

```json
{
  "event": "ReplayCreated",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### Manual Configuration File

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/configuration.md

Recommended minimum configuration for the TAStatsAPI.ini file.

```ini
[TAGame.MatchStatsExporter_TA]
Port=49123
PacketSendRate=30
```

--------------------------------

### GoalReplayStart Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the goal replay begins.

```json
{
  "event": "GoalReplayStart",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### PodiumStart Event

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the post-match podium sequence begins.

```json
{
  "event": "PodiumStart",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### Quick checks

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/contributing.md

Commands to run for code formatting and linting checks.

```bash
python -m black .
python -m pylint src examples tests
```

--------------------------------

### CLI enable command

Source: https://github.com/manucabral/rlstatsapi/blob/main/README.md

Enable the rlstatsapi service with specified port and rate.

```bash
rlstatsapi enable --port 49123 --rate 30
```

--------------------------------

### CLI listen command for multiple events

Source: https://github.com/manucabral/rlstatsapi/blob/main/README.md

Listen for multiple events simultaneously.

```bash
rlstatsapi listen --event GoalScored --event MatchEnded --event MatchCreated
```

--------------------------------

### MatchCreated Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when a match session is created (before initialization).

```json
{
  "event": "MatchCreated",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### GoalReplayWillEnd Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired shortly before the goal replay ends.

```json
{
  "event": "GoalReplayWillEnd",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### CLI listen command for a single event

Source: https://github.com/manucabral/rlstatsapi/blob/main/README.md

Listen for a specific event, e.g., GoalScored.

```bash
rlstatsapi listen --event GoalScored
```

--------------------------------

### GoalReplayEnd Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the goal replay ends.

```json
{
  "event": "GoalReplayEnd",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### Code Style and Checks

Source: https://github.com/manucabral/rlstatsapi/blob/main/CONTRIBUTING.md

Commands to run formatting (black) and linting (pylint) checks.

```bash
python -m black .
python -m pylint src examples
```

--------------------------------

### Alternative helper on the message itself

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/typing.md

Shows an alternative helper method `msg.as_type(...)` for casting event data to a specific type.

```python
from rlstatsapi.models import EventMessage


def on_goal(msg: EventMessage) -> None:
    typed = msg.as_type("GoalScored")
    print(typed.data.get("Scorer", {}).get("Name"))
```

--------------------------------

### UpdateState Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired repeatedly while a match is live. Contains a full game and player snapshot.

```json
{
  "event": "UpdateState",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6",
    "Players": [
      {
        "Name": "Psyonix",
        "PrimaryId": "76561198000000000",
        "Shortcut": 0,
        "TeamNum": 0,
        "Score": 100,
        "Goals": 1,
        "Shots": 2,
        "Assists": 0,
        "Saves": 1,
        "Touches": 12,
        "CarTouches": 10,
        "Demos": 0,
        "bHasCar": true,
        "Speed": 1400.0,
        "Boost": 72,
        "bBoosting": false,
        "bOnGround": true,
        "bOnWall": false,
        "bPowersliding": false,
        "bDemolished": false,
        "bSupersonic": false
      }
    ],
    "Game": {
      "Teams": [
        {
          "Name": "Blue",
          "TeamNum": 0,
          "Score": 1,
          "ColorPrimary": "#0000FF",
          "ColorSecondary": "#FFFFFF"
        },
        {
          "Name": "Orange",
          "TeamNum": 1,
          "Score": 0,
          "ColorPrimary": "#FF8800",
          "ColorSecondary": "#000000"
        }
      ],
      "TimeSeconds": 204,
      "bOvertime": false,
      "Frame": 6120,
      "Elapsed": 102.0,
      "Ball": {
        "Speed": 800.0,
        "TeamNum": 255
      },
      "bReplay": false,
      "bHasWinner": false,
      "Winner": "",
      "Arena": "Stadium_P",
      "bHasTarget": false
    }
  }
}
```

--------------------------------

### MatchDestroyed Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the match session is torn down.

```json
{
  "event": "MatchDestroyed",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### RoundStarted Event

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when a new round begins (after kickoff countdown).

```json
{
  "event": "RoundStarted",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### MatchEnded Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when a match finishes. Includes the winning team.

```json
{
  "event": "MatchEnded",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6",
    "WinnerTeamNum": 0
  }
}
```

--------------------------------

### PlayerRef Type

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Represents a reference to a player.

```json
{ "Name": "Psyonix", "Shortcut": 0, "TeamNum": 0 }
```

--------------------------------

### TeamState Type

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Represents the state of a team.

```json
{
  "Name": "Blue",
  "TeamNum": 0,
  "Score": 1,
  "ColorPrimary": "#0000FF",
  "ColorSecondary": "#FFFFFF"
}
```

--------------------------------

### StatfeedEvent Event

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired for statfeed notifications (Epic Save, Aerial Goal, Hat Trick, etc.).

```json
{
  "event": "StatfeedEvent",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6",
    "EventName": "EpicSave",
    "Type": "Save",
    "MainTarget": {
      "Name": "Psyonix",
      "Shortcut": 0,
      "TeamNum": 0
    },
    "SecondaryTarget": {
      "Name": "Ghosting",
      "Shortcut": 1,
      "TeamNum": 1
    }
  }
}
```

--------------------------------

### Vector3 Type

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Represents a 3D vector.

```json
{ "X": 0.0, "Y": 0.0, "Z": 0.0 }
```

--------------------------------

### ClockUpdatedSeconds Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired each second while the match clock is running.

```json
{
  "event": "ClockUpdatedSeconds",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6",
    "TimeSeconds": 187,
    "bOvertime": false
  }
}
```

--------------------------------

### GoalScored Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when a goal is scored.

```json
{
  "event": "GoalScored",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6",
    "GoalSpeed": 2280.5,
    "GoalTime": 155.3,
    "ImpactLocation": {
      "X": -42.0,
      "Y": -5120.0,
      "Z": 200.0
    },
    "Scorer": {
      "Name": "Psyonix",
      "Shortcut": 0,
      "TeamNum": 0
    },
    "Assister": {
      "Name": "Ghosting",
      "Shortcut": 1,
      "TeamNum": 0
    },
    "BallLastTouch": {
      "Player": {
        "Name": "Psyonix",
        "Shortcut": 0,
        "TeamNum": 0
      },
      "Speed": 2280.5
    }
  }
}
```

--------------------------------

### CrossbarHit Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the ball hits the crossbar.

```json
{
  "event": "CrossbarHit",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6",
    "BallLocation": {
      "X": 0.0,
      "Y": -5120.0,
      "Z": 642.775
    },
    "BallSpeed": 2100.3,
    "ImpactForce": 0.85,
    "BallLastTouch": {
      "Player": {
        "Name": "Psyonix",
        "Shortcut": 0,
        "TeamNum": 0
      },
      "Speed": 1980.0
    }
  }
}
```

--------------------------------

### MatchUnpaused Event

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the match resumes after a pause.

```json
{
  "event": "MatchUnpaused",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### MatchPaused Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when the match is paused.

```json
{
  "event": "MatchPaused",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6"
  }
}
```

--------------------------------

### BallHit Event Structure

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Fired when a player hits the ball.

```json
{
  "event": "BallHit",
  "data": {
    "MatchGuid": "A1B2C3D4E5F6",
    "Players": [
      {
        "Name": "Psyonix",
        "Shortcut": 0,
        "TeamNum": 0
      }
    ],
    "Ball": {
      "PreHitSpeed": 0.0,
      "PostHitSpeed": 1200.5,
      "Location": {
        "X": 120.0,
        "Y": -200.0,
        "Z": 95.0
      }
    }
  }
}
```

--------------------------------

### BallLastTouch Type

Source: https://github.com/manucabral/rlstatsapi/blob/main/docs/events.md

Represents the last touch on the ball.

```json
{
  "Player": { "Name": "Psyonix", "Shortcut": 0, "TeamNum": 0 },
  "Speed": 1980.0
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.