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.

22.9 KB
Raw Blame
// /agora player mode — "Enter the Commons". The embodied, GTA-style layer over
// the spectator scaffold: your real avatar walks Times Square among the citizen
// NPCs (who keep living their real on-chain economy — claiming, working,
// proving, earning), other humans appear live over the shared multiplayer
// server, and walking up to any citizen offers a proximity interaction that
// opens their living passport (inspect → hire → vouch, via the existing
// me-hud/passport stack).
//
// Loaded LAZILY by agora-world.js the moment the visitor enters play mode, so
// the watchable Commons never pays for colyseus.js or nipplejs up front.
//
// Reuses, never reinvents:
//   • avatar loading + clips      → src/game/avatar-rig.js (same rig as /city, /play)
//   • multiplayer client          → src/walk-net.js (room 'agora_world', graceful solo)
//   • nameplates                  → buildLabelSprite from citizen-avatar.js
//   • movement/collision math     → player-logic.js (pure, unit-tested)
//   • interaction surface         → the existing passport/me-hud event bus
//
// The room is a dedicated 'agora_world' (multiplayer/src/rooms/AgoraRoom.js) —
// NOT a walk_world coin shard: the Commons is city-scale (±680 m) and WalkRoom's
// anti-cheat clamps assume a 60 m plaza. If the server is unreachable (or the
// room isn't deployed yet) the square stays fully playable solo — the NPCs'
// economy never depended on the presence socket.

import * as THREE from 'three';
import {
	loadManifest, resolveAvatarUrl, buildAvatar, newAnim,
	CLIP_IDLE, CLIP_WALK,
} from '../game/avatar-rig.js';
import { WalkNet } from '../walk-net.js';
import { buildLabelSprite, citizenProfessionLabel } from './citizen-avatar.js';
import { CITY_HALF } from '../city/city-map.js';
import {
	JUMP_VEL, GRAVITY,
	motionFor, stepMovement, easeYaw, resolveBuildingCollision,
	nearestInteractable, chooseAvatarSource, guestName, findOpenSpawn,
} from './player-logic.js';
import { injectPlayerCss } from './player-mode.css.js';
import { mountOnchainPresence } from './onchain-presence.js';
import { log } from '../shared/log.js';

const BOUNDS = CITY_HALF - 20; // matches the spectator PAN_BOUNDS — one world edge
const SPAWN = { x: 3.5, z: -2.5 }; // beside the job board, facing the square
const REMOTE_LERP = 0.22; // exponential-lerp factor toward 15 Hz snapshots
const PROXIMITY_HZ = 5; // interactable scan rate
const BUBBLE_MS = 5200; // how long a chat bubble hangs over a head
const CHAT_LOG_MAX = 6;

// ── Local player ─────────────────────────────────────────────────────────────

class AgoraPlayer {
	constructor(scene) {
		this._scene = scene;
		this.rig = new THREE.Group();
		scene.add(this.rig);
		this.velocity = new THREE.Vector3();
		this.onGround = true;
		this.motion = 'idle';
		this.height = 1.7;
		this._anim = null;
		this._targetYaw = 0;
		this._jumpQueued = false;
		// Analogue input the keyboard and the touch stick both write into.
		this.stick = { forward: 0, strafe: 0, running: false };
		this._keys = new Set();
	}

	async load(avatarInput, spawn = SPAWN) {
		await loadManifest();
		const url = await resolveAvatarUrl(avatarInput || '');
		this._anim = newAnim();
		// Locomotion clips only: entering the square must never wait on the full
		// emote library (dozens of clip downloads) — emotes lazy-load on use.
		const { height, fallback } = await buildAvatar(this.rig, url, this._anim, { clips: 'locomotion' });
		this.height = height;
		this.rig.position.set(spawn.x, 0, spawn.z);
		return { url, fallback };
	}

	queueJump() { this._jumpQueued = true; }

	// Merge keyboard state into the analogue stick each frame (keyboard is ±1).
	_input() {
		const k = this._keys;
		let forward = this.stick.forward;
		let strafe = this.stick.strafe;
		if (k.has('w') || k.has('arrowup')) forward = 1;
		if (k.has('s') || k.has('arrowdown')) forward = -1;
		if (k.has('a') || k.has('arrowleft')) strafe = -1;
		if (k.has('d') || k.has('arrowright')) strafe = 1;
		const running = this.stick.running || k.has('shift');
		return { forward, strafe, running };
	}

