75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# 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
|