Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Multiplayer client for /walk — wraps colyseus.js with a tiny event API
// that walk.js can subscribe to without knowing anything about Colyseus.
//
// Design goals:
// - Graceful single-player fallback. If the server is unreachable, the
// page still works; we surface the state via onStatus so the HUD can
// show "offline".
// - Bounded send rate. The render loop runs at 60+ Hz; we throttle to
// 15Hz outbound, matching the room's patch rate. Anything faster just
// wastes bandwidth.
// - No reconnection storms. On disconnect we attempt one reconnect with
// jittered backoff, then give up until the user clicks the HUD pill
// (handled in walk.js).
import { Client, getStateCallbacks } from 'colyseus.js';
import { log } from './shared/log.js';
import { joinRoomWithTimeout } from './shared/colyseus-connect.js';
import { defaultGameServerUrl } from './shared/game-server-url.js';
const ROOM_NAME = 'walk_world';
const SEND_HZ = 15;
const SEND_INTERVAL_MS = 1000 / SEND_HZ;
const POSITION_EPSILON = 0.005; // m — skip send if nothing meaningful changed
const YAW_EPSILON = 0.01; // rad
// Where the Colyseus host lives is one question with one answer, shared with
// /play and the Coin Wars arena via ./shared/game-server-url.js. This module
// used to carry its own copy, and the copy had drifted in the one place that
// matters to anyone running the server locally: it read the production
// <meta name="walk-server"> baked into pages/temporary.html BEFORE checking for
// localhost, so `npm run dev:walk-all` started a server the page then ignored,
// silently joining production instead. The shared resolver puts localhost first.
export class WalkNet {
/**
* @param {object} opts
* @param {string} [opts.name] Display name (1–24 chars after server clean)
* @param {string} [opts.url] Override server URL (otherwise resolved from meta)
* @param {string} [opts.room] Room type to join (default 'walk_world'). The Agora
* Commons joins its dedicated 'agora_world' room through the same client —
* identical status model, throttle, and reconnect semantics.
* @param {string} [opts.avatar] Loadable GLB URL for this player's avatar / 3D agent
* @param {string} [opts.agent] three.ws agent id this player embodies (cross-links)
* @param {string} [opts.coin] Coin mint — joins that coin's community world ('' = mainland)
* @param {string} [opts.coinName] Coin display name (seeds room identity on create)
* @param {string} [opts.coinSymbol] Coin ticker
* @param {string} [opts.coinImage] Coin image URL
*/
constructor(opts = {}) {
this.name = opts.name || 'guest';
this.url = opts.url || defaultGameServerUrl();
this.roomName = opts.room || ROOM_NAME;
this.avatar = opts.avatar || '';
this.agent = opts.agent || '';
// Coin community this client is entering. `coin` (the mint) doubles as the
// matchmaking key so everyone in the same coin lands in one room instance.
this.coin = opts.coin || '';
this.coinName = opts.coinName || '';
this.coinSymbol = opts.coinSymbol || '';
this.coinImage = opts.coinImage || '';
// Pre-join cosmetic loadout (R23): the wire string the player last equipped,
// so peers in this world see their fit the moment they appear. The server
// re-validates each id against what the account owns before publishing it.
this.cosmetics = opts.cosmetics || '';
this.client = null;
this.room = null;
this.status = 'idle'; // 'idle' | 'connecting' | 'online' | 'offline' | 'failed'
this.error = null;
this.mySessionId = null;
this._handlers = {
status: new Set(),
add: new Set(), // (player, sessionId)
remove: new Set(), // (sessionId)
change: new Set(), // (player, sessionId)
chat: new Set(), // ({ id, name, text, ts })
social: new Set(), // ({ type, ... }) — friends events: live DM, request/accept (Task 15)
message: new Set(), // (type, payload) — catch-all for every other room message
};
// Optional async presence-ticket supplier (Task 15). When provided, its
// resolved token rides the join so this coin world publishes the player's
// account presence to friends and can deliver DMs here live.
this.getPresence = typeof opts.getPresence === 'function' ? opts.getPresence : null;
// No `playPass` field here (community-net.js's join carries one) — /walk has
// no wallet sign-in UI to mint one. Harmless today (PLAY_GATE_MINT unset by
// default), but WalkRoom.onAuth will hard-reject every /walk join the moment
// that gate is turned on. See the landmine note at WalkRoom.onAuth before
// enabling PLAY_GATE_MINT/THREE_MINT in production.
this._lastSent = null; // { x, y, z, yaw, motion } we last broadcast
this._lastSentAt = 0;
this._reconnectTimer = null;
this._destroyed = false;
this._connectGen = 0;
}
on(event, fn) {
const bucket = this._handlers[event];
if (!bucket) throw new Error(`WalkNet: unknown event "${event}"`);
bucket.add(fn);
return () => bucket.delete(fn);
}
_emit(event, ...args) {
// A missing bucket must never throw: _emit runs inside colyseus message
// callbacks, so an unknown event would escape into the socket's dispatch
// loop and surface as an uncaught TypeError on every room message.
const bucket = this._handlers[event];
if (!bucket) return;
for (const fn of bucket) {
try { fn(...args); } catch (e) { log.error(`[walk-net] ${event} handler threw:`, e); }
}
}
_setStatus(status, error = null) {
this.status = status;
this.error = error;
this._emit('status', { status, error });
}
// Detach and close the current room without triggering a reconnect. Every
// (re)connect replaces this.room; left live, the old socket would keep firing
// onMessage('chat') alongside the new one, so a single broadcast got appended
// once per leftover connection — the duplicate chat bug. State events
// (move/avatar/blocks) hid it by being idempotent; chat appends a row per
// delivery, so it showed.
_closeRoom() {
const room = this.room;
if (!room) return;
this.room = null;
try { room.removeAllListeners(); } catch {}
try { room.leave(); } catch {}
}
async connect() {
if (this._destroyed) return;
this._closeRoom();
// No multiplayer server resolved for this environment (e.g. production
// with no walk-server meta/env configured). Surface a distinct, honest
// 'unavailable' state — the page still works solo — instead of throwing
// in `new Client('')`, looping on a dead endpoint, or showing a
// "reconnecting…" pill that will never reconnect (no server exists).
if (!this.url) {
this._setStatus('unavailable');
return;
}
// Bump a generation token so a slower in-flight connect (e.g. a manual
// retry racing the auto-reconnect timer) can detect it's been superseded
// after its await resolves and discard the room it joined, rather than
// orphaning a second live socket — the same duplicate-chat leak.
const gen = ++this._connectGen;
this._setStatus('connecting');
try {
this.client = new Client(this.url);
// `token` is the server's filterBy key (matchmaking): clients with the
// same coin mint join one room instance. `coin`/`coinName`/… seed that
// room's identity the first time it's created. Empty coin → mainland.
const presence = this.getPresence ? await this.getPresence().catch(() => null) : null;
// Hard timeout on the join: a hung handshake (cold-start server, proxy
// holding the WS upgrade) would otherwise strand us in 'connecting'
// forever — joinOrCreate has no timeout. On timeout this throws and the
// catch below schedules a reconnect.
const room = await joinRoomWithTimeout(this.client, this.roomName, {
name: this.name,
avatar: this.avatar,
agent: this.agent,
token: this.coin,
coin: this.coin,
coinName: this.coinName,
coinSymbol: this.coinSymbol,
coinImage: this.coinImage,
cosmetics: this.cosmetics,
...(presence ? { presence } : {}),
// No root-schema class passed on purpose: decode state from the server's
// reflected schema (handshake) so the client never desyncs when a deployed
// server adds an append-only field this bundle predates. See joinRoomWithTimeout.
});
if (this._destroyed || gen !== this._connectGen) {
try { room.leave(); } catch {}
return;
}
this.room = room;
this.mySessionId = this.room.sessionId;
// Colyseus 0.16 moved schema callbacks behind getStateCallbacks(room)
// — the legacy `state.players.onAdd(fn)` form no longer exists.
const $ = getStateCallbacks(this.room);
const $players = $(this.room.state)?.players;
if ($players) {
$players.onAdd((player, sessionId) => {
this._emit('add', player, sessionId);
// Per-instance onChange fires on every field delta.
$(player).onChange(() => this._emit('change', player, sessionId));
});
$players.onRemove((_player, sessionId) => {
this._emit('remove', sessionId);
});
}
// Chat is broadcast (not schema state) so it arrives as a room message.
// We relay it through our own event API; walk.js renders the bubble +
// log line and routes it to the right remote player.
this.room.onMessage('chat', (msg) => this._emit('chat', msg));
// Friends (Task 15): live DM + request/accept events pushed by the social hub.
this.room.onMessage('social', (msg) => this._emit('social', msg));
// The shared WalkRoom pushes more types than this page consumes
// (quests, game:king, floor:beat, profile, …) and the deployed server
// may add types this bundle predates. Catch-all relay: consumers
// subscribe to 'message' for anything beyond chat/social, and
// colyseus stops warning about unregistered types on every push.
this.room.onMessage('*', (type, msg) => this._emit('message', type, msg));
this.room.onLeave((code) => {
this._setStatus('offline');
if (!this._destroyed && code !== 1000) this._scheduleReconnect();
});
this.room.onError((code, message) => {
log.warn('[walk-net] room.onError', code, message);
});
this._setStatus('online');
} catch (err) {
// Colyseus handshake failures often carry an empty message (the 403
// is only visible on the WS upgrade) — fall back to code/String so
// the diagnostic is never blank.
const reason = err?.message || (err?.code != null ? `code ${err.code}` : String(err));
log.warn('[walk-net] connect failed:', reason);
this._setStatus('failed', reason);
// Single retry after ~3s — most failures here are "server not
// running yet" during local dev. After that we go offline until
// the user clicks the HUD pill (handled by walk.js).
this._scheduleReconnect();
}
}
_scheduleReconnect() {
if (this._reconnectTimer || this._destroyed) return;
const delay = 3000 + Math.random() * 1500;
this._reconnectTimer = setTimeout(() => {
this._reconnectTimer = null;
if (this._destroyed) return;
this.connect();
}, delay);
}
/**
* Send our local state to the server. Throttled to SEND_HZ — call this
* every frame and it'll do the right thing.
*
* @param {{ x:number, y:number, z:number, yaw:number, motion:string }} state
*/
// Send a message only when the wire is actually open. `this.room` alone isn't
// enough: between the socket entering CLOSING and onLeave firing, the room
// reference is still live, and ws.send() on that socket logs a console
// warning per message ("WebSocket is already in CLOSING or CLOSED state").
// Returns true when the message reached an open socket.
_send(type, payload) {
const room = this.room;
if (!room || room.connection?.isOpen !== true) return false;
try { room.send(type, payload); } catch { return false; }
return true;
}
sendState(state) {
if (!this.room) return;
const now = performance.now();
if (now - this._lastSentAt < SEND_INTERVAL_MS) return;
// Skip if nothing meaningful changed since the last send.
if (this._lastSent) {
const dx = state.x - this._lastSent.x;
const dy = state.y - this._lastSent.y;
const dz = state.z - this._lastSent.z;
const dyaw = state.yaw - this._lastSent.yaw;
const positionStill = Math.hypot(dx, dy, dz) < POSITION_EPSILON;
const yawStill = Math.abs(dyaw) < YAW_EPSILON;
const motionSame = state.motion === this._lastSent.motion;
if (positionStill && yawStill && motionSame) return;
}
if (!this._send('move', {
x: state.x,
y: state.y,
z: state.z,
yaw: state.yaw,
motion: state.motion,
})) return;
this._lastSent = { ...state };
this._lastSentAt = now;
}
rename(name) {
this.name = name;
this._send('rename', { name });
}
sendEmote(name) {
this._send('emote', { name });
}
sendChat(text) {
const t = String(text || '').trim().slice(0, 200);
if (t) this._send('chat', { text: t });
}
/** Swap this player's avatar mid-session (after picking a new one). */
sendAvatar(avatar, agent) {
this.avatar = avatar || this.avatar;
if (agent != null) this.agent = agent;
this._send('avatar', { avatar: this.avatar, agent: this.agent });
}
/** Force a reconnect (e.g. after the user clicks the offline pill). */
retry() {
if (this._reconnectTimer) {
clearTimeout(this._reconnectTimer);
this._reconnectTimer = null;
}
this.connect();
}
destroy() {
this._destroyed = true;
if (this._reconnectTimer) {
clearTimeout(this._reconnectTimer);
this._reconnectTimer = null;
}
this._closeRoom();
this.client = null;
}
}