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
// Ambient crowd for /play — a living world without a server.
//
// Self-attaching: this module watches the live CoinCommunities scene
// (window.__CC__) and, while the player is inside a coin world, fills the plaza
// with decorative wandering avatars that stroll, idle, emote, and drop the
// occasional line into chat. So a solo demo never looks like an empty room — and
// the crowd tapers to nothing as real peers join, so the space is never padded
// with fakes once it's genuinely busy.
//
// Deliberately ZERO edits to coincommunities.js: it reads only the public
// scene/camera/ui and runs its own rAF. That keeps it collision-free while the
// rest of the scene is under active development.
import { Group, Vector3 } from 'three';
import { AnimationManager } from '../animation-manager.js';
import { detectProfile } from '../club-perf.js';
// The crowd wears the same models the players do, so it loads them through the
// same shared template cache instead of keeping a second loader and a second
// copy of every model. That also buys it the Draco + VRM decoders and the
// refcounted eviction that only lived on the player path before.
import {
buildAvatar as buildRigAvatar, releaseAvatar, hasModelTemplate,
loadManifest as loadRigManifest, getAllEmoteDefs,
AVATAR_DEFAULT, CLIP_IDLE, CLIP_WALK,
} from './avatar-rig.js';
import { loadCitizenPool, isCitizen, openCitizenProfile } from './npc/citizens.js';
import { log } from '../shared/log.js';
const WORLD_RADIUS = 54; // a touch inside the plaza edge
const AMBIENT_SPEED = 1.7; // gentle stroll, slower than the player
const MB = 1024 * 1024;
// Memory budget for the decorative crowd, per render tier.
//
// The public gallery is user-uploaded and uncapped: live models in it run from
// ~700 KB to 24 MB. The crowd used to draw a fresh random model per wanderer,
// per re-sync, with no size filter, no reuse and no disposal, so a phone that
// happened to draw a few heavy avatars pulled tens of megabytes of GLB into
// memory within seconds of world entry, and iOS Safari killed the tab. That is
// what made /play "randomly" kick mobile players: the draw is random, so the
// crash was too.
//
// Three limits keep it bounded. `maxModelBytes` filters the pool down to models
// the device can afford at all, `sessionBytes` caps what one visit may download
// in total (past it, the crowd re-clones models already resident rather than
// fetching more), and `count` sizes the crowd itself. Shadow casting is dropped
// on the low tier, where five shadow-casting skinned meshes cost more than the
// crowd is worth.
const CROWD_BUDGET = {
high: { count: 5, maxModelBytes: 12 * MB, sessionBytes: 80 * MB, shadows: true },
medium: { count: 4, maxModelBytes: 6 * MB, sessionBytes: 32 * MB, shadows: true },
low: { count: 2, maxModelBytes: 3 * MB, sessionBytes: 10 * MB, shadows: false },
};
// A phone lands in the shared 'medium' tier because Safari reports neither
// deviceMemory nor hardwareConcurrency, so the detector defaults both to
// "plenty". That is the right call for the renderer (a modern iPhone draws the
// world fine) and the wrong one for a download budget: the phone still has a
// fraction of a laptop's memory headroom and is the device that actually gets
// killed. Step the crowd budget down one tier when the primary pointer is
// coarse, without touching the shared render profile.
function crowdBudget() {
const tiers = ['high', 'medium', 'low'];
let i = Math.max(0, tiers.indexOf(detectProfile()));
const touchPrimary = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
if (touchPrimary) i = Math.min(tiers.length - 1, i + 1);
return CROWD_BUDGET[tiers[i]];
}
const BUDGET = crowdBudget();
const NAMES = ['satoshi', 'anon', 'gm_ser', 'degenape', 'moonboy', 'pepe', 'wagmi', 'hodlqueen', 'vibes', 'chad', 'frfr', 'fomo', 'ngmi', 'based_dev', 'gigachad', '0xshill', 'florp'];
const LINES = ['gm ☀️', 'wen moon', 'lfg 🚀', 'wagmi', 'probably nothing', 'few understand', 'based', 'diamond hands 💎', 'ser…', 'this is the way', 'bullish af', 'vibes immaculate', 'we so back', 'iykyk', 'up only 📈'];
let _emotes = null; // a handful of emote defs
let _avatars = null; // pool of affordable gallery picks ([] once the fetch settles)
// Models the crowd has actually worn this visit, and the bytes it charged for
// them. The models themselves live in avatar-rig's shared template cache (one
// download per URL across players AND wanderers); this set only exists so the
// crowd can keep drawing from what it already paid for once its own download
// budget is spent.
const _worn = new Set();
let _spentBytes = 0;
async function loadManifest() {
if (_emotes) return;
await loadRigManifest();
_emotes = getAllEmoteDefs().slice(0, 6);
}
// Pull a varied set of real avatars from the public gallery so the crowd reads as
// a living mix of community models rather than one repeated default. The shared
// citizen pool (citizens.js) supplies full records, so each wanderer keeps the
// identity of the avatar it wears: its gallery name, bio, and the registered
// agent behind it. Only models whose published size fits this device's
// per-model budget make the pool; an entry with no size is skipped rather than
// gambled on, since one 24 MB draw is enough to end a mobile session. Settles
// to an empty array on failure; each wanderer then falls back to AVATAR_DEFAULT.
async function loadAvatarPool() {
if (_avatars) return;
const records = await loadCitizenPool();
_avatars = records.filter((p) => p.url && p.bytes > 0 && p.bytes <= BUDGET.maxModelBytes);
}
// Dress a wanderer through the shared avatar pipeline: one download and one
// parse per distinct model across the whole scene, Draco/meshopt/VRM decoders
// wired, a capsule stand-in of last resort, and refcounted templates that free
// themselves once nothing wears them. Only locomotion clips are loaded here; a
// wanderer's occasional emote fetches its clip on demand.
//
// `bytes` is the model's published size, charged against this visit's download
// budget the first time the crowd asks for a model nothing else already holds.
async function buildAvatar(rig, anim, pick) {
const url = pick?.url || AVATAR_DEFAULT;
if (!hasModelTemplate(url)) _spentBytes += pick?.bytes || 0;
const { height, downgraded } = await buildRigAvatar(rig, url, anim, { clips: 'locomotion' });
// Only record what is actually resident: a model that was refused (over the
// mobile size cap) or failed to parse must not be offered back as a "free"
// pick once the download budget runs out.
_worn.add(downgraded ? AVATAR_DEFAULT : url);
// Shadow casting is the crowd's own budget line: on the low tier five
// shadow-casting skinned meshes cost more than a decorative crowd is worth.
if (!BUDGET.shadows) rig.traverse((n) => { if (n.isMesh) n.castShadow = false; });
return height;
}
async function playEmote(anim, motion) {
if (!_emotes?.length) return;
const def = _emotes[(Math.random() * _emotes.length) | 0];
try {
if (!anim.clips?.has?.(def.name)) await anim.loadAnimation(def.name, def.url, { loop: false });
await anim.crossfadeTo(def.name, 0.15);
setTimeout(() => anim.crossfadeTo(motion === 'walk' ? CLIP_WALK : CLIP_IDLE, 0.2), 2400);
} catch { /* clip missing — ignore */ }
}
class Wanderer {
constructor(scene, name, avatarPick, onInspect) {
// A wanderer wearing a named gallery avatar IS that citizen: it carries the
// avatar's real name and identity, and its nameplate opens the profile.
// Only the nameless (default-avatar or anonymous-model) wanderers keep the
// decorative crowd names.
this.record = isCitizen(avatarPick) ? avatarPick : null;
this.name = this.record ? this.record.name : name;
this.held = false;
this.rig = new Group();
this.anim = new AnimationManager();
this.height = 1.7;
this.motion = 'idle';
const a = Math.random() * Math.PI * 2, r = 5 + Math.random() * (WORLD_RADIUS * 0.7);
this.rig.position.set(Math.cos(a) * r, 0, Math.sin(a) * r);
this.yaw = Math.random() * Math.PI * 2; this.rig.rotation.y = this.yaw;
scene.add(this.rig);
this.scene = scene;
this.label = document.createElement('div');
this.label.className = 'cc-label';
this.label.textContent = this.name;
if (this.record) {
this.citizen = {
record: this.record,
name: this.name,
say: (t) => this.say(t),
hold: () => { this.held = true; this._setMotion('idle'); },
release: () => { this.held = false; },
};
// .cc-label is pointer-events:none globally; re-enable for this one, the
// same way peer nameplates do, so the name itself is the tap target.
this.label.style.pointerEvents = 'auto';
this.label.style.cursor = 'pointer';
this.label.title = `Meet ${this.name}`;
this.label.addEventListener('click', (e) => { e.stopPropagation(); onInspect?.(this); });
}
document.body.appendChild(this.label);
this.bubble = null; this._bubbleTimer = null;
this._dest = null;
this._wait = 0.5 + Math.random() * 2.5;
this._sayIn = 5 + Math.random() * 16;
this._emoteIn = 9 + Math.random() * 22;
buildAvatar(this.rig, this.anim, avatarPick).then((h) => { this.height = h; });
}
_setMotion(m) {
if (m === this.motion) return;
this.motion = m;
this.anim.crossfadeTo(m === 'walk' ? CLIP_WALK : CLIP_IDLE, 0.2);
}
say(text, onChat) {
if (this._disposed) return; // churned away mid-conversation; the chat panel outlives the body
if (this.bubble) this.bubble.remove();
this.bubble = document.createElement('div');
this.bubble.className = 'cc-bubble';
this.bubble.textContent = text;
document.body.appendChild(this.bubble);
clearTimeout(this._bubbleTimer);
this._bubbleTimer = setTimeout(() => { this.bubble?.remove(); this.bubble = null; }, 4500);
onChat?.(this.name, text);
}
update(dt, onChat, player) {
// Held for a conversation: stand still, face whoever stopped to talk, and
// keep quiet (the chat panel drives the speech bubble now).
if (this.held) {
this._dest = null;
this._wait = 1 + Math.random() * 2;
if (player) {
const want = Math.atan2(player.x - this.rig.position.x, player.z - this.rig.position.z);
let d = want - this.yaw;
while (d > Math.PI) d -= Math.PI * 2;
while (d < -Math.PI) d += Math.PI * 2;
this.yaw += d * Math.min(1, dt * 6);
this.rig.rotation.y = this.yaw;
}
this.anim.update(dt);
return;
}
this._sayIn -= dt;
if (this._sayIn <= 0) { this._sayIn = 12 + Math.random() * 26; this.say(LINES[(Math.random() * LINES.length) | 0], onChat); }
this._emoteIn -= dt;
if (this._emoteIn <= 0 && this.motion === 'idle') { this._emoteIn = 16 + Math.random() * 26; playEmote(this.anim, this.motion); }
if (!this._dest) {
this._wait -= dt;
if (this._wait <= 0) {
const a = Math.random() * Math.PI * 2, r = Math.random() * (WORLD_RADIUS * 0.8);
this._dest = new Vector3(Math.cos(a) * r, 0, Math.sin(a) * r);
this._setMotion('walk');
}
} else {
const p = this.rig.position;
const dx = this._dest.x - p.x, dz = this._dest.z - p.z;
const dist = Math.hypot(dx, dz);
if (dist < 0.45) { this._dest = null; this._wait = 1.5 + Math.random() * 4.5; this._setMotion('idle'); }
else {
const step = Math.min(dist, AMBIENT_SPEED * dt);
p.x += (dx / dist) * step; p.z += (dz / dist) * step;
const tYaw = Math.atan2(dx, dz);
let d = tYaw - this.yaw;
while (d > Math.PI) d -= Math.PI * 2;
while (d < -Math.PI) d += Math.PI * 2;
this.yaw += d * Math.min(1, dt * 6);
this.rig.rotation.y = this.yaw;
}
}
this.anim.update(dt);
}
dispose() {
this._disposed = true;
this.scene.remove(this.rig);
// Dereference the shared model template and free this clone's own
// materials (and any capsule stand-in) before dropping the rig; a bare
// rig.clear() drops the JS reference and leaks the GPU buffers.
releaseAvatar(this.rig);
this.rig.clear();
// Drop the mixer + its bound clip actions. The clips themselves are shared
// module-wide and stay cached; only this rig's bindings go.
this.anim.dispose();
this.label.remove();
this.bubble?.remove();
clearTimeout(this._bubbleTimer);
}
}
class AmbientCrowd {
constructor(cc) {
this.cc = cc;
this.list = [];
this.active = false;
this._names = [...NAMES];
this._avatarBag = []; // shuffled gallery URLs, drained for distinct assignment
// Wanderers speak only through their overhead bubbles. They used to also
// append lines into the real chat log as if they were players, which reads
// as fabricated activity the moment anyone answers "gm" and gets silence.
// The chat log carries real messages only.
this._onChat = null;
}
_takeName() {
if (!this._names.length) this._names = [...NAMES];
const i = (Math.random() * this._names.length) | 0;
return this._names.splice(i, 1)[0];
}
// Hand out a distinct gallery avatar each time; refill (and reshuffle) only once
// the bag empties, so we exhaust the pool before any model repeats. Once this
// visit's download budget is spent, keep the variety we already paid for: draw
// from the models still resident in memory instead of fetching another one.
// Wanderers churn every time a real player joins or leaves, so without this an
// hour in a busy world would download the whole gallery.
_takeAvatar() {
if (!_avatars?.length) return null;
if (_spentBytes >= BUDGET.sessionBytes) {
const resident = [..._worn];
if (!resident.length) return null;
const url = resident[(Math.random() * resident.length) | 0];
// Keep the identity riding the resident model: same record, zero new
// bytes charged (the download already happened this visit).
const rec = _avatars.find((p) => p.url === url);
return rec ? { ...rec, bytes: 0 } : { url, bytes: 0 };
}
if (!this._avatarBag.length) this._avatarBag = [..._avatars];
const i = (Math.random() * this._avatarBag.length) | 0;
return this._avatarBag.splice(i, 1)[0];
}
// Open the citizen profile card for a wanderer: the real agent behind the
// gallery avatar it wears, with a "Talk 1-on-1" into the live NPC chat.
_inspect(w) {
if (!w.citizen) return;
const coin = this.cc.coin || {};
openCitizenProfile(w.citizen, {
world: { mint: coin.mint, name: coin.name, symbol: coin.symbol },
ui: this.cc.ui,
trigger: w.label,
});
}
sync(realCount) {
const want = Math.max(0, BUDGET.count - (realCount | 0));
while (this.list.length < want) this.list.push(new Wanderer(this.cc.scene, this._takeName(), this._takeAvatar(), (w) => this._inspect(w)));
while (this.list.length > want) this.list.pop().dispose();
// The HUD's online count reports REAL players only (self + live peers).
// Padding it with the decorative crowd was a lie a livestream can catch in
// one screenshot; the wanderers are scenery, not population.
try { this.cc.ui?.setOnline?.((realCount | 0) + 1); } catch { /* ignore */ }
}
update(dt) {
const cam = this.cc.camera;
const W = window.innerWidth, H = window.innerHeight;
const place = (node, pos, dy) => {
const v = new Vector3(pos.x, pos.y + dy, pos.z).project(cam);
if (v.z > 1 || v.z < -1) { node.style.display = 'none'; return; }
node.style.display = '';
node.style.transform = `translate(-50%, -100%) translate(${(v.x * 0.5 + 0.5) * W}px, ${(-v.y * 0.5 + 0.5) * H}px)`;
};
for (const w of this.list) {
w.update(dt, this._onChat, this.cc.localPos);
place(w.label, w.rig.position, w.height + 0.2);
if (w.bubble) place(w.bubble, w.rig.position, w.height + 0.7);
}
}
clear() {
for (const w of this.list) w.dispose();
this.list = [];
this._avatarBag = [];
// Each dispose() above released its template reference; anything no player
// still wears is now free to be evicted by the shared cache's memory
// budget. Leaving a world used to keep every model the crowd had ever worn
// resident for the rest of the page's life; on a phone that alone could
// outlive the tab.
_worn.clear();
_spentBytes = 0;
}
}
// How long the world must have been standing before the crowd starts spending
// on itself. See SETTLE_MS's use below for why this exists at all.
const SETTLE_MS = 2500;
// ---- bootstrap: wait for the scene, then run an independent update loop ----
async function attach(attempt = 0) {
const cc = window.__CC__;
if (!cc || !cc.scene || !cc.camera) {
// The scene never appearing means boot failed (e.g. no WebGL, error card
// up). Give up after ~90s instead of polling a dead page forever.
if (attempt < 300) setTimeout(() => attach(attempt + 1), 300);
return;
}
const crowd = new AmbientCrowd(cc);
let last = performance.now();
let realCount = -1;
// When the current world became playable. The crowd is scenery, and scenery
// must never compete with the thing it decorates: populating it the instant
// the world opened put a gallery fetch, several multi-megabyte GLB downloads,
// and a skeleton retarget per wanderer directly on top of world entry, which
// is already the busiest moment of the session (physics boot, district build,
// the player's own avatar, the room join). Everything below waits out
// SETTLE_MS of actual world time first, so the player's own world lands
// clean and the crowd fills in behind it.
let worldSince = 0;
// Started once, on the first settled world, and awaited before the first
// wanderer is built. The pool fetch used to run at module load, i.e. during
// the page's cold boot, for a crowd that could not be shown for seconds yet.
let assets = null;
const tick = () => {
requestAnimationFrame(tick);
const now = performance.now();
const dt = Math.min(0.05, (now - last) / 1000);
last = now;
if (cc.phase === 'world') {
if (!crowd.active) { crowd.active = true; realCount = -1; worldSince = now; }
if (now - worldSince < SETTLE_MS) return;
if (!assets) {
// A failed emote manifest costs the crowd its gestures, not its
// existence, and the citizen pool resolves to [] rather than throwing.
// Swallow so neither turns into an unhandled rejection.
assets = Promise.all([loadManifest(), loadAvatarPool()])
.catch((e) => log.warn('[ambient-crowd] asset load failed:', e?.message));
}
// The pool is what decides which models a wanderer may wear, so building
// one before it resolves would dress the whole crowd in the default
// avatar. Hold the population (not the update loop) until it lands.
if (!_avatars) return;
const rc = (cc.remotes?.size) | 0;
if (rc !== realCount) { realCount = rc; crowd.sync(rc); }
crowd.update(dt);
} else if (crowd.active) {
crowd.clear();
crowd.active = false;
}
};
requestAnimationFrame(tick);
}
attach();