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:

{"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:

Their normalized cellId values match, or
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

2.8 KiB Raw Blame History