3D engine that AI agents drive
Add a WebRTC data channel transport to the netcode addon (part of #778)
Nguyen Xuan Ana6599a5f04e7
diff --git a/changes/778-data-channel-transport.md b/changes/778-data-channel-transport.mdnew file mode 100644index 00000000..d61be244--- /dev/null+++ b/changes/778-data-channel-transport.md@@ -0,0 +1 @@+- The netcode addon gains `createDataChannelTransport`: one WebRTC data channel per peer, so a host player or server can sync players and props over WebRTC with the same authority and prediction code (part of #778)diff --git a/docs/netcode.md b/docs/netcode.mdindex 9e69ef0c..d420b8be 100644--- a/docs/netcode.md+++ b/docs/netcode.md@@ -51,7 +51,9 @@ Other entities are drawn `interpolationDelaySeconds` (default 0.1) behind the ne## 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.+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 WebTransport.++- `createDataChannelTransport({ id })` is the WebRTC transport. Your signalling code opens each `RTCDataChannel` and hands it over with `transport.addChannel(peerId, channel)`: a host adds one per player, a client adds one channel for the host. `removeChannel(peerId)` drops one. A peer is listed while its channel is `open`, so a player who disconnects leaves `peers()` on its own. Messages are JSON text, bounded by `maximumMessageBytes`; a malformed or oversized incoming message counts in `stats.rejected`. At most 32 channels. Use a reliable ordered channel, or `{ ordered: false, maxRetransmits: 0 }` for snapshots when you accept drops, which the delta scheme repairs. Signalling (offer, answer, ICE) is yours: this library opens no connection.- `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.- `createBroadcastChannelTransport(channel, { id })` wraps a `BroadcastChannel` so tabs, windows and workers of one browser play together with no server. Peers find each other with a hello the other side answers once, and a message to one peer reaches only that peer. A peer silent for `peerTimeoutMilliseconds` (default 5000) is forgotten until it speaks again, so a closed tab leaves the peer list; call `transport.close()` on `pagehide` to say goodbye at once. `now` swaps the clock for tests.@@ -86,4 +88,4 @@ A transport is a plain object `{ id, peers(), send(peerId, message), receive(cal## Not yet-WebRTC and WebTransport transports, peer-to-peer authority and a physics-prop sample come in later work on #778. Use the same `fixedRate` on the authority and every client.+A WebTransport transport, peer-to-peer authority, a browser sample over WebRTC and a relay on a real free host come in later work on #778. The data channel test covers a host with two clients and an ownerless prop driven by game code. Use the same `fixedRate` on the authority and every client.diff --git a/src/netcode.js b/src/netcode.jsindex 29123098..666c5df1 100644--- a/src/netcode.js+++ b/src/netcode.js@@ -1000,3 +1000,89 @@ export function createWebSocketTransport(socket, options = {}) {get stats() { return { ...stats }; },};}++// A transport over several WebRTC data channels (or any channel-like objects with send(text), addEventListener and+// readyState), one per peer. Your signalling code opens each RTCDataChannel and hands it over with addChannel(peerId, channel):+// a host adds one per player, a client adds one for the host. A peer is listed while its channel is open, so a player who+// disconnects leaves the peer list on its own. Nothing here opens a connection.+export function createDataChannelTransport(options = {}) {+ const id = requireName(options.id, 'createDataChannelTransport id');+ const maximumMessageBytes = boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.defaultMessageBytes, 'createDataChannelTransport maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes);+ const openState = 'open';+ const listeners = new Set();+ const channels = new Map();+ const stats = { sent: 0, received: 0, rejected: 0 };++ function readMessage(text) {+ if (typeof text !== 'string' || text.length > maximumMessageBytes) return undefined;+ try {+ return JSON.parse(text);+ } catch {+ return undefined;+ }+ }++ function detach(entry) {+ entry.channel.removeEventListener?.('message', entry.onMessage);+ }++ return {+ id,+ addChannel(peerId, channel) {+ requireName(peerId, 'addChannel peerId');+ if (channel === null || typeof channel !== 'object' || typeof channel.send !== 'function' || typeof channel.addEventListener !== 'function') {+ throw new TypeError('addChannel needs a data-channel-like object with send(text) and addEventListener(type, listener), such as an RTCDataChannel.');+ }+ if (!channels.has(peerId) && channels.size >= NETCODE_LIMITS.maximumPeers) {+ throw new RangeError(`addChannel: at most ${NETCODE_LIMITS.maximumPeers} peers are supported; remove one with removeChannel(peerId) first.`);+ }+ const previous = channels.get(peerId);+ if (previous) detach(previous);+ const entry = {+ channel,+ onMessage(event) {+ const message = readMessage(event?.data);+ if (message === undefined) {+ stats.rejected += 1;+ return;+ }+ stats.received += 1;+ for (const listener of [...listeners]) listener(peerId, message);+ },+ };+ channel.addEventListener('message', entry.onMessage);+ channels.set(peerId, entry);+ },+ removeChannel(peerId) {+ const entry = channels.get(peerId);+ if (!entry) return;+ detach(entry);+ channels.delete(peerId);+ },+ peers: () => [...channels].filter(([, entry]) => entry.channel.readyState === openState).map(([peerId]) => peerId),+ send(peerId, message) {+ const entry = channels.get(peerId);+ if (!entry || entry.channel.readyState !== openState) return;+ const text = JSON.stringify(message);+ if (text === undefined || text.length > maximumMessageBytes) {+ throw new RangeError(`Data channel transport send: a message must be JSON of at most ${maximumMessageBytes} characters, got ${text === undefined ? 'a value JSON cannot hold' : text.length}.`);+ }+ entry.channel.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() {+ for (const entry of channels.values()) {+ detach(entry);+ entry.channel.close?.();+ }+ channels.clear();+ listeners.clear();+ },+ get stats() { return { ...stats }; },+ };+}diff --git a/tests/netcode-datachannel.test.js b/tests/netcode-datachannel.test.jsnew file mode 100644index 00000000..63b36012--- /dev/null+++ b/tests/netcode-datachannel.test.js@@ -0,0 +1,111 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { createRuntime } from '../src/runtime.js';+import { createDataChannelTransport, createNetcode } from '../src/netcode.js';++const FRAME_MILLISECONDS = 20;+const idleScheduler = { request: () => 1, cancel: () => {} };++// Two connected data-channel-like ends, as RTCDataChannel pairs behave: send on one is a message event on the other.+function createChannelPair() {+ const ends = [0, 1].map(() => ({ readyState: 'open', listeners: new Set(), closed: false }));+ ends.forEach((end, index) => {+ const other = ends[1 - index];+ end.send = text => other.listeners.forEach(listener => listener({ data: text }));+ end.addEventListener = (type, listener) => end.listeners.add(listener);+ end.removeEventListener = (type, listener) => end.listeners.delete(listener);+ end.close = () => {+ end.closed = true;+ end.readyState = 'closed';+ };+ });+ return ends;+}++function createPeer(netcodeOptions) {+ const netcode = createNetcode(netcodeOptions);+ const runtime = createRuntime({ render() {} }, { mode: 'both', fixedRate: 50, scheduler: idleScheduler, systems: [netcode] });+ return { netcode, runtime };+}++test('a data channel transport lists open channels, delivers to the named peer and drops a closed one', () => {+ const [hostEnd, firstEnd] = createChannelPair();+ const [secondHostEnd, secondEnd] = createChannelPair();+ const host = createDataChannelTransport({ id: 'host' });+ host.addChannel('first', hostEnd);+ host.addChannel('second', secondHostEnd);+ const first = createDataChannelTransport({ id: 'first' });+ first.addChannel('host', firstEnd);+ const heard = [];+ host.receive((peerId, message) => heard.push([peerId, message]));+ const firstHeard = [];+ first.receive((peerId, message) => firstHeard.push([peerId, message]));++ assert.deepEqual(host.peers().sort(), ['first', 'second']);+ first.send('host', { type: 'input' });+ host.send('first', { type: 'snapshot' });+ assert.deepEqual(heard, [['first', { type: 'input' }]]);+ assert.deepEqual(firstHeard, [['host', { type: 'snapshot' }]]);++ secondEnd.close();+ secondHostEnd.readyState = 'closed';+ assert.deepEqual(host.peers(), ['first']);+ host.send('second', { ignored: true });+ assert.equal(host.stats.sent, 1, 'a closed channel is skipped without throwing');++ host.removeChannel('first');+ assert.deepEqual(host.peers(), []);+ first.send('host', { type: 'late' });+ assert.equal(heard.length, 1, 'a removed channel no longer delivers');+});++test('a data channel transport rejects bad options, channels, oversized and malformed messages', () => {+ assert.throws(() => createDataChannelTransport({}), /createDataChannelTransport id/);+ assert.throws(() => createDataChannelTransport({ id: 'a', maximumMessageBytes: 10 }), /maximumMessageBytes/);+ const transport = createDataChannelTransport({ id: 'a', maximumMessageBytes: 256 });+ const [end] = createChannelPair();+ assert.throws(() => transport.addChannel('', end), /addChannel peerId/);+ assert.throws(() => transport.addChannel('b', {}), /data-channel-like/);+ transport.addChannel('b', end);+ assert.throws(() => transport.send('b', { text: 'x'.repeat(300) }), /at most 256/);+ end.listeners.forEach(listener => listener({ data: 'not json' }));+ end.listeners.forEach(listener => listener({ data: 42 }));+ end.listeners.forEach(listener => listener({ data: 'x'.repeat(300) }));+ assert.equal(transport.stats.rejected, 3);+ for (let index = 0; index < 31; index += 1) transport.addChannel(`peer-${index}`, createChannelPair()[0]);+ assert.throws(() => transport.addChannel('one-too-many', createChannelPair()[0]), /at most 32 peers/);+ transport.addChannel('b', createChannelPair()[0]);+ transport.close();+ assert.deepEqual(transport.peers(), []);+ assert.equal(end.listeners.size, 0);+});++test('a host and two clients sync players and a driven prop over data channels', () => {+ const hostTransport = createDataChannelTransport({ id: 'host' });+ const host = createPeer({ role: 'authority', authority: 'host', transport: hostTransport, localEntityId: 'host' });+ const clients = ['bob', 'cara'].map(name => {+ const [hostEnd, clientEnd] = createChannelPair();+ hostTransport.addChannel(name, hostEnd);+ const transport = createDataChannelTransport({ id: name });+ transport.addChannel('host', clientEnd);+ host.netcode.addEntity(name, { owner: name, tag: 'player' });+ return createPeer({ role: 'client', serverId: 'host', localEntityId: name, transport, readInput: () => ({ moveX: name === 'bob' ? 1 : -1 }) });+ });+ host.netcode.addEntity('crate', { tag: 'prop', state: { position: [0, 1, 0] } });++ for (let frame = 0; frame < 100; frame += 1) {+ host.netcode.setEntityState('crate', { position: [frame * 0.05, 1, 0] });+ host.runtime.step(FRAME_MILLISECONDS);+ clients.forEach(client => client.runtime.step(FRAME_MILLISECONDS));+ }+ const [bob, cara] = clients;+ const hostCrate = host.netcode.getEntityState('crate').position[0];+ assert.ok(hostCrate > 4.9);+ for (const client of clients) {+ assert.ok(Math.abs(client.netcode.getEntityState('crate').position[0] - hostCrate) < 0.6, 'the prop follows the host');+ assert.equal(client.netcode.stats.rejectedMessages, 0);+ }+ assert.ok(bob.netcode.getEntityState('bob').position[0] > 5);+ assert.ok(cara.netcode.getEntityState('cara').position[0] < -5);+ assert.ok(Math.abs(bob.netcode.getEntityState('cara').position[0] - host.netcode.getEntityState('cara').position[0]) < 0.8);+});