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.

19.4 KB
Raw Blame
// Ambient world life, pedestrians and vehicle traffic that make the plaza
// breathe (W08).
//
// Everything here is a *pure function of a shared world clock* (wall time) and
// the world seed, so two players standing in the same town see the same crowd
// walking the same routes and the same cars on the same stretch of road,
// without a single ambient NPC crossing the wire. That's the brief's deal:
// ambient life is client-side and deterministic; only consequential NPCs
// (vendors, quests, mobs) are server-authoritative.
//
// Performance is built in: a small cast of detailed GLB pedestrians near the
// action, a larger instanced "impostor" crowd in the distance (two InstancedMesh
// for the whole background), and a handful of grouped vehicles on the ring road.
// Counts are honest and capped, and the detailed crowd tapers as real players
// join so a busy world is never padded with fakes.

import {
	Group, Vector3, Object3D, Color, Mesh,
	InstancedMesh, CapsuleGeometry, SphereGeometry, MeshStandardMaterial,
	BoxGeometry, CylinderGeometry, MeshBasicMaterial,
} from 'three';
import { AnimationManager } from '../../animation-manager.js';
import { buildAvatar, releaseAvatar, CLIP_IDLE, CLIP_WALK } from '../avatar-rig.js';
import { instantiateVehicleModel, TRENCH_CAR_URL } from '../vehicle-model.js';
import { mulberry32 } from './nav-graph.js';
import { loadCitizenPool, isCitizen } from './citizens.js';
import { log } from '../../shared/log.js';

const DEFAULT_AVATAR = '/avatars/default.glb';

const PED_WALK_SPEED = 1.35;     // m/s along the loop, an unhurried stroll
const DETAILED_PEDS = 6;         // GLB-bodied pedestrians near the centre
const IMPOSTOR_PEDS = 14;        // cheap instanced crowd in the distance
const VEHICLES = 5;              // cars on the ring road
const VEHICLE_SPEED = 6.5;       // m/s
const PED_AVOID_RADIUS = 2.0;    // how close before a ped sidesteps the player
const CAR_BRAKE_RADIUS = 5.5;    // how close before a car yields to the player

const PED_LINES = ['gm', 'wagmi', 'nice build', 'lfg', 'few understand', 'vibes', 'we so back', 'probably nothing'];

// One shared wall clock, in seconds. Clients are NTP-close, so a continuous
// function of this reads identically across machines for ambient purposes.
const worldClock = () => Date.now() / 1000;

// Free the geometry and materials of a subtree this module built itself. Never
// call it on a clone of a shared model template: those buffers are still in use
// by every other object wearing the same model.
function disposeTree(root) {
	root.traverse((o) => {
		if (o.geometry) o.geometry.dispose?.();
		if (o.material) {
			if (Array.isArray(o.material)) o.material.forEach((m) => m.dispose?.());
			else o.material.dispose?.();
		}
	});
}

// ---- detailed GLB pedestrian -------------------------------------------------

class Pedestrian {
	constructor(scene, nav, { loopIdx, phase, speedScale, record, seed, onInspect }) {
		this.scene = scene;
		this.nav = nav;
		this.loopIdx = loopIdx;
		this.phase = phase;
		this.speed = PED_WALK_SPEED * speedScale;
		this.height = 1.7;
		this._disposed = false;
		this._avoid = new Vector3();
		this._rng = mulberry32(seed);
		this._sayIn = 8 + this._rng() * 22;
		// Hold-to-talk: while a player has this pedestrian's profile or chat open,
		// they stop and face the player. `_lag` is how many seconds of stroll they
		// owe the shared schedule; it grows while held and decays after release, so
		// they briskly catch back up to where every other client says they are.
		this._held = false;
		this._lag = 0;

		this.rig = new Group();
		scene.add(this.rig);
		this.anim = new AnimationManager();
		this.bubble = null;
		this._bubbleTimer = null;

		// Real identity from the public avatar gallery (name, bio, and usually the
		// registered agent this avatar represents). A nameless model stays honest
		// anonymous scenery: no nameplate, no profile, no chat.
		this.record = record || null;
		this.label = null;
		if (isCitizen(record)) {
			this.name = record.name;
			this.citizen = {
				record,
				name: record.name,
				say: (t) => this.say(t),
				hold: () => this._setHeld(true),
				release: () => this._setHeld(false),
			};
			this.label = document.createElement('div');
			this.label.className = 'cc-label npc-name';
			this.label.textContent = record.name;
			// .cc-label is pointer-events:none globally (bubbles must never block the
			// look-drag); re-enable it for this one, the same way peer nameplates do.
			this.label.style.pointerEvents = 'auto';
			this.label.style.cursor = 'pointer';
			this.label.title = `Meet ${record.name}`;
			this.label.addEventListener('click', (e) => { e.stopPropagation(); onInspect?.(this); });
			document.body.appendChild(this.label);
		}

		// Locomotion clips only: pedestrians never emote, and each one with its own
		// AnimationManager would otherwise fetch the entire clip library.
		buildAvatar(this.rig, record?.url || DEFAULT_AVATAR, this.anim, { clips: 'locomotion' })
			.then(({ height }) => {
				// Disposed mid-download: release the clone buildAvatar just added, else
				// its shared-template ref leaks. Peds churn on every peer join/leave,
				// so this path is hot in a busy world.
				if (this._disposed) { releaseAvatar(this.rig); return; }
				this.height = height;
				// Loaded into idle by buildAvatar, set them strolling.
				if (!this._held) this.anim.crossfadeTo(CLIP_WALK, 0.2).catch(() => {});
			})
			.catch(() => {});
	}

