3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// A two-player sample for crucible/addons/netcode. One page hosts (it owns the truth and plays "alice"), the other is a client
// that predicts "bob". Each player moves a square with the arrow keys or WASD; both pages draw both squares.
// Open scripts/netcode-sample.html?role=host and scripts/netcode-sample.html?role=client in two tabs; see docs/netcode.md.
import { createRuntime } from '../src/runtime.js';
import {
createBroadcastChannelTransport,
createDataChannelTransport,
createNetcode,
createWebSocketTransport,
} from '../src/netcode.js';
const HOST_ID = 'alice';
const CLIENT_ID = 'bob';
const WORLD_HALF_SIZE = 8;
const FIXED_RATE = 50;
const SNAPSHOT_EVERY_TICKS = 1;
const INTERPOLATION_DELAY_SECONDS = 0.04;
const KEY_DIRECTIONS = {
ArrowLeft: [-1, 0], KeyA: [-1, 0],
ArrowRight: [1, 0], KeyD: [1, 0],
ArrowUp: [0, -1], KeyW: [0, -1],
ArrowDown: [0, 1], KeyS: [0, 1],
};
// The relay runs on the machine that serves this page: the socket URL takes the host from the page itself, ws or wss to
// match the page's protocol, and only a port number from the ?relayPort= query. No query text reaches the URL.
export const DEFAULT_RELAY_PORT = 8787;
export function relaySocketUrl(pageLocation, relayPort, playerId) {
const port = Number(relayPort);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new TypeError(`The relay port must be a whole number from 1 to 65535, got ${JSON.stringify(relayPort)}. Pass ?relayPort=${DEFAULT_RELAY_PORT}.`);
}
const scheme = pageLocation.protocol === 'https:' ? 'wss' : 'ws';
return `${scheme}://${pageLocation.hostname}:${port}/?id=${encodeURIComponent(playerId)}`;
}
function openWebSocket(relayPort, playerId) {
const socketUrl = relaySocketUrl(globalThis.location, relayPort, playerId);
return new Promise((resolve, reject) => {
const socket = new WebSocket(socketUrl);
socket.addEventListener('open', () => resolve(socket), { once: true });
socket.addEventListener('error', () => reject(new Error(`Could not reach the relay at ${socketUrl}. Start it on the machine that serves this page with: node scripts/netcode-relay.mjs --port ${relayPort}`)), { once: true });
});
}
// Delays what a transport sends, to feel a slow connection on one machine. Everything else, including the live `stats`
// getter, is read from the real transport, and delayed sends that have not left yet are dropped when it closes.
export function withInjectedLatency(transport, delayMilliseconds) {
if (delayMilliseconds <= 0) return transport;
const pendingTimers = new Set();
const delayed = Object.create(transport);
delayed.send = (peerId, message) => {
const timer = setTimeout(() => {
pendingTimers.delete(timer);
transport.send(peerId, message);
}, delayMilliseconds);
pendingTimers.add(timer);
};
delayed.close = () => {
for (const timer of pendingTimers) clearTimeout(timer);
pendingTimers.clear();
transport.close();
};
return delayed;
}
// WebRTC in one browser needs no server: the two pages trade the offer and the answer over a BroadcastChannel. A real game
// sends the same two messages through its own signalling service. Candidates are gathered before the description is sent, so
// there is no trickle. The client says hello until the host answers, so either page may load first.
const SIGNALLING_CHANNEL_NAME = 'crucible-netcode-signalling';
const SIGNALLING_RETRY_MILLISECONDS = 250;
const ICE_GATHERING_TIMEOUT_MILLISECONDS = 2000;
function describeWhenGathered(connection) {
return new Promise(resolve => {
const finish = () => resolve(connection.localDescription.toJSON());
if (connection.iceGatheringState === 'complete') {
finish();
return;
}
connection.addEventListener('icegatheringstatechange', () => { if (connection.iceGatheringState === 'complete') finish(); });
setTimeout(finish, ICE_GATHERING_TIMEOUT_MILLISECONDS);
});
}
function waitForOpen(channel) {
return new Promise((resolve, reject) => {
if (channel.readyState === 'open') {
resolve();
return;
}
channel.addEventListener('open', () => resolve(), { once: true });
channel.addEventListener('error', () => reject(new Error('The WebRTC data channel failed to open.')), { once: true });
});
}
async function createWebRtcTransport(playerId, remoteId, isHost) {
const transport = createDataChannelTransport({ id: playerId });
const signalling = new BroadcastChannel(SIGNALLING_CHANNEL_NAME);
const connection = new RTCPeerConnection({ iceServers: [] });
const channelOpen = new Promise(resolve => {
if (isHost) {
const channel = connection.createDataChannel('netcode', { ordered: false, maxRetransmits: 0 });
transport.addChannel(remoteId, channel);
resolve(waitForOpen(channel));
} else {
connection.addEventListener('datachannel', event => {
transport.addChannel(remoteId, event.channel);
resolve(waitForOpen(event.channel));
});
}
});
let offerSent = false;
signalling.onmessage = async event => {
const message = event.data;
if (message.to !== playerId) return;
if (isHost && message.type === 'hello' && !offerSent) {
offerSent = true;
await connection.setLocalDescription(await connection.createOffer());
signalling.postMessage({ to: remoteId, type: 'offer', description: await describeWhenGathered(connection) });
} else if (isHost && message.type === 'answer' && connection.signalingState === 'have-local-offer') {
await connection.setRemoteDescription(message.description);
} else if (!isHost && message.type === 'offer' && connection.signalingState === 'stable') {
await connection.setRemoteDescription(message.description);
await connection.setLocalDescription(await connection.createAnswer());
signalling.postMessage({ to: remoteId, type: 'answer', description: await describeWhenGathered(connection) });
}
};
const helloTimer = isHost ? null : setInterval(() => signalling.postMessage({ to: remoteId, type: 'hello' }), SIGNALLING_RETRY_MILLISECONDS);
await channelOpen;
clearInterval(helloTimer);
const closeChannels = transport.close;
transport.close = () => {
closeChannels();
connection.close();
signalling.close();
};
return transport;
}
async function createSampleTransport(options, playerId, remoteId) {
if (options.transport === 'broadcast') {
return createBroadcastChannelTransport(new BroadcastChannel('crucible-netcode-sample'), { id: playerId });
}
if (options.transport === 'websocket') {
const socket = await openWebSocket(options.relayPort ?? DEFAULT_RELAY_PORT, playerId);
return createWebSocketTransport(socket, { id: playerId, remoteId, multiplexed: true });
}
if (options.transport === 'webrtc') return createWebRtcTransport(playerId, remoteId, options.role === 'host');
throw new RangeError(`Sample transport must be "broadcast", "websocket" or "webrtc", got ${JSON.stringify(options.transport)}.`);
}
function readKeyboard(pressedKeys) {
let moveX = 0;
let moveZ = 0;
for (const code of pressedKeys) {
moveX += KEY_DIRECTIONS[code][0];
moveZ += KEY_DIRECTIONS[code][1];
}
return { moveX: Math.sign(moveX), moveZ: Math.sign(moveZ) };
}
function drawPlayers(canvas, netcode, localId) {
const context = canvas.getContext('2d');
const scale = canvas.width / (WORLD_HALF_SIZE * 2);
context.fillStyle = '#14161a';
context.fillRect(0, 0, canvas.width, canvas.height);
for (const [id, color] of [[HOST_ID, '#f0b429'], [CLIENT_ID, '#4fc3f7']]) {
const state = netcode.getEntityState(id);
if (!state) continue;
const x = (state.position[0] + WORLD_HALF_SIZE) * scale;
const y = (state.position[2] + WORLD_HALF_SIZE) * scale;
context.fillStyle = color;
context.fillRect(x - 10, y - 10, 20, 20);
if (id === localId) {
context.strokeStyle = '#ffffff';
context.strokeRect(x - 12, y - 12, 24, 24);
}
}
}
// options: { role: 'host' | 'client', transport: 'broadcast' | 'websocket' | 'webrtc', relayPort, delayMilliseconds, canvas,
// snapshotEveryTicks, interpolationDelaySeconds }
export async function startSample(options) {
const isHost = options.role === 'host';
const playerId = isHost ? HOST_ID : CLIENT_ID;
const remoteId = isHost ? CLIENT_ID : HOST_ID;
const transport = withInjectedLatency(await createSampleTransport(options, playerId, remoteId), options.delayMilliseconds ?? 0);
const pressedKeys = new Set();
let scriptedInput = null;
const readInput = () => scriptedInput ?? readKeyboard(pressedKeys);
window.addEventListener('keydown', event => { if (event.code in KEY_DIRECTIONS) pressedKeys.add(event.code); });
window.addEventListener('keyup', event => pressedKeys.delete(event.code));
// A snapshot every tick (20 ms) and a 40 ms interpolation delay: the drawn remote player trails by two snapshot intervals.
const timing = {
snapshotEveryTicks: options.snapshotEveryTicks ?? SNAPSHOT_EVERY_TICKS,
interpolationDelaySeconds: options.interpolationDelaySeconds ?? INTERPOLATION_DELAY_SECONDS,
};
const netcode = createNetcode(isHost
? { role: 'authority', authority: 'host', transport, readInput, ...timing }
: { role: 'client', serverId: HOST_ID, localEntityId: CLIENT_ID, transport, readInput, ...timing });
// A closed page tells the other one it left, so nobody keeps sending to a tab that is gone.
window.addEventListener('pagehide', () => transport.close());
if (isHost) {
netcode.addEntity(HOST_ID, { owner: HOST_ID, tag: 'player', state: { position: [-3, 0, 0] } });
netcode.addEntity(CLIENT_ID, { owner: CLIENT_ID, tag: 'player', state: { position: [3, 0, 0] } });
}
const runtime = createRuntime({ render() {} }, { fixedRate: FIXED_RATE, pauseWhenHidden: false, systems: [netcode] });
runtime.start();
const draw = () => {
if (options.canvas) drawPlayers(options.canvas, netcode, playerId);
requestAnimationFrame(draw);
};
draw();
// Resolves with the wall-clock time at which an entity drawn on this page has moved `distance` away from where it is now.
function whenEntityMoves(entityId, distance) {
const start = netcode.getEntityState(entityId).position;
return new Promise(resolve => {
const check = () => {
const position = netcode.getEntityState(entityId).position;
if (Math.hypot(position[0] - start[0], position[2] - start[2]) >= distance) resolve(Date.now());
else requestAnimationFrame(check);
};
check();
});
}
return {
playerId,
netcode,
runtime,
// Replaces the keyboard with a fixed input (or null to go back to the keyboard); used by tests and demos.
setInput(input) {
scriptedInput = input;
return Date.now();
},
position(entityId) {
return netcode.getEntityState(entityId)?.position ?? null;
},
whenEntityMoves,
};
}