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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonindex 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.mjsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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.