	_setHeld(held) {
		if (this._held === !!held) return;
		this._held = !!held;
		this.anim.crossfadeTo(this._held ? CLIP_IDLE : CLIP_WALK, 0.25).catch(() => {});
	}

	say(text) {
		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 npc-bubble';
		this.bubble.textContent = text;
		document.body.appendChild(this.bubble);
		clearTimeout(this._bubbleTimer);
		this._bubbleTimer = setTimeout(() => { this.bubble?.remove(); this.bubble = null; }, 4000);
	}

	update(dt, T, player) {
		// Base position is a pure function of the shared clock, identical on every
		// client. Arc-length advances at a steady stroll. Hold-to-talk is a local,
		// cosmetic deviation like the sidestep below: while held the pedestrian
		// banks lag instead of moving, and afterwards walks it off at a brisk pace
		// until they re-converge with the shared baseline.
		if (this._held) this._lag += dt;
		else if (this._lag > 0) this._lag = Math.max(0, this._lag - dt * 0.6);
		const d = this.phase + this.speed * (T - this._lag);
		const p = this.nav.pedPoint(this.loopIdx, d);

		// Local, cosmetic sidestep around the player. Re-converges to zero, so it
		// never desyncs the shared baseline between clients.
		if (player && !this._held) {
			const dx = p.x - player.x, dz = p.z - player.z;
			const dist = Math.hypot(dx, dz);
			if (dist < PED_AVOID_RADIUS && dist > 1e-3) {
				const push = (PED_AVOID_RADIUS - dist);
				this._avoid.x += (dx / dist * push - this._avoid.x) * Math.min(1, dt * 4);
				this._avoid.z += (dz / dist * push - this._avoid.z) * Math.min(1, dt * 4);
			}
		}
		this._avoid.multiplyScalar(1 - Math.min(1, dt * 2));

		this.rig.position.set(p.x + this._avoid.x, 0, p.z + this._avoid.z);
		// Held: turn to face whoever stopped to talk. Otherwise face travel.
		if (this._held && player) {
			const want = Math.atan2(player.x - this.rig.position.x, player.z - this.rig.position.z);
			let delta = want - this.rig.rotation.y;
			while (delta > Math.PI) delta -= Math.PI * 2;
			while (delta < -Math.PI) delta += Math.PI * 2;
			this.rig.rotation.y += delta * Math.min(1, dt * 6);
		} else {
			this.rig.rotation.y = Math.atan2(p.dirX, p.dirZ);
		}
		this.anim.update(dt);

		this._sayIn -= dt;
		if (this._sayIn <= 0 && !this._held) { this._sayIn = 14 + this._rng() * 26; this.say(PED_LINES[(this._rng() * PED_LINES.length) | 0]); }
	}

	dispose() {
		this._disposed = true;
		// Free the shared-template clone (geometry/textures), not just the scene
		// reference. Pedestrians are constructed and disposed on every peer churn,
		// so a leak here compounds within a single busy world session.
		releaseAvatar(this.rig);
		this.scene.remove(this.rig);
		this.bubble?.remove();
		clearTimeout(this._bubbleTimer);
		this.label?.remove();
		this.anim.dispose?.();
	}
}

