From e7f44caa854616e51c76d6c320d9f3083b145b91 Mon Sep 17 00:00:00 2001
From: Nomads_Reach <144523850+NomadsReach@users.noreply.github.com>
Date: Sat, 15 Aug 2026 21:06:06 -0400
Subject: [PATCH] Document the Protocol V2 transition contract

---
 server/PROTOCOL_V2.md | 74 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 server/PROTOCOL_V2.md

diff --git a/server/PROTOCOL_V2.md b/server/PROTOCOL_V2.md
new file mode 100644
index 0000000..288c4e4
--- /dev/null
+++ b/server/PROTOCOL_V2.md
@@ -0,0 +1,74 @@
+# 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