	update(dt, buildingBoxes, cameraYaw) {
		const input = this._input();
		const step = stepMovement({
			input, cameraYaw, running: input.running,
			vx: this.velocity.x, vz: this.velocity.z, yaw: this._targetYaw, dt,
		});
		this.velocity.x = step.vx;
		this.velocity.z = step.vz;
		if (step.moving) this._targetYaw = step.yaw;

		if (this._jumpQueued && this.onGround) {
			this.velocity.y = JUMP_VEL;
			this.onGround = false;
		}
		this._jumpQueued = false;
		if (!this.onGround) this.velocity.y += GRAVITY * dt;

		const p = this.rig.position;
		let nx = p.x + this.velocity.x * dt;
		let ny = p.y + this.velocity.y * dt;
		const nz0 = p.z + this.velocity.z * dt;
		const resolved = resolveBuildingCollision(nx, ny, nz0, buildingBoxes);
		nx = resolved.x;
		let nz = resolved.z;

		if (ny <= 0) { ny = 0; this.velocity.y = 0; this.onGround = true; }
		else this.onGround = false;

		nx = Math.max(-BOUNDS, Math.min(BOUNDS, nx));
		nz = Math.max(-BOUNDS, Math.min(BOUNDS, nz));
		p.set(nx, ny, nz);

		this.rig.rotation.y = easeYaw(this.rig.rotation.y, this._targetYaw, dt);

		const hSpeed = Math.hypot(this.velocity.x, this.velocity.z);
		const next = motionFor(hSpeed, input.running);
		if (next !== this.motion) {
			this.motion = next;
			// The clip set is idle + walk; running is the walk clip driven faster.
			const clip = next === 'idle' ? CLIP_IDLE : CLIP_WALK;
			this._anim?.crossfadeTo(clip, 0.2).catch(() => {});
		}
		this._anim?.update(dt);
	}

	get position() { return this.rig.position; }

	dispose() {
		this._scene.remove(this.rig);
		disposeObject(this.rig);
	}
}

// ── Remote players (the other humans in the square) ─────────────────────────

class RemotePlayers {
	constructor(scene, bubblesEl) {
		this._scene = scene;
		this._bubbles = bubblesEl;
		this._byId = new Map(); // sessionId → entry
	}

	get count() { return this._byId.size; }

	upsert(player, sessionId) {
		let entry = this._byId.get(sessionId);
		if (entry && entry.avatarUrl !== (player.avatar || '')) {
			// Live avatar swap: rebuild rather than patch a half-loaded rig.
			this.remove(sessionId);
			entry = null;
		}
		if (!entry) {
			entry = this._create(player, sessionId);
			this._byId.set(sessionId, entry);
		}
		entry.target.x = player.x;
		entry.target.y = player.y;
		entry.target.z = player.z;
		entry.target.yaw = player.yaw;
		const motion = player.motion === 'idle' ? 'idle' : 'walk';
		if (motion !== entry.motion && entry.anim) {
			entry.motion = motion;
			entry.anim.crossfadeTo(motion === 'idle' ? CLIP_IDLE : CLIP_WALK, 0.2).catch(() => {});
		} else {
			entry.motion = motion;
		}
		return entry;
	}

	_create(player, sessionId) {
		const group = new THREE.Group();
		group.position.set(player.x, player.y, player.z);
		this._scene.add(group);
		const entry = {
			sessionId,
			group,
			anim: null,
			avatarUrl: player.avatar || '',
			name: player.name || 'visitor',
			target: { x: player.x, y: player.y, z: player.z, yaw: player.yaw },
			motion: 'idle',
			height: 1.7,
			bubbleEl: null,
			bubbleUntil: 0,
			gone: false,
		};
		// Async body load; the entry is live (and lerping) before the GLB lands.
		(async () => {
			const anim = newAnim();
			const { height } = await buildAvatar(group, player.avatar || '', anim, { clips: 'locomotion' });
			if (entry.gone) { disposeObject(group); return; }
			entry.anim = anim;
			entry.height = height;
			const accent = `#${(Number(player.color) >>> 0).toString(16).padStart(6, '0').slice(-6)}`;
			const label = buildLabelSprite(entry.name, 'visitor', accent);
			label.position.y = height + 0.42;
			group.add(label);
		})().catch((err) => log.warn('[agora-play] remote avatar failed', err?.message));
		return entry;
	}

