Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(viewer): frame the avatar's face, not its back, whatever axis its rig faces

nirholas66de9305b1f6
diff --git a/src/shared/idle-avatar.js b/src/shared/idle-avatar.js
index 6ee4098dc..14c2d51e2 100644
--- a/src/shared/idle-avatar.js
+++ b/src/shared/idle-avatar.js
@@ -35,6 +35,11 @@ function loadAnimationDefs() {
return _manifestPromise;
}
+/** True when the reader asked the platform to hold decorative motion still. */
+function prefersReducedMotion() {
+ return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
/**
* Mount a living, idle-animated avatar into `container`.
*
@@ -44,6 +49,7 @@ function loadAnimationDefs() {
* @param {string} glbUrl Avatar model URL.
* @param {Object} [opts]
* @param {boolean} [opts.autoRotate=true] Slowly turn the figure on a turntable.
+ * Held still regardless when the reader prefers reduced motion.
* @param {string} [opts.seed] Stable seed so the idle phase is deterministic per agent.
* @param {string} [opts.environment='Neutral'] Lighting environment name.
* @param {boolean} [opts.cameraControls=false] Allow orbit/zoom (used in the modal).
@@ -83,7 +89,10 @@ export function mountIdleAvatar(container, glbUrl, opts = {}) {
}
viewer.state.environment = environment;
- viewer.state.autoRotate = autoRotate;
+ // A turntable is decorative motion nobody asked for: a reader who set
+ // "reduce motion" gets the figure held still, and its idle life (breathing,
+ // blink) still plays because that is the content, not the decoration.
+ viewer.state.autoRotate = autoRotate && !prefersReducedMotion();
viewer.controls.enabled = cameraControls;
viewer.controls.enableZoom = cameraControls;
viewer.controls.enablePan = false;
diff --git a/src/viewer.js b/src/viewer.js
index 953b7a798..78bc64578 100644
--- a/src/viewer.js
+++ b/src/viewer.js
@@ -54,6 +54,7 @@ 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 { applyAvatarMaterialRealism, looksLikeAvatarMesh } from './shared/avatar-material-realism.js';
@@ -712,9 +713,14 @@ export class Viewer {
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(bbSize.x, bbSize.y, framingMode);
+ 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);
@@ -722,7 +728,11 @@ export class Viewer {
// 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 + dist * 0.12, focusY, bbCenter.z + dist);
+ const pos = new Vector3(
+ bbCenter.x + forward.x * dist,
+ focusY,
+ bbCenter.z + forward.z * dist,
+ );
if (animate) {
this._tweenCamera(pos, target, durationMs);
@@ -1343,9 +1353,14 @@ export class Viewer {
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(bbSize.x, bbSize.y, framingMode);
+ 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);
@@ -1355,14 +1370,13 @@ export class Viewer {
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.
- // (The legacy 6% 3/4 angle pan was an aesthetic choice; removing it so
- // every embed opens with the character squarely facing the viewer.)
+ // 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(0, focusY, dist);
+ framedPos.set(forward.x * dist, focusY, forward.z * dist);
}
const orbitalTarget = new Vector3(0, focusY, 0);
diff --git a/src/viewer/facing.js b/src/viewer/facing.js
new file mode 100644
index 000000000..c8b1fe884
--- /dev/null
+++ b/src/viewer/facing.js
@@ -0,0 +1,110 @@
+// Which way is the avatar looking? Pure geometry plus a scene-graph probe, kept
+// out of viewer.js so both framing paths (setContent's first frame and
+// frameContent's re-frame) can agree and so the math is unit-testable without a
+// WebGL context.
+//
+// The viewer used to place the camera on +Z unconditionally and describe that as
+// "front-on". That only holds for rigs authored facing +Z. glTF characters
+// arrive facing every axis (Mixamo and Unreal exports commonly face -Z, VRM
+// faces +Z), so a large share of avatars opened showing the viewer their back.
+// Reading the facing off the rig fixes that for every avatar at once, with no
+// per-model metadata and no allowlist.
+
+import { canonicalizeBoneName } from '../glb-canonicalize.js';
+
+/**
+ * Bone pairs that span the body left-to-right, best first. Shoulders barely
+ * move in an idle clip, so they give a steadier read than hands or feet.
+ * Names are canonical (see CANONICAL_BONES in ../glb-canonicalize.js).
+ */
+const SPAN_PAIRS = [
+ ['LeftShoulder', 'RightShoulder'],
+ ['LeftArm', 'RightArm'],
+ ['LeftUpLeg', 'RightUpLeg'],
+];
+
+/**
+ * Yaw of the direction a body faces, from the horizontal span between its left
+ * and right side.
+ *
+ * With Y up, the character's right vector r and forward f satisfy f = up x r,
+ * so f = (r.z, 0, -r.x). Yaw is measured from +Z, the axis the camera has
+ * always sat on, which makes 0 the exact legacy behaviour.
+ *
+ * @param {number} dx world x of (right landmark - left landmark)
+ * @param {number} dz world z of (right landmark - left landmark)
+ * @param {number} [minSpan=0] reject spans shorter than this (world units)
+ * @returns {number|null} yaw in radians, or null when the span is degenerate
+ */
+export function yawFromRightSpan(dx, dz, minSpan = 0) {
+ if (!Number.isFinite(dx) || !Number.isFinite(dz)) return null;
+ if (Math.hypot(dx, dz) <= Math.max(minSpan, 0)) return null;
+ return Math.atan2(dz, -dx);
+}
+
+/**
+ * Unit forward vector for a yaw, in the horizontal plane.
+ * @param {number} yaw radians, measured from +Z
+ * @returns {{x:number, z:number}}
+ */
+export function forwardFromYaw(yaw) {
+ return { x: Math.sin(yaw), z: Math.cos(yaw) };
+}
+
+/**
+ * Width of an axis-aligned bounding box as seen from a camera at `yaw`.
+ *
+ * Camera distance is driven partly by how wide the subject is on screen, and
+ * that width is the box projected onto the camera's right vector
+ * (cos(yaw), 0, -sin(yaw)). At yaw 0 this returns sizeX, so a +Z-facing avatar
+ * is framed exactly as before; a side-facing one is now measured across its
+ * depth instead of being framed against the wrong axis.
+ *
+ * @param {number} sizeX bounding-box size on x
+ * @param {number} sizeZ bounding-box size on z
+ * @param {number} yaw radians
+ * @returns {number}
+ */
+export function horizontalExtentAt(sizeX, sizeZ, yaw) {
+ return Math.abs(Math.cos(yaw)) * sizeX + Math.abs(Math.sin(yaw)) * sizeZ;
+}
+
+/**
+ * Read the facing yaw off a loaded model's rig.
+ *
+ * Walks the graph once for the best available left/right bone pair and measures
+ * the span between their world positions. World translation is read straight
+ * out of matrixWorld, so this needs no THREE import and can be tested with
+ * plain objects; call it after the world matrices are up to date (Box3's
+ * setFromObject does that, and both framing paths compute a box first).
+ *
+ * @param {{traverse:Function}} root loaded model root
+ * @param {number} [bodyHeight=0] bounding-box height, used to reject a
+ * degenerate span (a rig collapsed onto its own centre line)
+ * @returns {number|null} yaw in radians, or null when the rig cannot say
+ */
+export function estimateFacingYaw(root, bodyHeight = 0) {
+ if (!root || typeof root.traverse !== 'function') return null;
+
+ const found = new Map();
+ root.traverse((node) => {
+ if (!node?.isBone || typeof node.name !== 'string') return;
+ const canonical = canonicalizeBoneName(node.name);
+ if (!canonical || found.has(canonical)) return;
+ const e = node.matrixWorld?.elements;
+ if (!e) return;
+ found.set(canonical, { x: e[12], z: e[14] });
+ });
+
+ // A body collapsed to a line has no readable facing; 4% of height is well
+ // under any real shoulder span and well over floating-point noise.
+ const minSpan = bodyHeight * 0.04;
+ for (const [left, right] of SPAN_PAIRS) {
+ const l = found.get(left);
+ const r = found.get(right);
+ if (!l || !r) continue;
+ const yaw = yawFromRightSpan(r.x - l.x, r.z - l.z, minSpan);
+ if (yaw !== null) return yaw;
+ }
+ return null;
+}
diff --git a/tests/viewer-facing.test.js b/tests/viewer-facing.test.js
new file mode 100644
index 000000000..1e657fdc3
--- /dev/null
+++ b/tests/viewer-facing.test.js
@@ -0,0 +1,130 @@
+/**
+ * Viewer facing detection: which way does the avatar look?
+ *
+ * The camera seat used to be hardcoded to +Z and called "front-on", which only
+ * held for rigs authored facing +Z. These tests pin the geometry that replaced
+ * it, including the one case that must never regress: a model with no readable
+ * rig still gets the legacy +Z seat.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+ yawFromRightSpan,
+ forwardFromYaw,
+ horizontalExtentAt,
+ estimateFacingYaw,
+} from '../src/viewer/facing.js';
+
+/** Minimal stand-in for a THREE.Bone: only name + world translation are read. */
+function bone(name, x, z) {
+ const elements = new Array(16).fill(0);
+ elements[12] = x;
+ elements[14] = z;
+ return { isBone: true, name, matrixWorld: { elements } };
+}
+
+/** Minimal stand-in for an Object3D root that owns the bones. */
+function model(...bones) {
+ return { traverse(fn) { fn(this); bones.forEach(fn); } };
+}
+
+describe('yawFromRightSpan', () => {
+ it('reads +Z facing when the right side sits on -X (the legacy assumption)', () => {
+ expect(yawFromRightSpan(-1, 0)).toBeCloseTo(0, 12);
+ });
+
+ it('reads -Z facing when the right side sits on +X', () => {
+ expect(Math.abs(yawFromRightSpan(1, 0))).toBeCloseTo(Math.PI, 12);
+ });
+
+ it('reads +X facing when the right side sits on +Z', () => {
+ expect(yawFromRightSpan(0, 1)).toBeCloseTo(Math.PI / 2, 12);
+ });
+
+ it('rejects a span shorter than the floor, so a collapsed rig cannot spin the camera', () => {
+ expect(yawFromRightSpan(0.001, 0.001, 0.05)).toBeNull();
+ });
+
+ it('rejects non-finite input rather than producing NaN yaw', () => {
+ expect(yawFromRightSpan(Number.NaN, 0)).toBeNull();
+ expect(yawFromRightSpan(0, Number.POSITIVE_INFINITY)).toBeNull();
+ });
+});
+
+describe('forwardFromYaw', () => {
+ it('maps yaw 0 to +Z, the seat every existing embed already had', () => {
+ const f = forwardFromYaw(0);
+ expect(f.x).toBeCloseTo(0, 12);
+ expect(f.z).toBeCloseTo(1, 12);
+ });
+
+ it('maps a quarter turn to +X', () => {
+ const f = forwardFromYaw(Math.PI / 2);
+ expect(f.x).toBeCloseTo(1, 12);
+ expect(f.z).toBeCloseTo(0, 12);
+ });
+
+ it('stays a unit vector at an arbitrary angle', () => {
+ const f = forwardFromYaw(1.2345);
+ expect(Math.hypot(f.x, f.z)).toBeCloseTo(1, 12);
+ });
+});
+
+describe('horizontalExtentAt', () => {
+ it('is the box width at yaw 0, so full-body framing is unchanged', () => {
+ expect(horizontalExtentAt(0.9, 0.3, 0)).toBeCloseTo(0.9, 12);
+ });
+
+ it('is the box depth when the camera looks along X', () => {
+ expect(horizontalExtentAt(0.9, 0.3, Math.PI / 2)).toBeCloseTo(0.3, 12);
+ });
+
+ it('blends the two axes at an oblique angle', () => {
+ const e = horizontalExtentAt(0.9, 0.3, Math.PI / 4);
+ expect(e).toBeCloseTo(Math.SQRT1_2 * (0.9 + 0.3), 12);
+ expect(e).toBeGreaterThan(0.3);
+ expect(e).toBeLessThan(0.9 + 0.3);
+ });
+});
+
+describe('estimateFacingYaw', () => {
+ it('prefers shoulders and reads a -Z facing rig', () => {
+ const yaw = estimateFacingYaw(model(
+ bone('mixamorigLeftShoulder', -0.18, 0),
+ bone('mixamorigRightShoulder', 0.18, 0),
+ ), 1.8);
+ expect(Math.abs(yaw)).toBeCloseTo(Math.PI, 6);
+ });
+
+ it('canonicalizes vendor bone names before matching', () => {
+ const yaw = estimateFacingYaw(model(
+ bone('J_Bip_L_UpperArm', 0, -0.2),
+ bone('J_Bip_R_UpperArm', 0, 0.2),
+ ), 1.8);
+ expect(yaw).toBeCloseTo(Math.PI / 2, 6);
+ });
+
+ it('falls back to the legs when the rig has no arms', () => {
+ const yaw = estimateFacingYaw(model(
+ bone('LeftUpLeg', -0.1, 0),
+ bone('RightUpLeg', 0.1, 0),
+ ), 1.8);
+ expect(Math.abs(yaw)).toBeCloseTo(Math.PI, 6);
+ });
+
+ it('returns null for a prop with no bones, leaving the camera on +Z', () => {
+ expect(estimateFacingYaw(model(), 1.8)).toBeNull();
+ });
+
+ it('returns null when the left and right bones sit on top of each other', () => {
+ expect(estimateFacingYaw(model(
+ bone('LeftShoulder', 0, 0),
+ bone('RightShoulder', 0.0001, 0),
+ ), 1.8)).toBeNull();
+ });
+
+ it('tolerates a root that is not a scene graph', () => {
+ expect(estimateFacingYaw(null, 1.8)).toBeNull();
+ expect(estimateFacingYaw({}, 1.8)).toBeNull();
+ });
+});