Networking Overview

Deterministic Mode

Frame numbers are the primary packet identifier. Input replication is the sync mechanism. State replication is optional — useful only as a divergence correction signal.

• All peers must run at the same logic Hz
• Slow clients are a policy problem, not an architectural one: rollback fast-forwards them back; disconnect policy handles unrecoverable deficit
• Suited for competitive play where simulation integrity is paramount

Non-Deterministic Mode

Server timestamps (server_time_us) replace frame numbers as the primary packet identifier. State replication is the primary sync signal — not optional in practice, since clients cannot guarantee identical outcomes.

• Clients can run at any logic frame rate
• Uncapped renderer interpolates smoothly between 30Hz snapshots regardless of local frame rate
• Suited for co-op, casual games, or games with variable client performance expectations

The TNet policy axis encodes which mode a given build uses. AuthoritySim and OwnerSim currently implement Deterministic Mode only. Non-Deterministic Mode requires a separate rewrite of those paths — see Known Gaps.

GNSContext

Thin wrapper around GNS library init/teardown. Isolates GNS headers from the rest of the engine. Statically linked. One per process lifetime.

NetConnectionManager

Socket API: Listen(port) / Connect(address, port), PollIncoming() / Send().

Per-connection state (ConnectionInfo): GNS handle, OwnerID, sequence numbers, RTT, ack bitfield, ClientRepState machine. Max simultaneous connections = 2^NetOwnerID_Bits (currently 8 bits → 256 connections).

NetThread

Dedicated network poller. Default rate: 30Hz (configurable via INI NetworkUpdateHz). Runs HandleMessage dispatch loop.

NetChannel

Per-connection typed send API — the natural home for all future per-connection state (delta compression baselines, coalescing buffers, reliability policy tables, RPC dispatch).

class NetChannel
{
    uint8_t OwnerID;

    template<typename T>
    void Send(NetMessageType type, const T& payload);

    template<typename T>
    void SendTo(uint8_t targetOwnerID, NetMessageType type, const T& payload);

    void Flush();
};

All gameplay messages route through the Authority. The Owner specifies a target OwnerID; the Authority relays without inspecting the payload. This is addressed routing, not multicast — no "everyone filters it" overhead.

EntityNetHandle

Packed uint32_t: NetOwnerID:8 | NetIndex:24. OwnerID 0 = Authority/global, 1–255 = Owners. NetIndex allocated per entity on the Authority. NetToRecord[] maps NetIndex → EntityRecord.

Three handle spaces in Registry:

EntityRef vs EntityNetHandle (Two-Tier)

Internal (32-bit) EntityNetHandle: Used exclusively inside engine systems. Compact, fast, no generation. Valid on bulk paths where the Authority is pushing state.

External (64-bit) EntityRef: Used in gameplay code, RPCs, and all Owner→Authority messages. Embeds the generation captured at spawn time for ABA protection.

struct EntityRef {
    EntityNetHandle Handle;      // 32-bit wire handle
    uint16_t        Generation;  // from GlobalEntityHandle::Generation at spawn
    uint16_t        Flags;       // IsPredicted:1, IsOwned:1, reserved:14
};  // 8 bytes total

When an Owner sends a targeted message, the Authority validates the generation before any state mutation. Stale references are rejected.

ConstructHandle (Planned)

Pure-logic Constructs (Soul, GameMode, AIDirector) have no EntityNetHandle — they're not entities. ConstructHandle fills this gap:

struct ConstructHandle {  // fits in uint32_t
    uint8_t  OwnerID;     // Soul that owns this Construct (0 = Authority-owned)
    uint16_t LocalIndex;  // index into that owner's ConstructRegistry PagedMap
    uint8_t  Generation;  // stale-handle detection
};

RPCs targeting a Construct as a whole use ConstructHandle. Multi-entity Constructs (Turret with barrel + base entities) have multiple EntityNetHandles but one ConstructHandle.

AuthorityClass Tags

Each entity in a ListenNet game carries an AuthorityClass tag that governs authority transfer:

Prerequisites Already Satisfied

Migration requires no new infrastructure — only assembly of existing parts:

• Temporal ring buffer — every peer has recent state history available as a snapshot
• Base frame offset per client — re-anchoring to a new host is recalculating the offset
• Health metrics — a degrading host is detectable before full disconnection
• Input windowing — already active; retransmit input stream to new host to cover the gap

Handshake Protocol

1. Old host continues simulating and acting as Authority during the handshake window
2. Old host sends explicit state and input stream to the migration candidate
3. New host fast-forwards via rollback until its snapshot matches
4. New host signals ready and notifies all connected peers
5. Old host receives confirmation and stops sending state snapshots
6. Authority transfer complete — peers experience no gap

Candidate Election

• Ranked by latency and snapshot recency; freshest snapshot wins ties
• Old host does not relinquish authority until it receives explicit confirmation from the new host that all peers have been notified

Handshake Timeout and Candidate Failure

If the old host detects candidate loss: abort handshake, reassert full authority, select next ranked candidate, restart handshake.

Memory Constraint

No logical host/client split exists internally — preallocated slabs make doubling the footprint unreasonable. Migration serializes into snapshot format and transmits to the new host, which deserializes into its own preallocated slab. This serialization path also serves save states, late join, reconnect, and debug replay.

Status: Designed, not yet implemented. Requires the snapshot serialization path first.