# Commonwealth Online Protocol V2

Protocol V2 is the transition layer between the current TCP JSON relay and the planned GameNetworkingSockets transport. The gameplay schema and validation rules are intended to survive the transport change.

## Session states

A TCP connection starts as **pending**. Pending connections receive a `welcome` packet but do not count against active player capacity and cannot own world/NPC authority.

A V2 client activates with:

```json
{"type":"hello","protocolVersion":2}
```

The server replies with `sessionReady`. During the client transition, legacy clients are temporarily activated by their first valid gameplay packet. This compatibility behavior is temporary and tracked by issue #3.

## Framing and limits

- Current transport: UTF-8 newline-delimited JSON over TCP
- Maximum line size: 64 KiB
- Handshake timeout: 10 seconds
- Active idle timeout: 60 seconds
- Packet rate: 120 packets/second per client, with sustained-window escalation
- Connection attempts: 8 per source IP per 10 seconds
- JSON `NaN`/`Infinity` values are rejected
- Outbound JSON is serialized with non-finite values disabled

## Interest management

Player transforms are no longer blindly broadcast to every connected player.

Peers are relevant when:

1. Their normalized `cellId` values match, or
2. They have the same non-empty `worldspaceId` and are within 8192 world units in the XY plane.

If an older client has not provided enough scope data yet, the server falls back to relaying for compatibility rather than hiding peers.

NPC snapshots are filtered per recipient using the same interest rule.

## Authority

Only **active** sessions can own world/NPC authority. A TCP probe or idle pending socket cannot become host.

The current global host is transitional. Per-cell/worldspace authority with epochs is tracked by issue #5.

## Transform validation

Required transform fields:

- `x`, `y`, `z`, `angleZ`: finite and bounded
- `cellId`: non-zero hex FormID
- `worldspaceId`: optional hex FormID

Optional V2-ready animation fields are normalized when present:

- `animationDirection`
- `aimPitch`
- `turnDelta`

Client capture/application work for those fields is tracked by issue #4.

## Combat

`combatHit` remains a targeted reliable-style gameplay event on the current transport. The relay now rejects malformed/non-finite values, duplicate or out-of-order sender sequences, self-targeting, disconnected targets, and targets outside the sender's interest scope.

Server-authoritative movement correction and stronger combat validation are tracked by issue #6.

## Transport migration

GameNetworkingSockets migration is tracked by issue #2. The intended split is:

- Unreliable/sequenced: transforms and NPC snapshots
- Reliable: session/control, actions, equipment, combat, world state, and authority changes