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
fix(club): stop a centimetre-scale crowd avatar from spawning 700 m tall over the alley
ni3a140723be4f91
diff --git a/data/changelog.json b/data/changelog.jsonindex e36fd17d9..9b4184b60 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,15 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-09-21",+ "title": "The club alley no longer renders a giant avatar across the sky",+ "summary": "Walking into /club, some visitors saw a huge metallic shape filling the sky above the alley, and their computer ran hot. It was a crowd member: one avatar model built at centimetre scale was measured wrong before it was sized, so it spawned about 400 times too big, roughly 700 metres tall, and the GPU spent the whole walk-in painting it. Crowd members, your own avatar in the agent switcher, the theater stage and the Agora now size every avatar from its real posed mesh, so that model stands at normal human height like everyone else.",+ "tags": [+ "fix"+ ],+ "link": "/club"+ },{"date": "2026-09-21","title": "The club no longer runs your computer hot on the way in",diff --git a/src/agora/citizen-avatar.js b/src/agora/citizen-avatar.jsindex 377dab64c..e69205449 100644--- a/src/agora/citizen-avatar.js+++ b/src/agora/citizen-avatar.js@@ -26,6 +26,7 @@ import { gltfLoader } from '../loaders/gltf.js';import { AnimationManager } from '../animation-manager.js';import { loadManifest, getLocomotionDefs, resolveAvatarUrl, AVATAR_DEFAULT, CLIP_IDLE, CLIP_WALK } from '../game/avatar-rig.js';import { log } from '../shared/log.js';+import { scaleToHeight, groundFeet } from '../shared/avatar-fit.js';// Target on-screen height so wildly-scaled GLBs all read as people in the square.const AVATAR_HEIGHT = 1.74;@@ -117,16 +118,6 @@ export function citizenProfessionLabel(citizen) {const _box = new Box3();const _v = new Vector3();-function scaleToHeight(obj, h) {- _box.setFromObject(obj, true);- const cur = _box.max.y - _box.min.y || 1;- obj.scale.multiplyScalar(h / cur);-}-function groundFeet(obj) {- _box.setFromObject(obj, true);- if (Number.isFinite(_box.min.y)) obj.position.y -= _box.min.y;-}-// Build a crisp, high-DPI billboard label: bold name over a profession chip.// Returns a Sprite that always faces the camera (sizeAttenuation on, so distant// labels recede naturally). Drawn on a transparent rounded panel for contrastdiff --git a/src/club-crowd.js b/src/club-crowd.jsindex d27964179..c140e3e77 100644--- a/src/club-crowd.js+++ b/src/club-crowd.js@@ -27,11 +27,12 @@// the pole stage always work without it. A rig the canonical clip library can't// drive is skipped rather than left standing in a bind/T-pose.-import { AnimationMixer, Box3, Group, LoopOnce, Raycaster, Vector3 } from 'three';+import { AnimationMixer, Group, LoopOnce, Raycaster, Vector3 } from 'three';import { clone as cloneSkinnedScene } from 'three/addons/utils/SkeletonUtils.js';import { gltfLoader } from './loaders/gltf.js';import { AnimationManager } from './animation-manager.js';import { log } from './shared/log.js';+import { scaleToHeight, groundFeet } from './shared/avatar-fit.js';// Clip pools, by mood. Names must exist in /animations/manifest.json; URLs are// resolved from the manifest passed to the constructor. A missing clip is just@@ -67,19 +68,8 @@ const LIVELY_FLOOR = 9;const LINEUP_DISTINCT = 6;const DOWN = new Vector3(0, -1, 0);-const _box = new Box3();const _origin = new Vector3();-function scaleToHeight(obj, h) {- _box.setFromObject(obj, true);- const cur = _box.max.y - _box.min.y || 1;- obj.scale.multiplyScalar(h / cur);-}-function groundFeet(obj) {- _box.setFromObject(obj, true);- if (Number.isFinite(_box.min.y)) obj.position.y -= _box.min.y;-}-function shuffle(arr) {const a = arr.slice();for (let i = a.length - 1; i > 0; i--) {diff --git a/src/club-entrance.js b/src/club-entrance.jsindex 25d02c749..7c67dcb75 100644--- a/src/club-entrance.js+++ b/src/club-entrance.js@@ -63,6 +63,7 @@ import { ClubBouncer, BOUNCER_AVATAR_URL } from './club-bouncer.js';import { detectProfile, PROFILES, createFrameWatchdog } from './club-perf.js';import { getPowerSaver } from './shared/frame-governor.js';import { log } from './shared/log.js';+import { scaleToHeight, groundFeet } from './shared/avatar-fit.js';import { isExpressEntry } from './shared/club-express.js';import { loadEnvironment } from './shared/cinematic-render.js';import { resolveClubVariant, listClubEntrances } from './club-variant.js';@@ -362,7 +363,7 @@ async function start(canvasEl) {let avatar = avatarGltf.scene;let currentAvatarUrl = AVATAR_URL;scaleToHeight(avatar, AVATAR_HEIGHT);- placeOnFloor(avatar);+ groundFeet(avatar);const rig = new Group(); // yaw the rig; the model sits at the rig originrig.add(avatar);scene.add(rig);@@ -740,7 +741,7 @@ async function start(canvasEl) {const gltf = await loader.loadAsync(url);const next = gltf.scene;scaleToHeight(next, AVATAR_HEIGHT);- placeOnFloor(next);+ groundFeet(next);// Verify the clip library can actually drive this rig BEFORE committing.// The switcher lists public gallery rigs, not all of them humanoid — a// non-canonical skeleton (Fox, CesiumMan, a robot…) can't be retargeted@@ -1525,16 +1526,6 @@ function buildMinimap() {return { setVenue, update, resize };}-function scaleToHeight(obj, h) {- const b = new Box3().setFromObject(obj, true);- const cur = b.max.y - b.min.y || 1;- obj.scale.multiplyScalar(h / cur);-}-function placeOnFloor(obj) {- const b = new Box3().setFromObject(obj, true);- obj.position.y -= b.min.y;-}-function disposeObject(obj) {obj.traverse((n) => {if (n.isMesh) {diff --git a/src/shared/avatar-fit.js b/src/shared/avatar-fit.jsnew file mode 100644index 000000000..0f24f44fe--- /dev/null+++ b/src/shared/avatar-fit.js@@ -0,0 +1,48 @@+// Size and ground a loaded avatar by its real, posed mesh.+//+// Both helpers measure with a precise Box3, which for a SkinnedMesh skins every+// vertex through its bones' matrixWorld. A GLB fresh out of the loader (or a+// SkeletonUtils clone of one) has never had its world matrices computed, so the+// bones still hold identity there. Measured that way, a centimetre-scale Mixamo+// rig (armature exported at scale 0.01, e.g. /avatars/michelle.glb) reads as a+// few millimetres tall, and scaling it "to 1.7 m" blew it up ~430x into a+// building-sized smear across the sky of /club. Refreshing the subtree's world+// matrices first makes the measurement the real one on every rig.+//+// The refresh must go through updateMatrixWorld, not updateWorldMatrix: only the+// former runs SkinnedMesh's override that re-derives bindMatrixInverse for an+// 'attached' mesh. Skipping it counts any ancestor move or scale twice.++import { Box3 } from 'three';++const _box = new Box3();++function measure(obj) {+ obj.parent?.updateWorldMatrix(true, false);+ obj.updateMatrixWorld(true);+ return _box.setFromObject(obj, true);+}++/**+ * Uniformly scale `obj` so its bounding height is `h` world units. A model that+ * cannot be measured (empty, or a degenerate box) is left untouched.+ *+ * @param {import('three').Object3D} obj+ * @param {number} h+ */+export function scaleToHeight(obj, h) {+ const b = measure(obj);+ const cur = b.max.y - b.min.y;+ if (!(cur > 1e-6) || !Number.isFinite(cur)) return;+ obj.scale.multiplyScalar(h / cur);+}++/**+ * Shift `obj` vertically so its lowest point sits at its parent's y = 0.+ *+ * @param {import('three').Object3D} obj+ */+export function groundFeet(obj) {+ const b = measure(obj);+ if (Number.isFinite(b.min.y)) obj.position.y -= b.min.y;+}diff --git a/src/theater-stage.js b/src/theater-stage.jsindex 6425cdded..62d0625f5 100644--- a/src/theater-stage.js+++ b/src/theater-stage.js@@ -56,6 +56,7 @@ import { gltfLoader, disposeGltfLoader } from './loaders/gltf.js';import { AnimationManager } from './animation-manager.js';import { agentAvatarGlb, MANNEQUIN_GLB } from './shared/agent-3d.js';import { log } from './shared/log.js';+import { scaleToHeight, groundFeet } from './shared/avatar-fit.js';import { loadEnvironment } from './shared/cinematic-render.js';// Reaction vocabulary mapped onto the real pre-baked clip library@@ -130,16 +131,6 @@ const _box = new Box3();const _v = new Vector3();const _v2 = new Vector3();-function scaleToHeight(obj, h) {- _box.setFromObject(obj, true);- const cur = _box.max.y - _box.min.y || 1;- obj.scale.multiplyScalar(h / cur);-}-function groundFeet(obj) {- _box.setFromObject(obj, true);- if (Number.isFinite(_box.min.y)) obj.position.y -= _box.min.y;-}-// Deterministic small hash so a given agent id always picks the same reaction// from a pool (stable performances across reconnects).function hashPick(arr, key) {diff --git a/tests/avatar-fit.test.js b/tests/avatar-fit.test.jsnew file mode 100644index 000000000..0c930c56c--- /dev/null+++ b/tests/avatar-fit.test.js@@ -0,0 +1,90 @@+// Tests for src/shared/avatar-fit.js: sizing and grounding an avatar by its+// skinned mesh. The regression case is a centimetre-scale Mixamo layout (the+// armature node scaled 0.01, bones and bind-space vertices in centimetres),+// measured on a SkeletonUtils clone whose world matrices were never computed.+// That is exactly what the /club crowd does, and before the fix it read the rig+// as a few millimetres tall and scaled it into a ~700 m giant.++import { describe, it, expect } from 'vitest';+import {+ Bone,+ Box3,+ BufferGeometry,+ Float32BufferAttribute,+ Group,+ MeshBasicMaterial,+ Skeleton,+ SkinnedMesh,+ Uint16BufferAttribute,+} from 'three';+import { clone } from 'three/addons/utils/SkeletonUtils.js';+import { scaleToHeight, groundFeet } from '../src/shared/avatar-fit.js';++// A 170 cm tall two-bone column under a 0.01-scaled armature node, laid out+// like a GLTFLoader result: nothing has had updateMatrixWorld called on it.+function centimetreRig() {+ const root = new Group();+ const armature = new Group();+ armature.scale.setScalar(0.01);+ root.add(armature);++ const hips = new Bone();+ hips.name = 'mixamorigHips';+ hips.position.set(0, 100, 0);+ const head = new Bone();+ head.name = 'mixamorigHead';+ head.position.set(0, 70, 0);+ hips.add(head);+ armature.add(hips);++ const positions = [-20, 0, 0, 20, 0, 0, 0, 170, 0, 0, 100, 10];+ const geometry = new BufferGeometry();+ geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));+ geometry.setAttribute('skinIndex', new Uint16BufferAttribute([0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0], 4));+ geometry.setAttribute('skinWeight', new Float32BufferAttribute([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0], 4));+ geometry.setIndex([0, 1, 2, 0, 3, 2]);+ const mesh = new SkinnedMesh(geometry, new MeshBasicMaterial());+ armature.add(mesh);++ // Bind in the armature's local (centimetre) frame, then throw the computed+ // world matrices away so the graph looks freshly loaded again.+ armature.updateMatrixWorld(true);+ mesh.bind(new Skeleton([hips, head]), mesh.matrixWorld);+ root.traverse((n) => n.matrixWorld.identity());+ return root;+}++function bounds(obj) {+ obj.updateMatrixWorld(true);+ return new Box3().setFromObject(obj, true);+}++function height(obj) {+ const b = bounds(obj);+ return b.max.y - b.min.y;+}++describe('scaleToHeight', () => {+ it('sizes a never-updated clone of a centimetre-scale rig to the requested height', () => {+ const model = clone(centimetreRig());+ scaleToHeight(model, 1.7);+ expect(height(model)).toBeCloseTo(1.7, 3);+ });++ it('is a no-op on an empty object instead of scaling by infinity', () => {+ const empty = new Group();+ scaleToHeight(empty, 1.7);+ expect(empty.scale.toArray()).toEqual([1, 1, 1]);+ });+});++describe('groundFeet', () => {+ it('puts the lowest skinned vertex on y = 0', () => {+ const model = clone(centimetreRig());+ model.position.y = 3;+ scaleToHeight(model, 1.7);+ groundFeet(model);+ expect(bounds(model).min.y).toBeCloseTo(0, 4);+ expect(height(model)).toBeCloseTo(1.7, 3);+ });+});