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
import {
AudioListener,
AxesHelper,
Box3,
BufferAttribute,
BufferGeometry,
Cache,
CanvasTexture,
Color,
GridHelper,
LoaderUtils,
LoopOnce,
LoopRepeat,
Mesh,
PMREMGenerator,
PerspectiveCamera,
PCFShadowMap,
PlaneGeometry,
Points,
PointsMaterial,
Scene,
ShadowMaterial,
SkeletonHelper,
Spherical,
Vector3,
WebGLRenderer,
LinearToneMapping,
ACESFilmicToneMapping,
NeutralToneMapping,
} from 'three';
import Stats from 'three/addons/libs/stats.module.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
import { GUI } from 'dat.gui';
import { environments } from './environments.js';
import { createModelInfo } from './model-info.js';
import { isDecentralizedURI, resolveURI, normalizeGatewayURL } from './ipfs.js';
import { canUseQuickLook, openQuickLook } from './ar/quick-look.js';
import { canUseSceneViewer, openSceneViewer } from './ar/scene-viewer.js';
import { WebXRSession } from './ar/webxr.js';
import { buildAnnotations, renderAnnotationCanvas } from './annotations.js';
import {
DEFAULT_CAMERA,
Preset,
MANAGER,
getDecoders,
traverseMaterials,
} from './viewer/internal.js';
import { addLights, removeLights } from './viewer/lights.js';
import { getCubeMapTexture } from './viewer/environment.js';
import { takeScreenshot, captureScreenshot } from './viewer/screenshot.js';
import { setClips, playAllClips } from './viewer/animation.js';
import { computeFramingExtent, computeFramingWidth } from './viewer/framing.js';
import { estimateFacingYaw, forwardFromYaw, horizontalExtentAt } from './viewer/facing.js';
import { LightProbeGrid } from './light-probe-grid.js';
import { AnimationManager } from './animation-manager.js';
import { installVrmPlugin, prepareVrmModel } from './game/vrm-loader.js';
import './game/vrm-boot.js'; // side effect: registers the real @pixiv/three-vrm plugin
import { applyAvatarMaterialRealism, looksLikeAvatarMesh } from './shared/avatar-material-realism.js';
import { computeBoundsTree, disposeBoundsTree, acceleratedRaycast } from 'three-mesh-bvh';
import {
CinematicPipeline,
CINEMATIC_PRESET_NAMES,
CINEMATIC_DEFAULTS,
DEFAULT_CINEMATIC_PRESET,
} from './viewer/cinematic.js';
import { log } from './shared/log.js';
// Install BVH-accelerated raycasting on Three.js prototypes. This must happen
// before any geometry is created so every Mesh benefits transparently.
BufferGeometry.prototype.computeBoundsTree = computeBoundsTree;
BufferGeometry.prototype.disposeBoundsTree = disposeBoundsTree;
Mesh.prototype.raycast = acceleratedRaycast;
Cache.enabled = true;
// Canvas focus ring + reduced-motion opt-out, injected once per document.
// The viewer's <canvas> is appended directly into arbitrary host pages (forge,
// avatar-page, embeds, kiosks) with no guaranteed shared stylesheet, so this
// mirrors the pattern used by the SDK's <three-ws-viewer> (avatar-sdk/src/viewer.js):
// a tiny scoped <style> tag rather than assuming a page-level CSS file loaded.
// `var(--accent, …)` matches the site's existing focus-visible token
// (see src/character-creator.css, src/exchanges.css) with a safe fallback for
// pages that don't define it.
const VIEWER_A11Y_STYLE_ID = 'tws-viewer-canvas-a11y';
function ensureViewerA11yStyles() {
if (typeof document === 'undefined' || document.getElementById(VIEWER_A11Y_STYLE_ID)) return;
const style = document.createElement('style');
style.id = VIEWER_A11Y_STYLE_ID;
style.textContent = `
canvas.tws-viewer-canvas { outline: none; touch-action: none; }
canvas.tws-viewer-canvas:focus-visible { outline: 2px solid var(--accent, #6ee7b7); outline-offset: -2px; }
@media (prefers-reduced-motion: reduce) {
canvas.tws-viewer-canvas { scroll-behavior: auto; }
}
`;
document.head.appendChild(style);
}
function viewerPrefersReducedMotion() {
return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
}
// Low-power heuristic: coarse pointer (touch) + few cores/little memory almost
// always means an entry-level phone/tablet. `deviceMemory` is Chromium-only
// and absent on iOS/Firefox, so it only ever *adds* signal, never gates alone.
// The touch requirement means desktop — mouse or trackpad, any core count —
// never matches, so default desktop behavior is unchanged. Mirrors
// avatar-sdk/src/viewer.js's identical heuristic for the lightweight SDK
// component, kept as a local copy since the two are separate bundles.
function viewerLooksLowPower() {
if (typeof navigator === 'undefined' || typeof matchMedia === 'undefined') return false;
const touch = matchMedia('(pointer: coarse)').matches;
if (!touch) return false;
const fewCores = typeof navigator.hardwareConcurrency === 'number' && navigator.hardwareConcurrency <= 4;
const lowMem = typeof navigator.deviceMemory === 'number' && navigator.deviceMemory <= 4;
return fewCores || lowMem;
}
// Draw a small gold coin sprite on a canvas for the pump.fun trade shower, so the
// effect is self-contained (no external image asset to 404). A fresh texture is
// returned each call; the caller owns disposal.
function makeCoinTexture() {
const size = 64;
const canvas = document.createElement('canvas');
canvas.width = canvas.height = size;
const ctx = canvas.getContext('2d');
const r = size / 2;
const grad = ctx.createRadialGradient(r * 0.7, r * 0.7, r * 0.2, r, r, r);
grad.addColorStop(0, '#ffe9a8');
grad.addColorStop(0.6, '#f4b73d');
grad.addColorStop(1, '#b9791a');
ctx.beginPath();
ctx.arc(r, r, r - 2, 0, Math.PI * 2);
ctx.fillStyle = grad;
ctx.fill();
ctx.lineWidth = 3;
ctx.strokeStyle = 'rgba(255,243,205,0.85)';
ctx.stroke();
const tex = new CanvasTexture(canvas);
tex.needsUpdate = true;
return tex;
}
/**
* @class Viewer
*
* @param {Element} el
* @param {object} options
*/
/**
* dat.GUI renders every control as a bare `<input>`/`<select>` beside a text
* span, which leaves each one without an accessible name: a screen reader
* announces "checkbox" with no idea what it toggles, and axe flags it on every
* page that embeds a viewer. dat.GUI has no hook for this, so the rows are
* labelled after the fact from the property name each row already displays.
* @param {HTMLElement} root the GUI's DOM element
*/
function labelGUIControls(root) {
if (!root) return;
for (const row of root.querySelectorAll('.cr')) {
const name = row.querySelector('.property-name')?.textContent?.trim();
if (!name) continue;
for (const field of row.querySelectorAll('input, select')) {
if (!field.getAttribute('aria-label') && !field.id) field.setAttribute('aria-label', name);
}
}
// Folder titles are clickable <li>s, not buttons: give them a role and a
// name so the panel can be operated without a mouse.
for (const title of root.querySelectorAll('li.folder > .title')) {
if (!title.getAttribute('role')) title.setAttribute('role', 'button');
if (!title.hasAttribute('tabindex')) title.setAttribute('tabindex', '0');
}
}
/**
* Controls appear long after the panel is built: the animation, morph-target
* and camera folders fill in when a model finishes loading, and refill on every
* model swap. Labelling once at construction therefore leaves every
* later-added row nameless, so the panel is watched and each new row labelled
* as it arrives.
* @param {HTMLElement} root the GUI's DOM element
* @returns {MutationObserver|null}
*/
function watchGUIControls(root) {
if (!root || typeof MutationObserver !== 'function') return null;
const observer = new MutationObserver(() => labelGUIControls(root));
observer.observe(root, { childList: true, subtree: true });
return observer;
}
export class Viewer {
constructor(el, options) {
this.el = el;
this.options = options;
this.postToParent = options.postToParent || null;
this.lights = [];
this.content = null;
this.mixer = null;
this.clips = [];
this.gui = null;
this._lightProbeGrid = null;
// External animation system (Mixamo-style)
this.animationManager = new AnimationManager();
this._animPanelEl = null;
// Restart the on-demand render loop whenever an external clip starts.
// crossfadeTo/play set currentAction asynchronously and hold no viewer
// reference, so onChange is the only signal that a new action is live —
// without invalidating here, a clip started after the load-reveal frames
// settle would never tick the mixer and the avatar would freeze in its
// bind pose (T-pose). Wired at construction so it survives kiosk mode,
// where _setupAnimationPanel (and its own onChange) is skipped.
this.animationManager.onChange = () => {
if (this._animPanelEl) this._renderAnimButtons();
this.invalidate();
};
this.state = {
environment:
options.preset === Preset.ASSET_GENERATOR
? environments.find((e) => e.id === 'footprint-court').name
: environments[1].name,
background: false,
playbackSpeed: 1.0,
actionStates: {},
camera: DEFAULT_CAMERA,
wireframe: false,
skeleton: false,
grid: false,
autoRotate: false,
// Lights — studio three-point rig (key + fill + rim) plus ambient
// base, lit by the Khronos PBR-Neutral tone mapper. Neutral keeps
// midtone brightness and saturation instead of crushing them the way
// ACES/Linear do, so auto-generated avatars read bright and true
// rather than dark and muddy in gallery cards. See updateLights() and
// viewer/lights.js for how the rig is assembled.
punctualLights: true,
exposure: 0.0,
toneMapping: NeutralToneMapping,
ambientIntensity: 0.45,
ambientColor: '#FFFFFF',
// The 0.8 * π factor compensates for three.js's historical
// `irradiance *= PI` step on punctual lights and keeps direct
// lighting visually matched to the upstream three-gltf-viewer
// baseline. See donmccurdy/three-gltf-viewer#116 — closed as a
// question; removing π would require a shader-side adjustment.
directIntensity: 0.8 * Math.PI,
directColor: '#FFFFFF',
// Fill softens the key's shadow side; rim/back light carves the
// silhouette out of dark backdrops so even a black-clad avatar never
// disappears into a black card. Ratios are relative to directIntensity.
fillRatio: 0.4,
fillColor: '#DCE6FF',
rimRatio: 0.55,
rimColor: '#FFFFFF',
// Image-based lighting strength (RoomEnvironment / HDRI). >1 lifts the
// ambient PBR response without washing out direct highlights.
environmentIntensity: 1.15,
bgColor: '#000000',
transparentBg: false,
pointSize: 1.0,
// Info overlay
showInfo: true,
showLabels: false,
// Avatar follow mode
followMode: 'mouse',
// Light probe grid
probeNx: 4,
probeNy: 2,
probeNz: 4,
probeCubeFace: 64,
};
this.prevTime = 0;
this.stats = new Stats();
this.stats.dom.height = '48px';
[].forEach.call(this.stats.dom.children, (child) => (child.style.display = ''));
this.backgroundColor = new Color(this.state.bgColor);
this.scene = new Scene();
this.scene.background = this.backgroundColor;
// The host element can still be unlaid-out at construction (hidden tab,
// CSS not applied yet, flex parent that sizes on the next frame). A 0-px
// renderer/composer allocates zero-dimension GL textures, which the
// driver rejects (glTexStorage2D: dimensions must be > 0) and every
// subsequent clear/blit/draw then fails against an incomplete
// framebuffer. Start at 1 px and let the ResizeObserver below re-size to
// the real box on the first frame that has one.
const initialWidth = Math.max(1, el.clientWidth);
const initialHeight = Math.max(1, el.clientHeight);
const fov = options.preset === Preset.ASSET_GENERATOR ? (0.8 * 180) / Math.PI : 60;
const aspect = el.clientHeight > 0 ? el.clientWidth / el.clientHeight : 1;
this.defaultCamera = new PerspectiveCamera(fov, aspect, 0.01, 1000);
this.activeCamera = this.defaultCamera;
this.scene.add(this.defaultCamera);
this.audioListener = new AudioListener();
// Patch: Chrome throws TypeError("non-finite") from AudioParam when the
// listener's world matrix contains NaN (e.g. first frame before the scene
// graph is fully initialized). Swallow silently — position corrects next frame.
const _alUpdate = this.audioListener.updateMatrixWorld.bind(this.audioListener);
this.audioListener.updateMatrixWorld = (force) => {
try { _alUpdate(force); } catch (e) {
if (!(e instanceof TypeError)) throw e;
}
};
this.defaultCamera.add(this.audioListener);
// Quality auto-degrade: a touch device with few cores/little memory
// (entry-level phone/tablet) skips MSAA — the single biggest GPU cost on
// weak mobile GPUs — in exchange for a stable frame rate. Gated on a
// coarse pointer, so desktop (mouse/trackpad) never matches — default
// desktop behavior is unchanged.
this._lowPower = viewerLooksLowPower();
this.renderer = window.renderer = new WebGLRenderer({ antialias: !this._lowPower, alpha: true });
this.renderer.setClearColor(0x000000, 1);
// DPR cap: kiosk/embed modes default to 1.5 (saves ~40% fragment work on
// retina). Override with options.maxPixelRatio. Standalone tabs default
// to 2.0 to preserve sharpness on high-DPI displays. Low-power devices
// are capped at 1.0 regardless of mode — resolution is the second
// biggest lever after MSAA on weak mobile GPUs.
const dprCap = this._lowPower ? 1 : (options.maxPixelRatio ?? (options.kiosk ? 1.5 : 2));
this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, dprCap));
this.renderer.setSize(initialWidth, initialHeight);
// Ground contact shadow (the one rendering-quality gap vs the
// model-viewer surfaces). Cheap when nothing casts; skipped entirely on
// low-power devices, matching the MSAA/DPR degrade above.
this.renderer.shadowMap.enabled = !this._lowPower;
this.renderer.shadowMap.type = PCFShadowMap;
this.shadowCatcher = null;
this.pmremGenerator = new PMREMGenerator(this.renderer);
this.pmremGenerator.compileEquirectangularShader();
this.neutralEnvironment = this.pmremGenerator.fromScene(new RoomEnvironment()).texture;
this.controls = new OrbitControls(this.defaultCamera, this.renderer.domElement);
this.controls.screenSpacePanning = true;
this._onControlsChange = () => this.invalidate();
this.controls.addEventListener('change', this._onControlsChange);
// prefers-reduced-motion: OrbitControls damping (inertial drift after
// pointer release) is opt-in in three.js and defaults off, so there's
// nothing to disable here — this flag only gates the keyboard-orbit
// step size below, keeping motion-sensitive users' arrow-key input
// snappy/discrete rather than smoothed.
this._reducedMotion = viewerPrefersReducedMotion();
this.el.appendChild(this.renderer.domElement);
// Accessibility: the canvas is the primary interactive surface but has
// no accessible name or keyboard path by default. Make it a reachable,
// labeled, orbit/zoom-able control — mirrors the SDK's lightweight
// <three-ws-viewer> (avatar-sdk/src/viewer.js) so keyboard behavior is
// consistent whichever viewer a page embeds.
ensureViewerA11yStyles();
const canvasEl = this.renderer.domElement;
canvasEl.classList.add('tws-viewer-canvas');
canvasEl.tabIndex = 0;
canvasEl.setAttribute('role', 'img');
canvasEl.setAttribute('aria-label', options.alt || options.title || '3D model viewer. Focus and use arrow keys to orbit, +/- to zoom.');
this._onCanvasKeyDown = (e) => this._handleOrbitKeydown(e);
canvasEl.addEventListener('keydown', this._onCanvasKeyDown);
// Post-processing: the CinematicPipeline owns the full post chain (SSAO,
// depth-of-field, bloom, colour grade, chromatic aberration, film grain,
// vignette) behind selectable presets. The default 'Studio' preset
// reproduces the historical look exactly — subtle bloom + vignette, nothing
// else — so gallery thumbnails and embeds are unchanged unless a user opts
// into a richer look. Screenshot capture bypasses this — see screenshot.js.
this.state.cinematicPreset = options.cinematicPreset ?? DEFAULT_CINEMATIC_PRESET;
this._cinematic = new CinematicPipeline(this.renderer, this.scene, this.activeCamera, {
width: initialWidth,
height: initialHeight,
preset: this.state.cinematicPreset,
});
this._composer = this._cinematic.composer;
this.cameraCtrl = null;
this.cameraFolder = null;
this.animFolder = null;
this.animCtrls = [];
this.morphFolder = null;
this.morphCtrls = [];
this.skeletonHelpers = [];
this.gridHelper = null;
this.axesHelper = null;
this.modelInfo = null;
this.annotationEls = [];
this._tempVec = new Vector3();
this.addAxesHelper();
this.addGUI();
if (options.kiosk) this.gui.close();
this.animate = this.animate.bind(this);
this._rafId = null;
this._visible = true;
this._tabVisible = !document.hidden;
this._disposed = false;
this._loadedEnvironment = null;
this._needsRender = true;
this._animating = false;
this._onVisibilityChange = () => {
const wasHidden = !this._tabVisible;
this._tabVisible = !document.hidden;
if (wasHidden && this._tabVisible) this._needsRender = true;
this._updateRenderLoop();
};
document.addEventListener('visibilitychange', this._onVisibilityChange);
if (typeof IntersectionObserver !== 'undefined') {
this._intersectionObserver = new IntersectionObserver(
(entries) => {
const wasHidden = !this._visible;
this._visible = entries[entries.length - 1].isIntersecting;
if (wasHidden && this._visible) this._needsRender = true;
this._updateRenderLoop();
},
{ threshold: 0 },
);
this._intersectionObserver.observe(this.el);
}
// Coalesce resize bursts (a window drag, or the ResizeObserver firing
// alongside the window 'resize' event) into one resize() per animation
// frame — resize() reallocates the renderer + composer framebuffers and
// may re-frame the model, which is wasteful to run several times per
// frame. _resizeRaf holds the pending frame id; resize() runs once when
// it fires.
this._resizeRaf = null;
this._onResize = () => {
if (this._resizeRaf != null) return;
this._resizeRaf = requestAnimationFrame(() => {
this._resizeRaf = null;
if (!this._disposed) this.resize();
});
};
this._onKeyDown = (e) => {
if (this.isInputFocused()) return;
if (e.key === 'p' || e.key === 'P') {
this.takeScreenshot();
} else if (e.code === 'Space') {
e.preventDefault();
this.toggleAnimationPlayback();
} else if (e.key === 'f' || e.key === 'F') {
this.frameContent();
}
};
this._onDblClick = () => this.frameContent({ animate: true });
this._onMessage = this.onMessage.bind(this);
this._updateRenderLoop();
window.addEventListener('resize', this._onResize, false);
window.addEventListener('keydown', this._onKeyDown);
this.renderer.domElement.addEventListener('dblclick', this._onDblClick);
window.addEventListener('message', this._onMessage, false);
// Track the host element's own box (not just the window) so the canvas
// follows when the embed wrap is resized, the page lays out late, or a
// flex/grid parent reflows.
if (typeof ResizeObserver !== 'undefined') {
this._ro = new ResizeObserver(() => this._onResize());
this._ro.observe(this.el);
}
}
// Keyboard-only orbit + zoom for users who can't drag a pointer: arrow keys
// rotate azimuth/polar around the current OrbitControls target, +/- and
// PageUp/PageDown dolly. Scoped to the canvas element's own keydown (only
// fires while the canvas has focus) so it never steals arrow-key
// scroll/navigation elsewhere on the host page. Step sizes match
// avatar-sdk/src/viewer.js's keyboard orbit for a consistent feel across
// every three.ws viewer surface; reduced-motion halves the step so users
// who asked for less motion get finer, calmer control instead of smoothing.
_handleOrbitKeydown(event) {
const stepScale = this._reducedMotion ? 0.5 : 1;
const rotateStep = 0.05 * stepScale;
const zoomStep = 1.08;
let handled = true;
switch (event.key) {
case 'ArrowLeft': handled = this.orbitBy(-rotateStep, 0); break;
case 'ArrowRight': handled = this.orbitBy(rotateStep, 0); break;
case 'ArrowUp': handled = this.orbitBy(0, -rotateStep); break;
case 'ArrowDown': handled = this.orbitBy(0, rotateStep); break;
case '+':
case '=':
case 'PageUp': handled = this.dollyBy(1 / zoomStep); break;
case '-':
case '_':
case 'PageDown': handled = this.dollyBy(zoomStep); break;
default: handled = false;
}
if (!handled) return;
event.preventDefault();
event.stopPropagation();
}
/**
* Move the camera around its orbit target, in radians. `dTheta` turns
* around the model, `dPhi` raises and lowers the shot (clamped clear of the
* poles, where the up vector flips and the view snaps).
*
* Public because the keyboard is no longer the only thing that steers this
* camera: acoustic gestures drive it too (src/sonar/controller.js), and both
* need the same spherical move rather than two copies of it.
*
* @returns {boolean} false when there is no camera to move yet.
*/
orbitBy(dTheta = 0, dPhi = 0) {
if (!this.controls || !this.activeCamera) return false;
const offset = this._tempVec.subVectors(this.activeCamera.position, this.controls.target);
const spherical = new Spherical().setFromVector3(offset);
spherical.theta += dTheta;
spherical.phi = Math.max(0.05, Math.min(Math.PI - 0.05, spherical.phi + dPhi));
this._applySpherical(spherical);
return true;
}
/**
* Dolly the camera along its view ray. Factors below 1 move in, above 1 move
* out; the range is clamped against the framed distance so a caller cannot
* drive the camera inside the model or off into the void.
*
* @returns {boolean} false when there is no camera to move yet.
*/
dollyBy(factor) {
if (!this.controls || !this.activeCamera || !(factor > 0)) return false;
const offset = this._tempVec.subVectors(this.activeCamera.position, this.controls.target);
const spherical = new Spherical().setFromVector3(offset);
const min = this.controls.minDistance || spherical.radius * 0.2;
const max = this.controls.maxDistance || spherical.radius * 5;
spherical.radius = Math.max(min, Math.min(max, spherical.radius * factor));
this._applySpherical(spherical);
return true;
}
_applySpherical(spherical) {
const newOffset = new Vector3().setFromSpherical(spherical);
this.activeCamera.position.copy(this.controls.target).add(newOffset);
this.controls.update();
this.invalidate();
}
setCameraTarget(boneName) {
if (!this.content) return;
const bone = this.content.getObjectByName(boneName);
if (bone) {
const target = new Vector3();
bone.getWorldPosition(target);
this._tweenCamera(this.defaultCamera.position, target, 600);
}
}
invalidate() {
if (this._disposed) return;
this._needsRender = true;
this._updateRenderLoop();
}
onMessage(e) {
if (!e.data || typeof e.data !== 'object' || !e.data.op) return;
// SECURITY: Check origin if we ever handle sensitive ops. For gesture/emote,
// it's fine to be promiscuous so any parent window can control the avatar.
switch (e.data.op) {
case 'gesture':
this.onGesture(e.data.payload);
break;
case 'get_clips': {
if (!this.postToParent) return;
const clips = this.clips.map((c) => ({
name: c.name,
loop: true, // Assume baked-in clips loop by default
source: 'glb',
}));
this.postToParent({ __agent: true, type: 'clips', clips });
break;
}
case 'clips':
// This is one-way for now; the embed doesn't need to receive clips.
break;
default:
log.warn(`[a-embed] unhandled op: ${e.data.op}`);
}
}
async onGesture(payload) {
if (!payload || !payload.name) return;
const { name, loop } = payload;
// If the name looks like an API clip id (uuid or user:<id> prefix), load it
// from the API before trying the manifest. This lets embeds trigger user
// animations by id through the same postMessage channel as built-ins.
let ready = await this.animationManager.ensureLoaded(name);
if (!ready && (name.startsWith('user:') || /^[0-9a-f-]{36}$/i.test(name))) {
try {
const clipId = name.startsWith('user:') ? name.slice(5) : name;
await this.playAnimationById(clipId);
return;
} catch {
/* fall through — clip not found or private */
}
}
if (!ready) return;
const action = this.animationManager.actions.get(name);
if (action) {
action.setLoop(loop ? LoopRepeat : LoopOnce);
if (!loop) action.clampWhenFinished = true;
}
this.animationManager.play(name);
}
// Per-agent scene preferences (background, environment, exposure, etc.)
// persisted to localStorage. Call attachScenePrefs(agentId) once per
// session — it restores the saved values into state and starts auto-saving
// future tweaks.
attachScenePrefs(agentId) {
if (!agentId || typeof window === 'undefined') return;
this._prefsKey = `3dagent:scene:${agentId}`;
try {
const raw = localStorage.getItem(this._prefsKey);
if (raw) {
const saved = JSON.parse(raw);
const KEYS = [
'background',
'transparentBg',
'bgColor',
'autoRotate',
'exposure',
'environment',
'cinematicPreset',
];
let touched = false;
for (const key of KEYS) {
if (saved[key] !== undefined && saved[key] !== this.state[key]) {
this.state[key] = saved[key];
touched = true;
}
}
if (touched) {
this.backgroundColor.set(this.state.bgColor);
this.updateLights();
this.updateEnvironment();
this.updateDisplay();
this.updateBackground();
this._cinematic?.applyPreset(this.state.cinematicPreset);
this.updateGUI?.();
}
}
} catch {
/* ignore corrupt prefs */
}
const save = () => {
if (!this._prefsKey) return;
try {
const snapshot = {
background: this.state.background,
transparentBg: this.state.transparentBg,
bgColor: this.state.bgColor,
autoRotate: this.state.autoRotate,
exposure: this.state.exposure,
environment: this.state.environment,
cinematicPreset: this.state.cinematicPreset,
};
localStorage.setItem(this._prefsKey, JSON.stringify(snapshot));
} catch {
/* quota or disabled storage */
}
};
// Debounce to avoid hammering localStorage while users drag a slider.
let timer = null;
this._scenePrefsSave = () => {
if (timer) clearTimeout(timer);
timer = setTimeout(save, 250);
};
}
// Public hook — controllers (dat.gui, drawer UI) call this after a state
// change so we persist the latest value.
notifyScenePrefChange() {
if (this._scenePrefsSave) this._scenePrefsSave();
}
// Spacebar handler: pause/resume the active animation, or play the first
// available one if nothing is currently selected.
toggleAnimationPlayback() {
const a = this.animationManager;
if (!a) return;
if (a.currentAction) {
a.currentAction.paused = !a.currentAction.paused;
this.invalidate();
this._recomputeAnimating();
this._updateRenderLoop();
return;
}
const defs = a.getAnimationDefs?.() || [];
const first = defs.find((d) => a.isLoaded?.(d.name));
if (first) {
a.play(first.name);
this.invalidate();
this._recomputeAnimating();
this._updateRenderLoop();
}
}
// Frame the loaded model with a flattering 3/4 angle. Optionally animates
// the camera over a short duration ("F" key snaps; double-click animates).
frameContent({ animate = false, durationMs = 600 } = {}) {
if (!this.content || !this.defaultCamera || !this.controls) return;
const box = new Box3().setFromObject(this.content);
const bbSize = box.getSize(new Vector3());
const size = bbSize.length();
if (!isFinite(size) || size === 0) return;
const bbCenter = box.getCenter(new Vector3());
const vFovRad = this.defaultCamera.fov * (Math.PI / 180);
const aspect = Math.max(this.defaultCamera.aspect, 0.01);
const hFovRad = 2 * Math.atan(Math.tan(vFovRad / 2) * aspect);
const panelFrac = this._panelFrac();
const usableFrac = Math.max(1 - panelFrac, 0.55);
// Padding around the model. 1.25 leaves ~12.5% margin per side so the
// avatar isn't clipped at idle and stays mostly visible during animations
// with root motion (Death, Jump, etc).
const PAD_V = 1.25;
const PAD_H = 1.15;
// `portrait` framing crops to head-to-mid-thigh so the avatar fills the
// frame in a wide/short card; `full` is unchanged (baseY == bbCenter.y).
const framingMode = this.options?.framing === 'portrait' ? 'portrait' : 'full';
const { visH, baseY } = computeFramingExtent(bbSize.y, box.max.y, framingMode);
// Sit the camera in front of the avatar's face, whichever way its rig
// was authored; yaw 0 (no readable rig) keeps the historical +Z seat.
const yaw = estimateFacingYaw(this.content, bbSize.y) ?? 0;
const forward = forwardFromYaw(yaw);
const extentV = (visH / 2) * PAD_V / usableFrac;
const distV = extentV / Math.tan(vFovRad / 2);
const framingWidth = computeFramingWidth(horizontalExtentAt(bbSize.x, bbSize.z, yaw), bbSize.y, framingMode);
const distH = (framingWidth / 2) * PAD_H / Math.tan(hFovRad / 2);
const dist = Math.max(distV, distH);
// Center look-at on the usable area: with no panel focusY = baseY;
// with a bottom panel, shift down so the avatar rises into the upper area.
const focusY = baseY - extentV * panelFrac;
const target = new Vector3(bbCenter.x, focusY, bbCenter.z);
const pos = new Vector3(
bbCenter.x + forward.x * dist,
focusY,
bbCenter.z + forward.z * dist,
);
if (animate) {
this._tweenCamera(pos, target, durationMs);
} else {
this.defaultCamera.position.copy(pos);
this.controls.target.copy(target);
this.controls.update();
this.invalidate();
}
}
/**
* Switch the framing mode ('full' | 'portrait') at runtime and re-frame.
* Used by the <agent-3d> `framing` attribute so an embed can opt into the
* head-to-mid-thigh crop without reloading the model.
* @param {'full'|'portrait'} mode
*/
setFraming(mode) {
const next = mode === 'portrait' ? 'portrait' : 'full';
if (!this.options) this.options = {};
if (this.options.framing === next) return;
this.options.framing = next;
if (this.content) this.frameContent({ animate: true });
}
/** Fraction of canvas height occupied by the animation panel (0 when no panel). */
_panelFrac() {
if (!this._animPanelEl) return 0;
const ph = this._animPanelEl.offsetHeight;
const pb = parseFloat(getComputedStyle(this._animPanelEl).bottom) || 0;
const ch = this.renderer.domElement.clientHeight;
if (!ch) return 0;
return Math.min((ph + pb) / ch, 0.45);
}
// Smooth ease-out camera tween. Both position and OrbitControls.target
// are interpolated together so the framing stays correct mid-flight.
_tweenCamera(toPos, toTarget, durationMs = 600) {
if (this._cameraTweenRaf) cancelAnimationFrame(this._cameraTweenRaf);
const fromPos = this.defaultCamera.position.clone();
const fromTarget = this.controls.target.clone();
const start = performance.now();
const ease = (t) => 1 - Math.pow(1 - t, 3); // cubic ease-out
const step = (now) => {
const t = Math.min(1, (now - start) / durationMs);
const k = ease(t);
this.defaultCamera.position.lerpVectors(fromPos, toPos, k);
this.controls.target.lerpVectors(fromTarget, toTarget, k);
this.controls.update();
this.invalidate();
if (t < 1 && !this._disposed) {
this._cameraTweenRaf = requestAnimationFrame(step);
} else {
this._cameraTweenRaf = null;
}
};
this._cameraTweenRaf = requestAnimationFrame(step);
}
_recomputeAnimating() {
let animating = false;
if (this.state && this.state.autoRotate) animating = true;
if (!animating && this.mixer && this.state) {
for (const key in this.state.actionStates) {
if (this.state.actionStates[key]) {
animating = true;
break;
}
}
}
// External animation manager also drives the render loop
if (!animating && this.animationManager.currentAction) {
animating = true;
}
this._animating = animating;
}
_updateRenderLoop() {
if (this._disposed) return;
const canRun = this._visible && this._tabVisible;
const shouldRun = canRun && (this._needsRender || this._animating);
if (shouldRun && this._rafId === null) {
this.prevTime = performance.now();
this._rafId = requestAnimationFrame(this.animate);
} else if (!canRun && this._rafId !== null) {
cancelAnimationFrame(this._rafId);
this._rafId = null;
}
}
animate(time) {
const dt = (time - this.prevTime) / 1000;
this.prevTime = time;
this._recomputeAnimating();
this.controls.update();
this.stats.update();
if (this.mixer) this.mixer.update(dt);
this.animationManager.update(dt);
if (this._lightProbeGrid) this._lightProbeGrid.update(this.activeCamera.position);
// Extension point for the AgentAvatar empathy tick and any other per-frame hooks
if (this._afterAnimateHooks) {
for (let i = 0; i < this._afterAnimateHooks.length; i++) {
this._afterAnimateHooks[i](dt);
}
}
this.render(dt);
this._needsRender = false;
if (this._animating && this._visible && this._tabVisible && !this._disposed) {
this._rafId = requestAnimationFrame(this.animate);
} else {
this._rafId = null;
}
}
isInputFocused() {
const el = document.activeElement;
return el && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable);
}
getHeadScreenPosition() {
if (!this.content || !this.activeCamera || !this.renderer) return null;
let headBone = null, neckBone = null;
this.content.traverse((obj) => {
if (!obj.isBone) return;
const canon = obj.name.replace(/^mixamorig/i, '').replace(/^.*[:_]/, '').toLowerCase();
if (!headBone && canon === 'head') headBone = obj;
else if (!neckBone && canon === 'neck') neckBone = obj;
});
const bone = headBone || neckBone;
if (!bone) return null;
const pos = new Vector3();
bone.getWorldPosition(pos);
pos.project(this.activeCamera);
const canvas = this.renderer.domElement;
return {
x: (pos.x * 0.5 + 0.5) * canvas.clientWidth,
y: (-pos.y * 0.5 + 0.5) * canvas.clientHeight,
};
}
/**
* Project a world-space point to CSS pixels on the canvas, for hotspot
* placement. `behindCamera` is true once the point is behind the near
* plane (NDC z > 1), the one case translate(x,y) alone renders wrong
* (a point behind the camera projects to a flipped position in front).
*/
projectToScreen(worldPos) {
if (!this.activeCamera || !this.renderer) return null;
const pos = worldPos.clone().project(this.activeCamera);
const canvas = this.renderer.domElement;
return {
x: (pos.x * 0.5 + 0.5) * canvas.clientWidth,
y: (-pos.y * 0.5 + 0.5) * canvas.clientHeight,
behindCamera: pos.z > 1,
};
}
render(deltaTime = 0) {
// Additive bloom bleeds bright highlights into neighbouring pixels —
// including the alpha-0 background. Over a transparent canvas that halo
// composites onto the host page as a washed-out "box" around the avatar
// (very visible on light backgrounds). For transparent embeds we skip the
// bloom/vignette pass and render the scene straight to the canvas so it
// composites cleanly; opaque/studio backgrounds keep the cinematic pass.
if (this.state.transparentBg) {
this.renderer.render(this.scene, this.activeCamera);
} else {
this._cinematic.render(deltaTime);
}
if (this.state.grid) {
this._ensureAxesRenderer();
this.axesCamera.position.copy(this.defaultCamera.position);
this.axesCamera.lookAt(this.axesScene.position);
this.axesRenderer.render(this.axesScene, this.axesCamera);
}
this.projectAnnotations();
}
showPumpFunTrades() {
// Re-entrant guard: a second call while a shower is live would orphan the
// first's geometry/material/texture and stack animate hooks.
if (this._pumpFunFx || this._disposed) return;
const particleCount = 1000;
const particles = new BufferGeometry();
const positions = new Float32Array(particleCount * 3);
const coinTexture = makeCoinTexture();
for (let i = 0; i < particleCount; i++) {
positions[i * 3] = (Math.random() * 2 - 1) * 10;
positions[i * 3 + 1] = Math.random() * 20;
positions[i * 3 + 2] = (Math.random() * 2 - 1) * 10;
}
particles.setAttribute('position', new BufferAttribute(positions, 3));
const particleMaterial = new PointsMaterial({
map: coinTexture,
size: 0.5,
transparent: true,
alphaTest: 0.5,
});
const particleSystem = new Points(particles, particleMaterial);
this.scene.add(particleSystem);
const animateParticles = () => {
const pos = particleSystem.geometry.attributes.position.array;
for (let i = 0; i < particleCount; i++) {
pos[i * 3 + 1] -= 0.1;
if (pos[i * 3 + 1] < -10) {
pos[i * 3 + 1] = 20;
}
}
particleSystem.geometry.attributes.position.needsUpdate = true;
this.invalidate();
};
if (!this._afterAnimateHooks) {
this._afterAnimateHooks = [];
}
this._afterAnimateHooks.push(animateParticles);
this._pumpFunFx = { particleSystem, particles, particleMaterial, coinTexture, animateParticles };
this._pumpFunTimer = setTimeout(() => this._clearPumpFunTrades(), 10000);
}
// Tear down the pump.fun coin shower: detach the animate hook, remove from the
// scene, and dispose every GPU resource it allocated. Idempotent.
_clearPumpFunTrades() {
if (this._pumpFunTimer) {
clearTimeout(this._pumpFunTimer);
this._pumpFunTimer = null;
}
const fx = this._pumpFunFx;
if (!fx) return;
this._pumpFunFx = null;
if (this._afterAnimateHooks) {
const index = this._afterAnimateHooks.indexOf(fx.animateParticles);
if (index > -1) this._afterAnimateHooks.splice(index, 1);
}
this.scene.remove(fx.particleSystem);
fx.particles.dispose();
fx.particleMaterial.dispose();
fx.coinTexture.dispose();
this.invalidate();
}
takeScreenshot() {
takeScreenshot(this);
}
captureScreenshot() {
return captureScreenshot(this);
}
async bakeLightProbes() {
if (!this.content) {
log.warn('LightProbeGrid: load a model first');
return;
}
if (this._lightProbeGrid) {
this._lightProbeGrid.removeFromScene(this.scene);
this._lightProbeGrid.dispose();
}
const bounds = new Box3().setFromObject(this.content);
// Expand slightly so probes sit inside the volume, not on surface.
bounds.expandByScalar(0.5);
const { probeNx, probeNy, probeNz, probeCubeFace } = this.state;
const grid = new LightProbeGrid(probeNx, probeNy, probeNz, bounds);
let progressEl = this.el.querySelector('.lpg-progress');
if (!progressEl) {
progressEl = document.createElement('div');
progressEl.className = 'lpg-progress';
progressEl.style.cssText =
'position:absolute;bottom:12px;left:50%;transform:translateX(-50%);' +
'background:rgba(0,0,0,.7);color:#fff;font:12px/1.5 monospace;' +
'padding:6px 12px;border-radius:4px;pointer-events:none;z-index:100';
this.el.appendChild(progressEl);
}
progressEl.textContent = 'Baking probes… 0%';
progressEl.style.display = 'block';
try {
await grid.bake(this.renderer, this.scene, probeCubeFace, (t) => {
progressEl.textContent = `Baking probes… ${Math.round(t * 100)}%`;
});
} catch (err) {
log.error('LightProbeGrid bake failed:', err);
return;
} finally {
progressEl.style.display = 'none';
}
this._lightProbeGrid = grid;
grid.addToScene(this.scene);
log.log(`LightProbeGrid baked: ${probeNx}×${probeNy}×${probeNz} cells`);
}
saveLightProbes() {
if (!this._lightProbeGrid) {
log.warn('LightProbeGrid: bake or load a grid first');
return;
}
const json = JSON.stringify(this._lightProbeGrid.toJSON());
const blob = new Blob([json], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'light-probe-grid.json';
a.click();
URL.revokeObjectURL(url);
}
loadLightProbes() {
const input = document.createElement('input');
input.type = 'file';
input.accept = '.json,application/json';
input.onchange = async (e) => {
const file = e.target.files[0];
if (!file) return;
const text = await file.text();
let json;
try {
json = JSON.parse(text);
} catch {
log.error('LightProbeGrid: invalid JSON file');
return;
}
if (this._lightProbeGrid) {
this._lightProbeGrid.removeFromScene(this.scene);
this._lightProbeGrid.dispose();
}
this._lightProbeGrid = LightProbeGrid.fromJSON(json);
this._lightProbeGrid.addToScene(this.scene);
log.log(`LightProbeGrid loaded: ${json.nx}×${json.ny}×${json.nz} cells`);
};
input.click();
}
/**
* Update the AR button visibility and target URLs after a model loads.
* @param {string|null} glbUrl — absolute or relative URL to the GLB (for Android/WebXR)
* @param {string|null} usdzUrl — absolute or relative URL to a USDZ (for iOS Quick Look)
* @param {{modes?: string[], placement?: 'floor'|'wall'}} [opts]
* `modes` allow-lists which AR launch paths may be used (mirrors
* `<model-viewer>`'s `ar-modes` tokens: "webxr", "scene-viewer",
* "quick-look"); omitted or empty means all three. `placement` only
* reaches Scene Viewer today (WebXR hit-testing here is floor-only).
*/
async setARTarget(glbUrl, usdzUrl = null, { modes, placement } = {}) {
this._arGlbUrl = glbUrl;
this._arUsdzUrl = usdzUrl;
this._arModes = modes && modes.length ? modes : ['webxr', 'scene-viewer', 'quick-look'];
this._arPlacement = placement === 'wall' ? 'wall' : 'floor';
if (!this._arBtn) return;
const hasGlb = !!glbUrl;
const hasUsdz = !!usdzUrl;
const iosOk = hasUsdz && this._arModes.includes('quick-look') && canUseQuickLook();
const androidOk = hasGlb && this._arModes.includes('scene-viewer') && canUseSceneViewer();
const webxrOk =
hasGlb && this._arModes.includes('webxr') && (await WebXRSession.isSupported());
this._arBtn.hidden = !(iosOk || androidOk || webxrOk);
}
/** True once `setARTarget()` has found at least one usable AR launch path on this device. */
get canActivateAR() {
return !!this._arBtn && !this._arBtn.hidden;
}
/**
* Launch AR on whichever path this device and the `ar-modes` allow-list
* both support: on-device USDZ via iOS Quick Look, a Scene Viewer intent
* on Android, or a WebXR immersive-ar session otherwise. A second call
* while a WebXR session is live ends it instead (the button doubles as
* an exit control). Returns whether a launch path ran.
*/
async activateAR() {
const modes = this._arModes || ['webxr', 'scene-viewer', 'quick-look'];
if (modes.includes('quick-look') && canUseQuickLook() && this._arUsdzUrl) {
openQuickLook(this._arUsdzUrl);
return true;
} else if (modes.includes('scene-viewer') && canUseSceneViewer() && this._arGlbUrl) {
openSceneViewer(this._arGlbUrl, { placement: this._arPlacement });
return true;
} else if (modes.includes('webxr') && this._arGlbUrl) {
// Desktop/Android WebXR
if (this._xrSession) {
await this._xrSession.end();
this._xrSession = null;
this._arBtn.classList.remove('ar-btn--active');
return true;
}
this._xrSession = new WebXRSession(this, {
onEnd: () => {
this._xrSession = null;
this._arBtn.classList.remove('ar-btn--active');
},
});
await this._xrSession.start();
this._arBtn.classList.add('ar-btn--active');
return true;
}
return false;
}
/**
* Tween the camera to a saved orbit, used by hotspot click-to-fly-to-view.
* @param {number} thetaDeg azimuthal angle in degrees
* @param {number} phiDeg polar angle in degrees (0 = straight down +Y)
* @param {number} radius distance from `target`
* @param {Vector3} [target]
*/
setCameraOrbit(thetaDeg, phiDeg, radius, target = new Vector3(0, 0, 0)) {
if (!this.controls || !this.activeCamera) return false;
const theta = (thetaDeg * Math.PI) / 180;
const phi = (phiDeg * Math.PI) / 180;
const offset = new Vector3().setFromSphericalCoords(radius, phi, theta);
this._tweenCamera(target.clone().add(offset), target.clone(), 700);
return true;
}
resize() {
const { clientHeight, clientWidth } = this.el;
if (clientWidth === 0 || clientHeight === 0) return;
const prevAspect = this.defaultCamera.aspect;
const nextAspect = clientWidth / clientHeight;
this.defaultCamera.aspect = nextAspect;
this.defaultCamera.updateProjectionMatrix();
this.renderer.setSize(clientWidth, clientHeight);
this._composer?.setSize(clientWidth, clientHeight);
this.axesCamera.aspect = this.axesDiv.clientWidth / this.axesDiv.clientHeight;
this.axesCamera.updateProjectionMatrix();
this.axesRenderer?.setSize(this.axesDiv.clientWidth, this.axesDiv.clientHeight);
// Re-frame so the full avatar stays visible after the canvas changes
// shape — the initial framing uses the aspect at load time, which is
// often stale (e.g. before ResizeObserver kicks in on first paint).
if (this.content && Math.abs(nextAspect - prevAspect) > 0.001) {
this.frameContent();
}
this.invalidate();
}
load(url, rootPath, assetMap, onProgress) {
const baseURL = LoaderUtils.extractUrlBase(url);
// Remember the source URL so the animation manager's fallen-pose guard can
// report which avatar produced a broken retarget (passed to attach below).
this._sourceUrl = url;
// Load.
return new Promise((resolve, reject) => {
// Intercept and override relative URLs.
MANAGER.setURLModifier((url, path) => {
// Repair retired IPFS gateway hosts (cf-ipfs.com /
// cloudflare-ipfs.com) and resolve ipfs://, ar:// schemes.
let finalUrl = normalizeGatewayURL(url);
if (isDecentralizedURI(finalUrl)) {
return resolveURI(finalUrl);
}
// URIs in a glTF file may be escaped, or not. Assume that assetMap is
// from an un-escaped source, and decode all URIs before lookups.
// See: https://github.com/nirholas/three.ws/issues/146
const normalizedURL =
rootPath +
decodeURI(finalUrl)
.replace(baseURL, '')
.replace(/^(\.?\/)/, '');
if (assetMap.has(normalizedURL)) {
const blob = assetMap.get(normalizedURL);
const blobURL = URL.createObjectURL(blob);
blobURLs.push(blobURL);
return blobURL;
}
return (path || '') + finalUrl;
});
const blobURLs = [];
getDecoders().then(({ dracoLoader, ktx2Loader, meshoptDecoder }) => {
const loader = new GLTFLoader(MANAGER)
.setCrossOrigin('anonymous')
.setDRACOLoader(dracoLoader)
.setKTX2Loader(ktx2Loader.detectSupport(this.renderer))
.setMeshoptDecoder(meshoptDecoder);
installVrmPlugin(loader);
loader.load(
url,
(gltf) => {
if (window.VIEWER) window.VIEWER.json = gltf;
prepareVrmModel(gltf);
const scene = gltf.scene || gltf.scenes[0];
const clips = gltf.animations || [];
if (!scene) {
// Valid, but not supported by this viewer.
throw new Error(
'This model contains no scene, and cannot be viewed here. However,' +
' it may contain individual 3D resources.',
);
}
this.setContent(scene, clips);
blobURLs.forEach(URL.revokeObjectURL);
// See: https://github.com/google/draco/issues/349
// DRACOLoader.releaseDecoderModule();
resolve(gltf);
},
// XHR progress events while the GLB streams down. The `total`
// field is only populated when the server sends a
// Content-Length header — R2 does, our blob URLs do not.
typeof onProgress === 'function'
? (xhr) => {
try {
onProgress(xhr);
} catch (e) {
log.warn('[viewer] onProgress threw', e);
}
}
: undefined,
reject,
);
}, reject);
});
}
/**
* @param {THREE.Object3D} object
* @param {Array<THREE.AnimationClip} clips
*/
// Soft ground contact shadow: a ShadowMaterial plane just under the
// recentered model (feet sit at -bbSize.y/2 after setContent recentering).
// Created once, then resized/repositioned per load; invisible except where
// the shadow_light's shadow falls, so it composes with any bgColor.
_updateShadowCatcher(bbSize) {
if (this._lowPower) return;
if (!isFinite(bbSize.x) || !isFinite(bbSize.y) || !isFinite(bbSize.z)) return;
if (!this.shadowCatcher) {
this.shadowCatcher = new Mesh(
new PlaneGeometry(1, 1),
new ShadowMaterial({ opacity: 0.25, depthWrite: false }),
);
this.shadowCatcher.rotation.x = -Math.PI / 2;
this.shadowCatcher.receiveShadow = true;
this.shadowCatcher.name = 'shadow_catcher';
this.scene.add(this.shadowCatcher);
}
const span = Math.max(bbSize.x, bbSize.z, 0.5) * 3;
this.shadowCatcher.scale.set(span, span, 1);
this.shadowCatcher.position.y = -bbSize.y / 2 + 0.002;
// Fit the caster's frustum to the model so shadow texels aren't wasted
// on a prop or clipped on an oversized scene.
const sun = this.lights.find((l) => l.name === 'shadow_light');
if (sun) {
const r = Math.max(bbSize.x, bbSize.y, bbSize.z, 0.5) * 1.2;
sun.position.set(r * 0.4, r * 1.6, r * 0.7); // keep the overhead angle at any scale
const cam = sun.shadow.camera;
cam.left = -r;
cam.right = r;
cam.top = r;
cam.bottom = -r;
cam.near = 0.1;
cam.far = r * 4;
cam.updateProjectionMatrix();
}
}
setContent(object, clips) {
this.clear();
object.updateMatrixWorld(); // nirholas/3d-agent#330
const box = new Box3().setFromObject(object);
const size = box.getSize(new Vector3()).length();
const center = box.getCenter(new Vector3());
this.controls.reset();
// Guard: empty bounding box (no geometry / all-invisible meshes) yields
// Infinity center → NaN after subtraction, which corrupts world matrices
// and causes AudioParam "non-finite" throws in PositionalAudio.updateMatrixWorld.
if (isFinite(center.x) && isFinite(center.y) && isFinite(center.z)) {
object.position.x -= center.x;
object.position.y -= center.y;
object.position.z -= center.z;
}
this.controls.maxDistance = isFinite(size) && size > 0 ? size * 10 : 10;
this.defaultCamera.near = isFinite(size) && size > 0 ? size / 100 : 0.01;
this.defaultCamera.far = isFinite(size) && size > 0 ? size * 100 : 1000;
this.defaultCamera.updateProjectionMatrix();
// Add content and build the animation panel BEFORE computing the camera
// so the panel's rendered height is available for panel-aware framing.
this.scene.add(object);
// Avatars are authored with +Z as their forward axis (see
// _trackBodyToCamera in agent-avatar.js, which faces them via
// atan2(dx, dz)). The framing camera sits on +Z looking at origin,
// so a zero yaw already presents the front. Do NOT flip 180° here —
// that turns every static preview (dashboard card, kiosk embed)
// around to show the avatar's back.
object.rotation.y = 0;
this.content = object;
// Build BVH acceleration structures for every mesh geometry so raycasting
// (hover / click interactions) is O(log n) instead of O(n) on triangle count.
object.traverse((node) => {
if (node.isMesh && node.geometry) {
node.geometry.computeBoundsTree();
node.castShadow = true;
}
});
// Skin/eye/hair realism pass — name-matched, so props and non-humanoid
// meshes are never touched. See src/shared/avatar-material-realism.js.
if (looksLikeAvatarMesh(object)) {
applyAvatarMaterialRealism(object);
}
this.state.punctualLights = true;
this.content.traverse((node) => {
if (node.isLight) {
this.state.punctualLights = false;
}
});
this.setClips(clips);
this.animationManager.attach(this.content, { avatarUrl: this._sourceUrl || '' });
this._setupAnimationPanel();
// _panelFrac() reads offsetHeight after _setupAnimationPanel has
// populated the panel DOM, which forces a synchronous reflow.
const panelFrac = this._panelFrac();
const usableFrac = Math.max(1 - panelFrac, 0.55);
// Compute camera distance so the full avatar fits in the usable viewport
// area (above the animation panel) with breathing room above/below.
const bbSize = box.getSize(new Vector3());
const vFovRad = this.defaultCamera.fov * (Math.PI / 180);
const aspect = Math.max(this.defaultCamera.aspect, 0.01);
const hFovRad = 2 * Math.atan(Math.tan(vFovRad / 2) * aspect);
// Same padding as frameContent() — keep both code paths in sync.
const PAD_V = 1.25;
const PAD_H = 1.15;
// Model has been recentered so the body spans [-bbSize.y/2, +bbSize.y/2]
// and the crown is at +bbSize.y/2. `portrait` crops to head-to-mid-thigh;
// `full` reduces to the original full-body framing (baseY == 0).
const framingMode = this.options?.framing === 'portrait' ? 'portrait' : 'full';
const { visH, baseY } = computeFramingExtent(bbSize.y, bbSize.y / 2, framingMode);
// Same front-on seat as frameContent(): read the rig's facing rather
// than assuming the avatar was authored looking down +Z.
const yaw = estimateFacingYaw(this.content, bbSize.y) ?? 0;
const forward = forwardFromYaw(yaw);
const extentV = (visH / 2) * PAD_V / usableFrac;
const distV = extentV / Math.tan(vFovRad / 2);
const framingWidth = computeFramingWidth(horizontalExtentAt(bbSize.x, bbSize.z, yaw), bbSize.y, framingMode);
const distH = (framingWidth / 2) * PAD_H / Math.tan(hFovRad / 2);
const dist = Math.max(distV, distH);
// Center the look-at on the usable area: with no panel focusY=baseY;
// with a bottom panel shift down so the avatar rises into the usable
// upper portion of the canvas.
const focusY = baseY - extentV * panelFrac;
// Final framed camera (the position the user should end up at).
// Avatar sits dead-centered front-on by default: no lateral offset, and
// the seat rotates with the rig's facing so "front" means the face.
const framedPos = new Vector3();
if (this.options.cameraPosition) {
framedPos.fromArray(this.options.cameraPosition);
} else {
framedPos.set(forward.x * dist, focusY, forward.z * dist);
}
const orbitalTarget = new Vector3(0, focusY, 0);
// In kiosk / embed modes (and on subsequent loads), snap straight to
// the framed position. On the first interactive load we tween in from
// a slightly wider angle so the reveal feels intentional.
const skipReveal =
this.options.kiosk || this.options.cameraPosition || this._hasRevealed === true;
if (skipReveal) {
this.defaultCamera.position.copy(framedPos);
this.defaultCamera.lookAt(orbitalTarget);
} else {
// Start ~40% wider and slightly higher, then ease into the framed pose.
const startPos = new Vector3()
.subVectors(framedPos, orbitalTarget)
.multiplyScalar(1.4)
.add(orbitalTarget);
startPos.y += size / 8;
this.defaultCamera.position.copy(startPos);
this.defaultCamera.lookAt(orbitalTarget);
this._pendingReveal = { framedPos: framedPos.clone(), target: orbitalTarget.clone() };
this._hasRevealed = true;
}
this.setCamera(DEFAULT_CAMERA);
this.axesCamera.position.copy(this.defaultCamera.position);
this.axesCamera.lookAt(this.axesScene.position);
this.axesCamera.near = size / 100;
this.axesCamera.far = size * 100;
this.axesCamera.updateProjectionMatrix();
this.axesCorner.scale.set(size, size, size);
this.controls.target.copy(orbitalTarget);
this.controls.update();
this.controls.saveState();
this.updateLights();
this._updateShadowCatcher(bbSize); // after updateLights so shadow_light exists to fit
this.updateGUI();
this.updateEnvironment();
this.updateDisplay();
this.updateModelInfo(object, clips);
this.updateAnnotations();
if (window.VIEWER) window.VIEWER.scene = this.content;
this.controls.enabled = true;
this.invalidate();
// Smooth first-load camera reveal — runs after the scene is fully wired
// so OrbitControls and damping pick it up cleanly.
if (this._pendingReveal) {
const { framedPos, target } = this._pendingReveal;
this._pendingReveal = null;
this._tweenCamera(framedPos, target, 1500);
}
// Announce the swap so overlays can react to the new rig (e.g. re-filter
// animation suggestions against what this model can actually perform).
try {
window.dispatchEvent(new CustomEvent('viewer:model-loaded', { detail: { viewer: this } }));
} catch {}
}
setClips(clips) {
setClips(this, clips);
}
playAllClips() {
playAllClips(this);
}
/**
* @param {string} name
*/
setCamera(name) {
if (name === DEFAULT_CAMERA) {
this.controls.enabled = true;
this.activeCamera = this.defaultCamera;
} else {
this.controls.enabled = false;
this.content.traverse((node) => {
if (node.isCamera && node.name === name) {
this.activeCamera = node;
}
});
}
// Keep the post-processing passes pointed at the live camera.
if (this._cinematic) this._cinematic.setCamera(this.activeCamera);
this.invalidate();
}
updateLights() {
const state = this.state;
const lights = this.lights;
if (state.punctualLights && !lights.length) {
addLights(this);
} else if (!state.punctualLights && lights.length) {
removeLights(this);
}
this.renderer.toneMapping = Number(state.toneMapping);
this.renderer.toneMappingExposure = Math.pow(2, state.exposure);
// Image-based lighting strength (RoomEnvironment / HDRI). Supported by
// three r163+; guarded so older peers degrade to the baseline response.
if (this.scene && 'environmentIntensity' in this.scene) {
this.scene.environmentIntensity = state.environmentIntensity ?? 1.0;
}
// Keep the studio rig in sync with GUI / scene-pref edits, addressing
// each light by name so the rig can grow without re-indexing.
for (const light of lights) {
switch (light.name) {
case 'ambient_light':
light.intensity = state.ambientIntensity;
light.color.set(state.ambientColor);
break;
case 'main_light':
light.intensity = state.directIntensity;
light.color.set(state.directColor);
break;
case 'fill_light':
light.intensity = state.directIntensity * (state.fillRatio ?? 0.4);
light.color.set(state.fillColor ?? '#DCE6FF');
break;
case 'rim_light':
light.intensity = state.directIntensity * (state.rimRatio ?? 0.65);
light.color.set(state.rimColor ?? '#FFFFFF');
break;
default:
break;
}
}
this.invalidate();
}
updateEnvironment() {
const environment = environments.filter(
(entry) => entry.name === this.state.environment,
)[0];
getCubeMapTexture(this, environment)
.then(({ envMap }) => {
if (this._disposed || !this.scene) return;
this.scene.environment = envMap;
this.scene.background = this.state.transparentBg
? null
: this.state.background
? envMap
: this.backgroundColor;
this.invalidate();
})
.catch((err) => {
// EXR HDRIs are fetched from an external CDN; a network drop or a
// blocked request (Safari surfaces these as "Load failed") must not
// escape as an unhandled rejection. The scene keeps its current
// environment — IBL is a visual nicety, never load-blocking.
log.warn('[viewer] environment HDRI load failed', err?.message || err);
});
}
/**
* Public env preset switcher used by the widget config pipeline + JSON-RPC
* `viewer.setEnvironment`. Accepts an environment id (e.g. `neutral`,
* `venice-sunset`) or a display name. Internally we store the name on
* `state.environment` because the GUI dropdown binds to it.
*/
setEnvironment(preset) {
const key = String(preset || '').trim();
if (!key) return;
const entry =
environments.find((e) => e.id === key) ||
environments.find((e) => e.name === key) ||
environments.find((e) => e.name.toLowerCase() === key.toLowerCase());
if (!entry) return;
this.state.environment = entry.name;
this.updateEnvironment();
}
updateDisplay() {
if (this.skeletonHelpers.length) {
this.skeletonHelpers.forEach((helper) => this.scene.remove(helper));
}
// May run before any model has loaded (e.g. idle-avatar configures the
// viewer up front, then loads the GLB). The material/skeleton passes need
// content; the grid/auto-rotate state below does not, so skip just these.
if (this.content) {
traverseMaterials(this.content, (material) => {
material.wireframe = this.state.wireframe;
if (material instanceof PointsMaterial) {
material.size = this.state.pointSize;
}
});
this.content.traverse((node) => {
if (node.geometry && node.skeleton && this.state.skeleton) {
const helper = new SkeletonHelper(node.skeleton.bones[0].parent);
helper.material.linewidth = 3;
this.scene.add(helper);
this.skeletonHelpers.push(helper);
}
});
}
if (this.state.grid !== Boolean(this.gridHelper)) {
if (this.state.grid) {
this._ensureAxesRenderer();
this.gridHelper = new GridHelper();
this.axesHelper = new AxesHelper();
this.axesHelper.renderOrder = 999;
this.axesHelper.onBeforeRender = (renderer) => renderer.clearDepth();
this.scene.add(this.gridHelper);
this.scene.add(this.axesHelper);
} else {
this.scene.remove(this.gridHelper);
this.scene.remove(this.axesHelper);
this.gridHelper = null;
this.axesHelper = null;
this.axesRenderer?.clear();
}
}
this.controls.autoRotate = this.state.autoRotate;
this.invalidate();
}
updateBackground() {
this.backgroundColor.set(this.state.bgColor);
if (this.state.transparentBg) {
this.scene.background = null;
this.renderer.setClearColor(0x000000, 0);
} else {
this.scene.background = this.backgroundColor;
this.renderer.setClearColor(0x000000, 1);
}
// Always apply IBL — updateEnvironment() sets scene.background to null for
// transparent mode so the canvas stays clear while still lighting materials.
this.updateEnvironment();
this.invalidate();
}
/**
* Public setter for the scene background color. Used by the widget runtime
* + Studio postMessage bridge to apply brand config without touching dat.gui.
* @param {string|number} color CSS color string or hex int.
*/
setBackgroundColor(color) {
this.state.bgColor =
typeof color === 'string' ? color : '#' + color.toString(16).padStart(6, '0');
this.state.transparentBg = false;
this.updateBackground();
}
/**
* Adds AxesHelper.
*
* See: https://stackoverflow.com/q/16226693/1314762
*/
updateModelInfo(object, clips) {
if (this.modelInfo) {
this.modelInfo.remove();
this.modelInfo = null;
}
if (this.state.showInfo && object) {
this.modelInfo = createModelInfo(this.el, object, clips);
}
}
updateAnnotations() {
// Clear existing
this.annotationEls.forEach((a) => a.el.remove());
this.annotationEls = [];
if (!this.state.showLabels || !this.content) return;
const annotations = buildAnnotations(this.content);
annotations.forEach((ann) => {
const canvas = renderAnnotationCanvas(ann);
const el = document.createElement('div');
el.classList.add('annotation-label');
el.appendChild(canvas);
this.el.appendChild(el);
this.annotationEls.push({ el, position: ann.position });
});
this.invalidate();
}
projectAnnotations() {
if (this.annotationEls.length === 0) return;
const width = this.el.clientWidth;
const height = this.el.clientHeight;
const halfW = width / 2;
const halfH = height / 2;
const tempVec = this._tempVec;
this.annotationEls.forEach(({ el, position }) => {
tempVec.copy(position);
tempVec.project(this.activeCamera);
// Behind camera check
if (tempVec.z > 1) {
el.style.display = 'none';
return;
}
const x = tempVec.x * halfW + halfW;
const y = -(tempVec.y * halfH) + halfH;
el.style.display = '';
el.style.left = x + 'px';
el.style.top = y + 'px';
});
}
addAxesHelper() {
this.axesDiv = document.createElement('div');
this.el.appendChild(this.axesDiv);
this.axesDiv.classList.add('axes');
const { clientWidth, clientHeight } = this.axesDiv;
this.axesScene = new Scene();
this.axesCamera = new PerspectiveCamera(50, clientWidth / clientHeight, 0.1, 10);
this.axesScene.add(this.axesCamera);
// The axes gizmo is a debug helper, shown only when the "grid" display
// toggle is on (off by default, and the GUI is closed entirely in kiosk/
// embed mode). Its WebGLRenderer is a whole second GL context, so we
// create it lazily — otherwise every <agent-3d> on a page would burn two
// contexts and exhaust the browser's ~16-context budget twice as fast.
this.axesRenderer = null;
this.axesCamera.up = this.defaultCamera.up;
this.axesCorner = new AxesHelper(5);
this.axesScene.add(this.axesCorner);
}
_ensureAxesRenderer() {
if (this.axesRenderer || !this.axesDiv) return this.axesRenderer;
this.axesRenderer = new WebGLRenderer({ alpha: true });
// Match the main renderer's DPR cap — the tiny axes gizmo gains nothing
// from rendering at full retina density and the extra fragments are pure
// waste on high-DPI phones.
this.axesRenderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
this.axesRenderer.setSize(this.axesDiv.clientWidth, this.axesDiv.clientHeight);
this.axesDiv.appendChild(this.axesRenderer.domElement);
return this.axesRenderer;
}
addGUI() {
const isMobile = window.innerWidth <= 700;
const gui = (this.gui = new GUI({
autoPlace: false,
width: isMobile ? 220 : 260,
hideable: true,
}));
// dat.GUI's OptionController change handler reads
// `select.options[select.selectedIndex].value` with no guard, so a `change`
// event fired while a dropdown sits at selectedIndex === -1 throws
// "Cannot read properties of undefined (reading 'value')". A user can never
// put a populated <select> in that state, but a programmatic deselect — an
// automated form fuzzer or accessibility crawler dispatching synthetic
// change events — can. Normalize the index in the capture phase, before
// dat.GUI's own bubble-phase listener runs, so the control degrades to its
// first option (or the event is dropped when there is nothing to select)
// instead of crashing the whole viewer.
gui.domElement.addEventListener(
'change',
(e) => {
const t = /** @type {HTMLSelectElement} */ (e.target);
if (t && t.tagName === 'SELECT' && t.selectedIndex < 0) {
if (t.options.length) t.selectedIndex = 0;
else e.stopImmediatePropagation();
}
},
true,
);
// Display controls.
const dispFolder = gui.addFolder('Display');
const envBackgroundCtrl = dispFolder.add(this.state, 'background');
envBackgroundCtrl.onChange(() => {
this.updateEnvironment();
this.notifyScenePrefChange();
});
const autoRotateCtrl = dispFolder.add(this.state, 'autoRotate');
autoRotateCtrl.onChange(() => {
this.updateDisplay();
this.notifyScenePrefChange();
});
const wireframeCtrl = dispFolder.add(this.state, 'wireframe');
wireframeCtrl.onChange(() => this.updateDisplay());
const skeletonCtrl = dispFolder.add(this.state, 'skeleton');
skeletonCtrl.onChange(() => this.updateDisplay());
const gridCtrl = dispFolder.add(this.state, 'grid');
gridCtrl.onChange(() => this.updateDisplay());
dispFolder.add(this.controls, 'screenSpacePanning');
const pointSizeCtrl = dispFolder.add(this.state, 'pointSize', 1, 16);
pointSizeCtrl.onChange(() => this.updateDisplay());
const transparentCtrl = dispFolder.add(this.state, 'transparentBg').name('transparent bg');
transparentCtrl.onChange(() => {
this.updateBackground();
this.notifyScenePrefChange();
});
const bgColorCtrl = dispFolder.addColor(this.state, 'bgColor');
bgColorCtrl.onChange(() => {
this.updateBackground();
this.notifyScenePrefChange();
});
dispFolder
.add({ screenshot: () => this.takeScreenshot() }, 'screenshot')
.name('Screenshot [P]');
const infoCtrl = dispFolder.add(this.state, 'showInfo').name('model info');
infoCtrl.onChange(() => this.updateModelInfo(this.content, this.clips));
const labelsCtrl = dispFolder.add(this.state, 'showLabels').name('mesh labels');
labelsCtrl.onChange(() => this.updateAnnotations());
// Lighting controls.
const lightFolder = gui.addFolder('Lighting');
const envMapCtrl = lightFolder.add(
this.state,
'environment',
environments.map((env) => env.name),
);
envMapCtrl.onChange(() => {
this.updateEnvironment();
this.notifyScenePrefChange();
});
const exposureCtrl = lightFolder.add(this.state, 'exposure', -10, 10, 0.01);
exposureCtrl.onChange(() => {
this.updateLights();
this.notifyScenePrefChange();
});
[
lightFolder.add(this.state, 'toneMapping', {
Neutral: NeutralToneMapping,
Linear: LinearToneMapping,
'ACES Filmic': ACESFilmicToneMapping,
}),
lightFolder.add(this.state, 'punctualLights').listen(),
lightFolder.add(this.state, 'environmentIntensity', 0, 3).name('IBL intensity'),
lightFolder.add(this.state, 'ambientIntensity', 0, 2),
lightFolder.addColor(this.state, 'ambientColor'),
// Slider range tracks the π-scaled default above (see #116 note).
lightFolder.add(this.state, 'directIntensity', 0, 4),
lightFolder.addColor(this.state, 'directColor'),
lightFolder.add(this.state, 'fillRatio', 0, 1).name('fill'),
lightFolder.addColor(this.state, 'fillColor'),
lightFolder.add(this.state, 'rimRatio', 0, 1.5).name('rim'),
lightFolder.addColor(this.state, 'rimColor'),
].forEach((ctrl) => ctrl.onChange(() => this.updateLights()));
// Cinematic FX — selectable post-processing looks plus live per-effect
// tuning. Preset picker rewrites every slider; sliders write straight into
// the live pipeline so the canvas updates as you drag.
const fxFolder = gui.addFolder('Cinematic FX');
const fx = this._cinematic;
const presetHolder = { preset: this.state.cinematicPreset };
const fxCtrls = [];
const syncFxCtrls = () => fxCtrls.forEach((c) => c.updateDisplay());
fxFolder
.add(presetHolder, 'preset', CINEMATIC_PRESET_NAMES)
.name('preset')
.onChange((name) => {
fx.applyPreset(name);
this.state.cinematicPreset = name;
syncFxCtrls();
this.invalidate();
this.notifyScenePrefChange();
});
// Each slider mutates fx.params[key] in place, then re-pushes the whole
// param set so the canvas updates live as you drag.
const onFxChange = () => {
fx.apply();
this.invalidate();
};
const addFx = (key, min, max, step, label) => {
const c = fxFolder.add(fx.params, key, min, max, step).name(label).onChange(onFxChange);
fxCtrls.push(c);
return c;
};
addFx('bloom', 0, 3, 0.01, 'bloom');
addFx('bloomThreshold', 0, 1, 0.01, 'bloom threshold');
addFx('vignette', 0, 1, 0.01, 'vignette');
addFx('ssao', 0, 1, 1, 'ambient occlusion');
addFx('ssaoIntensity', 0, 4, 0.05, 'AO strength');
addFx('dof', 0, 1, 1, 'depth of field');
addFx('dofFocusDistance', 0.2, 12, 0.1, 'focus distance');
addFx('dofBokeh', 0, 6, 0.1, 'bokeh');
addFx('saturation', -1, 1, 0.01, 'saturation');
addFx('contrast', -1, 1, 0.01, 'contrast');
addFx('brightness', -1, 1, 0.01, 'brightness');
addFx('hue', 0, Math.PI * 2, 0.01, 'hue shift');
addFx('chromaticAberration', 0, 0.01, 0.0001, 'chromatic ab.');
addFx('grain', 0, 0.5, 0.01, 'film grain');
fxFolder.close();
// Light Probe Grid controls.
const probeFolder = gui.addFolder('Light Probes');
probeFolder.add(this.state, 'probeNx', 1, 8, 1).name('grid X');
probeFolder.add(this.state, 'probeNy', 1, 4, 1).name('grid Y');
probeFolder.add(this.state, 'probeNz', 1, 8, 1).name('grid Z');
probeFolder.add(this.state, 'probeCubeFace', { '32px': 32, '64px': 64, '128px': 128 }).name('cube face');
probeFolder.add({ bake: () => this.bakeLightProbes() }, 'bake').name('Bake Probes');
probeFolder.add({ save: () => this.saveLightProbes() }, 'save').name('Save JSON');
probeFolder.add({ load: () => this.loadLightProbes() }, 'load').name('Load JSON');
// Animation controls.
this.animFolder = gui.addFolder('Animation');
this.animFolder.domElement.style.display = 'none';
const playbackSpeedCtrl = this.animFolder.add(this.state, 'playbackSpeed', 0, 1);
playbackSpeedCtrl.onChange((speed) => {
if (this.mixer) this.mixer.timeScale = speed;
});
this.animFolder.add({ playAll: () => this.playAllClips() }, 'playAll');
// Morph target controls.
this.morphFolder = gui.addFolder('Morph Targets');
this.morphFolder.domElement.style.display = 'none';
// Camera controls.
this.cameraFolder = gui.addFolder('Cameras');
this.cameraFolder.domElement.style.display = 'none';
// Agent controls.
const agentFolder = gui.addFolder('Agent');
agentFolder
.add(this.state, 'followMode', {
None: 'none',
'Follow Mouse': 'mouse',
'Follow Keystrokes': 'keystrokes',
})
.name('follow mode');
// Stats.
const perfFolder = gui.addFolder('Performance');
const perfLi = document.createElement('li');
this.stats.dom.style.position = 'static';
perfLi.appendChild(this.stats.dom);
perfLi.classList.add('gui-stats');
perfFolder.__ul.appendChild(perfLi);
// `embed` (the <agent-3d> web component) keeps the GUI object, which the
// load path updates, but never mounts its DOM: its styles live in the
// site stylesheet, which a shadow root cannot see, so on a host page the
// panel spilled out below the element as thousands of unstyled controls.
const mountDebugUI = !this.options.embed;
const guiWrap = document.createElement('div');
if (mountDebugUI) this.el.appendChild(guiWrap);
guiWrap.classList.add('gui-wrap');
guiWrap.classList.add('gui-wrap--hidden');
guiWrap.appendChild(gui.domElement);
this._guiWrap = guiWrap;
labelGUIControls(gui.domElement);
this._guiObserver = watchGUIControls(gui.domElement);
// Toggle button — hides dat.GUI behind an "Advanced" control
const toggle = document.createElement('button');
toggle.className = 'gui-toggle';
// In kiosk/embed there's no GUI surface to expose.
if (this.options.kiosk) toggle.hidden = true;
toggle.setAttribute('title', 'Toggle advanced controls');
toggle.setAttribute('aria-label', 'Toggle advanced controls');
toggle.innerHTML =
'<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
'<circle cx="12" cy="12" r="3"></circle>' +
'<path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"></path>' +
'</svg>' +
'<span class="gui-toggle__label">Controls</span>';
toggle.addEventListener('click', () => {
const shown = guiWrap.classList.toggle('gui-wrap--hidden');
toggle.classList.toggle('gui-toggle--active', !shown);
});
if (mountDebugUI) this.el.appendChild(toggle);
this._guiToggle = toggle;
// AR button — hidden until setARTarget() is called with a supported URL
const arBtn = document.createElement('button');
arBtn.className = 'ar-btn';
arBtn.setAttribute('title', 'View in AR');
arBtn.setAttribute('aria-label', 'View in AR');
arBtn.innerHTML =
'<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
'<path d="M1 6l5-3 5 3v5l-5 3-5-3z"></path>' +
'<path d="M11 3l5 3v5l-5-3z"></path>' +
'<path d="M1 11l5 3 5-3"></path>' +
'<path d="M6 9v5"></path>' +
'<path d="M16 6v5l5 3v-5z"></path>' +
'<path d="M11 8l5 3"></path>' +
'</svg>' +
'<span class="ar-btn__label">AR</span>';
arBtn.hidden = true;
arBtn.part = 'ar-button';
arBtn.addEventListener('click', () => this.activateAR());
this.el.appendChild(arBtn);
this._arBtn = arBtn;
this._arGlbUrl = null;
this._arUsdzUrl = null;
this._arModes = ['webxr', 'scene-viewer', 'quick-look'];
this._arPlacement = 'floor';
this._xrSession = null;
if (isMobile) {
gui.close();
} else {
gui.open();
}
}
updateGUI() {
this.cameraFolder.domElement.style.display = 'none';
this.morphCtrls.forEach((ctrl) => ctrl.remove());
this.morphCtrls.length = 0;
this.morphFolder.domElement.style.display = 'none';
this.animCtrls.forEach((ctrl) => ctrl.remove());
this.animCtrls.length = 0;
this.animFolder.domElement.style.display = 'none';
const cameraNames = [];
const morphMeshes = [];
this.content.traverse((node) => {
if (node.geometry && node.morphTargetInfluences) {
morphMeshes.push(node);
}
if (node.isCamera) {
node.name = node.name || `VIEWER__camera_${cameraNames.length + 1}`;
cameraNames.push(node.name);
}
});
if (cameraNames.length) {
this.cameraFolder.domElement.style.display = '';
if (this.cameraCtrl) this.cameraCtrl.remove();
const cameraOptions = [DEFAULT_CAMERA].concat(cameraNames);
this.cameraCtrl = this.cameraFolder.add(this.state, 'camera', cameraOptions);
this.cameraCtrl.onChange((name) => this.setCamera(name));
}
if (morphMeshes.length) {
this.morphFolder.domElement.style.display = '';
morphMeshes.forEach((mesh) => {
if (mesh.morphTargetInfluences.length) {
const nameCtrl = this.morphFolder.add(
{ name: mesh.name || 'Untitled' },
'name',
);
this.morphCtrls.push(nameCtrl);
}
for (let i = 0; i < mesh.morphTargetInfluences.length; i++) {
const ctrl = this.morphFolder
.add(mesh.morphTargetInfluences, i, 0, 1, 0.01)
.listen();
Object.keys(mesh.morphTargetDictionary).forEach((key) => {
if (key && mesh.morphTargetDictionary[key] === i) ctrl.name(key);
});
this.morphCtrls.push(ctrl);
}
});
}
if (this.clips.length) {
this.animFolder.domElement.style.display = '';
const actionStates = (this.state.actionStates = {});
this.clips.forEach((clip, clipIndex) => {
clip.name = `${clipIndex + 1}. ${clip.name}`;
// Autoplay the first clip.
let action;
if (clipIndex === 0) {
actionStates[clip.name] = true;
action = this.mixer.clipAction(clip);
action.play();
} else {
actionStates[clip.name] = false;
}
// Play other clips when enabled.
const ctrl = this.animFolder.add(actionStates, clip.name).listen();
ctrl.onChange((playAnimation) => {
action = action || this.mixer.clipAction(clip);
action.setEffectiveTimeScale(1);
playAnimation ? action.play() : action.stop();
this.invalidate();
});
this.animCtrls.push(ctrl);
});
}
}
// ── External Animation Panel (Mixamo-style) ─────────────────────────────
/**
* Register a list of external animation definitions (name + URL).
* @param {Array<{name: string, url: string, label?: string, icon?: string, loop?: boolean}>} defs
*/
setAnimationDefs(defs) {
this.animationManager.setAnimationDefs(defs);
if (this.content) this._setupAnimationPanel();
}
/**
* Create / rebuild the animation selector panel.
* @private
*/
_setupAnimationPanel() {
// Remove existing panel
if (this._animPanelEl) {
this._animPanelEl.remove();
this._animPanelEl = null;
}
// The clip panel is editor chrome. Kiosk views and the <agent-3d> embed
// (whose host page carries none of its styles) play clips on demand.
if (this.options.kiosk || this.options.embed) return;
const defs = this.animationManager.getAnimationDefs();
if (defs.length === 0) return;
// Check model has a skeleton (no point showing anim panel for static meshes)
let hasSkeleton = false;
this.content.traverse((node) => {
if (node.isSkinnedMesh) hasSkeleton = true;
});
if (!hasSkeleton) return;
// Create panel container
const panel = document.createElement('div');
panel.className = 'anim-panel';
panel.innerHTML =
'<div class="anim-panel__header">' +
'<span class="anim-panel__title">Animations</span>' +
'<button class="anim-panel__stop" title="Stop all">⏹</button>' +
'</div>' +
'<div class="anim-panel__grid"></div>';
this.el.appendChild(panel);
this._animPanelEl = panel;
// Render buttons
this._renderAnimButtons();
// Preload walk and idle first so they're ready before the first brain:stream.
// loadAll() below fetches all clips with CONCURRENCY=4 and may not reach
// these two before the user sends a message; ensureLoaded kicks them off
// immediately and returns early if they're already in-progress or cached.
// allSettled so a missing walk clip doesn't block idle from playing.
console.time('walk-ready');
Promise.allSettled([
this.animationManager.ensureLoaded('idle'),
this.animationManager.ensureLoaded('walk'),
]).then(() => {
console.timeEnd('walk-ready');
if (!this.animationManager.currentAction) {
this.animationManager.play('idle');
}
});
// Load all animations in background. We deliberately do NOT auto-play
// the first animation: external Mixamo-rigged FBX clips often retarget
// imperfectly onto Ready Player Me / Avaturn avatars, which collapses
// the rig and makes the model look "disappeared" on first load. Show
// the authored pose instead and let the user pick an animation when
// they want one.
this.animationManager.loadAll().then(() => {
this._renderAnimButtons();
});
// Fetch user-owned and public animations from the API and append them
// to the panel alongside the built-in manifest clips.
this._fetchAndAppendUserAnimations();
// Stop button
panel.querySelector('.anim-panel__stop').addEventListener('click', () => {
this.animationManager.stopAll();
this._renderAnimButtons();
this.invalidate();
});
// onChange (render panel buttons + invalidate the render loop) is wired
// once in the constructor so it also runs in kiosk mode, where this panel
// setup is skipped entirely.
}
/**
* Fetch user-owned and public animation clips from the API and append them
* to the animation panel so they appear alongside the manifest built-ins.
* Non-fatal: if the API is unavailable or the user isn't signed in the panel
* still shows the built-in clips.
* @private
*/
async _fetchAndAppendUserAnimations() {
try {
const res = await fetch('/api/animations/clips?include_public=true&limit=100', {
credentials: 'include',
});
if (!res.ok) return;
const { items } = await res.json();
if (!Array.isArray(items) || items.length === 0) return;
const defs = items.map((c) => ({
name: `user:${c.id}`,
url: `/api/animations/clips/${encodeURIComponent(c.id)}?play=1`,
label: c.name || c.slug || 'Animation',
icon: c.visibility === 'public' ? '🌐' : '🔒',
loop: c.loop !== false,
source: 'user',
}));
this.animationManager.appendAnimationDefs(defs);
this._renderAnimButtons();
} catch {
/* Non-fatal — user clips just won't appear in the panel */
}
}
/**
* Load a user or public animation clip by its API id (or slug) and play it
* on the currently attached avatar. Increments play_count on the server.
* Safe to call before setAnimationDefs; registers the clip directly.
*
* @param {string} clipId — animation_clips.id (UUID) or slug
* @returns {Promise<string>} the internal clip name used by the manager
*/
async playAnimationById(clipId) {
const name = `user:${clipId}`;
// If already registered as a def, use the normal ensureLoaded path.
const existing = this.animationManager.getAnimationDefs().find(
(d) => d.name === name || d.url?.includes(`/${encodeURIComponent(clipId)}`),
);
if (!existing) {
// Register the def so the manager knows how to lazy-load it.
this.animationManager.appendAnimationDefs([{
name,
url: `/api/animations/clips/${encodeURIComponent(clipId)}?play=1`,
label: 'Animation',
icon: '🎬',
loop: true,
source: 'user',
}]);
}
const ready = await this.animationManager.ensureLoaded(name);
if (!ready) throw new Error(`animation ${clipId} unavailable`);
await this.animationManager.crossfadeTo(name);
this.invalidate();
this._recomputeAnimating?.();
this._updateRenderLoop?.();
return name;
}
/**
* Render / re-render animation buttons in the panel.
* @private
*/
_renderAnimButtons() {
if (!this._animPanelEl) return;
const grid = this._animPanelEl.querySelector('.anim-panel__grid');
const defs = this.animationManager.getAnimationDefs();
const activeName = this.animationManager.currentName;
const ICONS = {
idle: '🧍',
breathing: '🧍',
standing: '🧍',
walking: '🚶',
walk: '🚶',
running: '🏃',
run: '🏃',
waving: '👋',
wave: '👋',
dancing: '💃',
dance: '💃',
sitting: '🪑',
sit: '🪑',
jumping: '🦘',
jump: '🦘',
talking: '🗣️',
talk: '🗣️',
clapping: '👏',
clap: '👏',
punching: '👊',
punch: '👊',
kicking: '🦵',
kick: '🦵',
};
grid.innerHTML = defs
.map((def, i) => {
const loaded = this.animationManager.isLoaded(def.name);
const isActive = activeName === def.name;
const icon = def.icon || ICONS[def.name.toLowerCase()] || '▶';
const label = def.label || def.name.charAt(0).toUpperCase() + def.name.slice(1);
const keyHint = i < 9 ? i + 1 : '';
return (
'<button class="anim-btn' +
(isActive ? ' anim-btn--active' : '') +
(loaded ? '' : ' anim-btn--loading') +
'" data-anim="' +
def.name +
'"' +
' title="' +
label +
(keyHint ? ' — press ' + keyHint : '') +
'"' +
(loaded ? '' : ' disabled') +
'>' +
(keyHint ? '<span class="anim-btn__key">' + keyHint + '</span>' : '') +
'<span class="anim-btn__icon">' +
icon +
'</span>' +
'<span class="anim-btn__label">' +
label +
'</span>' +
'</button>'
);
})
.join('');
// Bind click events
grid.querySelectorAll('.anim-btn:not([disabled])').forEach((btn) => {
btn.addEventListener('click', () => {
const name = btn.dataset.anim;
this.animationManager.crossfadeTo(name);
this.invalidate();
this._recomputeAnimating();
this._updateRenderLoop();
});
});
// Bind keyboard shortcuts (1-9) — only once. Stored on `this` so
// dispose() can remove it; otherwise viewer recreations stack handlers.
if (!this._onAnimHotkey) {
this._onAnimHotkey = (e) => {
if (e.target && /INPUT|TEXTAREA|SELECT/.test(e.target.tagName)) return;
if (e.metaKey || e.ctrlKey || e.altKey) return;
const n = parseInt(e.key, 10);
if (!n || n < 1 || n > 9) return;
const currentDefs = this.animationManager.getAnimationDefs();
const def = currentDefs[n - 1];
if (!def || !this.animationManager.isLoaded(def.name)) return;
this.animationManager.crossfadeTo(def.name);
this.invalidate();
this._recomputeAnimating();
this._updateRenderLoop();
};
document.addEventListener('keydown', this._onAnimHotkey);
}
}
clear() {
if (!this.content) return;
// Detach external animation manager
this.animationManager.detach();
if (this._animPanelEl) {
this._animPanelEl.remove();
this._animPanelEl = null;
}
if (this.modelInfo) {
this.modelInfo.remove();
this.modelInfo = null;
}
this.annotationEls.forEach((a) => a.el.remove());
this.annotationEls = [];
this.scene.remove(this.content);
// dispose BVH acceleration structures before geometry
this.content.traverse((node) => {
if (node.isMesh && node.geometry?.boundsTree) {
node.geometry.disposeBoundsTree();
}
});
// dispose geometry
this.content.traverse((node) => {
if (!node.geometry) return;
node.geometry.dispose();
});
// dispose textures
traverseMaterials(this.content, (material) => {
for (const key in material) {
if (key !== 'envMap' && material[key] && material[key].isTexture) {
material[key].dispose();
}
}
});
this.content = null;
if (!this._disposed) this.invalidate();
}
dispose() {
if (this._disposed) return;
this._disposed = true;
// Stop watching the control panel before its DOM goes away.
this._guiObserver?.disconnect();
this._guiObserver = null;
if (this._rafId !== null) {
cancelAnimationFrame(this._rafId);
this._rafId = null;
}
if (this._resizeRaf != null) {
cancelAnimationFrame(this._resizeRaf);
this._resizeRaf = null;
}
document.removeEventListener('visibilitychange', this._onVisibilityChange);
window.removeEventListener('resize', this._onResize, false);
window.removeEventListener('keydown', this._onKeyDown);
if (this._onDblClick && this.renderer?.domElement) {
this.renderer.domElement.removeEventListener('dblclick', this._onDblClick);
}
if (this._onCanvasKeyDown && this.renderer?.domElement) {
this.renderer.domElement.removeEventListener('keydown', this._onCanvasKeyDown);
this._onCanvasKeyDown = null;
}
if (this._onMessage) {
window.removeEventListener('message', this._onMessage, false);
}
if (this._cameraTweenRaf) cancelAnimationFrame(this._cameraTweenRaf);
this._clearPumpFunTrades();
if (this._onAnimHotkey) {
document.removeEventListener('keydown', this._onAnimHotkey);
this._onAnimHotkey = null;
}
if (this._intersectionObserver) {
this._intersectionObserver.disconnect();
this._intersectionObserver = null;
}
if (this._ro) {
this._ro.disconnect();
this._ro = null;
}
this.clear();
if (this.mixer) {
this.mixer.stopAllAction();
const root = this.mixer.getRoot();
if (root) this.mixer.uncacheRoot(root);
this.mixer = null;
}
this.clips = [];
// Dispose external animation system
this.animationManager.dispose();
if (this._animPanelEl) {
this._animPanelEl.remove();
this._animPanelEl = null;
}
if (this.skeletonHelpers.length) {
this.skeletonHelpers.forEach((helper) => {
this.scene.remove(helper);
helper.dispose?.();
});
this.skeletonHelpers.length = 0;
}
if (this.gridHelper) {
this.scene.remove(this.gridHelper);
this.gridHelper.geometry?.dispose();
this.gridHelper.material?.dispose();
this.gridHelper = null;
}
if (this.axesHelper) {
this.scene.remove(this.axesHelper);
this.axesHelper.geometry?.dispose();
this.axesHelper.material?.dispose();
this.axesHelper = null;
}
if (this.axesCorner) {
this.axesScene?.remove(this.axesCorner);
this.axesCorner.geometry?.dispose();
this.axesCorner.material?.dispose();
this.axesCorner = null;
}
this.lights.forEach((light) => light.parent?.remove(light));
this.lights = [];
if (this.shadowCatcher) {
this.scene.remove(this.shadowCatcher);
this.shadowCatcher.geometry?.dispose();
this.shadowCatcher.material?.dispose();
this.shadowCatcher = null;
}
if (this.annotationEls.length) {
this.annotationEls.forEach((a) => a.el.remove());
this.annotationEls = [];
}
if (this.modelInfo) {
this.modelInfo.remove();
this.modelInfo = null;
}
if (this.gui) {
this.gui.destroy();
this.gui = null;
}
if (this._guiWrap) {
this._guiWrap.remove();
this._guiWrap = null;
}
if (this._guiToggle) {
this._guiToggle.remove();
this._guiToggle = null;
}
if (this.stats?.dom) this.stats.dom.remove();
if (this.controls) {
if (this._onControlsChange) {
this.controls.removeEventListener('change', this._onControlsChange);
this._onControlsChange = null;
}
this.controls.dispose();
this.controls = null;
}
if (this._loadedEnvironment) {
this._loadedEnvironment.dispose();
this._loadedEnvironment = null;
}
if (this.neutralEnvironment) {
this.neutralEnvironment.dispose();
this.neutralEnvironment = null;
}
if (this.scene) {
this.scene.environment = null;
this.scene.background = null;
}
if (this._lightProbeGrid) {
this._lightProbeGrid.removeFromScene(this.scene);
this._lightProbeGrid.dispose();
this._lightProbeGrid = null;
}
if (this.pmremGenerator) {
this.pmremGenerator.dispose();
this.pmremGenerator = null;
}
if (this.axesRenderer) {
this.axesRenderer.dispose();
this.axesRenderer.forceContextLoss?.();
this.axesRenderer.domElement?.remove();
this.axesRenderer = null;
}
if (this.axesDiv) {
this.axesDiv.remove();
this.axesDiv = null;
}
this.axesScene = null;
this.axesCamera = null;
if (this._cinematic) {
this._cinematic.dispose();
this._cinematic = null;
this._composer = null;
}
if (this.renderer) {
this.renderer.dispose();
this.renderer.forceContextLoss?.();
this.renderer.domElement?.remove();
if (window.renderer === this.renderer) window.renderer = null;
this.renderer = null;
}
if (this.audioListener) {
this.defaultCamera?.remove(this.audioListener);
this.audioListener = null;
}
this.scene = null;
this.content = null;
this.activeCamera = null;
this.defaultCamera = null;
this._afterAnimateHooks = null;
}
}