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 walk-sdk avatar loader (loadWalkAvatar) so the guide
// is the same rig the visitor picked for the Walk Companion 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.
import {
AmbientLight,
Box3,
Timer,
DirectionalLight,
Group,
HemisphereLight,
PerspectiveCamera,
Scene,
Vector3,
WebGLRenderer,
} from 'three';
import { loadWalkAvatar } from '../../walk-sdk/src/internal/load-avatar.js';
import { resolveConfig, resolveAvatarEntry } from '../../walk-sdk/src/config.js';
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 (src/walk.js GRAVITY = -14) 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;
// The platform's recurring default character — "Ava", the photoreal full-body
// humanoid (/avatars/realistic-female.glb). The same rig stands in as the guide
// NPC in the walk world, so the tour guide matches her by default.
const DEFAULT_GUIDE_AVATAR = 'realistic-female';
export class GuideAvatar {
constructor() {
this.config = resolveConfig({
assetBase: '',
apiBase: '',
manifestUrl: '/animations/manifest.json',
docsUrl: '/avatar-studio',
defaultAvatarId: DEFAULT_GUIDE_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._walkResolve = null;
this._bubbleHideTimer = 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);
this._onVisibility = this._onVisibility.bind(this);
}
// Stop rendering the guide while the tab is backgrounded; resume on return.
_onVisibility() {
if (this._headless) return;
if (document.hidden) {
cancelAnimationFrame(this._raf);
this._raf = 0;
} else if (this.host && this.clock && !this._raf) {
this.clock.getDelta(); // drop the hidden span so gravity doesn't lurch
this._raf = requestAnimationFrame(this._tick);
}
}
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);
document.addEventListener('visibilitychange', this._onVisibility);
} 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.config.keys.avatar) || this.config.defaultAvatarId;
const entry = resolveAvatarEntry(savedId, this.config);
const fallback = resolveAvatarEntry(this.config.defaultAvatarId, this.config);
const { model, controller, entry: active } = await loadWalkAvatar(entry, {
assetBase: this.config.assetBase,
apiBase: this.config.apiBase,
manifestUrl: this.config.manifestUrl,
fallbackEntry: fallback,
});
this.model = model;
this.controller = controller;
this._entry = active;
this._frame(model, this.rig, this.camera);
}
// ── Live avatar swap ───────────────────────────────────────────────────────
// Hot-swap the guide to any roster (or user-generated) avatar. Persists the
// choice to the shared Walk Companion key so it sticks across the tour and the
// rest of the site, then disposes the old rig and drops the new one in under
// gravity. Resolves to the entry actually shown (the fallback if the pick fails
// to load), so the picker UI can reflect what really happened.
async setAvatar(idOrEntry) {
const entry =
typeof idOrEntry === 'string' ? resolveAvatarEntry(idOrEntry, this.config) : idOrEntry;
if (!entry) return this._entry;
lsSet(this.config.keys.avatar, entry.id);
// Headless (WebGL/GLB failed) or not yet built — remember the pick; it
// applies on the next successful mount.
if (this._headless || !this.rig) {
this._entry = entry;
return entry;
}
const fallback = resolveAvatarEntry(this.config.defaultAvatarId, this.config);
try {
const { model, controller, entry: active } = await loadWalkAvatar(entry, {
assetBase: this.config.assetBase,
apiBase: this.config.apiBase,
manifestUrl: this.config.manifestUrl,
fallbackEntry: fallback,
});
// The guide may have been torn down while the GLB was loading.
if (!this.rig) {
model.traverse((n) => n.isMesh && disposeMesh(n));
controller.dispose?.();
return this._entry;
}
if (this.model) {
this.rig.remove(this.model);
this.model.traverse((n) => n.isMesh && disposeMesh(n));
}
this.controller?.dispose();
this._yaw = 0;
this._targetYaw = 0;
this.rig.rotation.y = 0;
this.model = model;
this.controller = controller;
this._entry = active;
this._frame(model, this.rig, this.camera);
return active;
} catch (err) {
console.warn('[tour] guide avatar swap failed:', err?.message || err);
return this._entry;
}
}
// The roster the guide can switch between, and the id it's currently wearing —
// surfaced so the tour's settings UI can build a picker without reaching into
// the SDK config itself.
avatars() {
return this.config.avatars;
}
currentAvatarId() {
return this._entry?.id || lsGet(this.config.keys.avatar) || this.config.defaultAvatarId;
}
_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.
// Settle its promise first so an awaiter (approach/park) can never hang
// forever once we cancel the RAF that would have resolved it.
if (this._walkResolve) {
const prev = this._walkResolve;
this._walkResolve = null;
prev();
}
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) => {
this._walkResolve = 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._walkResolve = null;
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 / keyboard / edge-scroll follow): clamp to the
// viewport, face the direction of travel, run the walk (or run) cycle, and
// auto-settle to idle shortly after movement stops so a parked guide isn't
// stuck mid-stride. `running` switches to the run gait for keyboard sprinting.
place(pos, { running = false } = {}) {
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(running ? 'run' : '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?.(running ? RUN_TIMESCALE : 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;
clearTimeout(this._bubbleHideTimer);
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');
clearTimeout(this._bubbleHideTimer);
this._bubbleHideTimer = 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() {
document.removeEventListener('visibilitychange', this._onVisibility);
cancelAnimationFrame(this._raf);
cancelAnimationFrame(this._walkRaf);
clearTimeout(this._settleTimer);
clearTimeout(this._bubbleHideTimer);
this._raf = 0;
this._walkRaf = 0;
// Settle any awaiter blocked on an in-flight walk so it can't hang past teardown.
if (this._walkResolve) {
const prev = this._walkResolve;
this._walkResolve = null;
prev();
}
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;
this.bubble = 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 lsSet(key, value) {
try {
localStorage.setItem(key, value);
} catch {
/* private mode / quota — the swap still applies for this session */
}
}
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);
}