Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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.js
index 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.js
new file mode 100644
index 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);
+});