	remove(sessionId) {
		const entry = this._byId.get(sessionId);
		if (!entry) return;
		entry.gone = true;
		this._byId.delete(sessionId);
		this._scene.remove(entry.group);
		disposeObject(entry.group);
		entry.bubbleEl?.remove();
	}

	say(sessionId, text) {
		const entry = this._byId.get(sessionId);
		if (!entry) return;
		if (!entry.bubbleEl) {
			entry.bubbleEl = document.createElement('div');
			entry.bubbleEl.className = 'agora-p-bubble';
			this._bubbles.appendChild(entry.bubbleEl);
		}
		entry.bubbleEl.textContent = String(text || '').slice(0, 200);
		entry.bubbleUntil = performance.now() + BUBBLE_MS;
	}

	tick(dt, camera, viewW, viewH) {
		const k = 1 - Math.pow(1 - REMOTE_LERP, dt * 60);
		for (const entry of this._byId.values()) {
			const p = entry.group.position;
			p.x += (entry.target.x - p.x) * k;
			p.y += (entry.target.y - p.y) * k;
			p.z += (entry.target.z - p.z) * k;
			entry.group.rotation.y = easeYaw(entry.group.rotation.y, entry.target.yaw, dt, 10);
			entry.anim?.update(dt);

			// Project the speech bubble (screen-space DOM) over the head.
			if (entry.bubbleEl) {
				if (performance.now() > entry.bubbleUntil) {
					entry.bubbleEl.remove();
					entry.bubbleEl = null;
				} else {
					_v.set(p.x, p.y + entry.height + 0.55, p.z).project(camera);
					if (_v.z > 1) {
						entry.bubbleEl.style.display = 'none';
					} else {
						entry.bubbleEl.style.display = '';
						entry.bubbleEl.style.left = `${(_v.x * 0.5 + 0.5) * viewW}px`;
						entry.bubbleEl.style.top = `${(-_v.y * 0.5 + 0.5) * viewH}px`;
					}
				}
			}
		}
	}

	// Drop every remote (freeing rigs + bubbles). Used on a reconnect: while the
	// socket was down, peers may have left without a `remove` event (walk-net's
	// _closeRoom drops all listeners), so on rejoin their entries would linger as
	// motionless ghosts. Clearing here lets onAdd repopulate only who's actually
	// present. The object stays usable — the map is simply emptied.
	clear() {
		for (const id of [...this._byId.keys()]) this.remove(id);
	}

	dispose() {
		this.clear();
	}
}

const _v = new THREE.Vector3();

function disposeObject(root) {
	root.traverse((n) => {
		if (n.isMesh || n.isSkinnedMesh) {
			n.geometry?.dispose?.();
			const mats = Array.isArray(n.material) ? n.material : [n.material];
			for (const m of mats) {
				if (!m) continue;
				for (const key of Object.keys(m)) {
					const val = m[key];
					if (val && val.isTexture) val.dispose();
				}
				m.dispose?.();
			}
		}
		if (n.isSprite) {
			n.material?.map?.dispose?.();
			n.material?.dispose?.();
		}
	});
}

// ── Mount ────────────────────────────────────────────────────────────────────

/**
 * Mount the playable layer.
 *
 * @param {object} ctx
 * @param {THREE.Scene}   ctx.scene
 * @param {THREE.Camera}  ctx.camera
 * @param {object}        ctx.population      CitizenPopulation (the NPC crowd)
 * @param {Array}         ctx.buildingBoxes   AABBs from buildCity
 * @param {() => number}  ctx.getCameraYaw    cityCamera.yaw supplier
 * @param {(id) => void}  ctx.openPassport    opens a citizen's passport panel
 * @returns {Promise<{update(dt):void, playerPosition:THREE.Vector3, playerHeight:number, dispose():void}>}
 */
