# Protocol Overview

The Commonwealth Online protocol defines the messages sent between Fallout 4 clients and the external server.

Early versions should stay simple and easy to debug.

## Early Design

The first version can use human-readable packets during testing.

Long-term versions may move to a binary protocol if performance becomes a problem.

## First Required Messages

- `welcome`
- `transform`
- `worldState`
- `worldStateHost`
- `serverWorldState`
- `disconnect`
- `ping`
- `pong`

## LAN Discovery (UDP)

Local server discovery uses a separate UDP channel so clients can find
Commonwealth Online relays on the LAN without scanning every TCP port.

- **Discovery port:** `7778` (UDP)
- **Game port:** `7777` (TCP) by default

### `discover` (client → server, UDP)

```json
{"type":"discover","protocol":"commonwealth-online","version":1}
```

### `discoverResponse` (server → client, UDP)

```json
{
  "type": "discoverResponse",
  "protocol": "commonwealth-online",
  "version": 1,
  "name": "Commonwealth Online Server",
  "port": 7777,
  "players": 2,
  "maxPlayers": 16
}
```

Clients should connect to the **source IP** of the UDP response using the
`port` from the response body.

If UDP discovery is unavailable, the plugin may fall back to probing
`127.0.0.1:7777` and the local LAN IPv4 address with a short TCP connect and
`welcome` handshake check.

## Main Rule

The protocol should be testable outside Fallout 4 before it is used inside the F4SE plugin.

`transform` packets carry position, movement state, optional `equippedItems`
apparel snapshots, and optional `appearance` snapshots for best-effort proxy
body/face visuals. The canonical field list and compatibility rules live in
[`protocol/packets.md`](../protocol/packets.md).