Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add netcode addon: state sync with pluggable transport and authority (part of #778)

Nguyen Xuan An22cdadbf91d3
diff --git a/README.md b/README.md
index a6c49b51..dc26b745 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,7 @@ Each addon is a separate import, so a page loads only what it uses.
| Physics | `67js/addons/physics` | [Rapier contacts and joints](docs/physics.md) recorded into a timeline |
| Live games | `67js/addons/runtime` | [Game loop](docs/runtime.md) with fixed or variable steps and pluggable systems |
| Live games | `67js/addons/streaming` | [Streaming](docs/streaming.md): loader plugins, distance and request loading, a byte budget with LRU eviction and LOD with hysteresis |
+| Live games | `67js/addons/netcode` | [Netcode](docs/netcode.md): server or host authority, pluggable transports, delta snapshots, client prediction with reconciliation and remote interpolation |
| Live games | `67js/addons/input` | [Input](docs/input.md): keyboard, mouse, gamepad and custom sources mapped to named actions and axes |
| Live games | `67js/addons/animation-graph` | [Animation graph](docs/animation-graph.md): states, 1D and 2D blend spaces, parameter transitions with crossfades and masked layers for any rig |
| Live games | `67js/addons/player` | [Player](docs/player.md): character controller, follow, first-person and top-down camera rigs, swappable at runtime |
diff --git a/changes/778.md b/changes/778.md
new file mode 100644
index 00000000..1bbd02fe
--- /dev/null
+++ b/changes/778.md
@@ -0,0 +1 @@
+- `67js/addons/netcode` adds `createNetcode`, a runtime system for multiplayer state sync: server or host authority, a transport plugin interface with an in-memory loopback (seeded latency, jitter and loss) and a WebSocket wrapper, bounded delta snapshots with quantisation, client prediction with reconciliation and remote interpolation (first slice of #778)
diff --git a/docs/netcode.md b/docs/netcode.md
new file mode 100644
index 00000000..91e6a680
--- /dev/null
+++ b/docs/netcode.md
@@ -0,0 +1,80 @@
+# Netcode: multiplayer state sync
+
+`67js/addons/netcode` is a [runtime](runtime.md) system for multiplayer. One side is the authority and owns the truth. It applies every client's input and sends bounded delta snapshots. A client predicts its own entity, corrects it when a snapshot arrives and draws the other entities slightly in the past, between two snapshots. It loads only when imported, adds no dependency and opens no connection or timer.
+
+```js
+import { createRuntime } from '67js/addons/runtime';
+import { createNetcode, createWebSocketTransport } from '67js/addons/netcode';
+
+// Server (or host): owns the truth.
+const server = createNetcode({ role: 'authority', authority: 'server', transport: serverTransport });
+server.addEntity('alice', { owner: 'alice', tag: 'player' });
+server.addEntity('crate', { tag: 'prop', state: { position: [3, 1, 3], variables: { health: 10 } } });
+
+// Client: predicts 'alice', interpolates the rest.
+const client = createNetcode({
+ role: 'client',
+ serverId: 'server',
+ localEntityId: 'alice',
+ transport: createWebSocketTransport(socket, { id: 'alice', remoteId: 'server' }),
+ readInput: () => ({ moveX: keys.right - keys.left, moveZ: keys.down - keys.up }),
+});
+createRuntime(renderer, { fixedRate: 50, systems: [client] }).start();
+// each frame: client.getEntityState('crate') -> { position, rotation, velocity, variables }
+```
+
+## Authority
+
+`authority: 'server'` is a dedicated authority with no player. `authority: 'host'` is a player who also runs the world: give it `readInput` and an entity it owns (`owner` is its own transport id) and it plays with no prediction. `'peer'` (peer to peer) is reserved and throws until it exists.
+
+The authority methods are `addEntity(id, { owner, tag, state })`, `removeEntity(id)` and `setEntityState(id, partialState)`. `owner` is the transport peer id whose input drives the entity (one entity per peer). An entity without an owner is driven by game code: a physics prop, a door, a score. Write its state with `setEntityState` each step. Parts left out keep their value.
+
+An entity state is `{ position: [x, y, z], rotation: [x, y, z, w], velocity: [x, y, z], variables: { name: number } }`. Parts you leave out start at zero, identity rotation and no variables.
+
+## Simulation and input
+
+Client and authority run the same pure function `simulate(state, input, stepSeconds) -> state` for each input, so the client can predict. The default is `createPlanarMovement({ speed: 5 })`: input `{ moveX, moveZ }` from -1 to 1 sets a flat velocity. Pass your own `simulate` for jumping, collisions or anything else, and keep it deterministic. An input is an object of at most 16 numbers and booleans.
+
+Each fixed step the client samples `readInput`, applies it to its predicted entity at once and sends it with a sequence number, the last `inputRedundancy` unconfirmed inputs together so one lost packet costs nothing. The authority applies each sequence once, in order. It holds a small jitter buffer (`inputBufferSteps`) so remote movement stays even, and catches up when a backlog builds.
+
+## Snapshots
+
+Every `snapshotEveryTicks` fixed steps (default 2) the authority builds one snapshot of all entities, quantised to integers (`positionStep` 0.01, `rotationStep` 0.001, `velocityStep` 0.01, `variableStep` 0.01) and sends each peer a delta against the last snapshot that peer acknowledged. A peer that has acknowledged nothing, or whose base is too old, gets a full snapshot. A lost snapshot is repaired by the next one, since the delta base only moves forward on acknowledgement. Stale and out-of-order snapshots are dropped.
+
+## Prediction, reconciliation and interpolation
+
+When a snapshot arrives the client takes the authoritative state of its entity, drops the inputs the authority has already applied (`lastProcessedInput`) and replays the rest through `simulate`. If the prediction was right the result does not move; if not, the entity is corrected in one step (`stats.lastCorrection`, `stats.maximumCorrection`). Smooth a big correction in your drawing code if the look needs it.
+
+Other entities are drawn `interpolationDelaySeconds` (default 0.1) behind the newest snapshot, blended between the two samples around that time. Past the newest sample the entity carries on at its velocity for at most `maximumExtrapolationSeconds` (0.25). The drawing clock follows real time and is nudged by at most 10 percent toward the target, so a late packet slows the clock instead of jumping the entity. Raise the delay on a jittery connection.
+
+`getEntityState(id)` returns the state to draw: the truth on the authority, the prediction for `localEntityId`, the interpolation for the rest.
+
+## Transports
+
+A transport is a plain object `{ id, peers(), send(peerId, message), receive(callback) }`. `peers()` returns the connected peer ids, `send` takes a JSON-compatible object and must not throw for a transient failure, and `receive(callback)` registers `callback(peerId, message)` and returns a function that unregisters it. Write your own for WebRTC or WebTransport.
+
+- `createLoopbackNetwork({ seed, latencyMilliseconds, jitterMilliseconds, lossRate })` is an in-memory network for tests. `network.createTransport(id)` adds a peer; `network.advance(milliseconds)` moves time and delivers what is due. Latency, jitter and loss come from the seeded generator, so a seed repeats a run exactly. Messages are copied through JSON and may arrive out of order.
+- `createWebSocketTransport(socket, { id, remoteId, multiplexed, maximumMessageBytes })` wraps a socket-like object you opened (`send(text)`, `addEventListener`, `readyState`, `close()`). By default it is a line to one peer, `remoteId`. With `multiplexed: true` it speaks to a relay that wraps messages as `{ to, data }` going out and `{ from, data }` coming in (and `{ from, left: true }` when a peer leaves), so a server or host can hear many clients.
+
+## Options and bounds
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `role` | `'client'` | `'authority'` or `'client'` |
+| `authority` | `'server'` | `'server'` or `'host'` |
+| `transport` | required | The transport above |
+| `serverId` | required for a client | Peer id of the authority |
+| `localEntityId` | none | The entity a client predicts |
+| `simulate`, `readInput` | planar movement, none | See above |
+| `snapshotEveryTicks` | 2 | 1 to 60 |
+| `inputRedundancy`, `inputBufferSteps` | 3, 3 | Inputs resent per message (1 to 8), authority jitter buffer (0 to 16) |
+| `interpolationDelaySeconds`, `maximumExtrapolationSeconds` | 0.1, 0.25 | 0 to 2 |
+| `maximumMessageBytes` | 65536 | A snapshot over this throws; up to 1 MB |
+
+`NETCODE_LIMITS` holds the hard bounds: 256 entities, 32 peers, 16 variables per entity, names up to 64 characters, 8 inputs per message, 64 queued inputs per peer, 64 snapshots of history. Network input is untrusted: a bad message is counted in `stats.rejectedMessages` and ignored, never thrown. Option and call errors say what to pass.
+
+`stats` reports `snapshotsSent`, `fullSnapshotsSent`, `bytesSent`, `inputsProcessed`, `snapshotsReceived`, `staleSnapshots`, `missingBaseSnapshots`, `reconciliations`, `lastCorrection`, `maximumCorrection` and `rejectedMessages`.
+
+## Not yet
+
+WebRTC and WebTransport transports, peer-to-peer authority, a reference relay on a free host and a two-browser sample game come in later slices of #778. Use the same `fixedRate` on the authority and every client.
diff --git a/package.json b/package.json
index 9bfa7975..25b85833 100644
--- a/package.json
+++ b/package.json
@@ -43,6 +43,7 @@
"docs/physics.md",
"docs/runtime.md",
"docs/streaming.md",
+ "docs/netcode.md",
"docs/input.md",
"docs/animation-graph.md",
"docs/player.md",
@@ -124,6 +125,7 @@
"./addons/cloth": "./build/cloth.js",
"./addons/runtime": "./build/runtime.js",
"./addons/streaming": "./build/streaming.js",
+ "./addons/netcode": "./build/netcode.js",
"./addons/input": "./build/input.js",
"./addons/animation-graph": "./build/animation-graph.js",
"./addons/player": "./build/player.js",
diff --git a/scripts/prepare-release.mjs b/scripts/prepare-release.mjs
index 2328c902..1b8d3ec7 100644
--- a/scripts/prepare-release.mjs
+++ b/scripts/prepare-release.mjs
@@ -53,7 +53,7 @@ const sourceDocuments = [
'vehicle.md',
'vegetation.md', 'terrain.md', 'grass.md', 'clutter.md', 'light-bake.md', 'path-tracer.md', 'gaussian-splats.md',
'camera-path.md', 'lighting.md', 'volumetric.md', 'film-physics.md',
- 'runtime.md', 'streaming.md', 'input.md', 'player.md', 'animation-graph.md', 'surface-attachment.md', 'agent-scene.md', 'mcp.md', 'agent-look.md', 'agent-asset.md', 'agent-render-jobs.md', 'agent-motion.md', 'agent-character-motion.md', 'agent-review.md',
+ 'runtime.md', 'streaming.md', 'netcode.md', 'input.md', 'player.md', 'animation-graph.md', 'surface-attachment.md', 'agent-scene.md', 'mcp.md', 'agent-look.md', 'agent-asset.md', 'agent-render-jobs.md', 'agent-motion.md', 'agent-character-motion.md', 'agent-review.md',
];
for (const name of sourceDocuments) {
await copyFile(resolve(root, 'docs', name), resolve(root, 'public', name));
diff --git a/src/netcode.js b/src/netcode.js
new file mode 100644
index 00000000..c02632be
--- /dev/null
+++ b/src/netcode.js
@@ -0,0 +1,907 @@
+// Multiplayer state sync as a runtime system. One side is the authority (a dedicated server or a host player) and owns the
+// truth. It applies every client's inputs, then sends bounded delta snapshots of its entities. A client predicts its own
+// entity from its own input, corrects it when the authoritative state arrives (reconciliation) and draws the other entities
+// a little in the past, between two snapshots (interpolation). The transport is a plugin: any object with
+// { id, peers(), send(peerId, message), receive(callback) }. This file ships an in-memory loopback for tests and a wrapper
+// for a socket-like object. Nothing here opens a connection or a timer. See docs/netcode.md.
+
+export const NETCODE_AUTHORITIES = Object.freeze(['server', 'host']);
+export const NETCODE_ROLES = Object.freeze(['authority', 'client']);
+
+export const NETCODE_LIMITS = Object.freeze({
+ maximumEntities: 256,
+ maximumPeers: 32,
+ maximumNameLength: 64,
+ maximumVariablesPerEntity: 16,
+ maximumInputKeys: 16,
+ maximumInputsPerMessage: 8,
+ maximumQueuedInputsPerPeer: 64,
+ maximumPendingInputs: 128,
+ maximumSnapshotHistory: 64,
+ maximumSamplesPerEntity: 32,
+ maximumInputRedundancy: 8,
+ maximumInputsPerStep: 8,
+ maximumCoordinate: 100000,
+ maximumMessageBytes: 1048576,
+ defaultMessageBytes: 65536,
+});
+
+const DEFAULTS = Object.freeze({
+ snapshotEveryTicks: 2,
+ inputRedundancy: 3,
+ inputBufferSteps: 3,
+ interpolationDelaySeconds: 0.1,
+ maximumExtrapolationSeconds: 0.25,
+ clockCorrectionRate: 0.1,
+ positionStep: 0.01,
+ rotationStep: 0.001,
+ velocityStep: 0.01,
+ variableStep: 0.01,
+ movementSpeed: 5,
+});
+
+const VECTOR_FIELDS = Object.freeze([
+ Object.freeze({ wire: 'p', name: 'position', length: 3, stepOption: 'positionStep' }),
+ Object.freeze({ wire: 'r', name: 'rotation', length: 4, stepOption: 'rotationStep' }),
+ Object.freeze({ wire: 'v', name: 'velocity', length: 3, stepOption: 'velocityStep' }),
+]);
+
+const MAXIMUM_WIRE_INTEGER = 1e12;
+
+function describe(value) {
+ return value === null ? 'null' : typeof value;
+}
+
+function isPlainObject(value) {
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireName(value, label) {
+ if (typeof value !== 'string' || value === '' || value.length > NETCODE_LIMITS.maximumNameLength) {
+ throw new TypeError(`${label} must be a string of 1 to ${NETCODE_LIMITS.maximumNameLength} characters, got ${typeof value === 'string' ? `${value.length} characters` : describe(value)}.`);
+ }
+ return value;
+}
+
+function boundedNumber(value, label, minimum, maximum) {
+ if (!Number.isFinite(value) || value < minimum || value > maximum) {
+ throw new RangeError(`${label} must be a number from ${minimum} to ${maximum}, got ${String(value)}.`);
+ }
+ return value;
+}
+
+function boundedInteger(value, label, minimum, maximum) {
+ if (!Number.isInteger(value) || value < minimum || value > maximum) {
+ throw new RangeError(`${label} must be an integer from ${minimum} to ${maximum}, got ${String(value)}.`);
+ }
+ return value;
+}
+
+function createSeededRandom(seed) {
+ let state = seed >>> 0;
+ return () => {
+ state = (state + 0x6d2b79f5) >>> 0;
+ let mixed = Math.imul(state ^ (state >>> 15), state | 1);
+ mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+ return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+function validateTransport(transport, label) {
+ if (!isPlainObject(transport)) {
+ throw new TypeError(`${label} needs a transport: an object like { id, peers(), send(peerId, message), receive(callback) }, got ${describe(transport)}.`);
+ }
+ requireName(transport.id, `${label} transport.id`);
+ for (const method of ['peers', 'send', 'receive']) {
+ if (typeof transport[method] !== 'function') {
+ throw new TypeError(`${label} transport.${method} must be a function. A transport is { id, peers(), send(peerId, message), receive(callback) }.`);
+ }
+ }
+}
+
+// ----- State: one entity is a position, a rotation, a velocity and a few named numbers -----
+
+function readVector(value, length, label) {
+ if (!Array.isArray(value) || value.length !== length) {
+ throw new TypeError(`${label} must be an array of ${length} numbers, got ${Array.isArray(value) ? `${value.length} entries` : describe(value)}.`);
+ }
+ return value.map((component, index) => boundedNumber(component, `${label}[${index}]`, -NETCODE_LIMITS.maximumCoordinate, NETCODE_LIMITS.maximumCoordinate));
+}
+
+function readVariables(value, label) {
+ if (!isPlainObject(value)) throw new TypeError(`${label} must be an object of named numbers like { score: 3 }, got ${describe(value)}.`);
+ const names = Object.keys(value);
+ if (names.length > NETCODE_LIMITS.maximumVariablesPerEntity) {
+ throw new RangeError(`${label} holds ${names.length} variables; at most ${NETCODE_LIMITS.maximumVariablesPerEntity} are synced per entity.`);
+ }
+ const variables = {};
+ for (const name of names) {
+ requireName(name, `${label} variable name`);
+ variables[name] = boundedNumber(value[name], `${label}.${name}`, -NETCODE_LIMITS.maximumCoordinate, NETCODE_LIMITS.maximumCoordinate);
+ }
+ return variables;
+}
+
+// Fills the parts a caller left out. `base` supplies them when it is given, so a partial update keeps the rest.
+function readState(candidate, label, base = null) {
+ if (!isPlainObject(candidate)) throw new TypeError(`${label} must be an object like { position, rotation, velocity, variables }, got ${describe(candidate)}.`);
+ const state = {
+ position: candidate.position === undefined ? [...(base?.position ?? [0, 0, 0])] : readVector(candidate.position, 3, `${label}.position`),
+ rotation: candidate.rotation === undefined ? [...(base?.rotation ?? [0, 0, 0, 1])] : readVector(candidate.rotation, 4, `${label}.rotation`),
+ velocity: candidate.velocity === undefined ? [...(base?.velocity ?? [0, 0, 0])] : readVector(candidate.velocity, 3, `${label}.velocity`),
+ variables: candidate.variables === undefined ? { ...(base?.variables ?? {}) } : readVariables(candidate.variables, `${label}.variables`),
+ };
+ return state;
+}
+
+function cloneState(state) {
+ return {
+ position: [...state.position],
+ rotation: [...state.rotation],
+ velocity: [...state.velocity],
+ variables: { ...state.variables },
+ };
+}
+
+function distanceBetween(first, second) {
+ return Math.hypot(first[0] - second[0], first[1] - second[1], first[2] - second[2]);
+}
+
+// ----- Inputs: a small object of numbers and booleans, checked on both ends -----
+
+function readInput(candidate, label) {
+ if (!isPlainObject(candidate)) throw new TypeError(`${label} must be an object of numbers and booleans like { moveX: 1, jump: true }, got ${describe(candidate)}.`);
+ const names = Object.keys(candidate);
+ if (names.length > NETCODE_LIMITS.maximumInputKeys) {
+ throw new RangeError(`${label} has ${names.length} keys; at most ${NETCODE_LIMITS.maximumInputKeys} are sent per input.`);
+ }
+ const input = {};
+ for (const name of names) {
+ requireName(name, `${label} key`);
+ const value = candidate[name];
+ if (typeof value === 'boolean') {
+ input[name] = value;
+ } else {
+ input[name] = boundedNumber(value, `${label}.${name}`, -NETCODE_LIMITS.maximumCoordinate, NETCODE_LIMITS.maximumCoordinate);
+ }
+ }
+ return input;
+}
+
+// The default movement rule: input { moveX, moveZ } from -1 to 1 sets a flat velocity. Pass your own `simulate` for more.
+export function createPlanarMovement(options = {}) {
+ const speed = boundedNumber(options.speed ?? DEFAULTS.movementSpeed, 'createPlanarMovement speed', 0, 1000);
+ return function planarMovement(state, input, stepSeconds) {
+ const moveX = Math.max(-1, Math.min(1, Number(input.moveX) || 0));
+ const moveZ = Math.max(-1, Math.min(1, Number(input.moveZ) || 0));
+ const velocity = [moveX * speed, 0, moveZ * speed];
+ const position = [
+ state.position[0] + velocity[0] * stepSeconds,
+ state.position[1],
+ state.position[2] + velocity[2] * stepSeconds,
+ ];
+ return { ...state, position, velocity };
+ };
+}
+
+// ----- Quantisation and deltas -----
+
+function quantizeEntity(state, tag, steps) {
+ const entity = {};
+ if (tag !== null) entity.t = tag;
+ for (const field of VECTOR_FIELDS) {
+ const step = steps[field.stepOption];
+ entity[field.wire] = state[field.name].map(component => Math.round(component / step));
+ }
+ entity.x = {};
+ for (const [name, value] of Object.entries(state.variables)) entity.x[name] = Math.round(value / steps.variableStep);
+ return entity;
+}
+
+function dequantizeEntity(entity, steps) {
+ const state = {};
+ for (const field of VECTOR_FIELDS) {
+ const step = steps[field.stepOption];
+ state[field.name] = entity[field.wire].map(integer => integer * step);
+ }
+ state.variables = {};
+ for (const [name, integer] of Object.entries(entity.x)) state.variables[name] = integer * steps.variableStep;
+ return state;
+}
+
+function sameNumbers(first, second) {
+ return first.length === second.length && first.every((value, index) => value === second[index]);
+}
+
+// Only the parts of an entity that differ from `base`. Null when nothing differs; the whole entity when there is no base.
+function diffEntity(base, current) {
+ if (!base) return current;
+ const delta = {};
+ for (const field of VECTOR_FIELDS) {
+ if (!sameNumbers(base[field.wire], current[field.wire])) delta[field.wire] = current[field.wire];
+ }
+ const changedVariables = {};
+ for (const [name, value] of Object.entries(current.x)) {
+ if (base.x[name] !== value) changedVariables[name] = value;
+ }
+ for (const name of Object.keys(base.x)) {
+ if (!(name in current.x)) changedVariables[name] = null;
+ }
+ if (Object.keys(changedVariables).length > 0) delta.x = changedVariables;
+ return Object.keys(delta).length > 0 ? delta : null;
+}
+
+function applyEntityDelta(base, delta) {
+ const entity = { ...(base ?? {}) };
+ if (delta.t !== undefined) entity.t = delta.t;
+ for (const field of VECTOR_FIELDS) {
+ if (delta[field.wire] !== undefined) entity[field.wire] = delta[field.wire];
+ }
+ const variables = { ...(base?.x ?? {}) };
+ for (const [name, value] of Object.entries(delta.x ?? {})) {
+ if (value === null) delete variables[name];
+ else variables[name] = value;
+ }
+ entity.x = variables;
+ return entity;
+}
+
+function readWireIntegers(value, length) {
+ if (!Array.isArray(value) || value.length !== length) return null;
+ for (const integer of value) {
+ if (!Number.isSafeInteger(integer) || Math.abs(integer) > MAXIMUM_WIRE_INTEGER) return null;
+ }
+ return value;
+}
+
+// Network data is untrusted: returns the cleaned delta, or null when anything about it is wrong.
+function readWireEntityDelta(raw, isNewEntity) {
+ if (!isPlainObject(raw)) return null;
+ const delta = {};
+ if (raw.t !== undefined) {
+ if (typeof raw.t !== 'string' || raw.t.length > NETCODE_LIMITS.maximumNameLength) return null;
+ delta.t = raw.t;
+ }
+ for (const field of VECTOR_FIELDS) {
+ if (raw[field.wire] === undefined) {
+ if (isNewEntity) return null;
+ continue;
+ }
+ const integers = readWireIntegers(raw[field.wire], field.length);
+ if (!integers) return null;
+ delta[field.wire] = integers;
+ }
+ if (raw.x !== undefined) {
+ if (!isPlainObject(raw.x) || Object.keys(raw.x).length > NETCODE_LIMITS.maximumVariablesPerEntity) return null;
+ delta.x = {};
+ for (const [name, value] of Object.entries(raw.x)) {
+ if (name.length > NETCODE_LIMITS.maximumNameLength) return null;
+ if (value !== null && !(Number.isSafeInteger(value) && Math.abs(value) <= MAXIMUM_WIRE_INTEGER)) return null;
+ delta.x[name] = value;
+ }
+ }
+ return delta;
+}
+
+// ----- Interpolation -----
+
+function blendVectors(first, second, fraction) {
+ return first.map((component, index) => component + (second[index] - component) * fraction);
+}
+
+function normalizeQuaternion(quaternion) {
+ const length = Math.hypot(...quaternion) || 1;
+ return quaternion.map(component => component / length);
+}
+
+function blendRotations(first, second, fraction) {
+ const sign = first[0] * second[0] + first[1] * second[1] + first[2] * second[2] + first[3] * second[3] < 0 ? -1 : 1;
+ const flipped = second.map(component => component * sign);
+ return normalizeQuaternion(blendVectors(first, flipped, fraction));
+}
+
+// The drawn state at `time`: between the two samples around it, or past the newest one moved on by its velocity for a short while.
+function sampleAt(samples, time, maximumExtrapolationSeconds) {
+ const first = samples[0];
+ if (time <= first.time) return cloneState(first.state);
+ const last = samples[samples.length - 1];
+ if (time >= last.time) {
+ const state = cloneState(last.state);
+ const seconds = Math.min(time - last.time, maximumExtrapolationSeconds);
+ state.position = state.position.map((component, index) => component + last.state.velocity[index] * seconds);
+ return state;
+ }
+ let upperIndex = samples.length - 1;
+ while (samples[upperIndex - 1].time > time) upperIndex -= 1;
+ const before = samples[upperIndex - 1];
+ const after = samples[upperIndex];
+ const fraction = (time - before.time) / (after.time - before.time);
+ return {
+ position: blendVectors(before.state.position, after.state.position, fraction),
+ rotation: blendRotations(before.state.rotation, after.state.rotation, fraction),
+ velocity: blendVectors(before.state.velocity, after.state.velocity, fraction),
+ variables: { ...before.state.variables },
+ };
+}
+
+// ----- Options -----
+
+function validateNetcodeOptions(options) {
+ if (!isPlainObject(options)) throw new TypeError('createNetcode needs an options object like { role: "client", transport, serverId: "server" }.');
+ validateTransport(options.transport, 'createNetcode');
+ const role = options.role ?? 'client';
+ if (!NETCODE_ROLES.includes(role)) {
+ throw new RangeError(`createNetcode role must be one of ${NETCODE_ROLES.join(', ')}, got ${String(role)}.`);
+ }
+ const authority = options.authority ?? 'server';
+ if (authority === 'peer') {
+ throw new RangeError(`createNetcode authority "peer" (peer to peer) is not supported yet. Use one of ${NETCODE_AUTHORITIES.join(', ')}.`);
+ }
+ if (!NETCODE_AUTHORITIES.includes(authority)) {
+ throw new RangeError(`createNetcode authority must be one of ${NETCODE_AUTHORITIES.join(', ')}, got ${String(authority)}.`);
+ }
+ if (role === 'client') requireName(options.serverId, 'createNetcode serverId');
+ for (const name of ['simulate', 'readInput']) {
+ if (options[name] !== undefined && typeof options[name] !== 'function') {
+ throw new TypeError(`createNetcode ${name} must be a function or left out, got ${describe(options[name])}.`);
+ }
+ }
+ if (role === 'client' && options.localEntityId !== undefined) requireName(options.localEntityId, 'createNetcode localEntityId');
+ return {
+ role,
+ authority,
+ transport: options.transport,
+ serverId: options.serverId,
+ localEntityId: options.localEntityId,
+ simulate: options.simulate ?? createPlanarMovement(),
+ readInput: options.readInput,
+ maximumMessageBytes: boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.defaultMessageBytes, 'createNetcode maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes),
+ snapshotEveryTicks: boundedInteger(options.snapshotEveryTicks ?? DEFAULTS.snapshotEveryTicks, 'createNetcode snapshotEveryTicks', 1, 60),
+ inputRedundancy: boundedInteger(options.inputRedundancy ?? DEFAULTS.inputRedundancy, 'createNetcode inputRedundancy', 1, NETCODE_LIMITS.maximumInputRedundancy),
+ inputBufferSteps: boundedInteger(options.inputBufferSteps ?? DEFAULTS.inputBufferSteps, 'createNetcode inputBufferSteps', 0, 16),
+ interpolationDelaySeconds: boundedNumber(options.interpolationDelaySeconds ?? DEFAULTS.interpolationDelaySeconds, 'createNetcode interpolationDelaySeconds', 0, 2),
+ maximumExtrapolationSeconds: boundedNumber(options.maximumExtrapolationSeconds ?? DEFAULTS.maximumExtrapolationSeconds, 'createNetcode maximumExtrapolationSeconds', 0, 2),
+ steps: {
+ positionStep: boundedNumber(options.positionStep ?? DEFAULTS.positionStep, 'createNetcode positionStep', 1e-6, 1),
+ rotationStep: boundedNumber(options.rotationStep ?? DEFAULTS.rotationStep, 'createNetcode rotationStep', 1e-6, 1),
+ velocityStep: boundedNumber(options.velocityStep ?? DEFAULTS.velocityStep, 'createNetcode velocityStep', 1e-6, 1),
+ variableStep: boundedNumber(options.variableStep ?? DEFAULTS.variableStep, 'createNetcode variableStep', 1e-6, 1),
+ },
+ };
+}
+
+// ----- The authority side -----
+
+function createAuthority(settings, stats) {
+ const { transport, steps } = settings;
+ const entities = new Map(); // id -> { owner, tag, state }
+ const peers = new Map(); // peer id -> { queue, lastQueuedSequence, lastProcessedSequence, acknowledgedTick }
+ const history = new Map(); // tick -> Map(id -> quantised entity)
+ let tick = 0;
+
+ function peerRecord(peerId) {
+ let record = peers.get(peerId);
+ if (record) return record;
+ if (peers.size >= NETCODE_LIMITS.maximumPeers) return null;
+ record = { queue: [], lastQueuedSequence: 0, lastProcessedSequence: 0, acknowledgedTick: null };
+ peers.set(peerId, record);
+ return record;
+ }
+
+ function receiveMessage(peerId, message) {
+ const record = peerRecord(peerId);
+ const inputs = isPlainObject(message) && message.type === 'input' && Array.isArray(message.inputs) ? message.inputs : null;
+ if (!record || !inputs || inputs.length > NETCODE_LIMITS.maximumInputsPerMessage) {
+ stats.rejectedMessages += 1;
+ return;
+ }
+ if (Number.isInteger(message.acknowledgedTick) && message.acknowledgedTick >= (record.acknowledgedTick ?? -1)) {
+ record.acknowledgedTick = message.acknowledgedTick;
+ }
+ for (const entry of inputs) {
+ try {
+ const sequence = boundedInteger(entry?.sequence, 'input sequence', 1, Number.MAX_SAFE_INTEGER);
+ if (sequence <= record.lastQueuedSequence) continue;
+ record.queue.push({ sequence, input: readInput(entry.input, 'input') });
+ record.lastQueuedSequence = sequence;
+ } catch {
+ stats.rejectedMessages += 1;
+ }
+ }
+ while (record.queue.length > NETCODE_LIMITS.maximumQueuedInputsPerPeer) record.queue.shift();
+ }
+
+ function entityOwnedBy(peerId) {
+ for (const entity of entities.values()) {
+ if (entity.owner === peerId) return entity;
+ }
+ return null;
+ }
+
+ function applyInput(entity, input, stepSeconds) {
+ entity.state = readState(settings.simulate(cloneState(entity.state), input, stepSeconds), 'simulate result', entity.state);
+ stats.inputsProcessed += 1;
+ }
+
+ function processInputs(stepSeconds) {
+ for (const [peerId, record] of peers) {
+ if (record.queue.length === 0) continue;
+ const backlog = record.queue.length - settings.inputBufferSteps;
+ const count = Math.min(Math.max(1, backlog), NETCODE_LIMITS.maximumInputsPerStep, record.queue.length);
+ const entity = entityOwnedBy(peerId);
+ for (let index = 0; index < count; index += 1) {
+ const { sequence, input } = record.queue.shift();
+ if (entity) applyInput(entity, input, stepSeconds);
+ record.lastProcessedSequence = sequence;
+ }
+ }
+ if (settings.readInput) {
+ const hostEntity = entityOwnedBy(transport.id);
+ if (hostEntity) applyInput(hostEntity, readInput(settings.readInput(), 'readInput result'), stepSeconds);
+ }
+ }
+
+ function dropDisconnectedPeers(currentPeers) {
+ for (const peerId of peers.keys()) {
+ if (!currentPeers.includes(peerId)) peers.delete(peerId);
+ }
+ }
+
+ function buildSnapshot() {
+ const snapshot = new Map();
+ for (const [id, entity] of entities) snapshot.set(id, quantizeEntity(entity.state, entity.tag, steps));
+ history.set(tick, snapshot);
+ while (history.size > NETCODE_LIMITS.maximumSnapshotHistory) history.delete(history.keys().next().value);
+ return snapshot;
+ }
+
+ function buildMessage(snapshot, record) {
+ const base = record.acknowledgedTick !== null && history.has(record.acknowledgedTick) ? record.acknowledgedTick : null;
+ const baseEntities = base === null ? null : history.get(base);
+ const changed = {};
+ for (const [id, entity] of snapshot) {
+ const delta = diffEntity(baseEntities?.get(id) ?? null, entity);
+ if (delta) changed[id] = delta;
+ }
+ const removed = baseEntities ? [...baseEntities.keys()].filter(id => !snapshot.has(id)) : [];
+ return {
+ type: 'snapshot',
+ tick,
+ base,
+ lastProcessedInput: record.lastProcessedSequence,
+ entities: changed,
+ removed,
+ };
+ }
+
+ function sendSnapshots() {
+ const currentPeers = transport.peers();
+ dropDisconnectedPeers(currentPeers);
+ const snapshot = buildSnapshot();
+ for (const peerId of currentPeers.slice(0, NETCODE_LIMITS.maximumPeers)) {
+ const record = peerRecord(peerId);
+ if (!record) continue;
+ const message = buildMessage(snapshot, record);
+ const bytes = JSON.stringify(message).length;
+ if (bytes > settings.maximumMessageBytes) {
+ throw new RangeError(`A netcode snapshot is ${bytes} bytes, over maximumMessageBytes ${settings.maximumMessageBytes}. Sync fewer entities or variables, or raise maximumMessageBytes (up to ${NETCODE_LIMITS.maximumMessageBytes}).`);
+ }
+ transport.send(peerId, message);
+ stats.snapshotsSent += 1;
+ stats.bytesSent += bytes;
+ if (message.base === null) stats.fullSnapshotsSent += 1;
+ }
+ }
+
+ return {
+ receiveMessage,
+ fixedUpdate(stepSeconds) {
+ processInputs(stepSeconds);
+ tick += 1;
+ if (tick % settings.snapshotEveryTicks === 0) sendSnapshots();
+ },
+ addEntity(id, definition = {}) {
+ requireName(id, 'addEntity id');
+ if (entities.has(id)) throw new RangeError(`addEntity: an entity named "${id}" already exists. Use setEntityState to change it.`);
+ if (entities.size >= NETCODE_LIMITS.maximumEntities) {
+ throw new RangeError(`A netcode world syncs at most ${NETCODE_LIMITS.maximumEntities} entities. Remove some, or sync only what players see.`);
+ }
+ const owner = definition.owner === undefined ? null : requireName(definition.owner, 'addEntity owner');
+ const tag = definition.tag === undefined ? null : requireName(definition.tag, 'addEntity tag');
+ if (owner !== null && entityOwnedBy(owner)) {
+ throw new RangeError(`addEntity: "${owner}" already owns an entity. A peer drives one entity.`);
+ }
+ entities.set(id, { owner, tag, state: readState(definition.state ?? {}, `addEntity "${id}" state`) });
+ },
+ removeEntity(id) {
+ if (!entities.delete(id)) throw new RangeError(`removeEntity: no entity named "${String(id)}". Present: ${[...entities.keys()].join(', ') || 'none'}.`);
+ },
+ setEntityState(id, partialState) {
+ const entity = entities.get(id);
+ if (!entity) throw new RangeError(`setEntityState: no entity named "${String(id)}". Present: ${[...entities.keys()].join(', ') || 'none'}. Use addEntity first.`);
+ entity.state = readState(partialState, `setEntityState "${id}" state`, entity.state);
+ },
+ getEntityState(id) {
+ const entity = entities.get(id);
+ return entity ? cloneState(entity.state) : null;
+ },
+ entityIds: () => [...entities.keys()],
+ get tick() { return tick; },
+ };
+}
+
+// ----- The client side -----
+
+function createClient(settings, stats) {
+ const { transport, steps } = settings;
+ const localEntityId = settings.localEntityId ?? null;
+ const receivedStates = new Map(); // tick -> Map(id -> quantised entity)
+ const samples = new Map(); // id -> [{ time, state }]
+ const pendingInputs = []; // { sequence, input }, not yet confirmed by a snapshot
+ let stepSeconds = null;
+ let latestTick = -1;
+ let inputSequence = 0;
+ let predicted = null;
+ let renderTime = null;
+
+ function reconcile(authoritativeState, lastProcessedInput) {
+ while (pendingInputs.length > 0 && pendingInputs[0].sequence <= lastProcessedInput) pendingInputs.shift();
+ const before = predicted;
+ let corrected = authoritativeState;
+ for (const { input } of pendingInputs) {
+ corrected = readState(settings.simulate(cloneState(corrected), input, stepSeconds), 'simulate result', corrected);
+ }
+ predicted = corrected;
+ stats.reconciliations += 1;
+ if (before) {
+ stats.lastCorrection = distanceBetween(before.position, predicted.position);
+ stats.maximumCorrection = Math.max(stats.maximumCorrection, stats.lastCorrection);
+ }
+ }
+
+ function readSnapshot(message) {
+ if (!isPlainObject(message) || message.type !== 'snapshot' || !Number.isSafeInteger(message.tick) || message.tick < 0) return null;
+ if (message.base !== null && !Number.isSafeInteger(message.base)) return null;
+ if (!isPlainObject(message.entities) || Object.keys(message.entities).length > NETCODE_LIMITS.maximumEntities) return null;
+ if (!Array.isArray(message.removed) || message.removed.length > NETCODE_LIMITS.maximumEntities) return null;
+ if (!Number.isSafeInteger(message.lastProcessedInput) || message.lastProcessedInput < 0) return null;
+ return message;
+ }
+
+ function receiveMessage(peerId, rawMessage) {
+ if (peerId !== settings.serverId) return;
+ const message = readSnapshot(rawMessage);
+ if (!message) {
+ stats.rejectedMessages += 1;
+ return;
+ }
+ if (message.tick <= latestTick) {
+ stats.staleSnapshots += 1;
+ return;
+ }
+ const baseEntities = message.base === null ? new Map() : receivedStates.get(message.base);
+ if (!baseEntities) {
+ stats.missingBaseSnapshots += 1;
+ return;
+ }
+ const full = new Map(baseEntities);
+ for (const id of message.removed) full.delete(id);
+ for (const [id, rawDelta] of Object.entries(message.entities)) {
+ const delta = readWireEntityDelta(rawDelta, !full.has(id));
+ if (!delta) {
+ stats.rejectedMessages += 1;
+ return;
+ }
+ full.set(id, applyEntityDelta(full.get(id) ?? null, delta));
+ }
+ if (full.size > NETCODE_LIMITS.maximumEntities) {
+ stats.rejectedMessages += 1;
+ return;
+ }
+ acceptSnapshot(message, full);
+ }
+
+ function acceptSnapshot(message, full) {
+ latestTick = message.tick;
+ stats.snapshotsReceived += 1;
+ receivedStates.set(message.tick, full);
+ while (receivedStates.size > NETCODE_LIMITS.maximumSnapshotHistory) receivedStates.delete(receivedStates.keys().next().value);
+ const time = message.tick * stepSeconds;
+ for (const id of samples.keys()) {
+ if (!full.has(id)) samples.delete(id);
+ }
+ for (const [id, entity] of full) {
+ const list = samples.get(id) ?? [];
+ list.push({ time, state: dequantizeEntity(entity, steps) });
+ while (list.length > NETCODE_LIMITS.maximumSamplesPerEntity) list.shift();
+ samples.set(id, list);
+ }
+ if (renderTime === null) renderTime = time - settings.interpolationDelaySeconds;
+ if (localEntityId !== null && full.has(localEntityId)) {
+ reconcile(dequantizeEntity(full.get(localEntityId), steps), message.lastProcessedInput);
+ }
+ }
+
+ function sendInput(context) {
+ inputSequence += 1;
+ const input = settings.readInput ? readInput(settings.readInput(context), 'readInput result') : {};
+ if (settings.readInput) {
+ pendingInputs.push({ sequence: inputSequence, input });
+ while (pendingInputs.length > NETCODE_LIMITS.maximumPendingInputs) pendingInputs.shift();
+ if (predicted) predicted = readState(settings.simulate(cloneState(predicted), input, stepSeconds), 'simulate result', predicted);
+ }
+ transport.send(settings.serverId, {
+ type: 'input',
+ acknowledgedTick: latestTick >= 0 ? latestTick : null,
+ inputs: pendingInputs.slice(-settings.inputRedundancy).map(({ sequence, input: pending }) => ({ sequence, input: pending })),
+ });
+ }
+
+ // Moves the drawing clock on with real time, nudged by at most a tenth toward "newest snapshot minus the delay".
+ function advanceRenderTime(deltaSeconds) {
+ if (renderTime === null) return;
+ const target = latestTick * stepSeconds - settings.interpolationDelaySeconds;
+ const error = target - renderTime;
+ if (Math.abs(error) > 1) {
+ renderTime = target;
+ return;
+ }
+ const limit = deltaSeconds * DEFAULTS.clockCorrectionRate;
+ renderTime += deltaSeconds + Math.max(-limit, Math.min(limit, error));
+ }
+
+ return {
+ receiveMessage,
+ setStep(seconds) { stepSeconds = seconds; },
+ fixedUpdate(step, context) {
+ stepSeconds = step;
+ sendInput(context);
+ },
+ update(deltaSeconds) {
+ advanceRenderTime(deltaSeconds);
+ },
+ getEntityState(id) {
+ if (id === localEntityId && predicted) return cloneState(predicted);
+ const list = samples.get(id);
+ if (!list || renderTime === null) return null;
+ return sampleAt(list, renderTime, settings.maximumExtrapolationSeconds);
+ },
+ entityIds: () => [...samples.keys()],
+ get latestTick() { return latestTick; },
+ get pendingInputCount() { return pendingInputs.length; },
+ };
+}
+
+// ----- createNetcode: the runtime system -----
+
+export function createNetcode(options) {
+ const settings = validateNetcodeOptions(options);
+ const stats = {
+ snapshotsSent: 0,
+ fullSnapshotsSent: 0,
+ bytesSent: 0,
+ inputsProcessed: 0,
+ snapshotsReceived: 0,
+ staleSnapshots: 0,
+ missingBaseSnapshots: 0,
+ reconciliations: 0,
+ lastCorrection: 0,
+ maximumCorrection: 0,
+ rejectedMessages: 0,
+ };
+ const side = settings.role === 'authority' ? createAuthority(settings, stats) : createClient(settings, stats);
+ let unsubscribe = null;
+
+ function requireAuthority(action) {
+ if (settings.role !== 'authority') throw new TypeError(`${action} is only for the authority. This netcode is a client; the authority owns the entities.`);
+ }
+
+ const netcode = {
+ name: 'netcode',
+ get role() { return settings.role; },
+ get authority() { return settings.authority; },
+ get stats() { return { ...stats }; },
+ get tick() { return settings.role === 'authority' ? side.tick : side.latestTick; },
+ get pendingInputCount() { return side.pendingInputCount ?? 0; },
+
+ init(context) {
+ side.setStep?.(context.fixedStepSeconds);
+ unsubscribe = settings.transport.receive((peerId, message) => side.receiveMessage(peerId, message));
+ },
+ fixedUpdate(step, context) {
+ side.fixedUpdate(step, context);
+ },
+ update(deltaSeconds) {
+ side.update?.(deltaSeconds);
+ },
+ dispose() {
+ if (typeof unsubscribe === 'function') unsubscribe();
+ unsubscribe = null;
+ },
+
+ // Authority: add an entity peers can see. `owner` is the peer id whose inputs drive it; `tag` names its kind.
+ addEntity(id, definition) {
+ requireAuthority('addEntity');
+ side.addEntity(id, definition);
+ return netcode;
+ },
+ removeEntity(id) {
+ requireAuthority('removeEntity');
+ side.removeEntity(id);
+ return netcode;
+ },
+ // Authority: write a state the game computed itself (a physics prop, a teleport). Parts left out keep their value.
+ setEntityState(id, partialState) {
+ requireAuthority('setEntityState');
+ side.setEntityState(id, partialState);
+ return netcode;
+ },
+ // The state to draw: the truth on the authority, the prediction for the local entity, the interpolation for the rest.
+ getEntityState(id) {
+ return side.getEntityState(id);
+ },
+ get entityIds() { return side.entityIds(); },
+ };
+ return netcode;
+}
+
+// ----- Transports -----
+
+// An in-memory network for tests and local play. Time moves only when advance() is called, and latency, jitter and loss
+// come from a seeded generator, so the same seed gives the same run. Messages are copied through JSON like a real wire.
+export function createLoopbackNetwork(options = {}) {
+ const seed = boundedInteger(options.seed ?? 1, 'createLoopbackNetwork seed', 0, 4294967295);
+ const latencyMilliseconds = boundedNumber(options.latencyMilliseconds ?? 0, 'createLoopbackNetwork latencyMilliseconds', 0, 60000);
+ const jitterMilliseconds = boundedNumber(options.jitterMilliseconds ?? 0, 'createLoopbackNetwork jitterMilliseconds', 0, 60000);
+ const lossRate = boundedNumber(options.lossRate ?? 0, 'createLoopbackNetwork lossRate', 0, 1);
+ const maximumMessageBytes = boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.maximumMessageBytes, 'createLoopbackNetwork maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes);
+ const maximumInFlight = boundedInteger(options.maximumInFlight ?? 4096, 'createLoopbackNetwork maximumInFlight', 1, 65536);
+ const random = createSeededRandom(seed);
+ const endpoints = new Map(); // id -> { listeners }
+ const inFlight = [];
+ const stats = { sent: 0, delivered: 0, dropped: 0 };
+ let nowMilliseconds = 0;
+ let sequence = 0;
+
+ function send(fromId, toId, message) {
+ if (!endpoints.has(toId)) throw new RangeError(`Loopback send: no transport named "${String(toId)}". Connected: ${[...endpoints.keys()].join(', ')}.`);
+ const text = JSON.stringify(message);
+ if (text === undefined || text.length > maximumMessageBytes) {
+ throw new RangeError(`Loopback send: a message must be JSON of at most ${maximumMessageBytes} characters, got ${text === undefined ? 'a value JSON cannot hold' : text.length}.`);
+ }
+ stats.sent += 1;
+ const lossDraw = random();
+ const jitterDraw = random();
+ if (lossDraw < lossRate || inFlight.length >= maximumInFlight) {
+ stats.dropped += 1;
+ return;
+ }
+ const delay = Math.max(0, latencyMilliseconds + (jitterDraw * 2 - 1) * jitterMilliseconds);
+ sequence += 1;
+ inFlight.push({ deliverAt: nowMilliseconds + delay, sequence, fromId, toId, text });
+ }
+
+ function deliverDue() {
+ inFlight.sort((first, second) => first.deliverAt - second.deliverAt || first.sequence - second.sequence);
+ while (inFlight.length > 0 && inFlight[0].deliverAt <= nowMilliseconds) {
+ const packet = inFlight.shift();
+ const endpoint = endpoints.get(packet.toId);
+ if (!endpoint) continue;
+ stats.delivered += 1;
+ for (const listener of [...endpoint.listeners]) listener(packet.fromId, JSON.parse(packet.text));
+ }
+ }
+
+ return {
+ createTransport(id) {
+ requireName(id, 'createTransport id');
+ if (endpoints.has(id)) throw new RangeError(`createTransport: a transport named "${id}" is already connected.`);
+ const endpoint = { listeners: new Set() };
+ endpoints.set(id, endpoint);
+ return {
+ id,
+ peers: () => [...endpoints.keys()].filter(other => other !== id),
+ send: (peerId, message) => send(id, peerId, message),
+ receive(callback) {
+ if (typeof callback !== 'function') throw new TypeError('transport.receive needs a callback (peerId, message) => void.');
+ endpoint.listeners.add(callback);
+ return () => endpoint.listeners.delete(callback);
+ },
+ close() {
+ endpoints.delete(id);
+ },
+ };
+ },
+ // Moves network time forward and delivers every message that is due.
+ advance(milliseconds) {
+ boundedNumber(milliseconds, 'advance milliseconds', 0, 60000);
+ nowMilliseconds += milliseconds;
+ deliverDue();
+ },
+ get stats() { return { ...stats, inFlight: inFlight.length }; },
+ get nowMilliseconds() { return nowMilliseconds; },
+ };
+}
+
+// Wraps a socket-like object ({ send(text), addEventListener, readyState, close }) and opens nothing itself.
+// By default the socket is a line to one peer (`remoteId`). With `multiplexed: true` it talks through a relay that
+// wraps each message as { to, data } going out and { from, data } coming in, so a server or host can hear many clients.
+export function createWebSocketTransport(socket, options = {}) {
+ if (socket === null || typeof socket !== 'object' || typeof socket.send !== 'function' || typeof socket.addEventListener !== 'function') {
+ throw new TypeError('createWebSocketTransport needs a socket-like object with send(text) and addEventListener(type, listener), such as a WebSocket you opened.');
+ }
+ const id = requireName(options.id ?? 'local', 'createWebSocketTransport id');
+ const remoteId = requireName(options.remoteId ?? 'server', 'createWebSocketTransport remoteId');
+ const multiplexed = options.multiplexed === true;
+ const maximumMessageBytes = boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.defaultMessageBytes, 'createWebSocketTransport maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes);
+ const openState = 1;
+ const listeners = new Set();
+ const relayPeers = new Set();
+ const stats = { sent: 0, received: 0, rejected: 0 };
+
+ function readPacket(text) {
+ if (typeof text !== 'string' || text.length > maximumMessageBytes) return null;
+ try {
+ const parsed = JSON.parse(text);
+ return isPlainObject(parsed) ? parsed : null;
+ } catch {
+ return null;
+ }
+ }
+
+ function onMessage(event) {
+ const packet = readPacket(event?.data);
+ if (!packet) {
+ stats.rejected += 1;
+ return;
+ }
+ let peerId = remoteId;
+ let message = packet;
+ if (multiplexed) {
+ if (typeof packet.from !== 'string' || packet.from === '' || packet.from.length > NETCODE_LIMITS.maximumNameLength) {
+ stats.rejected += 1;
+ return;
+ }
+ peerId = packet.from;
+ if (packet.left === true) {
+ relayPeers.delete(peerId);
+ return;
+ }
+ if (relayPeers.size >= NETCODE_LIMITS.maximumPeers && !relayPeers.has(peerId)) {
+ stats.rejected += 1;
+ return;
+ }
+ relayPeers.add(peerId);
+ message = packet.data;
+ }
+ stats.received += 1;
+ for (const listener of [...listeners]) listener(peerId, message);
+ }
+
+ socket.addEventListener('message', onMessage);
+
+ return {
+ id,
+ peers: () => multiplexed ? [...relayPeers] : socket.readyState === openState ? [remoteId] : [],
+ send(peerId, message) {
+ if (socket.readyState !== openState) return;
+ const text = JSON.stringify(multiplexed ? { to: peerId, data: message } : message);
+ if (text === undefined || text.length > maximumMessageBytes) {
+ throw new RangeError(`WebSocket transport send: a message must be JSON of at most ${maximumMessageBytes} characters, got ${text === undefined ? 'a value JSON cannot hold' : text.length}.`);
+ }
+ socket.send(text);
+ stats.sent += 1;
+ },
+ receive(callback) {
+ if (typeof callback !== 'function') throw new TypeError('transport.receive needs a callback (peerId, message) => void.');
+ listeners.add(callback);
+ return () => listeners.delete(callback);
+ },
+ close() {
+ socket.removeEventListener?.('message', onMessage);
+ listeners.clear();
+ socket.close?.();
+ },
+ get stats() { return { ...stats }; },
+ };
+}
diff --git a/tests/netcode.test.js b/tests/netcode.test.js
new file mode 100644
index 00000000..2a6462e1
--- /dev/null
+++ b/tests/netcode.test.js
@@ -0,0 +1,325 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createRuntime } from '../src/runtime.js';
+import {
+ NETCODE_LIMITS,
+ createLoopbackNetwork,
+ createNetcode,
+ createPlanarMovement,
+ createWebSocketTransport,
+} from '../src/netcode.js';
+
+const FRAME_MILLISECONDS = 20;
+const FIXED_RATE = 50;
+const PLAYER_SPEED = 5;
+
+const idleScheduler = { request: () => 1, cancel: () => {} };
+
+function createPeer(netcodeOptions) {
+ const netcode = createNetcode(netcodeOptions);
+ const runtime = createRuntime({ render() {} }, { mode: 'both', fixedRate: FIXED_RATE, scheduler: idleScheduler, systems: [netcode] });
+ return { netcode, runtime };
+}
+
+// A scripted input for one player: a function of the frame number.
+function scriptFor(pattern) {
+ return frame => {
+ const segment = pattern.find(entry => frame < entry.untilFrame);
+ return segment ? { moveX: segment.moveX, moveZ: segment.moveZ } : { moveX: 0, moveZ: 0 };
+ };
+}
+
+const SCRIPT_A = scriptFor([
+ { untilFrame: 100, moveX: 1, moveZ: 0 },
+ { untilFrame: 160, moveX: 0, moveZ: 1 },
+ { untilFrame: 230, moveX: -1, moveZ: 0 },
+ { untilFrame: 300, moveX: 0.5, moveZ: -0.5 },
+]);
+const SCRIPT_B = scriptFor([
+ { untilFrame: 80, moveX: 0, moveZ: -1 },
+ { untilFrame: 170, moveX: 1, moveZ: 0 },
+ { untilFrame: 260, moveX: 0, moveZ: 1 },
+]);
+
+// Two clients and a server on a 100 ms, plus or minus 30 ms, 2 percent loss network, driven frame by frame.
+function runSession({ seed = 11, frames = 520, lossRate = 0.02, onFrame, teleportAtFrame = null } = {}) {
+ const network = createLoopbackNetwork({ seed, latencyMilliseconds: 100, jitterMilliseconds: 30, lossRate });
+ const server = createPeer({ role: 'authority', authority: 'server', transport: network.createTransport('server') });
+ server.netcode.addEntity('a', { owner: 'client-a', tag: 'player' });
+ server.netcode.addEntity('b', { owner: 'client-b', tag: 'player' });
+ server.netcode.addEntity('crate', { tag: 'prop', state: { position: [3, 1, 3], variables: { health: 10 } } });
+ let frame = 0;
+ const clientA = createPeer({ role: 'client', serverId: 'server', transport: network.createTransport('client-a'), localEntityId: 'a', readInput: () => SCRIPT_A(frame) });
+ const clientB = createPeer({ role: 'client', serverId: 'server', transport: network.createTransport('client-b'), localEntityId: 'b', readInput: () => SCRIPT_B(frame) });
+ const peers = [server, clientA, clientB];
+ for (frame = 0; frame < frames; frame += 1) {
+ network.advance(FRAME_MILLISECONDS);
+ if (frame === teleportAtFrame) server.netcode.setEntityState('a', { position: [-20, 0, 15] });
+ if (frame === 200) server.netcode.setEntityState('crate', { position: [4, 1, 3], variables: { health: 7 } });
+ for (const peer of peers) peer.runtime.step(FRAME_MILLISECONDS);
+ onFrame?.({ frame, server, clientA, clientB });
+ }
+ return { network, server, clientA, clientB };
+}
+
+function distance(first, second) {
+ return Math.hypot(first[0] - second[0], first[1] - second[1], first[2] - second[2]);
+}
+
+test('a predicted local player converges to the authority after reconciliation', () => {
+ const { server, clientA, clientB } = runSession();
+ for (const [client, id] of [[clientA, 'a'], [clientB, 'b']]) {
+ const truth = server.netcode.getEntityState(id).position;
+ const predicted = client.netcode.getEntityState(id).position;
+ assert.ok(distance(truth, predicted) < 0.05, `${id}: predicted ${predicted} vs authority ${truth}`);
+ assert.ok(client.netcode.stats.reconciliations > 50);
+ assert.equal(client.netcode.pendingInputCount < NETCODE_LIMITS.maximumPendingInputs, true);
+ }
+ const moved = server.netcode.getEntityState('a').position;
+ assert.ok(Math.abs(moved[0]) + Math.abs(moved[2]) > 1, 'the scripted input moved the player');
+});
+
+test('a correction from the authority pulls the prediction back within a bound', () => {
+ const { server, clientA } = runSession({ teleportAtFrame: 300, frames: 520 });
+ const truth = server.netcode.getEntityState('a').position;
+ assert.ok(distance(truth, clientA.netcode.getEntityState('a').position) < 0.05);
+ assert.ok(clientA.netcode.stats.maximumCorrection > 10, 'the teleport showed up as one large correction');
+ assert.ok(truth[0] < -15, 'the authority state holds the teleport');
+});
+
+test('remote entities move without jumps above a bound', () => {
+ let previous = null;
+ let largestStep = 0;
+ let frames = 0;
+ runSession({
+ onFrame({ frame, clientB }) {
+ const seen = clientB.netcode.getEntityState('a');
+ if (!seen || frame < 40) return;
+ if (previous) largestStep = Math.max(largestStep, distance(previous, seen.position));
+ previous = seen.position;
+ frames += 1;
+ },
+ });
+ const nominalStep = PLAYER_SPEED * (FRAME_MILLISECONDS / 1000);
+ assert.ok(frames > 400);
+ assert.ok(largestStep <= nominalStep * 1.6, `largest per-frame step ${largestStep} vs nominal ${nominalStep}`);
+});
+
+test('a remote view settles on the authority state and carries variables', () => {
+ const { server, clientA, clientB } = runSession();
+ const truth = server.netcode.getEntityState('a').position;
+ assert.ok(distance(truth, clientB.netcode.getEntityState('a').position) < 0.05);
+ const crate = clientA.netcode.getEntityState('crate');
+ assert.ok(distance(crate.position, [4, 1, 3]) < 0.02);
+ assert.ok(Math.abs(crate.variables.health - 7) < 0.02);
+ assert.deepEqual(clientA.netcode.entityIds.sort(), ['a', 'b', 'crate']);
+});
+
+test('the same seed gives the same run and another seed gives another', () => {
+ const trace = seed => {
+ const positions = [];
+ const { network, server } = runSession({
+ seed,
+ frames: 300,
+ onFrame: ({ frame, clientB }) => {
+ if (frame % 25 === 0) positions.push(clientB.netcode.getEntityState('a')?.position ?? null);
+ },
+ });
+ return JSON.stringify({ positions, network: network.stats, bytes: server.netcode.stats.bytesSent });
+ };
+ assert.equal(trace(5), trace(5));
+ assert.notEqual(trace(5), trace(6));
+});
+
+test('delta snapshots are mostly deltas and loss only costs a resend', () => {
+ const { server } = runSession({ lossRate: 0.02 });
+ const { snapshotsSent, fullSnapshotsSent } = server.netcode.stats;
+ assert.ok(fullSnapshotsSent < snapshotsSent * 0.2, `${fullSnapshotsSent} full of ${snapshotsSent}`);
+ const lossless = runSession({ lossRate: 0, frames: 300 });
+ assert.ok(lossless.server.netcode.stats.fullSnapshotsSent <= 12);
+});
+
+test('a host also plays its own entity with no prediction', () => {
+ const network = createLoopbackNetwork({ seed: 3, latencyMilliseconds: 40 });
+ const host = createPeer({ role: 'authority', authority: 'host', transport: network.createTransport('host'), readInput: () => ({ moveX: 1 }) });
+ host.netcode.addEntity('host-player', { owner: 'host' });
+ const guest = createPeer({ role: 'client', serverId: 'host', transport: network.createTransport('guest'), localEntityId: 'guest-player', readInput: () => ({ moveZ: 1 }) });
+ host.netcode.addEntity('guest-player', { owner: 'guest' });
+ for (let frame = 0; frame < 150; frame += 1) {
+ network.advance(FRAME_MILLISECONDS);
+ host.runtime.step(FRAME_MILLISECONDS);
+ guest.runtime.step(FRAME_MILLISECONDS);
+ }
+ const hostPosition = host.netcode.getEntityState('host-player').position;
+ assert.ok(hostPosition[0] > 10);
+ assert.ok(Math.abs(guest.netcode.getEntityState('host-player').position[0] - hostPosition[0]) < PLAYER_SPEED * 0.3);
+});
+
+test('custom simulation, removed entities and variables sync', () => {
+ const network = createLoopbackNetwork({ seed: 2 });
+ const jumper = (state, input, step) => ({
+ ...state,
+ variables: { ...state.variables, jumps: (state.variables.jumps ?? 0) + (input.jump ? 1 : 0) },
+ position: [state.position[0] + step, 0, 0],
+ });
+ const server = createPeer({ role: 'authority', transport: network.createTransport('server'), simulate: jumper });
+ const client = createPeer({ role: 'client', serverId: 'server', transport: network.createTransport('c'), simulate: jumper, localEntityId: 'p', readInput: () => ({ jump: true }) });
+ server.netcode.addEntity('p', { owner: 'c' });
+ server.netcode.addEntity('gone');
+ for (let frame = 0; frame < 60; frame += 1) {
+ network.advance(FRAME_MILLISECONDS);
+ if (frame === 30) server.netcode.removeEntity('gone');
+ server.runtime.step(FRAME_MILLISECONDS);
+ client.runtime.step(FRAME_MILLISECONDS);
+ }
+ assert.deepEqual(client.netcode.entityIds, ['p']);
+ assert.ok(client.netcode.getEntityState('p').variables.jumps > 30);
+});
+
+test('invalid options and calls throw errors that say what to pass', () => {
+ const transport = createLoopbackNetwork().createTransport('t');
+ assert.throws(() => createNetcode(), /options object/);
+ assert.throws(() => createNetcode({ transport: {} }), /transport\.id/);
+ assert.throws(() => createNetcode({ transport: { id: 'x' } }), /transport\.peers must be a function/);
+ assert.throws(() => createNetcode({ transport, role: 'spectator' }), /role must be one of authority, client/);
+ assert.throws(() => createNetcode({ transport, role: 'client' }), /serverId/);
+ assert.throws(() => createNetcode({ transport, role: 'authority', authority: 'peer' }), /peer to peer\) is not supported yet/);
+ assert.throws(() => createNetcode({ transport, role: 'authority', authority: 'cloud' }), /authority must be one of server, host/);
+ assert.throws(() => createNetcode({ transport, role: 'authority', snapshotEveryTicks: 0 }), /snapshotEveryTicks/);
+ assert.throws(() => createNetcode({ transport, role: 'authority', simulate: 3 }), /simulate must be a function/);
+ const authority = createNetcode({ transport, role: 'authority' });
+ assert.throws(() => authority.addEntity('', {}), /1 to 64 characters/);
+ authority.addEntity('p', { owner: 'x', state: { position: [1, 2, 3] } });
+ assert.throws(() => authority.addEntity('p'), /already exists/);
+ assert.throws(() => authority.addEntity('q', { owner: 'x' }), /already owns/);
+ assert.throws(() => authority.addEntity('q', { state: { position: [1, 2] } }), /array of 3 numbers/);
+ assert.throws(() => authority.addEntity('q', { state: { position: [1e9, 0, 0] } }), /position\[0\] must be a number/);
+ assert.throws(() => authority.addEntity('q', { state: { variables: { score: 'high' } } }), /score must be a number/);
+ assert.throws(() => authority.setEntityState('nope', {}), /no entity named "nope"/);
+ assert.throws(() => authority.removeEntity('nope'), /no entity named "nope"/);
+ const client = createNetcode({ transport, role: 'client', serverId: 's' });
+ assert.throws(() => client.addEntity('p'), /only for the authority/);
+ assert.throws(() => createLoopbackNetwork({ lossRate: 2 }), /lossRate must be a number from 0 to 1/);
+ assert.throws(() => createLoopbackNetwork().createTransport(''), /1 to 64 characters/);
+ const network = createLoopbackNetwork();
+ const first = network.createTransport('one');
+ assert.throws(() => network.createTransport('one'), /already connected/);
+ assert.throws(() => first.send('ghost', {}), /no transport named "ghost"/);
+ assert.throws(() => createWebSocketTransport({}), /socket-like/);
+});
+
+test('bad network input is counted and ignored, and too many entities are refused', () => {
+ const network = createLoopbackNetwork();
+ const server = createPeer({ role: 'authority', transport: network.createTransport('server') });
+ const rogue = network.createTransport('rogue');
+ server.netcode.addEntity('p', { owner: 'rogue' });
+ server.runtime.step(FRAME_MILLISECONDS);
+ rogue.send('server', { type: 'input', inputs: 'nope' });
+ rogue.send('server', { type: 'input', inputs: [{ sequence: 1, input: { moveX: 'fast' } }] });
+ rogue.send('server', { type: 'input', inputs: [{ sequence: 1, input: { moveX: 1 } }, { sequence: 1, input: { moveX: -1 } }] });
+ network.advance(1);
+ server.runtime.step(FRAME_MILLISECONDS);
+ assert.equal(server.netcode.stats.rejectedMessages, 2);
+ assert.equal(server.netcode.stats.inputsProcessed, 1);
+ assert.ok(server.netcode.getEntityState('p').position[0] > 0);
+
+ const client = createPeer({ role: 'client', serverId: 'server', transport: network.createTransport('c') });
+ client.runtime.step(FRAME_MILLISECONDS);
+ const lookalike = network.createTransport('server-lookalike');
+ lookalike.send('c', { type: 'snapshot', tick: 'x' });
+ network.advance(1);
+ assert.equal(client.netcode.stats.rejectedMessages, 0, 'a message from a peer that is not the server is ignored');
+ const garbage = network.createTransport('garbage');
+ garbage.send('server', 7);
+ network.advance(1);
+ assert.equal(server.netcode.stats.rejectedMessages, 3);
+ for (let index = 0; index < NETCODE_LIMITS.maximumEntities - 1; index += 1) server.netcode.addEntity(`e${index}`);
+ assert.throws(() => server.netcode.addEntity('overflow'), /at most 256 entities/);
+});
+
+test('a snapshot over the byte limit fails loudly instead of being cut', () => {
+ const network = createLoopbackNetwork();
+ const server = createPeer({ role: 'authority', transport: network.createTransport('server'), maximumMessageBytes: 300 });
+ network.createTransport('c');
+ for (let index = 0; index < 20; index += 1) server.netcode.addEntity(`entity-${index}`);
+ server.runtime.step(FRAME_MILLISECONDS);
+ assert.throws(() => server.runtime.step(FRAME_MILLISECONDS), /over maximumMessageBytes 300/);
+});
+
+test('planar movement turns input into a flat velocity', () => {
+ const simulate = createPlanarMovement({ speed: 2 });
+ const state = { position: [0, 1, 0], rotation: [0, 0, 0, 1], velocity: [0, 0, 0], variables: {} };
+ const moved = simulate(state, { moveX: 5, moveZ: -1 }, 0.5);
+ assert.deepEqual(moved.position, [1, 1, -1]);
+ assert.deepEqual(moved.velocity, [2, 0, -2]);
+ assert.throws(() => createPlanarMovement({ speed: -1 }), /speed must be a number/);
+});
+
+function createFakeSocket() {
+ const listeners = new Map();
+ return {
+ readyState: 1,
+ sent: [],
+ send(text) { this.sent.push(text); },
+ close() { this.readyState = 3; },
+ addEventListener(type, listener) { listeners.set(type, listener); },
+ removeEventListener(type) { listeners.delete(type); },
+ emit(type, event) { listeners.get(type)?.(event); },
+ };
+}
+
+test('the WebSocket transport wraps a passed-in socket and opens nothing', () => {
+ const socket = createFakeSocket();
+ const transport = createWebSocketTransport(socket, { id: 'me', remoteId: 'host' });
+ const received = [];
+ const stop = transport.receive((peerId, message) => received.push([peerId, message]));
+ assert.deepEqual(transport.peers(), ['host']);
+ transport.send('host', { type: 'input', inputs: [] });
+ assert.equal(socket.sent[0], '{"type":"input","inputs":[]}');
+ socket.emit('message', { data: '{"type":"snapshot","tick":1}' });
+ socket.emit('message', { data: 'not json' });
+ socket.emit('message', { data: 42 });
+ assert.deepEqual(received, [['host', { type: 'snapshot', tick: 1 }]]);
+ assert.equal(transport.stats.rejected, 2);
+ stop();
+ socket.emit('message', { data: '{"a":1}' });
+ assert.equal(received.length, 1);
+ socket.readyState = 3;
+ assert.deepEqual(transport.peers(), []);
+ transport.send('host', {});
+ assert.equal(socket.sent.length, 1);
+ assert.throws(() => createWebSocketTransport(socket, { maximumMessageBytes: 10 }), /maximumMessageBytes must be/);
+});
+
+test('a multiplexed WebSocket transport addresses peers through a relay envelope', () => {
+ const socket = createFakeSocket();
+ const transport = createWebSocketTransport(socket, { id: 'server', multiplexed: true });
+ const received = [];
+ transport.receive((peerId, message) => received.push([peerId, message]));
+ socket.emit('message', { data: '{"from":"alice","data":{"type":"input","inputs":[]}}' });
+ socket.emit('message', { data: '{"from":"bob","data":{"type":"input","inputs":[]}}' });
+ socket.emit('message', { data: '{"data":{}}' });
+ assert.deepEqual(transport.peers(), ['alice', 'bob']);
+ transport.send('alice', { type: 'snapshot' });
+ assert.equal(socket.sent[0], '{"to":"alice","data":{"type":"snapshot"}}');
+ socket.emit('message', { data: '{"from":"alice","left":true}' });
+ assert.deepEqual(transport.peers(), ['bob']);
+ assert.equal(received.length, 2);
+ assert.equal(transport.stats.rejected, 1);
+});
+
+test('netcode over a WebSocket pair syncs a client to a host', () => {
+ const clientSocket = createFakeSocket();
+ const serverSocket = createFakeSocket();
+ clientSocket.send = text => serverSocket.emit('message', { data: text });
+ serverSocket.send = text => clientSocket.emit('message', { data: text });
+ const server = createPeer({ role: 'authority', transport: createWebSocketTransport(serverSocket, { id: 'server', remoteId: 'client' }) });
+ const client = createPeer({ role: 'client', serverId: 'server', localEntityId: 'p', transport: createWebSocketTransport(clientSocket, { id: 'client', remoteId: 'server' }), readInput: () => ({ moveX: 1 }) });
+ server.netcode.addEntity('p', { owner: 'client' });
+ for (let frame = 0; frame < 100; frame += 1) {
+ server.runtime.step(FRAME_MILLISECONDS);
+ client.runtime.step(FRAME_MILLISECONDS);
+ }
+ assert.ok(distance(server.netcode.getEntityState('p').position, client.netcode.getEntityState('p').position) < 0.3);
+ assert.ok(server.netcode.getEntityState('p').position[0] > 5);
+});
diff --git a/vite.lib.config.js b/vite.lib.config.js
index 9cb64faa..75335574 100644
--- a/vite.lib.config.js
+++ b/vite.lib.config.js
@@ -111,6 +111,7 @@ export default defineConfig({
'animation-graph': 'src/animation-graph.js',
player: 'src/player.js',
streaming: 'src/streaming.js',
+ netcode: 'src/netcode.js',
'update-part-vertices':'src/update-part-vertices.js',
'replace-textured-parts': 'src/replace-textured-parts.js',
// Page of the MCP preview. It imports the engine chunks above instead of bundling its own copy.