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
// guide-avatar.js — the tour guide's body. A small, always-on-top 3D avatar
// that walks across the viewport to stand beside whatever the tour is showing,
// turns to face it, gestures at it, and carries a speech bubble above its head.
//
// It reuses the published @three-ws/walk avatar loader (loadWalkAvatar) so the
// guide is the same rig family the Walk Companion drives and can never freeze in
// a bind/T-pose, and the same simple controller surface — setState('walk' |
// 'idle') + playWave() — drives the walk-in and the point gesture. By default it
// reads the visitor's chosen companion avatar (config.avatarStorageKey), so the
// guide matches whoever they walk with; otherwise it loads config.guideAvatarId.
import {
AmbientLight,
Box3,
Timer,
DirectionalLight,
Group,
HemisphereLight,
PerspectiveCamera,
Scene,
Vector3,
WebGLRenderer,
} from 'three';
import { loadWalkAvatar, resolveConfig, resolveAvatarEntry } from '@three-ws/walk';
const CANVAS_W = 168;
const CANVAS_H = 240;
const MARGIN = 16;
const Z_AVATAR = 2147483300;
// Locomotion is tuned in real-world m/s — like the walk world (src/walk.js) — and
// converted to on-screen px/second at runtime using the avatar's measured
// pixels-per-meter (see _frame). This lets the walk clip's playback rate be scaled
// to actual travel so the feet plant instead of skating: at ~85 px/m a naive
// 460 px/s glide is ~5.4 m/s (a sprint) against a clip authored for 1.5 m/s, which
// is exactly the mismatch that made the guide moon-walk.
// WALK_MPS/RUN_MPS — target ground speeds; NATURAL_* — the shared clips' authored
// ground speed at timeScale 1 (same numbers/clip as src/walk.js). The playback
// timeScale is target ÷ natural, so stride cadence tracks travel by construction.
const WALK_MPS = 2.7;
const RUN_MPS = 4.2;
const NATURAL_WALK_MPS = 1.5;
const NATURAL_RUN_MPS = 3.4;
const WALK_TIMESCALE = WALK_MPS / NATURAL_WALK_MPS;
const RUN_TIMESCALE = RUN_MPS / NATURAL_RUN_MPS;
// Fallback screen pace (px/s) used only until the avatar is framed and its real
// pixels-per-meter is known — then _walkPx/_runPx take over.
const WALK_SPEED = 200;
// Gravity, mirrored from the walk platformer so the guide obeys the same physics
// the visitor sees there: it falls onto the ground plane and stays planted,
// never floating mid-air. SPAWN_DROP is how far above the floor the guide spawns
// so it visibly settles when it first appears.
const GRAVITY = -14;
const SPAWN_DROP = 0.32;
// How snappily the guide's facing follows its movement direction, mirrored from
// the walk world's TURN_LERP (src/walk.js) so the tour guide turns with the same
// weight as the walk/stroll robot.
const TURN_LERP = 0.18;
export class GuideAvatar {
constructor(tourConfig = {}) {
// Feed the host's avatar settings into the walk SDK's config resolver, which
// gives us the roster, the default avatar entry, and the storage keys.
this.config = resolveConfig({
assetBase: tourConfig.assetBase || '',
apiBase: tourConfig.apiBase || '',
manifestUrl: tourConfig.manifestUrl || '/animations/manifest.json',
defaultAvatarId: tourConfig.guideAvatarId || 'realistic-female',
});
// Which avatar the guide adopts: the visitor's saved companion choice if
// present, else the configured guide default.
this.avatarStorageKey = tourConfig.avatarStorageKey || this.config.keys.avatar;
this.host = null;
this.renderer = null;
this.scene = null;
this.camera = null;
this.rig = null;
this.model = null;
this.controller = null;
this.clock = null;
this._raf = 0;
// Screen travel pace in px/s, derived from the avatar's on-screen scale in
// _frame; the fallback holds until the first framing measures it.
this._pxPerMeter = 0;
this._walkPx = WALK_SPEED;
this._runPx = WALK_SPEED * (RUN_MPS / WALK_MPS);
this._yaw = 0;
this._targetYaw = 0;
this._walking = false;
this._walkRaf = 0;
this._reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
this._pos = { x: 0, y: 0 };
// Vertical physics state — height above the ground plane and its velocity.
// Gravity in _tick pulls _y down to 0 and holds it there (see GRAVITY).
this._groundY = 0;
this._y = 0;
this._vy = 0;
this._tick = this._tick.bind(this);
}
async mount() {
ensureStyles();
this._buildDom();
// The DOM host (and its speech bubble) is built first, so even if WebGL or
// the avatar GLB fail to load the tour degrades gracefully: captions still
// show above the moving host, and the spotlight + pointer beam still work.
// The guide just loses its rendered body rather than breaking the tour.
try {
await this._buildScene();
this.clock = new Timer();
this._raf = requestAnimationFrame(this._tick);
} catch (err) {
console.warn('[tour] guide avatar failed to load — continuing without a rendered body:', err?.message || err);
this._headless = true;
this.canvas?.remove();
}
// Park bottom-right until the first stop moves it.
const start = { x: window.innerWidth - CANVAS_W - MARGIN, y: window.innerHeight - CANVAS_H - MARGIN };
this._setPos(start);
}
_buildDom() {
const host = document.createElement('div');
host.className = 'tws-tour-guide';
host.setAttribute('role', 'complementary');
host.setAttribute('aria-label', 'Tour guide');
host.innerHTML = `
<div class="tws-tour-guide__bubble" hidden></div>
<canvas class="tws-tour-guide__canvas" width="${CANVAS_W}" height="${CANVAS_H}"></canvas>
`;
document.body.appendChild(host);
this.host = host;
this.canvas = host.querySelector('.tws-tour-guide__canvas');
this.bubble = host.querySelector('.tws-tour-guide__bubble');
requestAnimationFrame(() => host.classList.add('is-in'));
}
async _buildScene() {
const renderer = new WebGLRenderer({ canvas: this.canvas, alpha: true, antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5));
renderer.setSize(CANVAS_W, CANVAS_H, false);
this.renderer = renderer;
const scene = new Scene();
this.scene = scene;
scene.add(new AmbientLight(0xffffff, 0.9));
const hemi = new HemisphereLight(0xbcd6ff, 0x202830, 0.7);
hemi.position.set(0, 4, 0);
scene.add(hemi);
const sun = new DirectionalLight(0xffffff, 1.6);
sun.position.set(2, 5, 4);
scene.add(sun);
this.camera = new PerspectiveCamera(40, CANVAS_W / CANVAS_H, 0.05, 100);
this.rig = new Group();
scene.add(this.rig);
const savedId = lsGet(this.avatarStorageKey) || this.config.defaultAvatarId;
const entry = resolveAvatarEntry(savedId, this.config);
const fallback = resolveAvatarEntry(this.config.defaultAvatarId, this.config);
const { model, controller } = await loadWalkAvatar(entry, {
assetBase: this.config.assetBase,
apiBase: this.config.apiBase,
manifestUrl: this.config.manifestUrl,
fallbackEntry: fallback,
});
this.model = model;
this.controller = controller;
this._frame(model, this.rig, this.camera);
}
_frame(model, rig, camera) {
const box = new Box3().setFromObject(model);
const size = box.getSize(new Vector3());
const center = box.getCenter(new Vector3());
model.position.x -= center.x;
model.position.z -= center.z;
model.position.y -= box.min.y;
rig.add(model);
const height = Math.max(0.6, size.y);
camera.position.set(0, height * 0.62, height * 2.2);
camera.lookAt(0, height * 0.52, 0);
// Measure how many on-screen pixels one world meter spans at the avatar's
// depth, so px/s travel can be tied to the clip's m/s cadence. The visible
// world height at the look-at distance maps to the displayed canvas height
// (getBoundingClientRect, so CSS-scaled mobile sizing is handled too).
const camDist = camera.position.distanceTo(new Vector3(0, height * 0.52, 0));
const visibleWorldH = 2 * camDist * Math.tan((camera.fov * Math.PI) / 180 / 2);
const displayH = this.size().h || CANVAS_H;
this._pxPerMeter = visibleWorldH > 0 ? displayH / visibleWorldH : 0;
if (this._pxPerMeter > 0) {
this._walkPx = WALK_MPS * this._pxPerMeter;
this._runPx = RUN_MPS * this._pxPerMeter;
}
// Feet rest at rig-local y = 0; gravity in _tick drives rig.position.y down
// to the ground plane. Spawn a touch above it so the guide drops and settles
// onto the floor when it first appears — the same fall the walk platformer
// applies. Honour reduced-motion by starting already grounded.
this._y = this._reduced ? this._groundY : this._groundY + SPAWN_DROP;
this._vy = 0;
rig.position.y = this._y;
}
// ── Public choreography API ───────────────────────────────────────────────
// Walk the avatar to a screen position (top-left of its canvas). Resolves
// when it arrives. Rather than gliding via a CSS transition, it steps the
// guide there frame-by-frame at a constant pace through place() — the exact
// locomotion the visitor drives in free roam — so the body advances in
// lockstep with the walk cycle and reads as genuine walking, not a slide.
walkTo(pos) {
const clamped = {
x: clamp(pos.x, MARGIN, window.innerWidth - CANVAS_W - MARGIN),
y: clamp(pos.y, MARGIN, window.innerHeight - CANVAS_H - MARGIN),
};
// Supersede any walk already in flight so a fresh click redirects the guide.
cancelAnimationFrame(this._walkRaf);
this._walkRaf = 0;
const dx = clamped.x - this._pos.x;
const dy = clamped.y - this._pos.y;
const dist = Math.hypot(dx, dy);
if (dist < 4 || this._reduced) {
// Already there, or reduced-motion: place without a stride and settle.
this._setPos(clamped);
this.settle();
return Promise.resolve();
}
const ux = dx / dist;
const uy = dy / dist;
const from = { x: this._pos.x, y: this._pos.y };
let traveled = 0;
let last = performance.now();
return new Promise((resolve) => {
const step = (now) => {
const dt = Math.min((now - last) / 1000, 0.05);
last = now;
traveled = Math.min(dist, traveled + (this._walkPx || WALK_SPEED) * dt);
this.place({ x: from.x + ux * traveled, y: from.y + uy * traveled });
if (traveled >= dist) {
this._walkRaf = 0;
this.settle();
resolve();
return;
}
this._walkRaf = requestAnimationFrame(step);
};
this._walkRaf = requestAnimationFrame(step);
});
}
// Compute a resting spot beside a target rect (viewport coords), preferring
// whichever side has room, and walk there + turn to face the target.
async approach(rect) {
const pos = this._spotBeside(rect);
await this.walkTo(pos);
this._faceRect(rect);
}
// Park in a neutral corner and face forward (whole-page stops).
async park() {
await this.walkTo({
x: window.innerWidth - CANVAS_W - MARGIN,
y: window.innerHeight - CANVAS_H - MARGIN,
});
this._targetYaw = 0;
}
// Point at the current target: a wave-style gesture toward it.
point() {
this.controller?.playWave();
}
// ── Free-roam hooks ─────────────────────────────────────────────────────────
// The canvas host is pointer-events:none during the guided tour so it never
// eats page clicks; free-roam flips it interactive so the guide can be grabbed.
setInteractive(on) {
if (!this.host) return;
this.host.style.pointerEvents = on ? 'auto' : 'none';
this.host.classList.toggle('is-roam', !!on);
}
// Footprint of the avatar host, for centering it under a pointer.
size() {
const r = this.host?.getBoundingClientRect();
return { w: r?.width || CANVAS_W, h: r?.height || CANVAS_H };
}
// Instant placement (drag / edge-scroll follow): clamp to the viewport, face
// the direction of travel, run the walk cycle, and auto-settle to idle shortly
// after movement stops so a parked guide isn't stuck mid-stride.
place(pos) {
const s = this.size();
const x = clamp(pos.x, MARGIN, window.innerWidth - s.w - MARGIN);
const y = clamp(pos.y, MARGIN, window.innerHeight - s.h - MARGIN);
const dx = x - this._pos.x;
const dy = y - this._pos.y;
// Full 360° facing from the actual travel vector — the same omnidirectional
// turn the walk/stroll robot uses (src/walk.js: yaw = atan2(moveX, moveZ)).
// Screen +x maps to world +X (right); screen +y (downward, toward the viewer)
// maps to world +Z (toward the fixed front camera, the rig's yaw=0 forward),
// so atan2(dx, dy) turns the guide to face wherever it walks — left, right,
// toward the camera, or away — instead of the old ±40° horizontal tilt.
if (Math.hypot(dx, dy) > 1) this._targetYaw = Math.atan2(dx, dy);
this.controller?.setState('walk');
// Match clip cadence to travel so the stride ground-speed equals the body's
// and the feet plant (the walk world's mixer.timeScale = speed/natural trick).
this.controller?.setSpeed?.(WALK_TIMESCALE);
this._walking = true;
clearTimeout(this._settleTimer);
this._settleTimer = setTimeout(() => this.settle(), 180);
this._setPos({ x, y });
}
settle() {
clearTimeout(this._settleTimer);
this._walking = false;
this._targetYaw = 0;
this.controller?.setState('idle');
this.controller?.setSpeed?.(1); // idle plays at its authored cadence
}
_spotBeside(rect) {
const gap = 22;
const rightX = rect.left + rect.width + gap;
const leftX = rect.left - CANVAS_W - gap;
let x;
if (rightX + CANVAS_W <= window.innerWidth - MARGIN) x = rightX;
else if (leftX >= MARGIN) x = leftX;
else x = clamp(rect.cx - CANVAS_W / 2, MARGIN, window.innerWidth - CANVAS_W - MARGIN);
const y = clamp(rect.cy - CANVAS_H * 0.58, MARGIN, window.innerHeight - CANVAS_H - MARGIN);
return { x, y };
}
_faceRect(rect) {
const avatarCx = this._pos.x + CANVAS_W / 2;
const avatarCy = this._pos.y + CANVAS_H / 2;
// Turn to fully face the highlighted target, matching the walk robot's
// all-directions facing rather than the old ±34° horizontal clamp. Same
// screen→world axis mapping as place() (dx→X, dy→Z toward the camera).
this._targetYaw = Math.atan2(rect.cx - avatarCx, rect.cy - avatarCy);
}
// Approximate screen position of the avatar's head — origin for the pointer
// beam the director draws to the highlighted element.
headScreen() {
return { x: this._pos.x + CANVAS_W / 2, y: this._pos.y + CANVAS_H * 0.18 };
}
// ── Speech bubble ─────────────────────────────────────────────────────────
say(text) {
if (!this.bubble) return;
this.bubble.textContent = text;
this.bubble.hidden = false;
requestAnimationFrame(() => this.bubble.classList.add('is-in'));
}
hideBubble() {
if (!this.bubble) return;
this.bubble.classList.remove('is-in');
setTimeout(() => {
if (this.bubble) this.bubble.hidden = true;
}, 280);
}
// ── Internals ─────────────────────────────────────────────────────────────
// Snap the host to a screen position. All locomotion is now driven frame-by-
// frame (walkTo / place / free-roam), so the host never CSS-transitions — its
// stride and travel stay in sync.
_setPos(pos) {
this._pos = pos;
if (!this.host) return;
this.host.style.left = pos.x + 'px';
this.host.style.top = pos.y + 'px';
}
_tick() {
if (!this.host) return;
this.clock.update();
const dt = Math.min(this.clock.getDelta(), 0.05);
// Shortest-arc turn toward the target facing. With full 360° targets the
// naïve (target - current) lerp would spin the long way across the ±π seam;
// wrapping the delta into [-π, π] keeps every turn taking the near side.
this._yaw += shortestAngle(this._targetYaw - this._yaw) * TURN_LERP;
if (this.rig) {
this.rig.rotation.y = this._yaw;
// Gravity: integrate velocity, land on the ground plane, hold there —
// the same model the walk platformer uses so the guide is never airborne.
this._vy += GRAVITY * dt;
this._y += this._vy * dt;
if (this._y <= this._groundY) {
this._y = this._groundY;
if (this._vy < 0) this._vy = 0;
}
this.rig.position.y = this._y;
}
this.controller?.update(dt);
this.renderer.render(this.scene, this.camera);
this._raf = requestAnimationFrame(this._tick);
}
dispose() {
cancelAnimationFrame(this._raf);
cancelAnimationFrame(this._walkRaf);
clearTimeout(this._settleTimer);
this._raf = 0;
this._walkRaf = 0;
try {
this.controller?.dispose();
} catch {
/* non-fatal */
}
if (this.scene) {
this.scene.traverse((n) => {
if (n.isMesh) disposeMesh(n);
});
}
if (this.renderer) {
this.renderer.dispose();
this.renderer.forceContextLoss?.();
}
this.host?.remove();
this.host = null;
}
}
// ── helpers ──────────────────────────────────────────────────────────────────
function clamp(n, lo, hi) {
return Math.min(hi, Math.max(lo, n));
}
// Wrap an angle delta into [-π, π] so a yaw lerp always rotates the short way.
function shortestAngle(d) {
return Math.atan2(Math.sin(d), Math.cos(d));
}
function lsGet(key) {
try {
return localStorage.getItem(key);
} catch {
return null;
}
}
function disposeMesh(n) {
n.geometry?.dispose?.();
const mats = Array.isArray(n.material) ? n.material : [n.material];
mats.forEach((m) => {
if (!m) return;
for (const v of Object.values(m)) if (v && v.isTexture) v.dispose();
m.dispose?.();
});
}
let _stylesInjected = false;
function ensureStyles() {
if (_stylesInjected) return;
_stylesInjected = true;
const style = document.createElement('style');
style.id = 'tws-tour-guide-style';
style.textContent = `
.tws-tour-guide{position:fixed;left:0;top:0;width:${CANVAS_W}px;height:${CANVAS_H}px;z-index:${Z_AVATAR};pointer-events:none;opacity:0;transform:translateY(10px);transition:opacity .4s ease,transform .4s ease;-webkit-user-select:none;user-select:none}
.tws-tour-guide.is-in{opacity:1;transform:translateY(0)}
.tws-tour-guide__canvas{position:absolute;inset:0;width:100%;height:100%;filter:drop-shadow(0 16px 20px rgba(0,0,0,.34))}
.tws-tour-guide__bubble{position:absolute;left:50%;bottom:calc(100% - 30px);transform:translateX(-50%) translateY(8px);width:max-content;max-width:320px;background:rgba(18,20,28,.96);color:#f2f4f8;font:500 13px/1.45 system-ui,-apple-system,'Segoe UI',sans-serif;padding:10px 13px;border-radius:14px;border:1px solid rgba(122,162,255,.28);box-shadow:0 12px 30px rgba(0,0,0,.4);opacity:0;transition:opacity .3s ease,transform .3s ease;text-align:left}
.tws-tour-guide__bubble.is-in{opacity:1;transform:translateX(-50%) translateY(0)}
.tws-tour-guide__bubble::after{content:'';position:absolute;left:50%;top:100%;transform:translateX(-50%);border:7px solid transparent;border-top-color:rgba(18,20,28,.96)}
@media (max-width:560px){.tws-tour-guide{width:128px;height:182px}.tws-tour-guide__bubble{max-width:230px;font-size:12px}}
@media (prefers-reduced-motion:reduce){.tws-tour-guide,.tws-tour-guide__bubble{transition:opacity .2s ease}}
`;
document.head.appendChild(style);
}