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
// CommunityNet, multiplayer client for Coin Communities.
//
// Each coin is its own world: we join the shared `walk_world` room definition
// but pass `token = <mint>` so Colyseus's filterBy matches us only with players
// who entered the same coin's community. The server (WalkRoom) is authoritative
// for position, emotes, avatars, and chat relay.
//
// This is a focused sibling of walk-net.js, it adds coin identity, avatar URL,
// and chat on top of the same room, and leaves the /walk page's client
// untouched.
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 RECONNECT_BASE_MS = 3000;
// Stable persistence id for the off-schema economy (pack/purse/skills). When the
// player is signed in we key on their wallet; otherwise we mint and persist a guest
// id so progress survives a refresh on the same device. The server prefers the
// wallet it verified itself, so this only takes effect on un-gated/dev deploys.
function persistedPid(account) {
if (account) return account;
try {
let id = localStorage.getItem('cc-pid');
if (!id) { id = 'guest-' + Math.random().toString(36).slice(2, 12); localStorage.setItem('cc-pid', id); }
return id;
} catch { return ''; }
}
const RECONNECT_MAX_MS = 60_000;
// Attempts reset to 0 on every successful join, so this bounds ONE outage, not
// the session. Six attempts gave up ~2.5 minutes in, shorter than a server
// redeploy or instance replacement, which permanently stranded everyone present
// in single-player mid-session. Fourteen rides out ~11 minutes (the tail retries
// only once a minute) before parking on 'offline' with the manual retry().
const MAX_RECONNECT_ATTEMPTS = 14;
const SEND_HZ = 15;
const SEND_INTERVAL_MS = 1000 / SEND_HZ;
const POSITION_EPSILON = 0.01;
const YAW_EPSILON = 0.01;
const defaultServerUrl = defaultGameServerUrl;
export class CommunityNet {
/**
* @param {object} opts
* @param {string} [opts.name] display name
* @param {string} [opts.avatar] GLB/VRM URL for this player's avatar
* @param {string} [opts.agent] optional three.ws agent id
* @param {object} [opts.coin] { mint, name, symbol, image }, '' mint = lobby
* @param {string} [opts.tier] '' (open General world) | 'holders' (gated)
* @param {string} [opts.holderPass] signed pass required to join a holder world
* @param {number} [opts.holderMinUsd] USD floor the holder world gated on (HUD)
* @param {string} [opts.playPass] signed wallet+token pass for the platform gate
* @param {string} [opts.account] verified wallet address bound as the account id
* @param {string} [opts.url] server override
*/
constructor(opts = {}) {
this.name = opts.name || 'guest';
this.avatar = opts.avatar || '';
this.agent = opts.agent || '';
this.coin = opts.coin || { mint: '', name: '', symbol: '', image: '' };
this.tier = opts.tier === 'holders' ? 'holders' : '';
this.holderPass = opts.holderPass || '';
this.holderMinUsd = Number(opts.holderMinUsd) || 0;
// Platform token gate: when the server is gated, every join must carry this
// signed pass (proving wallet ownership + ≥ the token floor) or onAuth
// refuses with a play_pass_* error. Sent for all tiers, not just holders.
this.playPass = opts.playPass || '';
this.account = opts.account || '';
// Pre-join cosmetic loadout (W03): the compact wire string the creator built.
// The server re-validates ownership before applying it, so an unowned premium
// id here is simply dropped, never trusted.
this.cosmetics = opts.cosmetics || '';
// Stable economy persistence key (wallet when signed in, else a guest id).
this.pid = persistedPid(this.account);
this.url = opts.url || defaultServerUrl();
this.client = null;
this.room = null;
// Whether this room connection has announced its handlers (see _announceReady).
this._readySent = false;
this.status = 'idle';
this.error = null;
this.sessionId = null;
this.persistent = false; // set true once the server says this world is Redis-backed
this.worldTime = 0; // authoritative day fraction [0,1) for the day/night cycle
this._handlers = {
status: new Set(),
ready: new Set(), // (coinMeta)
add: new Set(), // (player, id)
change: new Set(), // (player, id)
remove: new Set(), // (id)
chat: new Set(), // ({id, name, text, ts})
interact: new Set(), // ({from, fromName, action, ts}), a peer interacted with us
denied: new Set(), // (reason), server refused the join (e.g. holder gate); no retry
voiceSignal: new Set(), // ({from, data}), relayed WebRTC SDP/ICE from a peer
ping: new Set(), // (ms), smoothed round-trip latency to the server
blockAdd: new Set(), // (key, type), a voxel appeared (placed or restored)
blockChange: new Set(), // (key, type), a voxel was repainted
blockRemove: new Set(), // (key), a voxel was broken
editReject: new Set(), // ({reason}), the server refused one of our edits
buildPerms: new Set(), // ({creator, cap, used, clearMaxRadius}), build-permission snapshot (R19)
buildCleared: new Set(), // ({count, all}), creator clear-area result (R19)
persistent: new Set(), // (bool), whether this world's build is durably saved
worldtime: new Set(), // (frac), authoritative day fraction [0,1) for day/night
// Off-schema economy (private to this player; delivered as targeted messages).
profile: new Set(), // (snapshot), full purse/pack/skills on join + on demand
inv: new Set(), // ({inv, hotbar, activeSlot, gold, hp, maxHp}), economy delta
xpgain: new Set(), // ({skill, amount, xp, level, levelXp, nextXp})
levelup: new Set(), // ({skill, level})
notice: new Set(), // ({kind, text, ...}), activity result toast (fish/eat/tool/full/quest)
souvenir: new Set(), // ({id, name, slot, eventId, eventName}): a live event just granted this account its free commemorative wearable (once, ever)
// General store, bank/ATM & the $THREE boutique (W04).
store: new Set(), // ({sell:[{item,label,price}], buy:[{item,qty,price,label}]})
boutique: new Set(), // ({listings, owned, configured}), premium cosmetics priced in $THREE
boutiqueQuote: new Set(), // ({id, price, quoteToken, txBase64}), unsigned $THREE purchase to sign
// Wheel of Fortune (W09), Fortune's Folly, the Mainland casino wheel.
spinInfo: new Set(), // ({segments, now, nextFreeSpinAt, avgLevel, minLevel, eligible, atWheel, paidAvailable, symbol, costUsd})
spinPrep: new Set(), // ({tx, tokenAmount, symbol, costUsd, quote}), unsigned paid-spin tx to sign
spinResult: new Set(), // ({mode, index, label, got, lost, refunded, nextFreeSpinAt?}), the server's roll
spinDenied: new Set(), // ({reason, ...}), a spin request refused
quests: new Set(), // ({offers, active, day, eventLive}), jobs board + active runs (W05)
questComplete: new Set(), // ({id, title, reward, kind, coop, event}), a mission/heist finished
// Live event (public/event.json window): the ranked standing for the event
// quest line, and this player's own running totals after each event job.
eventBoard: new Set(), // ({ok, event?, top?, you?, players?, totalRuns?, prizes?, reason?})
eventScore: new Set(), // ({runs, cash, eventId}), your totals after an event job
combat: new Set(), // ({role:'attacker'|'victim', target:'mob'|'player', kind?, mobHp?, mobMaxHp?, playerHp, playerMaxHp, dealt, dead, attacker?}), a swing/shot's result
// W07 combat world entities: roaming PvE mobs + lootable death tombstones.
// add/change/remove mirror the vehicle callbacks below.
mobAdd: new Set(), // (mob, id), a mob entered our view (spawn/restore)
mobChange: new Set(), // (mob, id), its position/hp/state changed
mobRemove: new Set(), // (id), a mob left the world (respawn cycle)
tombstoneAdd: new Set(), // (tombstone, id), a death dropped a lootable marker
tombstoneRemove: new Set(), // (id), looted or expired
// Vehicles (synced world entities). add/change/remove mirror the player
// callbacks; `vehicle` carries the server's targeted enter/exit/deny ack.
vehicleAdd: new Set(), // (vehicle, id), a vehicle entered our view (spawn/restore)
vehicleChange: new Set(), // (vehicle, id), its transform/driver changed
vehicleRemove: new Set(), // (id), a vehicle left the world
vehicle: new Set(), // ({event, id, ...}), enter/exit/deny ack for our request
// Generic world objects (R01/R02): the shared `objects` channel, balls,
// build props, pickups. add/change/remove mirror the player callbacks; the
// live schema object is passed through so the manager reads current fields.
objectAdd: new Set(), // (obj, id), an object appeared (spawned or restored)
objectChange: new Set(), // (obj, id), its transform/owner changed
objectRemove: new Set(), // (id), an object left the world
objectReject: new Set(), // ({reason}), server refused a spawn (world/player full)
// Fired once per connection, the moment the FIRST authoritative state
// snapshot has been decoded, i.e. every objectAdd/blockAdd the room had at
// join has already been emitted. `/play` uses it to retire the build it
// restored locally from the durable world store (P3.1), because from this
// point the room's own copies are in the scene and ours are duplicates.
synced: new Set(), // () : first full state patch applied
reaction: new Set(), // ({id, emoji}), a player sent a floating reaction
tag: new Set(), // ({event, itId, leaderboard}), tag mini-game state (R08)
floorBeat: new Set(), // ({clip}), disco-pad beat tick (R06): pulses the floor + aligns standing dancers
king: new Set(), // ({event, phase, endsAt, scores, kingId, winner, zone}), King of the Totem state (R07)
social: new Set(), // ({type, ...}), friends events: live DM, request/accept (W09)
};
// Optional async presence-ticket supplier (W09). When provided, its resolved
// token rides the join so this coin world publishes the player's account
// presence to their friends and can deliver DMs here live. Without it the
// player is connected but invisible to the social graph, the /walk surface
// has always passed one; /play now does too.
this.getPresence = typeof opts.getPresence === 'function' ? opts.getPresence : null;
this.ping = null; // smoothed RTT in ms, null until the first echo
this._pingSentAt = 0; // perf-clock stamp of the last move awaiting an echo
this._lastSent = null;
this._lastSentAt = 0;
this._reconnectTimer = null;
this._reconnectAttempts = 0;
this._destroyed = false;
this._connectGen = 0;
}
// The server-minted guest credential (HMAC-sealed guest id) persisted by the
// 'guestToken' message handler in connect(). Empty until the first join has
// sealed this device's guest id, or when storage is blocked.
_guestToken() {
try { return localStorage.getItem('tws-guest-token') || ''; } catch { return ''; }
}
on(event, fn) {
const bucket = this._handlers[event];
if (!bucket) throw new Error(`CommunityNet: unknown event "${event}"`);
bucket.add(fn);
return () => bucket.delete(fn);
}
_emit(event, ...args) {
for (const fn of this._handlers[event]) {
try { fn(...args); } catch (e) { log.error(`[community-net] ${event} handler threw:`, e); }
}
}
_setStatus(status, error = null) {
this.status = status; this.error = error;
this._emit('status', { status, error });
}
// Tell the room our message handlers are attached, so it can re-send the
// snapshot it pushed during onJoin (guest token, profile, quests, build perms,
// the King of the Totem sync). All of that goes out while we are still inside
// `await joinRoomWithTimeout`, before a single onMessage handler exists, and
// Colyseus drops a message nothing is listening for: measured on 2026-09-02,
// a guest lost the token their device needs to reclaim its progression and the
// HUD came up with no purse. The room re-sends full snapshots, so arriving
// twice is a repaint, never a double grant.
//
// Two things make this safe. It is gated on the room advertising support,
// because an older room build answers an unknown message type by closing the
// socket with 4002, which would kick every player during a client-before-server
// deploy. And it runs from the FIRST state sync, not from the end of connect():
// the flag lives on the schema, so reading it any earlier finds `undefined` and
// silently disables the handshake it is supposed to enable.
_announceReady() {
if (this._destroyed || this._readySent) return;
if (!this.room?.state?.acceptsReady) return;
this._readySent = true;
try { this.room.send('ready'); } catch { /* socket already gone */ }
}
// Detach and close the current room without triggering a reconnect. Every
// (re)connect replaces this.room; if the previous room were left live its
// 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-based events (move/avatar/blocks) hid it by being
// idempotent; chat appends a row on every delivery, so it showed.
_closeRoom() {
const room = this.room;
if (!room) return;
this.room = null;
// Drop onLeave/onError/onMessage first so leaving doesn't schedule a
// reconnect or surface a spurious error.
try { room.removeAllListeners(); } catch {}
try { room.leave(); } catch {}
}
async connect() {
if (this._destroyed) return;
this._closeRoom();
// No multiplayer server resolved for this environment (production with no
// game-server meta/env). Surface a distinct, honest 'unavailable' state,
// solo play still works, rather than throwing in `new Client('')`,
// looping on reconnects, or showing a "reconnecting…" pill that can never
// reconnect. (The exhausted-reconnect path below stays 'offline' because
// there a real server exists and a manual retry can still succeed.)
if (!this.url) {
this._setStatus('unavailable', 'multiplayer unavailable, single-player only');
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);
const mint = this.coin.mint || '';
// Resolve the presence ticket before the join so it can ride the options.
// Anonymous players resolve to null (nothing to publish) and a failed mint
// must never block play, hence the catch: the world still joins, the
// player is simply offline to their friends until the next reconnect.
const presence = this.getPresence ? await this.getPresence().catch(() => null) : null;
const options = {
// filterBy('coin','tier') isolates each coin into its own instance and
// splits the open General world from the gated Holders world; the
// coin-less lobby ('') groups all lobby players into one world.
coin: mint,
tier: this.tier,
coinName: this.coin.name || '',
coinSymbol: this.coin.symbol || '',
coinImage: this.coin.image || '',
name: this.name,
avatar: this.avatar,
agent: this.agent,
// Platform gate: harmless when the server isn't gated (ignored), required
// when it is. The verified wallet rides inside the signed pass; the server
// binds it as the account id, so we never trust a raw `account` option.
playPass: this.playPass,
// Pre-join cosmetic loadout (W03). Server-validated against ownership
// before it dresses the player, so peers can trust the broadcast look.
cosmetics: this.cosmetics,
// Legacy persistence key. Modern servers ignore it as an account key (a
// bare pid could claim any profile) except for the one-time migration of
// an old `guest-…` id into a signed guest token; older servers still read
// it, so keep sending it until every deploy is on the token flow.
pid: this.pid,
// Our own previous session id, sent only when this is a reconnect. A
// socket that died uncleanly is still half-open server-side for several
// seconds, so without this the room holds a frozen ghost of us at spawn
// until its ping retries expire. The server retires that exact session,
// and only when the persistent player key above matches ours too.
...(this.sessionId ? { prevSession: this.sessionId } : {}),
// Signed guest token (server-minted, HMAC-sealed guest id). This, not
// the raw pid, is what proves a guest owns their saved progression.
...(this._guestToken() ? { guestToken: this._guestToken() } : {}),
// Signed presence ticket (W09). WalkRoom verifies it and registers the
// account with the social hub under this world's name, so friends see
// "Online · <coin> Town" and DMs route to this socket. Omitted entirely
// when anonymous, the server treats its absence as "don't publish".
...(presence ? { presence } : {}),
};
// Holder worlds require a signed pass the server verifies in onAuth; carry
// it (and the floor it gated on, for the seed room's HUD) only for holders.
if (this.tier === 'holders') {
options.holderPass = this.holderPass;
options.holderMinUsd = this.holderMinUsd;
}
// Hard timeout on the join: a hung handshake (Cloud Run cold start, wedged
// room, proxy holding the upgrade) would otherwise strand us in 'connecting'
// forever, joinOrCreate has no timeout of its own. On timeout this throws
// 'connect_timeout', falling through to the catch → reconnect with backoff.
// No root-schema class passed on purpose: decode 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 for the why.
const room = await joinRoomWithTimeout(this.client, ROOM_NAME, options);
if (this._destroyed || gen !== this._connectGen) {
try { room.leave(); } catch {}
return;
}
this.room = room;
this.sessionId = this.room.sessionId;
// Per-room: a reconnect gets a fresh join snapshot, so it must announce
// itself again rather than inherit the previous session's flag.
this._readySent = false;
// Guest identity (see guest-token.js server-side): the room seals our guest
// id into a signed token and hands it back on every join. Persist it, the
// token is the credential that lets this device reclaim its progression.
this.room.onMessage('guestToken', (msg) => {
if (msg && typeof msg.token === 'string' && msg.token) {
try { localStorage.setItem('tws-guest-token', msg.token); } catch { /* storage blocked: session-only guest */ }
}
});
this.room.onMessage('chat', (msg) => this._emit('chat', msg));
this.room.onMessage('interact', (msg) => this._emit('interact', msg));
// Friends (W09): live DM + request/accept events pushed by the social hub
// to whichever realm room the account is currently registered in.
this.room.onMessage('social', (msg) => this._emit('social', msg));
this.room.onMessage('voice-signal', (msg) => this._emit('voiceSignal', msg));
// The server replies here when it refuses one of our place/break edits
// (budget full, rate limited, …) so the HUD can explain the no-op.
this.room.onMessage('edit-reject', (msg) => this._emit('editReject', msg || {}));
// Build permissions (R19): the per-player cap + usage, and whether we're the
// coin creator (which unlocks the clear-area moderation tool). Sent on join and
// whenever our tally moves. build-cleared confirms a creator clear-area sweep.
this.room.onMessage('build-perms', (msg) => this._emit('buildPerms', msg || {}));
this.room.onMessage('build-cleared', (msg) => this._emit('buildCleared', msg || {}));
// Off-schema economy: the server streams this player's own pack/purse/skills
// here (peers never see it). Drives the HUD, inventory, hotbar and toasts.
this.room.onMessage('profile', (msg) => this._emit('profile', msg || {}));
this.room.onMessage('inv', (msg) => this._emit('inv', msg || {}));
// Event souvenir: sent once, at the moment the server grants a live
// event's commemorative wearable to this account. Never repeated on a
// rejoin (the grant is idempotent), so the client can treat it as a
// one-time "you just earned this" moment rather than a state sync.
this.room.onMessage('souvenir', (msg) => this._emit('souvenir', msg || {}));
this.room.onMessage('xpgain', (msg) => this._emit('xpgain', msg || {}));
this.room.onMessage('levelup', (msg) => this._emit('levelup', msg || {}));
this.room.onMessage('notice', (msg) => this._emit('notice', msg || {}));
// General store, bank/ATM & the $THREE boutique (W04).
this.room.onMessage('store', (msg) => this._emit('store', msg || {}));
this.room.onMessage('boutique', (msg) => this._emit('boutique', msg || {}));
this.room.onMessage('boutiqueQuote', (msg) => this._emit('boutiqueQuote', msg || {}));
// Wheel of Fortune (W09).
this.room.onMessage('spinInfo', (msg) => this._emit('spinInfo', msg || {}));
this.room.onMessage('spinPrep', (msg) => this._emit('spinPrep', msg || {}));
this.room.onMessage('spinResult', (msg) => this._emit('spinResult', msg || {}));
this.room.onMessage('spinDenied', (msg) => this._emit('spinDenied', msg || {}));
// Quests, jobs & heists (W05): the board + active runs and completion events.
this.room.onMessage('quests', (msg) => this._emit('quests', msg || {}));
this.room.onMessage('questComplete', (msg) => this._emit('questComplete', msg || {}));
// Live event: the ranked leaderboard reply, and your own totals after a run.
this.room.onMessage('eventBoard', (msg) => this._emit('eventBoard', msg || {}));
this.room.onMessage('eventScore', (msg) => this._emit('eventScore', msg || {}));
this.room.onMessage('combat', (msg) => this._emit('combat', msg || {}));
// Vehicles: the server's targeted reply to our enter/exit request (grant,
// drop point, or denial). World transforms arrive via the state callbacks.
this.room.onMessage('vehicle', (msg) => this._emit('vehicle', msg || {}));
// Generic world objects (R01): the server replies here when it refuses a
// spawn (the room is full, or we've hit our per-player object cap) so the
// build HUD can explain why a placed prop never appeared.
this.room.onMessage('obj:reject', (msg) => this._emit('objectReject', msg || {}));
// Broadcast reactions (R04): floating emoji that rise above the sender's avatar.
this.room.onMessage('reaction', (msg) => this._emit('reaction', msg || {}));
this.room.onMessage('tag', (msg) => this._emit('tag', msg || {})); // R08 tag mini-game
// Dance floor (R06): the room broadcasts a beat every 4s so every client
// pulses the disco pad and crossfades standing dancers to the same clip in
// lockstep. The server message keeps its colon namespace; we normalize it to
// a camelCase event like the other namespaced messages above.
this.room.onMessage('floor:beat', (msg) => this._emit('floorBeat', msg || {}));
// King of the Totem (R07): the room broadcasts round start/tick/end (and a
// targeted sync on join) for the hold-the-totem mini-game. Server-authoritative
//, the client only renders the HUD + zone. Colon-namespaced like floor:beat;
// normalized to a camelCase `king` event.
this.room.onMessage('game:king', (msg) => this._emit('king', msg || {}));
const $ = getStateCallbacks(this.room);
const $state = $(this.room.state);
// Guard each collection: if the server is running an older schema that
// doesn't include a field yet, the proxy returns undefined for that key
// and calling .onAdd() on undefined throws, breaking the connect loop.
const $players = $state?.players;
if ($players) {
$players.onAdd((player, id) => {
this._emit('add', player, id);
$(player).onChange(() => {
// The server echoes our own authoritative state back after each
// move; the gap from send → echo is a real network+server RTT.
if (id === this.sessionId && this._pingSentAt) {
const rtt = performance.now() - this._pingSentAt;
this._pingSentAt = 0;
if (rtt > 0 && rtt < 5000) {
this.ping = this.ping == null ? rtt : this.ping * 0.7 + rtt * 0.3;
this._emit('ping', Math.round(this.ping));
}
}
this._emit('change', player, id);
});
});
$players.onRemove((_p, id) => this._emit('remove', id));
}
// Voxel builds: the server is authoritative for every block, so the
// world's geometry is driven entirely by these state callbacks, local
// place/break clicks only *send*; the block appears when the server
// echoes it back, keeping every client's build identical. onAdd fires
// for the full persisted build at join time and for each new placement.
// blocks field is optional (servers pre-dating voxel builds omit it).
const $blocks = $state?.blocks;
if ($blocks) {
$blocks.onAdd((block, key) => {
this._emit('blockAdd', key, block.t);
$(block).onChange(() => this._emit('blockChange', key, block.t));
});
$blocks.onRemove((_b, key) => this._emit('blockRemove', key));
}
// Vehicles: synced world entities. The full parked fleet arrives via onAdd
// at join; onChange streams each driver's transform; onRemove drops one.
// Optional field (servers pre-dating vehicles omit it), guarded like blocks.
const $vehicles = $state?.vehicles;
if ($vehicles) {
$vehicles.onAdd((vehicle, id) => {
this._emit('vehicleAdd', vehicle, id);
$(vehicle).onChange(() => this._emit('vehicleChange', vehicle, id));
});
$vehicles.onRemove((_v, id) => this._emit('vehicleRemove', id));
}
// Combat world entities (W07): roaming PvE mobs + lootable death tombstones.
// Both are server-owned synced state (everyone must see them, like
// vehicles), mirrors the vehicles wiring above exactly. Optional fields
// (servers pre-dating combat omit them), guarded like blocks/vehicles.
const $mobs = $state?.mobs;
if ($mobs) {
$mobs.onAdd((mob, id) => {
this._emit('mobAdd', mob, id);
$(mob).onChange(() => this._emit('mobChange', mob, id));
});
$mobs.onRemove((_m, id) => this._emit('mobRemove', id));
}
const $tombstones = $state?.tombstones;
if ($tombstones) {
$tombstones.onAdd((ts, id) => this._emit('tombstoneAdd', ts, id));
$tombstones.onRemove((_t, id) => this._emit('tombstoneRemove', id));
}
// Generic world objects (R01): the server is authoritative for every object,
// so the scene is driven entirely by these state callbacks, local spawn/
// move/remove only *send*; the object appears when the server echoes it back.
// onAdd fires for the full persisted set (durable props, R17) at join and for
// each new spawn. Optional field (older servers omit it), guarded like blocks.
const $objects = $state?.objects;
if ($objects) {
$objects.onAdd((obj, id) => {
this._emit('objectAdd', obj, id);
$(obj).onChange(() => this._emit('objectChange', obj, id));
});
$objects.onRemove((_o, id) => this._emit('objectRemove', id));
}
// Durability flag for this world's build (Redis-backed vs memory-only).
// Set once at room creation; listen so the HUD reflects it as soon as the
// first state patch lands and if it ever degrades mid-session.
this.persistent = !!this.room.state.persistent;
$state?.listen?.('persistent', (v) => { this.persistent = !!v; this._emit('persistent', !!v); });
// Authoritative time of day for the day/night cycle. The server advances it
// ~1Hz; the scene reads net.worldTime and interpolates between updates, so a
// coarse broadcast still renders a smooth sky every client agrees on.
this.worldTime = Number(this.room.state.worldTime) || 0;
$state?.listen?.('worldTime', (v) => { this.worldTime = Number(v) || 0; this._emit('worldtime', this.worldTime); });
// The first decoded state snapshot: everything the room already held
// (blocks, objects, vehicles) has now been emitted through the callbacks
// registered above. Registered AFTER them so their handlers run first.
// Guarded like every other optional room surface here: an older server
// build (or a stubbed room in a test harness) may not expose the signal,
// and a missing sync notification must never take the whole join down.
this.room.onStateChange?.once?.(() => {
if (!this._destroyed && gen === this._connectGen) this._emit('synced');
this._announceReady();
});
this.room.onLeave((code, reason) => {
this._setStatus('offline');
// A play-pass eviction (the server dropped us because our pass expired
// without a refresh, the wallet may have fallen below the token floor) is
// terminal: reconnecting would just fail onAuth again, so surface it as a
// denial and route the player back to the sign-in gate. Detect it by the
// server's close REASON, never by the bare close code: the legacy eviction
// code 4002 is also Colyseus's own WS_CLOSE_WITH_ERROR, which the server
// sends for any internal error (e.g. a message type this room build doesn't
// know), treating those as "session expired" kicked healthy players to a
// sign-in gate that wasn't even enabled. Anything else non-consented is a
// connection fault: reconnect with backoff.
if (/play_pass/i.test(reason || '')) { this._setStatus('denied', 'play_pass_required'); this._emit('denied', 'play_pass_required'); return; }
if (code === 4002) log.warn('[community-net] server closed with error:', reason || '(no reason)');
if (!this._destroyed && code !== 1000) this._scheduleReconnect();
});
this.room.onError((code, message) => log.warn('[community-net] room.onError', code, message));
// A reconnect gives us a fresh session the server spawns at the origin,
// so every send-suppression heuristic from the previous connection is
// now wrong. Clearing _lastSent is load-bearing: without it a player who
// reconnects while standing still never sends a move (the position is
// unchanged from the pre-drop one), so the server keeps them at spawn and
// every peer sees them teleported to 0,0,0 until they happen to walk.
// The RTT sample is dropped for the same reason, its send is gone.
this._lastSent = null;
this._lastSentAt = 0;
this._pingSentAt = 0;
this.ping = null;
this._reconnectAttempts = 0;
this._setStatus('online');
this._emit('ready', {
mint: this.room.state.coin,
name: this.room.state.coinName,
symbol: this.room.state.coinSymbol,
image: this.room.state.coinImage,
});
} catch (err) {
// Colyseus surfaces a failed matchmaking XHR as the raw ProgressEvent,
// which has no `message`, so the old `String(err)` fallback logged the
// literally useless "[object ProgressEvent]" and threw away the one fact
// worth knowing: which endpoint refused us. Name the target instead.
const msg = err?.message
|| (err?.code != null ? `code ${err.code}` : '')
|| (err?.target?.responseURL ? `no response from ${err.target.responseURL}` : '')
|| (err?.type ? `${err.type} from the game server` : String(err));
// A holder-gate refusal (onAuth threw) is terminal, not a flaky link,
// retrying with the same expired/invalid pass just loops. Surface it so
// the scene can route the player back to the gate, and stop here.
if (/holder_pass|play_pass/i.test(msg)) {
log.warn('[community-net] gate denied join:', msg);
this._setStatus('denied', msg);
this._emit('denied', msg);
return;
}
// Designed failure state, so this is expected-path telemetry rather than
// a warning: the status drives the HUD's connection pill, the backoff
// below retries on its own, and retry() offers a manual reconnect after
// that. An unreachable game server is the normal case on a dev box and
// behind a venue filter, and announcing our own offline mode as a defect
// in every visitor's console said nothing they or we could act on.
log.info('[community-net] connect failed:', msg);
this._setStatus('failed', msg);
this._scheduleReconnect();
}
}
// Exponential backoff with a hard ceiling. When the game server isn't
// reachable at all (e.g. not deployed), every attempt costs an 8s+ XHR
// timeout, retrying forever at a fixed 3s floods the console and the
// network tab. After MAX_RECONNECT_ATTEMPTS we stop and stay 'offline';
// the UI can offer manual reconnect via retry().
_scheduleReconnect() {
if (this._reconnectTimer || this._destroyed) return;
if (this._reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
this._setStatus('offline', 'multiplayer unreachable, single-player only');
return;
}
const attempt = this._reconnectAttempts++;
const backoff = Math.min(RECONNECT_BASE_MS * 2 ** attempt, RECONNECT_MAX_MS);
const delay = backoff + Math.random() * 1000;
this._reconnectTimer = setTimeout(() => {
this._reconnectTimer = null;
if (!this._destroyed) this.connect();
}, delay);
}
// 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; dropped messages are
// fine, every send here is a live-state signal the reconnect resyncs anyway.
_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;
}
sendMove(state) {
if (!this.room) return;
const now = performance.now();
if (now - this._lastSentAt < SEND_INTERVAL_MS) return;
if (this._lastSent) {
const moved = Math.hypot(state.x - this._lastSent.x, state.y - this._lastSent.y, state.z - this._lastSent.z);
const turned = Math.abs(state.yaw - this._lastSent.yaw);
if (moved < POSITION_EPSILON && turned < YAW_EPSILON && state.motion === this._lastSent.motion) 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;
// Stamp this move for RTT measurement unless one is already awaiting its
// echo, so each sample pairs a single send with its first state echo.
if (!this._pingSentAt) this._pingSentAt = now;
}
sendEmote(name) { this._send('emote', { name }); }
sendReaction(emoji) { this._send('reaction', { emoji }); }
sendChat(text) { this._send('chat', { text }); }
// Place/break a voxel at an integer grid cell. Server-authoritative: these only
// request the edit; the block is added/removed locally when the server patches
// state.blocks (see the onAdd/onRemove wiring above).
sendPlace(x, y, z, t) { this._send('place', { x, y, z, t }); }
// Place a composite piece in one atomic message: an array of {x,y,z,t} cells the
// server validates and applies all-or-nothing (see WalkRoom._handlePlaceBatch).
// Each placed block streams back through the same blockAdd path as single edits.
sendPlaceBatch(cells) { this._send('place-batch', { cells }); }
sendRemove(x, y, z) { this._send('remove', { x, y, z }); }
// Creator-only moderation (R19): clear a disc of blocks around a grid cell, or the
// whole world. The server validates the creator identity + bounds and streams each
// removal back through the usual blockRemove path.
sendClearArea(x, z, r) { this._send('build-clear', { x, z, r }); }
sendClearAll() { this._send('build-clear', { all: true }); }
sendInteract(to, action) { this._send('interact', { to, action }); }
// Spatial voice: relay a WebRTC offer/answer/ICE candidate to one peer, and
// flag ourselves in/out of voice so peers know whether to connect to us.
sendVoiceSignal(to, data) { this._send('voice-signal', { to, data }); }
setVoiceActive(on) { this._send('voice-state', { on: !!on }); }
rename(name) { this.name = name; this._send('rename', { name }); }
setAvatar(avatar, agent) { this.avatar = avatar; this._send('avatar', { avatar, agent }); }
// Equip a cosmetic into its slot (W03). Server-authoritative: it validates
// ownership, updates the player's schema `cosmetics` field (so peers re-render)
// and replies with a fresh profile. An unowned id is rejected with a 'notice'.
equipCosmetic(id) { this._send('equip-cosmetic', { id }); }
// Broadcast a full loadout wire in one shot, mirrors how the avatar is sent.
// Server validates every id against the catalog and the account's owned set,
// drops anything invalid or unowned, and publishes the sanitized wire on the
// schema so all peers re-render the correct look.
setCosmetics(wire) { this.cosmetics = typeof wire === 'string' ? wire : ''; this._send('set-cosmetics', { cosmetics: this.cosmetics }); }
// Activities & economy. Server-authoritative: these only request the action; the
// result arrives via the profile/inv/xpgain/levelup/notice events above.
// R05 physics ball: send a kick intent with the impulse the server should apply.
// The server validates magnitude, direction, and rate before touching the ball.
sendBallKick(vx, vy, vz) { this._send('ball:kick', { vx, vy, vz }); }
fish() { this._send('fish'); }
chop() { this._send('chop'); }
mine() { this._send('mine'); }
cook() { this._send('cook'); }
pickupRod() { this._send('pickupRod'); }
attack() { this._send('attack'); }
// Claim a tombstone's cash + items (W07). Server-gated by proximity; the
// result rides back over the usual profile/inv/notice channels.
lootTombstone(id) { this._send('loot', { id }); }
equip(slot) { this._send('equip', { slot }); }
consume(ref) { this._send('consume', { slot: ref }); }
requestProfile() { this._send('profileReq'); }
// General store & bank/ATM (W04). Cash trades and banking settle purely
// off-schema; the result streams back via the 'store'/'profile'/'inv'/
// 'notice' events above.
requestStore() { this._send('storeReq'); }
storeBuy(item) { this._send('storeBuy', { item }); }
storeSell(slot, qty) { this._send('storeSell', { slot, qty }); }
bank(amount) { this._send('bank', { amount }); }
// The $THREE boutique (W04). requestBoutique() fetches the catalog + owned
// set; boutiqueQuote() prices one item and returns the unsigned tx to sign
// (the reply arrives via the 'boutiqueQuote' event); boutiqueSettle() hands
// back the broadcast signature for the server to verify on-chain before it
// grants anything.
requestBoutique() { this._send('boutiqueReq'); }
boutiqueQuote(id, wallet) { this._send('boutiqueQuote', { id, wallet }); }
boutiqueSettle(quoteToken, txSig) { this._send('boutiqueSettle', { quoteToken, txSig }); }
// Wheel of Fortune (W09). spinInfo() asks for the current segments/eligibility/
// cooldown snapshot; spinFree() attempts the 12h free spin; spinPaidPrep(wallet)
// prices a $3-in-$THREE paid spin and returns the unsigned tx to sign (the
// reply arrives via the 'spinPrep' event); spinPaidSettle() hands back the
// broadcast signature for the server to verify on-chain before it rolls.
spinInfo() { this._send('spinInfo'); }
spinFree() { this._send('spinFree'); }
spinPaidPrep(wallet) { this._send('spinPaidPrep', { wallet }); }
spinPaidSettle(quote, txSig) { this._send('spinPaidSettle', { quote, txSig }); }
// Quests, jobs & heists (W05). Server-authoritative: accept/abandon a mission and
// interact at a quest object; the board + progress arrive via the 'quests' event
// and completions via 'questComplete'. questInteract acts on the zone the server
// finds the player standing in (pickup/dropoff/terminal/crack).
requestQuests() { this._send('questReq'); }
questAccept(id) { this._send('questAccept', { id }); }
questAbandon(id) { this._send('questAbandon', { id }); }
questInteract() { this._send('questInteract'); }
// The live event's leaderboard. The room proxies the same public read the web
// uses (api/play/event-leaderboard) and pins this player's own row from their
// verified account key, so the client never has to know or send an identity.
// The reply arrives on the 'eventBoard' event.
requestEventBoard() { this._send('eventBoardReq'); }
// Vehicles. enter/exit take + release the wheel (server-gated by proximity +
// occupancy, answered on the 'vehicle' event); vsync streams the driver's
// authoritative Rapier transform, which the server validates and relays. vsync
// is throttled to the move send rate; the driving loop calls it every frame.
sendVEnter(id) { this._send('venter', { id }); }
sendVExit(state) { this._send('vexit', state || {}); }
sendVSync(state) {
if (!this.room) return;
const now = performance.now();
if (now - (this._lastVSyncAt || 0) < SEND_INTERVAL_MS) return;
this._lastVSyncAt = now;
this._send('vsync', state);
}
// Generic world objects (R01/R02). These only *request* the change; the object
// appears/moves/disappears when the server echoes its authoritative `objects`
// state back (see the objectAdd/Change/Remove wiring above). The server assigns
// ownership, mints/clamps ids, and bounds-clamps the transform, the client
// never trusts its own optimistic copy. x/y/z must be finite or the server drops
// the spawn, so we guard here too and skip a malformed send.
spawnObject(kind, opts = {}) {
if (!this.room) return;
const { x, y, z } = opts;
if (![x, y, z].every(Number.isFinite)) return;
const msg = { kind: String(kind || ''), x, y, z };
if (typeof opts.type === 'string') msg.type = opts.type;
if (typeof opts.id === 'string') msg.id = opts.id;
// P3.3: a player-uploaded model url. The server re-validates it against the
// storage allow-list and refuses the spawn outright if it doesn't pass, so
// this is a request like any other, never a trusted value.
if (typeof opts.url === 'string' && opts.url) msg.url = opts.url;
if (Number.isFinite(opts.yaw)) msg.yaw = opts.yaw;
if (Number.isFinite(opts.scale)) msg.scale = opts.scale;
if (Number.isFinite(opts.vx)) msg.vx = opts.vx;
if (Number.isFinite(opts.vy)) msg.vy = opts.vy;
if (Number.isFinite(opts.vz)) msg.vz = opts.vz;
this._send('obj:spawn', msg);
}
updateObject(id, transform = {}) {
if (!this.room || typeof id !== 'string') return;
const msg = { id };
for (const k of ['x', 'y', 'z', 'yaw', 'scale', 'vx', 'vy', 'vz']) {
if (Number.isFinite(transform[k])) msg[k] = transform[k];
}
this._send('obj:update', msg);
}
removeObject(id) {
if (!this.room || typeof id !== 'string') return;
this._send('obj:remove', { id });
}
// Does an object's server-assigned ownerId belong to THIS client? The server keys
// ownership on the verified account when signed in, else the persisted economy id,
// else the session id (WalkRoom._ownerKey), match all three so delete-own works
// in gated, un-gated, and guest sessions alike.
ownsObject(obj) {
const owner = obj?.ownerId;
if (!owner) return false;
return owner === this.account || owner === this.pid || owner === this.sessionId;
}
// Adopt a refreshed play pass. Store it so the next reconnect (after a drop)
// uses the fresh credential, AND push it to the live session so the server can
// extend this connection's bound expiry, otherwise the server's per-minute
// sweep evicts a still-qualifying player at the original 10-min TTL (which
// stranded anyone in a long building session). The server re-verifies the pass
// against the gate before extending; a forged or below-floor pass is ignored.
updatePlayPass(pass) { this.playPass = pass || ''; if (pass) this._send('play-pass', { playPass: pass }); }
get state() { return this.room?.state ?? null; }
retry() {
if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
this._reconnectAttempts = 0;
this.connect();
}
// Is the wire actually carrying traffic right now? `status === 'online'` alone
// is a claim about the last thing that happened, not about the socket.
isLive() { return this.status === 'online' && this.room?.connection?.isOpen === true; }
// Call when the page comes back to the foreground. A backgrounded tab is the
// one case where the client's own status can be a lie: iOS Safari suspends the
// whole page, the OS reaps the TCP connection, and no 'close' event is ever
// delivered, so the client still reads 'online' while every send silently
// drops into a dead socket and no peer update ever arrives again. Probing the
// connection on resume converts that invisible half-death into the normal
// reconnect path. It also short-circuits the backoff when the retries were
// burned (or throttled) while the tab was hidden, so returning to the tab is
// always the fastest way back into the world.
resume() {
if (this._destroyed || !this.url) return;
if (this.status === 'online' && this.room?.connection?.isOpen !== true) {
log.warn('[community-net] socket died while backgrounded, reconnecting');
this._closeRoom();
this._setStatus('offline');
this.retry();
return;
}
if (this.status === 'offline' || this.status === 'failed') this.retry();
}
destroy() {
this._destroyed = true;
if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
this._closeRoom();
this.client = null;
}
}