# TrackSim Gateway Public Viewer

*Connect and subscribe to a live company and game telemetry feed.*

## Connect to the Gateway

Public viewers connect to the following secure WebSocket endpoint:

```text
wss://gateway.tracksim.app/v1/ws
```

No account or API key is required. This guide covers subscribing to and receiving a public feed.

Clients send UTF-8 JSON text frames. Binary frames are not part of protocol version 1. Incoming messages are limited to 256 KiB by default.

## Subscribe to a feed

The first valid message must establish the connection as a public viewer before the server's configured `WS_ROLE_TIMEOUT_MS` expires. Send a `subscribe` operation with the company and game feed you want to view:

```json
{
  "version": 1,
  "op": "subscribe",
  "data": {
    "company_id": 42,
    "game": "eut2"
  }
}
```

| Property | Type | Description |
|----------|------|-------------|
| `version` | `integer` | Protocol version. Use `1`. |
| `op` | `string` | Operation name. Use `subscribe` for a public viewer. |
| `data.company_id` | `integer` | Company whose live feed you want to view. |
| `data.game` | `string` | Game feed to view, for example `eut2`. |

Once this message is accepted, the connection is subscribed as a public viewer. Unsupported operations produce an `ERROR` event.

## Subscription confirmation

The Gateway confirms the active feed with a `SUBSCRIBED` event:

```json
{
  "version": 1,
  "op": "event",
  "type": "SUBSCRIBED",
  "data": {
    "company_id": 42,
    "game": "eut2",
    "snapshot_interval_ms": 1000
  }
}
```

The `snapshot_interval_ms` value tells you how often the Gateway is configured to send snapshots for this subscription.

## Receive telemetry snapshots

After confirmation, the Gateway sends full `TELEMETRY_SNAPSHOT` events at the configured interval:

```json
{
  "version": 1,
  "op": "event",
  "type": "TELEMETRY_SNAPSHOT",
  "data": {
    "company_id": 42,
    "game": "eut2",
    "generated_at_ms": 1794570360604,
    "drivers": [
      {
        "driver": "76561198000000000",
        "username": "Example Driver",
        "vehicle_type": "truck",
        "job": {
          "cargo": {
            "name": "Ketchup"
          },
          "source": {
            "city": {
              "name": "Parma"
            },
            "company": {
              "name": "Tesoro Gustoso"
            }
          },
          "destination": {
            "city": {
              "name": "Jyväskylä"
            },
            "company": {
              "name": "Vitas Power"
            }
          }
        },
        "multiplayer": {
          "mode": "truckersmp",
          "meta": {
            "player_id": "625",
            "server": "Server 4"
          }
        },
        "promods": false,
        "route": [
          {
            "time": 1794570056,
            "x": 28405.616455078125,
            "z": -15799.825675964355
          },
          {
            "time": 1794570061,
            "x": 28472.11004638672,
            "z": -15846.144718170166
          }
        ],
        "trailers": [
          {
            "attached": true,
            "body": "curtainside",
            "current_damage": {
              "chassis": 0.027918556705117226
            },
            "hook": {
              "x": 0,
              "y": 1,
              "z": -4.968114376068115
            },
            "position": {
              "x": 29667.296087265015,
              "z": -19123.01481628418
            },
            "rotation": {
              "heading": 0.7329810857772827
            }
          }
        ],
        "truck": {
          "brand": {
            "name": "DAF"
          },
          "current_damage": {
            "cabin": 0.009309615008533001,
            "chassis": 0.011637018993496895,
            "engine": 0.011725571006536484,
            "transmission": 0.010460477322340012,
            "wheels": 0.17786727845668793
          },
          "fuel": {
            "amount": 367.2578125
          },
          "hook": {
            "x": 0,
            "y": 0.999744176864624,
            "z": 1.6522263288497925
          },
          "name": "NGD",
          "position": {
            "x": 29673.877025604248,
            "z": -19122.310256958008
          },
          "speed": 24.90380605061849
        }
      }
    ]
  }
}
```

| Property | Type | Description |
|----------|------|-------------|
| `version` | `integer` | Protocol version. |
| `op` | `string` | `event` for server events. |
| `type` | `string` | `TELEMETRY_SNAPSHOT` for a full feed snapshot. |
| `data.company_id` | `integer` | Company represented by this snapshot. |
| `data.game` | `string` | Game represented by this snapshot. |
| `data.generated_at_ms` | `integer` | Snapshot generation time in Unix milliseconds. |
| `data.drivers` | `array` | Full list of drivers currently included in the feed. The list can be empty. |

