Networking

vgai’s networking is defined by a small contract (packages/engine/src/net/types.ts) so the engine doesn’t depend on any one netcode library; the concrete library (Colyseus today) lives inside a single implementer (packages/engine/src/net/colyseus.ts).

Server-authoritative sync.

The contract

• NetBackend.connect(opts) opens a connection and returns a live NetTransport.
• NetTransport is the send/recv/lifecycle half: sessionId (the stable id the server assigned this client), send(type, payload?), onMessage(type, handler), onLeave(handler), leave(), and a replication view.
• StateReplication is the server→client state half: onAdd(collection, handler), onRemove(collection, handler), onChange(item, handler), and onStateChange(handler) — all returning an unsubscribe function, none exposing Colyseus types.

Colyseus implementation

packages/engine/src/net/colyseus.ts is the one file that talks to @colyseus/sdk. It implements the contract over the Colyseus v0.17 Callbacks API (Callbacks.get(room) plus room.onStateChange), wrapping onAdd / onChange / onRemove.

Read live schema fields in onChange

Inside an onChange handler, read the schema instance’s fields live — do not destructure them into local copies at subscribe time, or you’ll capture stale values. This is the single most common Colyseus mistake.

Server-authoritative pattern

The typical shape: clients send() input up; the server room mutates authoritative @colyseus/schema state; that state syncs down and your onAdd / onChange handlers update the local scene. Defining a room and connecting a client is walked through in the Multiplayer guide.

See also

• Multiplayer — add a room, connect a client, the shipped examples.
• Entities & components — applying synced state to entities.