Skip to content

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.

18.3 KB
Raw Blame
// 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();