// ---- vehicle (the Trench Car, on the ring road) -------------------------------

// Build the low-poly stand-in car. Shared unit geometry scaled per part keeps a
// vehicle to a handful of meshes.
//
// Traffic is the Trench Car GLB in EVERY town, frontier ones included (owner
// directive 2026-08-17: it is the one car in the world). The same model the
// drivable fleet wears, so the traffic a player watches go by is the traffic they
// can flag down and take the wheel of. Each vehicle upgrades itself the moment
// the shared model lands (see Vehicle._upgradeToModel); this box car is the
// instant stand-in that holds the road until then, and the permanent body if the
// model can't be fetched.
function buildVehicle() {
	const g = new Group();
	const box = new BoxGeometry(1, 1, 1);
	const wheelGeo = new CylinderGeometry(0.34, 0.34, 0.22, 12);
	const wheels = [];
	const wheelMat = new MeshStandardMaterial({ color: 0x1a1a1d, roughness: 0.9 });
	const addWheel = (x, z) => {
		const w = new Mesh(wheelGeo, wheelMat);
		w.rotation.z = Math.PI / 2;
		w.position.set(x, 0.34, z);
		w.castShadow = true;
		g.add(w); wheels.push(w);
	};

	const bodyMat = new MeshStandardMaterial({ color: 0x2b3340, roughness: 0.5, metalness: 0.3 });
	const cabinMat = new MeshStandardMaterial({ color: 0x10151c, roughness: 0.3, metalness: 0.2 });
	const body = new Mesh(box, bodyMat); body.scale.set(1.7, 0.7, 3.6); body.position.y = 0.62; body.castShadow = true; g.add(body);
	const cabin = new Mesh(box, cabinMat); cabin.scale.set(1.5, 0.7, 1.9); cabin.position.set(0, 1.15, -0.1); cabin.castShadow = true; g.add(cabin);
	const head = new Mesh(box, new MeshBasicMaterial({ color: 0xfff3cf })); head.scale.set(1.5, 0.16, 0.1); head.position.set(0, 0.62, 1.81); g.add(head);
	const brakeLights = new Mesh(box, new MeshBasicMaterial({ color: 0x551111 })); brakeLights.scale.set(1.5, 0.18, 0.1); brakeLights.position.set(0, 0.62, -1.81); g.add(brakeLights);
	addWheel(-0.92, 1.15); addWheel(0.92, 1.15); addWheel(-0.92, -1.2); addWheel(0.92, -1.2);

	return { group: g, wheels, brakeLights };
}

class Vehicle {
	constructor(scene, nav, { phase, lane, dir }) {
		this.nav = nav;
		this.phase = phase;
		this.lane = lane;
		this.dir = dir; // +1 / -1 travel direction around the ring
		this.curL = phase;
		this.scene = scene;
		this._disposed = false;
		this._model = null;
		this._braking = false;

		this.group = new Group();
		const built = buildVehicle();
		this.group.add(built.group);
		this._standIn = built.group;
		this.wheels = built.wheels;          // spun by update(), whichever body is on
		this.brakeLights = built.brakeLights;
		scene.add(this.group);

		this._upgradeToModel();
	}

	// Swap the box stand-in for the real car. The model is shared with every other
	// car in the world (one download, one parse), and this is the only place the
	// swap happens, so a vehicle mid-lap keeps its position and phase.
	async _upgradeToModel() {
		let instance;
		try {
			instance = await instantiateVehicleModel(TRENCH_CAR_URL);
		} catch (e) {
			// The stand-in is already driving the route: traffic keeps flowing.
			log.warn('[ambient-life] traffic model unavailable, keeping the stand-in:', e?.message);
			return;
		}
		if (this._disposed) { instance.dispose(); return; }
		this.group.remove(this._standIn);
		disposeTree(this._standIn);
		this._standIn = null;
		this.group.add(instance.body);
		for (const wheel of instance.wheels) this.group.add(wheel.pivot);
		this.wheels = instance.wheels.map((w) => w.spinner);
		this.brakeLights = null;
		this._model = instance;
		this._model.setBrake(this._braking);
	}

