> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playpicklx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event types

> The five sensor events and their payloads.

The protocol defines **five event types** an event source can send. Each shares the common
[envelope](/endpoint#request-body) and adds a type-specific `payload`.

| Type              | Payload                                 | Description                       |
| ----------------- | --------------------------------------- | --------------------------------- |
| `BALL_BOUNCE`     | `{ x_ft, y_ft, is_in }`                 | A ball landing on the court.      |
| `BALL_HIT`        | `{ player_id, shot_type, swing_type? }` | A player striking the ball.       |
| `BALL_SPEED`      | `{ kmh }`                               | A ball-speed reading.             |
| `PLAYER_POSITION` | `{ player_id, x_ft, y_ft }`             | A player's position on the court. |
| `PLAYER_IDENTITY` | `{ player_id }`                         | Identifies a player.              |

## Coordinate frame

Positional payloads (`BALL_BOUNCE`, `PLAYER_POSITION`) use **court feet on the receiving
half**:

* `x_ft` — feet from the left sideline (expected range ≈ 0–20)
* `y_ft` — feet from the net (expected range ≈ 0–22)

<Note>
  These ranges describe the expected court frame; they are not a hard validation bound.
  Send coordinates already mapped to the court frame. If your sensor reports a different
  frame, PicklX fits a per-integration adapter at the boundary.
</Note>

## Examples

<CodeGroup>
  ```json BALL_BOUNCE theme={null}
  {
    "event_id": "b7e3a91c4f25d8a0c1e6f3b2",
    "session_id": "session-court1-20260609-001",
    "venue_id": "venue-la-01",
    "court_id": "court-1",
    "eot": "2026-06-09T20:00:06.120Z",
    "type": "BALL_BOUNCE",
    "confidence": 0.95,
    "source": "your-system",
    "schema_version": "1.0",
    "revision": 0,
    "payload": { "x_ft": 4.2, "y_ft": 19.3, "is_in": true }
  }
  ```

  ```json BALL_HIT theme={null}
  {
    "event_id": "a1c9e2d74b06f8e3a5d0c4b1",
    "session_id": "session-court1-20260609-001",
    "venue_id": "venue-la-01",
    "court_id": "court-1",
    "eot": "2026-06-09T20:00:05.480Z",
    "type": "BALL_HIT",
    "confidence": 0.98,
    "source": "your-system",
    "schema_version": "1.0",
    "revision": 0,
    "payload": { "player_id": "player-7f3a", "shot_type": "GROUNDSTROKE", "swing_type": "BACKHAND" }
  }
  ```

  ```json BALL_SPEED theme={null}
  {
    "event_id": "c4f0b6a83d17e9c2b5a8d1e0",
    "session_id": "session-court1-20260609-001",
    "venue_id": "venue-la-01",
    "court_id": "court-1",
    "eot": "2026-06-09T20:00:05.480Z",
    "type": "BALL_SPEED",
    "confidence": 0.9,
    "source": "your-system",
    "schema_version": "1.0",
    "revision": 0,
    "payload": { "kmh": 57.2 }
  }
  ```

  ```json PLAYER_POSITION theme={null}
  {
    "event_id": "d8a2c5e91f40b7d3a6c0e2f4",
    "session_id": "session-court1-20260609-001",
    "venue_id": "venue-la-01",
    "court_id": "court-1",
    "eot": "2026-06-09T20:00:07.900Z",
    "type": "PLAYER_POSITION",
    "confidence": 0.85,
    "source": "your-system",
    "schema_version": "1.0",
    "revision": 0,
    "payload": { "player_id": "player-7f3a", "x_ft": 9.5, "y_ft": 6.4 }
  }
  ```

  ```json PLAYER_IDENTITY theme={null}
  {
    "event_id": "e2b7d0f63a59c8e1b4d7f0a3",
    "session_id": "session-court1-20260609-001",
    "venue_id": "venue-la-01",
    "court_id": "court-1",
    "eot": "2026-06-09T20:45:00.000Z",
    "type": "PLAYER_IDENTITY",
    "confidence": 0.92,
    "source": "your-system",
    "schema_version": "1.0",
    "revision": 0,
    "payload": { "player_id": "player-7f3a" }
  }
  ```
</CodeGroup>