export async function mountPlayerMode(ctx) {
	injectPlayerCss();
	const { scene, camera, population, buildingBoxes, getCameraYaw, openPassport } = ctx;

	// ── HUD scaffold (all states designed) ─────────────────────────────────────
	const root = el('div', 'agora-p-root');
	const bubbles = el('div', 'agora-p-bubbles');
	const prompt = el('button', 'agora-p-prompt');
	prompt.type = 'button';
	prompt.innerHTML = `<kbd>E</kbd><span class="agora-p-prompt-text"><span class="agora-p-prompt-title"></span><span class="agora-p-prompt-sub"></span></span>`;
	const presence = el('button', 'agora-p-presence');
	presence.type = 'button';
	presence.dataset.state = 'connecting';
	presence.innerHTML = `<span class="dot"></span><span class="agora-p-presence-text">connecting…</span>`;
	const chat = el('div', 'agora-p-chat');
	const chatLog = el('div', 'agora-p-chat-log');
	const chatRow = el('div', 'agora-p-chat-row');
	const chatInput = el('input', 'agora-p-chat-input');
	chatInput.placeholder = 'Say something to the square…';
	chatInput.maxLength = 200;
	chatInput.setAttribute('aria-label', 'Chat with other visitors');
	const chatSend = el('button', 'agora-p-chat-send');
	chatSend.type = 'button';
	chatSend.textContent = 'Send';
	chatRow.append(chatInput, chatSend);
	chat.append(chatLog, chatRow);
	const stickZone = el('div', 'agora-p-stick');
	const actions = el('div', 'agora-p-actions');
	const jumpBtn = el('button', 'agora-p-action-btn');
	jumpBtn.type = 'button';
	jumpBtn.textContent = 'JUMP';
	jumpBtn.setAttribute('aria-label', 'Jump');
	const interactBtn = el('button', 'agora-p-action-btn');
	interactBtn.type = 'button';
	interactBtn.textContent = 'E';
	interactBtn.setAttribute('aria-label', 'Interact with the nearest citizen');
	actions.append(interactBtn, jumpBtn);
	root.append(bubbles, prompt, presence, chat, stickZone, actions);
	document.body.appendChild(root);

	// On-chain (BNB) presence — OFF by default, opt-in toggle (prompt 16).
	// Purely additive: with it OFF, zero BNB code runs and this whole layer is
	// dormant scaffolding (a docked toggle button + an empty THREE.Group).
	const onchain = mountOnchainPresence({ scene, hudRoot: root, network: 'bscTestnet' });

	// ── Identity + avatar ──────────────────────────────────────────────────────
	const params = new URLSearchParams(location.search);
	const getStored = (k) => { try { return localStorage.getItem(k); } catch { return null; } };
	const setStored = (k, v) => { try { localStorage.setItem(k, v); } catch { /* private mode */ } };
	const avatarChoice = chooseAvatarSource(params, getStored);
	if (avatarChoice.source.startsWith('param')) setStored('agora:avatar', avatarChoice.value);
	const name = guestName(getStored, Math.random());
	setStored('agora:name', name);

	const player = new AgoraPlayer(scene);
	// Spawn on OPEN ground: the OSM Manhattan substrate is dense, so the nominal
	// spot beside the board can sit inside a building footprint (where the player
	// would be walled in the moment it tries to move). findOpenSpawn spirals out to
	// the nearest clear point so the visitor always starts able to walk to citizens.
	const spawn = findOpenSpawn(SPAWN, buildingBoxes);
	const { url: avatarUrl } = await player.load(avatarChoice.value, spawn);

	// ── Multiplayer presence (dedicated Commons room; graceful solo) ───────────
	const remotes = new RemotePlayers(scene, bubbles);
	const net = new WalkNet({ name, avatar: avatarUrl, room: 'agora_world' });
	const presenceText = presence.querySelector('.agora-p-presence-text');
	let wasOnline = false; // tracks online→down transitions so we clear ghosts once
	function renderPresence() {
		const state = net.status === 'online' ? 'online'
			: net.status === 'connecting' ? 'connecting'
			: net.status === 'unavailable' ? 'solo'
			: 'offline';
		// Left the live room (drop / reconnect): peers may have departed during the
		// gap with no `remove` event, so drop every remote now. onAdd repopulates
		// only who's actually present when the socket comes back — no ghost avatars.
		if (wasOnline && state !== 'online') remotes.clear();
		wasOnline = state === 'online';
		presence.dataset.state = state;
		if (state === 'online') {
			const n = remotes.count + 1;
			presenceText.textContent = `${n} ${n === 1 ? 'human' : 'humans'} in the square`;
			presence.removeAttribute('data-clickable');
			presence.title = '';
		} else if (state === 'connecting') {
			presenceText.textContent = 'connecting…';
			presence.removeAttribute('data-clickable');
		} else if (state === 'solo') {
			presenceText.textContent = 'solo square — citizens still at work';
			presence.removeAttribute('data-clickable');
			presence.title = 'No multiplayer server configured for this environment';
		} else {
			presenceText.textContent = 'solo — tap to reconnect';
			presence.setAttribute('data-clickable', '');
			presence.title = 'Reconnect to the shared square';
		}
	}
	const offStatus = net.on('status', renderPresence);
	const offAdd = net.on('add', (p, sessionId) => {
		if (sessionId === net.mySessionId) return;
		remotes.upsert(p, sessionId);
		renderPresence();
	});
	const offChange = net.on('change', (p, sessionId) => {
		if (sessionId === net.mySessionId) return;
		remotes.upsert(p, sessionId);
	});
	const offRemove = net.on('remove', (sessionId) => {
		remotes.remove(sessionId);
		renderPresence();
	});
	const offChat = net.on('chat', (msg) => {
		if (!msg || !msg.text) return;
		appendChatLine(msg.name || 'visitor', msg.text);
		if (msg.id && msg.id !== net.mySessionId) remotes.say(msg.id, msg.text);
	});
	presence.addEventListener('click', () => {
		if (presence.hasAttribute('data-clickable')) net.retry();
	});
	net.connect();

	function appendChatLine(who, text) {
		const line = el('div', 'agora-p-chat-line');
		const b = document.createElement('b');
		b.textContent = who;
		line.append(b, document.createTextNode(` ${String(text).slice(0, 200)}`));
		chatLog.appendChild(line);
		while (chatLog.children.length > CHAT_LOG_MAX) chatLog.firstChild.remove();
	}
	function sendChat() {
		const text = chatInput.value.trim();
		if (!text) return;
		if (net.status === 'online') {
			net.sendChat(text);
		} else {
			// Honest solo echo — your words still appear, marked as unheard.
			appendChatLine(`${name} (solo)`, text);
		}
		chatInput.value = '';
	}
	chatSend.addEventListener('click', sendChat);
	chatInput.addEventListener('keydown', (e) => {
		if (e.key === 'Enter') { e.preventDefault(); sendChat(); }
		e.stopPropagation(); // typing must never move the avatar
	});

	// ── Input (keyboard) ───────────────────────────────────────────────────────
	const TRACKED = new Set(['w', 'a', 's', 'd', 'arrowup', 'arrowdown', 'arrowleft', 'arrowright', 'shift']);
	function typingSomewhere() {
		const ae = document.activeElement;
		return !!(ae && (/^(INPUT|TEXTAREA|SELECT)$/.test(ae.tagName) || ae.isContentEditable
			|| (ae.closest && ae.closest('.agora-passport, .agora-panel, .agora-h-root, [role="dialog"]'))));
	}
	const onKeyDown = (e) => {
		if (typingSomewhere()) return;
		const k = e.key.toLowerCase();
		if (k === ' ') { e.preventDefault(); player.queueJump(); return; }
		if (k === 'e') { interact(); return; }
		if (!TRACKED.has(k)) return;
		if (k.startsWith('arrow')) e.preventDefault();
		player._keys.add(k);
	};
	const onKeyUp = (e) => player._keys.delete(e.key.toLowerCase());
	window.addEventListener('keydown', onKeyDown);
	window.addEventListener('keyup', onKeyUp);
	jumpBtn.addEventListener('click', () => player.queueJump());
	interactBtn.addEventListener('click', () => interact());
	prompt.addEventListener('click', () => interact());

	// ── Touch stick (lazy nipplejs — only where touch is the medium) ──────────
	let stickManager = null;
	let disposed = false; // set by dispose(); guards the async nipplejs import below
	if (window.matchMedia?.('(hover: none), (max-width: 640px)').matches) {
		import('nipplejs').then(({ default: nipplejs }) => {
			// Leaving play mode before this dynamic import resolved would otherwise
			// create a stick (with live listeners writing to a disposed player) that
			// dispose() already ran past — tear it down immediately instead.
			if (disposed) return;
			stickManager = nipplejs.create({
				zone: stickZone,
				mode: 'dynamic',
				color: '#6ea8ff',
				size: 110,
			});
			stickManager.on('move', (_e, data) => {
				const a = data.angle?.radian ?? 0;
				const f = Math.min(1, (data.distance || 0) / 55);
				player.stick.forward = Math.sin(a) * f;
				player.stick.strafe = Math.cos(a) * f;
				player.stick.running = f > 0.92; // full extension sprints
			});
			stickManager.on('end', () => {
				player.stick.forward = 0;
				player.stick.strafe = 0;
				player.stick.running = false;
			});
		}).catch((err) => log.warn('[agora-play] touch stick unavailable', err?.message));
	}

	// ── Proximity interaction (the NPC handshake) ──────────────────────────────
	let promptTarget = null;
	let proximityAccum = 0;
	function scanProximity() {
		const p = player.position;
		const candidates = [];
		for (const inst of population.instances || []) {
			const c = inst?.citizen;
			if (!c) continue;
			const pos = population.worldPosition(c.id);
			if (!pos) continue;
			candidates.push({
				id: c.id,
				kind: 'citizen',
				x: pos.x,
				z: pos.z,
				name: c.displayName || 'Citizen',
				profession: citizenProfessionLabel(c),
				busy: !!inst.busy, // live economy state — set when a real claim walks them to work
			});
		}
		const hit = nearestInteractable(p.x, p.z, candidates);
		if (hit?.id !== promptTarget?.id) {
			if (promptTarget) population.highlight(null);
			promptTarget = hit;
			if (hit) {
				population.highlight(hit.id);
				prompt.querySelector('.agora-p-prompt-title').textContent = `Meet ${hit.name}`;
				prompt.querySelector('.agora-p-prompt-sub').textContent = hit.busy
					? `${hit.profession} — busy on a job right now. See their live work.`
					: `${hit.profession} — open their living passport`;
				prompt.setAttribute('data-show', '');
				prompt.setAttribute('aria-label', `Interact with ${hit.name}, ${hit.profession}`);
			} else {
				prompt.removeAttribute('data-show');
			}
		}
	}
	function interact() {
		if (!promptTarget) return;
		openPassport(promptTarget.id);
	}

	// ── Per-frame update (driven by agora-world's single rAF) ─────────────────
	function update(dt) {
		player.update(dt, buildingBoxes, getCameraYaw());
		net.sendState({
			x: player.position.x,
			y: player.position.y,
			z: player.position.z,
			yaw: player.rig.rotation.y,
			motion: player.motion,
		});
		remotes.tick(dt, camera, window.innerWidth, window.innerHeight);
		onchain.update(dt, player.position, player.rig.rotation.y);
		proximityAccum += dt;
		if (proximityAccum >= 1 / PROXIMITY_HZ) {
			proximityAccum = 0;
			scanProximity();
		}
	}

	function dispose() {
		disposed = true; // stop a still-pending nipplejs import from creating a stick
		window.removeEventListener('keydown', onKeyDown);
		window.removeEventListener('keyup', onKeyUp);
		offStatus(); offAdd(); offChange(); offRemove(); offChat();
		try { stickManager?.destroy(); } catch { /* already gone */ }
		try { net.destroy(); } catch { /* already gone */ }
		remotes.dispose();
		onchain.dispose();
		if (promptTarget) population.highlight(null);
		player.dispose();
		root.remove();
	}

	renderPresence();
	return {
		update,
		get playerPosition() { return player.position; },
		get playerHeight() { return player.height; },
		dispose,
	};
}

function el(tag, className) {
	const node = document.createElement(tag);
	node.className = className;
	return node;
}