	update(dt, T, player) {
		// Target arc-length from the shared clock, the consistent baseline.
		const targetL = this.phase + this.dir * VEHICLE_SPEED * T;

		// Yield to the local player: if they're standing on the road just ahead,
		// hold position rather than drive through them. This is local-only (each
		// player sees traffic yield to them) and re-converges to the baseline once
		// the road clears, so the shared schedule stays the source of truth.
		let blocked = false;
		if (player) {
			const ahead = this.nav.roadPoint(this.curL + this.dir * 3.5, this.lane);
			const dx = ahead.x - player.x, dz = ahead.z - player.z;
			if (Math.hypot(dx, dz) < CAR_BRAKE_RADIUS) blocked = true;
		}
		const desired = blocked ? Math.min(this.curL, targetL, this.curL) : targetL;
		const prevL = this.curL;
		this.curL += (desired - this.curL) * Math.min(1, dt * (blocked ? 4 : 2.5));

		const p = this.nav.roadPoint(this.curL, this.lane);
		this.group.position.set(p.x, 0, p.z);
		this.group.rotation.y = Math.atan2(p.dirX * this.dir, p.dirZ * this.dir);

		// Spin the wheels with actual travel; flash brake lights when yielding.
		const moved = Math.abs(this.curL - prevL);
		for (const w of this.wheels) w.rotation.x += moved * 1.8;
		if (blocked !== this._braking) {
			this._braking = blocked;
			if (this._model) this._model.setBrake(blocked);
			else if (this.brakeLights) this.brakeLights.material.color.setHex(blocked ? 0xff3b30 : 0x551111);
		}
	}

	dispose() {
		this._disposed = true;
		this.scene.remove(this.group);
		// The stand-in's geometry is this vehicle's own; the model's belongs to the
		// shared template and is only dereferenced.
		if (this._standIn) disposeTree(this._standIn);
		this._model?.dispose();
		this._model = null;
	}
}

// ---- the ambient-life system -------------------------------------------------

export class AmbientLife {
	// `onInspectPed` (optional) makes the detailed pedestrians selectable: called
	// with the Pedestrian when a player clicks its nameplate or body. The world
	// manager wires it to the citizen profile card (see citizens.js).
	constructor({ scene, nav, onInspectPed }) {
		this.scene = scene;
		this.nav = nav;
		this.onInspectPed = onInspectPed || null;
		this.peds = [];
		this.vehicles = [];
		this._avatarPool = null;
		this._impostor = null;
		this._dummy = new Object3D();
		this._wantPeds = DETAILED_PEDS;

		this._buildImpostors();
		this._buildVehicles();
		this._loadAvatarPoolThenPeds();
	}

	// A single InstancedMesh pair (bodies + heads) carries the whole background
	// crowd on the outermost loop, one draw call each, no per-ped objects.
	_buildImpostors() {
		const rand = mulberry32((this.nav.seed ^ 0x9e3779b9) >>> 0);
		const bodyGeo = new CapsuleGeometry(0.28, 0.7, 4, 8);
		const headGeo = new SphereGeometry(0.22, 10, 8);
		const bodyMat = new MeshStandardMaterial({ roughness: 0.95 });
		const headMat = new MeshStandardMaterial({ roughness: 0.9, color: 0xcaa98a });
		const bodies = new InstancedMesh(bodyGeo, bodyMat, IMPOSTOR_PEDS);
		const heads = new InstancedMesh(headGeo, headMat, IMPOSTOR_PEDS);
		bodies.castShadow = true;
		this._impostorSpec = [];
		const palette = [0x5a6472, 0x6b5a72, 0x4d6b5a, 0x72655a, 0x556070];
		for (let i = 0; i < IMPOSTOR_PEDS; i++) {
			bodies.setColorAt(i, new Color(palette[i % palette.length]));
			this._impostorSpec.push({
				loopIdx: 0, // outermost loop only, keeps impostors in the distance
				phase: rand() * 1000,
				speed: PED_WALK_SPEED * (0.85 + rand() * 0.4),
				bob: rand() * Math.PI * 2,
			});
		}
		if (bodies.instanceColor) bodies.instanceColor.needsUpdate = true;
		this.scene.add(bodies, heads);
		this._impostor = { bodies, heads };
	}

	_buildVehicles() {
		const rand = mulberry32((this.nav.seed ^ 0x85ebca6b) >>> 0);
		const spacing = this.nav.roadLen / VEHICLES;
		for (let i = 0; i < VEHICLES; i++) {
			const dir = i % 2 === 0 ? 1 : -1;
			const lane = dir > 0 ? -this.nav.roadWidth * 0.22 : this.nav.roadWidth * 0.22;
			this.vehicles.push(new Vehicle(this.scene, this.nav, {
				phase: i * spacing + rand() * spacing * 0.4,
				lane,
				dir,
			}));
		}
	}