Treat each event as a complete snapshot of the active feed rather than a partial update.

### Driver object

| Property | Type | Description |
|----------|------|-------------|
| `driver` | `string` | Driver Steam ID. |
| `username` | `string` | Driver display name. |
| `vehicle_type` | `string` or `null` | Current vehicle category, for example `truck` or `car`. |
| `job` | `object` or `null` | Current delivery details. `null` when the driver has no active job. |
| `multiplayer` | `object` | Multiplayer mode and its metadata. Values can be empty outside a supported multiplayer session. |
| `promods` | `boolean` | Whether ProMods is active for the driver. |
| `route` | `array` | Recent timestamped game-world positions. The list can be empty. |
| `trailers` | `array` | Current trailer objects. The list can be empty. |
| `truck` | `object` | Current vehicle telemetry. |

### Job object

| Property | Type | Description |
|----------|------|-------------|
| `cargo.name` | `string` | Cargo display name. |
| `source.city.name` | `string` | Origin city. |
| `source.company.name` | `string` | Origin company. |
| `destination.city.name` | `string` | Destination city. |
| `destination.company.name` | `string` | Destination company. |

### Multiplayer object

| Property | Type | Description |
|----------|------|-------------|
| `mode` | `string` | Multiplayer integration, for example `truckersmp` or `haulmp`. Can be an empty string. |
| `meta.player_id` | `string` | Player identifier reported by the multiplayer integration. Can be empty. |
| `meta.server` | `string` | Connected server name. Can be empty. |

### Route point

| Property | Type | Description |
|----------|------|-------------|
| `time` | `integer` | Route sample timestamp in Unix seconds. |
| `x` | `number` | Game-world X coordinate. |
| `z` | `number` | Game-world Z coordinate. |

### Truck object

| Property | Type | Description |
|----------|------|-------------|
| `brand.name` | `string` | Vehicle manufacturer. |
| `name` | `string` | Vehicle model name. |
| `current_damage` | `object` | Current `cabin`, `chassis`, `engine`, `transmission`, and `wheels` damage values. |
| `fuel.amount` | `number` | Current fuel amount reported by telemetry. |
| `hook` | `object` | Hook `x`, `y`, and `z` coordinates. |
| `position` | `object` | Current game-world `x` and `z` coordinates. |
| `speed` | `number` | Current speed reported by telemetry. |

### Trailer object

| Property | Type | Description |
|----------|------|-------------|
| `attached` | `boolean` | Whether the trailer is attached. |
| `body` | `string` | Trailer body type. |
| `current_damage.chassis` | `number` | Current trailer chassis damage. |
| `hook` | `object` | Trailer hook `x`, `y`, and `z` coordinates. |
| `position` | `object` | Trailer game-world `x` and `z` coordinates. |
| `rotation.heading` | `number` | Trailer heading. |

## Change feeds

A public viewer may switch feeds without reconnecting. Send another `subscribe` operation with the new `company_id` and `game`. Wait for the next `SUBSCRIBED` event before treating the new feed as active.

## Browser example

```javascript
const socket = new WebSocket("wss://gateway.tracksim.app/v1/ws");

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    version: 1,
    op: "subscribe",
    data: {
      company_id: 42,
      game: "eut2",
    },
  }));
});

socket.addEventListener("message", ({ data }) => {
  const message = JSON.parse(data);

  if (message.op !== "event") return;

  if (message.type === "SUBSCRIBED") {
    console.log("Active Gateway feed", message.data);
  }

  if (message.type === "TELEMETRY_SNAPSHOT") {
    console.log("Telemetry snapshot", message.data);
  }

  if (message.type === "ERROR") {
    console.error("Gateway error", message);
  }
});
```

## Errors and connection closure

An operation that is invalid for a public viewer produces an `ERROR` event. A fatal error is followed by the Gateway closing the WebSocket connection.

When reconnecting after a closure, open a new WebSocket and send the subscription again within `WS_ROLE_TIMEOUT_MS`. Do not assume that the previous feed remains active.

## Slow-viewer protection

The Gateway applies backpressure so a slow viewer does not accumulate an unbounded queue of snapshots:

- A snapshot is skipped while the socket buffer exceeds `SLOW_CLIENT_MAX_BUFFER_BYTES`.
- After `SLOW_CLIENT_MAX_SKIPS` consecutive skips, the Gateway closes the connection as retryable.

If this happens repeatedly, make snapshot processing faster and avoid blocking the WebSocket message handler before reconnecting.
