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
// Agora player mode — the PURE rules of embodied play. Everything here is
// deterministic math/state with no Three.js, DOM, or network imports, so the
// GTA-style layer (player-mode.js) stays unit-testable the same way the labor
// engine keeps its economics in workers/agora-citizens/policy.js.
//
// player-mode.js owns the scene objects and the wire; this module owns:
// • camera-relative movement + facing (stepMovement)
// • the idle/walk/run motion state (motionFor)
// • capsule-vs-AABB building collision (resolveBuildingCollision)
// • who the player can interact with right now (nearestInteractable)
// • which avatar the player embodies (chooseAvatarSource)
// • a stable guest display name (guestName)
// Movement tuning — deliberately close to /city's controller so crossing
// between the two city-substrate worlds feels identical underfoot.
export const WALK_SPEED = 4.2; // m/s
export const RUN_SPEED = 8.5; // m/s
export const JUMP_VEL = 8.5; // m/s initial upward
export const GRAVITY = -22; // m/s²
export const PLAYER_RADIUS = 0.42; // collision capsule radius (m)
// A citizen (or the job board) is reachable for interaction inside this range.
export const INTERACT_RADIUS = 3.2; // metres
/**
* The locomotion state for the animation mixer + the multiplayer wire.
* Matches the WalkRoom Player.motion vocabulary: 'idle' | 'walk' | 'run'.
*/
export function motionFor(horizontalSpeed, running) {
if (horizontalSpeed < 0.4) return 'idle';
return running ? 'run' : 'walk';
}
/**
* One movement step: camera-relative input → velocity + facing.
* Pure: mutates nothing — returns the next {vx, vz, yaw, moving}.
*
* @param {object} args
* @param {{forward:number, strafe:number}} args.input each in [-1, 1] (keyboard
* fills ±1, a touch stick fills the analogue range)
* @param {number} args.cameraYaw horizontal camera angle (rad, three.js Y)
* @param {boolean} args.running sprint modifier held
* @param {number} args.vx current horizontal velocity x
* @param {number} args.vz current horizontal velocity z
* @param {number} args.yaw current facing (rad)
* @param {number} args.dt frame delta (s)
*/
export function stepMovement({ input, cameraYaw, running, vx, vz, yaw, dt }) {
const f = clamp(input.forward, -1, 1);
const s = clamp(input.strafe, -1, 1);
// Camera-relative basis: forward = -Z rotated by cameraYaw.
let dx = -Math.sin(cameraYaw) * f + Math.cos(cameraYaw) * s;
let dz = -Math.cos(cameraYaw) * f - Math.sin(cameraYaw) * s;
const len = Math.hypot(dx, dz);
const moving = len > 0.08; // stick deadzone tail
if (moving) {
dx /= len;
dz /= len;
// Analogue magnitude scales speed so a gentle thumb = a stroll.
const mag = Math.min(1, len);
const speed = (running ? RUN_SPEED : WALK_SPEED) * mag;
return { vx: dx * speed, vz: dz * speed, yaw: Math.atan2(dx, dz), moving: true };
}
// Quick exponential stop (frame-rate independent).
const damp = Math.pow(0.02, dt);
return { vx: vx * damp, vz: vz * damp, yaw, moving: false };
}
/**
* Shortest-arc yaw easing so the avatar turns the short way round.
* Returns the next yaw after easing `current` toward `target` by k·dt.
*/
export function easeYaw(current, target, dt, k = 14) {
let diff = target - current;
while (diff > Math.PI) diff -= Math.PI * 2;
while (diff < -Math.PI) diff += Math.PI * 2;
return current + diff * Math.min(1, dt * k);
}
/**
* Capsule-vs-AABB push-out in the XZ plane — the same building collision the
* City player uses, kept pure. `boxes` are {minX,maxX,minZ,maxZ,h} from
* buildCity(); a player above a box's height clears it (jumping over stalls).
*
* @returns {{x:number, z:number}} the resolved position
*/
export function resolveBuildingCollision(nx, ny, nz, boxes, radius = PLAYER_RADIUS) {
for (const b of boxes || []) {
if (ny > b.h) continue;
const cx = Math.max(b.minX, Math.min(b.maxX, nx));
const cz = Math.max(b.minZ, Math.min(b.maxZ, nz));
const ox = nx - cx;
const oz = nz - cz;
const dist2 = ox * ox + oz * oz;
if (dist2 >= radius * radius) continue;
const dist = Math.sqrt(dist2);
if (dist < 0.001) {
// Dead-centre inside the box — eject toward the nearest face.
const toLeft = nx - b.minX;
const toRight = b.maxX - nx;
const toFront = nz - b.minZ;
const toBack = b.maxZ - nz;
const min = Math.min(toLeft, toRight, toFront, toBack);
if (min === toLeft) nx = b.minX - radius;
else if (min === toRight) nx = b.maxX + radius;
else if (min === toFront) nz = b.minZ - radius;
else nz = b.maxZ + radius;
} else {
const push = (radius - dist) / dist;
nx += ox * push;
nz += oz * push;
}
}
return { x: nx, z: nz };
}
/**
* Is a point clear of every building (outside all AABBs by at least `margin`)?
* The OSM Manhattan substrate is dense, so a naive spawn can land inside a tower.
*/
export function isOpenGround(x, z, boxes, margin = PLAYER_RADIUS + 0.2) {
for (const b of boxes || []) {
if (x > b.minX - margin && x < b.maxX + margin && z > b.minZ - margin && z < b.maxZ + margin) {
return false;
}
}
return true;
}
/**
* Find an open standing point near a desired spawn: spiral outward (golden-angle,
* so samples never line up with a street grid and miss every gap) until a point
* clear of all buildings is found. Falls back to the desired point if the whole
* search is walled (a degenerate map) — the player is never left unplaced.
* Pure: no Three.js, so it's unit-tested with plain AABBs.
*
* @returns {{x:number, z:number}}
*/
export function findOpenSpawn(desired, boxes, { maxRadius = 60, step = 0.7 } = {}) {
if (isOpenGround(desired.x, desired.z, boxes)) return { x: desired.x, z: desired.z };
const GOLDEN = 2.399963229728653;
for (let i = 1; i * step < maxRadius; i++) {
const r = step * Math.sqrt(i);
const a = i * GOLDEN;
const x = desired.x + Math.cos(a) * r;
const z = desired.z + Math.sin(a) * r;
if (isOpenGround(x, z, boxes)) return { x, z };
}
return { x: desired.x, z: desired.z };
}
/**
* The single nearest interactable within reach — drives the "press E" prompt.
* Candidates carry {id, kind, x, z, ...} (kind: 'citizen' | 'board' | …);
* the caller shapes the prompt from the winner's fields. Deterministic
* tie-break by distance then id so the prompt never flickers between two
* equidistant citizens.
*
* @returns {object|null} the winning candidate + its distance, or null
*/
export function nearestInteractable(px, pz, candidates, radius = INTERACT_RADIUS) {
let best = null;
let bestD = radius;
for (const c of candidates || []) {
const d = Math.hypot(c.x - px, c.z - pz);
if (d < bestD || (best && d === bestD && String(c.id) < String(best.id))) {
best = c;
bestD = d;
}
}
return best ? { ...best, distance: bestD } : null;
}
/**
* Which avatar the player embodies, in priority order:
* 1. ?avatarUrl=<direct GLB/VRM url> (deep link, same as /temporary)
* 2. ?avatar=<three.ws avatar id or url> (deep link)
* 3. the last avatar they walked as here (localStorage 'agora:avatar')
* 4. '' → avatar-rig's default (never a blank world)
* Pure: takes the parsed params + a storage getter so tests inject both.
*
* @param {URLSearchParams|Map} params
* @param {(key:string) => string|null} getStored
* @returns {{source:string, value:string}}
*/
export function chooseAvatarSource(params, getStored) {
const direct = (params.get('avatarUrl') || '').trim();
if (direct) return { source: 'param-url', value: direct };
const byId = (params.get('avatar') || '').trim();
if (byId) return { source: 'param', value: byId };
const stored = (getStored('agora:avatar') || '').trim();
if (stored) return { source: 'stored', value: stored };
return { source: 'default', value: '' };
}
/**
* A stable, human-friendly guest name. Reuses the stored one so a returning
* visitor keeps their identity in the square; otherwise derives 'visitor-xxxx'
* from the supplied entropy (caller passes randomness — pure function).
*/
export function guestName(getStored, entropy) {
const stored = (getStored('agora:name') || '').trim();
if (stored) return stored.slice(0, 24);
const tag = Math.abs(Math.floor(entropy * 46656)) // 36^3
.toString(36)
.padStart(3, '0')
.slice(0, 3);
return `visitor-${tag}`;
}
function clamp(v, min, max) {
const n = Number(v) || 0;
return Math.max(min, Math.min(max, n));
}