	async _loadAvatarPoolThenPeds() {
		// The shared citizen pool: full gallery records (model URL + the identity
		// riding it) so a pedestrian is a real, inspectable community avatar, not
		// an anonymous mesh. Settles to [] on failure; peds then wear the default.
		this._avatarPool = await loadCitizenPool();
		this._syncPeds();
	}

	// Deterministic avatar assignment: shuffle the pool by seed so ped #k shows the
	// same model, and therefore the same identity, on every client.
	_pedAvatar(k) {
		const pool = this._avatarPool;
		if (!pool || !pool.length) return null;
		const rand = mulberry32((this.nav.seed ^ (k * 0x27d4eb2f)) >>> 0);
		return pool[(rand() * pool.length) | 0];
	}

	_syncPeds() {
		if (!this._avatarPool) return; // pool still loading
		const want = this._wantPeds;
		while (this.peds.length < want) {
			const k = this.peds.length;
			const rand = mulberry32((this.nav.seed ^ (k * 0x165667b1)) >>> 0);
			// Detailed peds ride the inner loops; impostors hold the outer one.
			const loopIdx = 1 + (k % (this.nav.pedLoopCount - 1));
			this.peds.push(new Pedestrian(this.scene, this.nav, {
				loopIdx,
				phase: rand() * 1000,
				speedScale: 0.85 + rand() * 0.4,
				record: this._pedAvatar(k),
				seed: (this.nav.seed ^ (k * 0x9e3779b9)) >>> 0,
				onInspect: this.onInspectPed ? (ped) => this.onInspectPed(ped) : null,
			}));
		}
		while (this.peds.length > want) this.peds.pop().dispose();
	}

	// The crowd tapers as real peers arrive, so the world is lively when empty but
	// never padded with fakes once it's genuinely busy. Peer count is the room's
	// authoritative set, so this stays consistent across clients.
	setRealPeers(n) {
		const want = Math.max(0, DETAILED_PEDS - (n | 0));
		if (want === this._wantPeds) return;
		this._wantPeds = want;
		this._syncPeds();
	}

	// Drive everything from the shared clock. `project` places detailed-ped speech
	// bubbles; `player` is the local player position for reactivity.
	update(dt, { player, project } = {}) {
		const T = worldClock();

		for (const p of this.peds) {
			p.update(dt, T, player);
			if (project) {
				if (p.label) project(p.label, p.rig.position.x, p.height + 0.2, p.rig.position.z);
				if (p.bubble) project(p.bubble, p.rig.position.x, p.height + 0.6, p.rig.position.z);
			}
		}
		for (const v of this.vehicles) v.update(dt, T, player);

		// Impostor crowd, one matrix write per instance, distance only.
		if (this._impostor) {
			const { bodies, heads } = this._impostor;
			for (let i = 0; i < this._impostorSpec.length; i++) {
				const s = this._impostorSpec[i];
				const pt = this.nav.pedPoint(s.loopIdx, s.phase + s.speed * T);
				const bob = Math.sin(T * 4 + s.bob) * 0.04;
				this._dummy.position.set(pt.x, 0.71 + bob, pt.z);
				this._dummy.rotation.set(0, Math.atan2(pt.dirX, pt.dirZ), 0);
				this._dummy.updateMatrix();
				bodies.setMatrixAt(i, this._dummy.matrix);
				this._dummy.position.y = 1.5 + bob;
				this._dummy.updateMatrix();
				heads.setMatrixAt(i, this._dummy.matrix);
			}
			bodies.instanceMatrix.needsUpdate = true;
			heads.instanceMatrix.needsUpdate = true;
		}
	}

	// Honest live counts for the manager's HUD / debugging.
	get counts() {
		return { detailed: this.peds.length, impostors: IMPOSTOR_PEDS, vehicles: this.vehicles.length };
	}

	dispose() {
		for (const p of this.peds) p.dispose();
		for (const v of this.vehicles) v.dispose();
		this.peds = []; this.vehicles = [];
		if (this._impostor) {
			this.scene.remove(this._impostor.bodies, this._impostor.heads);
			this._impostor.bodies.geometry.dispose();
			this._impostor.bodies.material.dispose();
			this._impostor.heads.geometry.dispose();
			this._impostor.heads.material.dispose();
			this._impostor = null;
		}
	}
}