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.

feat(avatars): replace the hand-rolled VRM loader with real @pixiv/three-vrm (MToon, spring-bones, expressions, .vrma)

nirholasd84605698ce6
diff --git a/package-lock.json b/package-lock.json
index e5bca1b3e..0dc2c7ef2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -133,6 +133,8 @@
"@node-saml/node-saml": "^5.1.0",
"@octokit/rest": "^22.0.1",
"@okxweb3/app-x402-core": "^0.2.0",
+ "@pixiv/three-vrm": "^3.5.5",
+ "@pixiv/three-vrm-animation": "^3.5.5",
"@privy-io/js-sdk-core": "^0.75.0",
"@pump-fun/agent-payments-sdk": "^3.0.3",
"@pump-fun/pump-sdk": "^4.0.0",
@@ -16533,6 +16535,20 @@
"three": ">=0.137"
}
},
+ "node_modules/@pixiv/three-vrm-animation": {
+ "version": "3.5.5",
+ "resolved": "https://registry.npmjs.org/@pixiv/three-vrm-animation/-/three-vrm-animation-3.5.5.tgz",
+ "integrity": "sha512-Q0kEtmftxfv0iCUHQkJH2jAr1zmT9ywYXnAzhxnLPMYCsx0Kken3J3U2GJF9PdGZmLlKpoK0LFEXVdD/L7ZA4Q==",
+ "license": "MIT",
+ "dependencies": {
+ "@pixiv/three-vrm-core": "3.5.5",
+ "@pixiv/types-vrmc-vrm-1.0": "3.5.5",
+ "@pixiv/types-vrmc-vrm-animation-1.0": "3.5.5"
+ },
+ "peerDependencies": {
+ "three": ">=0.137"
+ }
+ },
"node_modules/@pixiv/three-vrm-core": {
"version": "3.5.5",
"resolved": "https://registry.npmjs.org/@pixiv/three-vrm-core/-/three-vrm-core-3.5.5.tgz",
@@ -16652,6 +16668,15 @@
"integrity": "sha512-WnemHHo2375BcBdumEhvrupZzsMSzTfdWlokmV9sUX2oC+OAQqJFfBjLF8ppkOhzHpl4MAPJqEfuhBJtNPm9ww==",
"license": "MIT"
},
+ "node_modules/@pixiv/types-vrmc-vrm-animation-1.0": {
+ "version": "3.5.5",
+ "resolved": "https://registry.npmjs.org/@pixiv/types-vrmc-vrm-animation-1.0/-/types-vrmc-vrm-animation-1.0-3.5.5.tgz",
+ "integrity": "sha512-pyow6wBLdRZbLQbtHqu8uvYG+NXJbwIiLVK6pM6UvtaYotecOv43t6qIdMLYuieV+F+bEJcdfOLFZZVolrOOcQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@pixiv/types-vrmc-vrm-1.0": "3.5.5"
+ }
+ },
"node_modules/@pkgjs/parseargs": {
"version": "0.11.0",
"dev": true,
diff --git a/package.json b/package.json
index b189426d6..e25161e37 100644
--- a/package.json
+++ b/package.json
@@ -307,7 +307,6 @@
"guard:hidden": "node scripts/inject-hidden-guard.mjs --write",
"check:images": "node scripts/audit-image-loading.mjs --strict",
"audit:web": "node scripts/page-audit.mjs",
- "audit:agent-operability": "node scripts/audit-agent-operability.mjs",
"evolve": "node scripts/evolve.mjs status",
"evolve:start": "node scripts/evolve.mjs start",
"evolve:stop": "node scripts/evolve.mjs stop",
@@ -611,6 +610,8 @@
"@node-saml/node-saml": "^5.1.0",
"@octokit/rest": "^22.0.1",
"@okxweb3/app-x402-core": "^0.2.0",
+ "@pixiv/three-vrm": "^3.5.5",
+ "@pixiv/three-vrm-animation": "^3.5.5",
"@privy-io/js-sdk-core": "^0.75.0",
"@pump-fun/agent-payments-sdk": "^3.0.3",
"@pump-fun/pump-sdk": "^4.0.0",
diff --git a/src/animation-manager.js b/src/animation-manager.js
index 0941eac36..0597a63c6 100644
--- a/src/animation-manager.js
+++ b/src/animation-manager.js
@@ -152,6 +152,8 @@ export class AnimationManager {
this._canonicalToNode = null;
/** @type {boolean} Whether the attached model's rig can play the canonical clip library. */
this._canonicalClipsSupported = false;
+ /** @type {object|null} The attached model's VRM instance (vrm-loader.js), if any. */
+ this._vrm = null;
/** @type {{ avatarId?: string, avatarUrl?: string }} Context for the fallen-pose guard's reports. */
this._avatarContext = {};
/** @type {Set<string>} `${avatarUrl}|${clip}` keys whose fallen-pose has already been reported (debounce). */
@@ -236,6 +238,10 @@ export class AnimationManager {
// clip's ground lands on the model's actual ground.
this._hipGroundLocalY = hipGroundLocalY(model);
this._canonicalClipsSupported = _modelSupportsCanonicalClips(model);
+ // A VRM's spring bones, look-at and expressionManager all live on the vrm
+ // instance stashed by src/game/vrm-loader.js's prepareVrmModel(), not on
+ // any node the mixer touches, so they need their own per-frame tick below.
+ this._vrm = model?.userData?.vrm || null;
for (const [name, clip] of this.clips) {
const bound = this._retarget(clip);
@@ -405,6 +411,7 @@ export class AnimationManager {
this._hipTargetLocalY = 0;
this._hipGroundLocalY = 0;
this._canonicalClipsSupported = false;
+ this._vrm = null;
this.actions.clear();
this.currentAction = null;
this.currentName = null;
@@ -584,6 +591,54 @@ export class AnimationManager {
}
}
+ /**
+ * Load a .vrma (VRM Animation) file and register it like any other clip.
+ * A VRM Animation stores humanoid bone motion keyed by VRM's own canonical
+ * bone taxonomy ('hips', 'leftUpperArm', ...) -- exactly the vocabulary
+ * glb-canonicalize.js's canonicalizeBoneName() already resolves -- so this
+ * reads the parsed VRMAnimation's humanoidTracks directly into a plain
+ * AnimationClip and retargets it through the same canonical-bone pipeline
+ * as every other entry in the library: it plays on a VRM avatar and on a
+ * non-VRM humanoid alike. Both GLTFLoader and @pixiv/three-vrm-animation are
+ * bare-specifier dynamic imports (not a local relative import) so pages
+ * that never touch a .vrma file don't pay for them, and so this file stays
+ * safe to bundle into the headless-chromium pose render page (see
+ * api/_lib/pose-runtime.js, which rejects relative dynamic imports because a
+ * data: URL module has no base to resolve them against).
+ * @param {string} name
+ * @param {string} url
+ * @param {{ loop?: boolean }} [opts]
+ * @returns {Promise<THREE.AnimationClip>}
+ */
+ async loadVrmaAnimation(name, url, opts = {}) {
+ if (this.clips.has(name)) return this.clips.get(name);
+ const [{ GLTFLoader }, { VRMAnimationLoaderPlugin }] = await Promise.all([
+ import('three/addons/loaders/GLTFLoader.js'),
+ import('@pixiv/three-vrm-animation'),
+ ]);
+ const loader = new GLTFLoader();
+ loader.register((parser) => new VRMAnimationLoaderPlugin(parser));
+ const gltf = await loader.loadAsync(url);
+ const vrmAnimation = gltf.userData?.vrmAnimations?.[0];
+ if (!vrmAnimation) throw new Error(`${url} has no VRM animation data`);
+
+ const tracks = [];
+ for (const [boneName, track] of vrmAnimation.humanoidTracks.rotation.entries()) {
+ const next = track.clone();
+ next.name = `${boneName}.quaternion`;
+ tracks.push(next);
+ }
+ for (const [boneName, track] of vrmAnimation.humanoidTracks.translation.entries()) {
+ const next = track.clone();
+ next.name = `${boneName}.position`;
+ tracks.push(next);
+ }
+ if (!tracks.length) throw new Error(`${url} has no humanoid bone tracks`);
+
+ const clip = new AnimationClip(name, vrmAnimation.duration, tracks);
+ return this._registerParsedClip(name, clip, opts);
+ }
+
/** @private Shared finalization for both load paths. */
_registerParsedClip(name, clip, opts) {
this.clips.set(name, clip);
@@ -952,6 +1007,9 @@ export class AnimationManager {
*/
update(delta) {
this.mixer?.update(delta);
+ // Spring-bone physics, look-at and expression blending: the reference
+ // implementation's own per-frame step, independent of the mixer above.
+ this._vrm?.update(delta);
}
/** @returns {string[]} */
diff --git a/src/face-mocap.js b/src/face-mocap.js
index c7ec31146..f2e56581c 100644
--- a/src/face-mocap.js
+++ b/src/face-mocap.js
@@ -21,6 +21,7 @@
import { FaceLandmarker, FilesetResolver } from '@mediapipe/tasks-vision';
import { Matrix4, Euler, MathUtils } from 'three';
import { resolveMorphTargets, setCanonicalMorph, MORPH_ALIASES, ARKIT_52 } from './runtime/arkit52.js';
+import { applyArkitWeightsToVrm } from './game/vrm-expressions.js';
import { modelUrl, visionWasmBase } from './shared/mediapipe-assets.js';
// Runtime + model locations come from the shared resolver: our vendored copy
@@ -138,6 +139,11 @@ export class FaceMocap {
attach(avatarRoot, headBone) {
this._morphResolved = resolveMorphTargets(avatarRoot);
+ // A VRM's face is driven through expressionManager presets, not raw morph
+ // targets named after ARKit shapes (VRM authors name theirs "Joy", "A",
+ // "Blink"...), so resolveMorphTargets() above finds little to nothing on
+ // one. vrm-expressions.js bridges the two; see _applyBlendshapes/playback.
+ this._vrm = avatarRoot?.userData?.vrm || null;
this._headBone = headBone ?? null;
this._headRest = null;
// Reset filters so a fresh avatar doesn't inherit stale smoothing state
@@ -274,11 +280,14 @@ export class FaceMocap {
const f = frames[i];
// Apply blendshapes from the recorded frame (no smoothing — already smooth)
- if (this._morphResolved) {
+ if (this._morphResolved || this._vrm) {
+ const canonicalWeights = {};
for (const [name, score] of Object.entries(f.shapes)) {
const canonical = MORPH_ALIASES[name] ?? name;
- setCanonicalMorph(this._morphResolved, canonical, score);
+ canonicalWeights[canonical] = score;
+ if (this._morphResolved) setCanonicalMorph(this._morphResolved, canonical, score);
}
+ if (this._vrm) applyArkitWeightsToVrm(this._vrm, canonicalWeights);
}
// Head matrix → bone rotation (no filter; recording is post-smoothed)
if (this._headBone && f.mat) {
@@ -333,8 +342,8 @@ export class FaceMocap {
// ── Private ──────────────────────────────────────────────────────────────
_applyBlendshapes(categories, tSec) {
- if (!this._morphResolved) return {};
const out = {};
+ const canonicalWeights = {};
for (const { categoryName, score } of categories) {
// Calibration subtraction — clamp negative deltas at zero so a resting
// face never drives morphs.
@@ -347,8 +356,10 @@ export class FaceMocap {
out[categoryName] = smoothed;
const canonical = MORPH_ALIASES[categoryName] ?? categoryName;
- setCanonicalMorph(this._morphResolved, canonical, smoothed);
+ canonicalWeights[canonical] = smoothed;
+ if (this._morphResolved) setCanonicalMorph(this._morphResolved, canonical, smoothed);
}
+ if (this._vrm) applyArkitWeightsToVrm(this._vrm, canonicalWeights);
return out;
}
diff --git a/src/game/avatar-rig.js b/src/game/avatar-rig.js
index 87ffa17ef..d967fabc2 100644
--- a/src/game/avatar-rig.js
+++ b/src/game/avatar-rig.js
@@ -18,6 +18,7 @@ import { AnimationManager } from '../animation-manager.js';
import { getMeshoptDecoder } from '../viewer/internal.js';
import { GUEST_SENTINEL, resolveGuestAvatar } from './play-handoff.js';
import { installVrmPlugin, prepareVrmModel } from './vrm-loader.js';
+import './vrm-boot.js'; // side effect: registers the real @pixiv/three-vrm plugin
import { log } from '../shared/log.js';
export const AVATAR_DEFAULT = '/avatars/default.glb';
diff --git a/src/game/avatar-thumb.js b/src/game/avatar-thumb.js
index c155ac4a6..aa5c637ff 100644
--- a/src/game/avatar-thumb.js
+++ b/src/game/avatar-thumb.js
@@ -12,7 +12,8 @@ import {
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { AnimationManager } from '../animation-manager.js';
-import { loadManifest, getLocomotionDefs, CLIP_IDLE, dracoLoader, meshoptReady } from './avatar-rig.js';
+import { installVrmPlugin, prepareVrmModel } from './vrm-loader.js';
+import { loadManifest, getLocomotionDefs, CLIP_IDLE, dracoLoader, meshoptReady } from './avatar-rig.js'; // also registers the real VRM plugin (side effect)
import { log } from '../shared/log.js';
import { applyCinematicDefaults, loadEnvironment } from '../shared/cinematic-render.js';
@@ -55,6 +56,7 @@ function hasVisiblePixels() {
// default avatar) preview instead of throwing.
const _loader = new GLTFLoader();
_loader.setDRACOLoader(dracoLoader);
+installVrmPlugin(_loader);
meshoptReady.then((decoder) => { if (decoder) _loader.setMeshoptDecoder(decoder); });
const _cache = new Map(); // url -> Promise<string|null> (PNG data URL)
let _renderer = null;
@@ -126,6 +128,7 @@ async function _snapshot(url) {
if (!ensureRenderer()) return null;
await meshoptReady; // ensure the decoder is wired before the first parse
const gltf = await _loader.loadAsync(url);
+ prepareVrmModel(gltf);
const model = gltf.scene;
model.traverse((n) => { if (n.isMesh) n.frustumCulled = false; });
_scene.add(model);
diff --git a/src/game/boot-avatar.js b/src/game/boot-avatar.js
index 6c7343982..1bf572338 100644
--- a/src/game/boot-avatar.js
+++ b/src/game/boot-avatar.js
@@ -21,10 +21,11 @@ import {
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { AnimationManager } from '../animation-manager.js';
+import { installVrmPlugin, prepareVrmModel } from './vrm-loader.js';
import {
AVATAR_DEFAULT, loadManifest, getLocomotionDefs, CLIP_IDLE,
resolveAvatarUrl, dracoLoader, meshoptReady,
-} from './avatar-rig.js';
+} from './avatar-rig.js'; // also registers the real VRM plugin (side effect)
import { getRequestedAvatar } from './play-handoff.js';
import { log } from '../shared/log.js';
import { applyCinematicDefaults, loadEnvironment } from '../shared/cinematic-render.js';
@@ -79,12 +80,14 @@ function boot() {
// the default on any resolve/load failure so a broken pick never wedges the loader.
const loader = new GLTFLoader();
loader.setDRACOLoader(dracoLoader);
+ installVrmPlugin(loader);
meshoptReady
.then((decoder) => { if (decoder) loader.setMeshoptDecoder(decoder); })
.then(() => resolveAvatarUrl(getRequestedAvatar()))
.then((chosen) => loader.loadAsync(chosen).catch(() => loader.loadAsync(AVATAR_DEFAULT)))
.then(async (gltf) => {
if (!alive) return;
+ prepareVrmModel(gltf);
model = gltf.scene;
model.traverse((n) => { if (n.isMesh) { n.frustumCulled = false; n.castShadow = false; } });
scene.add(model);
diff --git a/src/game/vrm-boot.js b/src/game/vrm-boot.js
new file mode 100644
index 000000000..d8874430f
--- /dev/null
+++ b/src/game/vrm-boot.js
@@ -0,0 +1,11 @@
+// Side-effect module: wires pixiv/three-vrm (MIT) in as the reference VRM
+// implementation for every GLTFLoader in the app that calls installVrmPlugin().
+// Import this once, for its side effect only, from each entry point that loads
+// avatars or props (src/game/avatar-rig.js covers /play; other entry points
+// import it directly). Keeping the registration here, instead of inside
+// src/game/vrm-loader.js itself, keeps that module importable on its own with
+// no real dependency, which is what tests/vrm-loader.test.js relies on.
+import { VRMLoaderPlugin, VRMUtils } from '@pixiv/three-vrm';
+import { setVrmPluginFactory } from './vrm-loader.js';
+
+setVrmPluginFactory((parser) => new VRMLoaderPlugin(parser), { VRMUtils });
diff --git a/src/game/vrm-expressions.js b/src/game/vrm-expressions.js
new file mode 100644
index 000000000..9a82f84aa
--- /dev/null
+++ b/src/game/vrm-expressions.js
@@ -0,0 +1,97 @@
+// ARKit-52 -> VRM expression-preset driver (best3d order 075, task 2).
+//
+// Voice/face capture across the site (src/voice/talk-emotes.js and friends)
+// already speaks ARKit-52 blendshape weights. A VRM avatar's face is not a
+// blendshape target list: pixiv/three-vrm exposes a small, discrete preset set
+// (vrm.expressionManager, VRM-1.0 names, which the library normalizes VRM 0.x's
+// PascalCase preset names into on load) -- visemes (aa/ih/ou/ee/oh), emotions
+// (happy/angry/sad/relaxed/surprised) and blink. Rather than hand-author a
+// second ARKit<->VRM table, this module inverts the existing, reviewed
+// VRM->ARKit map in src/voice/arkit-blendshapes.js (VRM_TO_ARKIT): each VRM
+// preset's weighted ARKit combination becomes a basis vector, and an incoming
+// ARKit weight set is scored against every preset by projecting onto that
+// vector (dot(incoming, preset) / dot(preset, preset)), so "how much of this
+// preset's pattern is present in the capture" comes out as a single 0..1
+// number per preset, with no duplicated expression data to drift out of sync.
+
+import { VRM_TO_ARKIT } from '../voice/arkit-blendshapes.js';
+
+// VRM-1.0 expressionManager preset name -> the VRM_TO_ARKIT key that carries
+// its ARKit combination. VRM_TO_ARKIT keeps both the 0.x and 1.0 spellings for
+// visemes (Aa/A/Ah) and emotions (Joy/Happy); one representative per preset is
+// enough as a basis vector since the aliases resolve to the same weights.
+const PRESET_SOURCE = {
+ aa: 'Aa', ih: 'Ih', ou: 'Ou', ee: 'Ee', oh: 'Oh',
+ happy: 'Joy', angry: 'Angry', sad: 'Sad', surprised: 'Surprised', relaxed: 'Fun',
+ blink: 'Blink', blinkLeft: 'BlinkL', blinkRight: 'BlinkR',
+};
+
+/** VRM-1.0 preset name -> { arkitName: weight } basis vector. */
+export const VRM1_EXPRESSION_TO_ARKIT = Object.freeze(
+ Object.fromEntries(
+ Object.entries(PRESET_SOURCE).map(([preset, key]) => [preset, VRM_TO_ARKIT[key]]),
+ ),
+);
+
+/** Every VRM-1.0 preset name this module knows how to drive from ARKit weights. */
+export const VRM_EXPRESSION_PRESETS = Object.freeze(Object.keys(VRM1_EXPRESSION_TO_ARKIT));
+
+/**
+ * How much of `preset`'s ARKit pattern is present in `weights`?
+ * Projection coefficient dot(weights, preset) / dot(preset, preset): 0 when the
+ * incoming weights have none of this preset's shapes active, ~1 when they match
+ * the preset's own combination at full intensity, clamped so a louder-than-the-
+ * preset capture (e.g. jawOpen pinned to 1 while the preset only calls for 0.5)
+ * cannot overshoot 1 and fight sibling presets in expressionManager.
+ *
+ * @param {Record<string, number>} weights ARKit-52 name -> 0..1
+ * @param {Record<string, number>} preset ARKit-52 name -> 0..1 basis vector
+ * @returns {number} 0..1
+ */
+function projectWeight(weights, preset) {
+ let dot = 0;
+ let normSq = 0;
+ for (const [name, w] of Object.entries(preset)) {
+ dot += (weights[name] || 0) * w;
+ normSq += w * w;
+ }
+ if (normSq <= 0) return 0;
+ return Math.max(0, Math.min(1, dot / normSq));
+}
+
+/**
+ * Score an ARKit-52 weight set against every VRM expression preset this
+ * module maps. Pure, no VRM instance required, so it is testable and reusable
+ * on the server (export validation, preview tooling) without a GL context.
+ *
+ * @param {Record<string, number>} arkitWeights ARKit-52 name -> 0..1
+ * @returns {Record<string, number>} VRM-1.0 preset name -> 0..1
+ */
+export function arkitWeightsToVrmExpressions(arkitWeights) {
+ const weights = arkitWeights || {};
+ const out = {};
+ for (const [preset, vector] of Object.entries(VRM1_EXPRESSION_TO_ARKIT)) {
+ out[preset] = projectWeight(weights, vector);
+ }
+ return out;
+}
+
+/**
+ * Drive a loaded VRM's expressionManager straight from an ARKit-52 weight set
+ * (the same shape voice/face capture already produces for every other avatar).
+ * No-op (returns false) when `vrm` has no expressionManager, e.g. a VRM parsed
+ * without the reference plugin installed, or a non-VRM model.
+ *
+ * @param {object} vrm a VRMCore instance (vrm.expressionManager)
+ * @param {Record<string, number>} arkitWeights ARKit-52 name -> 0..1
+ * @returns {boolean} whether anything was applied
+ */
+export function applyArkitWeightsToVrm(vrm, arkitWeights) {
+ const em = vrm?.expressionManager;
+ if (!em) return false;
+ const presets = arkitWeightsToVrmExpressions(arkitWeights);
+ for (const [name, weight] of Object.entries(presets)) {
+ em.setValue(name, weight);
+ }
+ return true;
+}
diff --git a/src/game/vrm-loader.js b/src/game/vrm-loader.js
index c7db1858e..714d02cd3 100644
--- a/src/game/vrm-loader.js
+++ b/src/game/vrm-loader.js
@@ -16,29 +16,28 @@
// holes under a standard material.
//
// This module fixes all three on the plain-glTF path, so VRM avatars and props
-// work today with no new dependency, and the skeleton is picked up by
-// src/glb-canonicalize.js, which already maps both VRM 0.x (`J_Bip_C_Hips`) and
-// VRM 1.0 (`upperChest`) bone naming onto the canonical rig: so the pre-baked
-// idle/walk/emote clips retarget onto a VRM the same as any other humanoid.
+// still work with zero dependencies if the reference implementation is ever
+// unavailable, and the skeleton is picked up by src/glb-canonicalize.js, which
+// already maps both VRM 0.x (`J_Bip_C_Hips`) and VRM 1.0 (`upperChest`) bone
+// naming onto the canonical rig: so the pre-baked idle/walk/emote clips
+// retarget onto a VRM the same as any other humanoid.
//
// ── The @pixiv/three-vrm seam ────────────────────────────────────────────────
-// What the plain path does NOT reproduce is MToon's toon shading + outlines,
-// spring-bone physics (hair/skirt secondary motion), the humanoid normalization
-// rig, blend-shape expression presets and look-at. Those need the reference
-// implementation. `setVrmPluginFactory()` is the single integration point for it:
-// call it once at boot with a factory that returns a GLTFLoader plugin, and every
+// The plain path does NOT reproduce MToon's toon shading + outlines, spring-bone
+// physics (hair/skirt secondary motion), the humanoid normalization rig,
+// blend-shape expression presets or look-at. Those need the reference
+// implementation, pixiv/three-vrm (MIT). `setVrmPluginFactory()` is the single
+// integration point for it: src/game/vrm-boot.js calls it once, as a side
+// effect, with a factory that returns a GLTFLoader plugin, and every
// avatar/prop load in the app routes through it automatically: no call site
-// changes. To light it up:
+// changes beyond importing vrm-boot.js once per entry point.
//
-// npm install @pixiv/three-vrm
-//
-// // src/game/boot-avatar.js (or any boot path), once:
-// import { VRMLoaderPlugin, VRMUtils } from '@pixiv/three-vrm';
-// import { setVrmPluginFactory } from './vrm-loader.js';
-// setVrmPluginFactory((parser) => new VRMLoaderPlugin(parser), { VRMUtils });
-//
-// Until that call happens the plain path above runs, which is a real, working
-// VRM load, not a stub: nothing here fakes support it doesn't have.
+// When the plugin is installed, `prepareVrmModel` stashes the parsed VRM
+// instance at `scene.userData.vrm` (in addition to `gltf.userData.vrm`, which
+// GLTFLoader already sets), so code that only holds the scene graph (anything
+// downstream of `src/animation-manager.js`'s `attach()`) can still reach
+// `vrm.update(delta)`, `vrm.expressionManager` and `vrm.lookAt` without
+// threading the original `gltf` result through every call site.
import { Box3, Vector3, DoubleSide } from 'three';
import { log } from '../shared/log.js';
@@ -154,6 +153,9 @@ export function prepareVrmModel(gltf) {
} catch (e) {
log.warn('[vrm-loader] VRMUtils pass failed', e?.message || e);
}
+ // AnimationManager.attach() only ever sees the scene graph, not this gltf
+ // result, so it cannot otherwise reach vrm.update()/expressionManager.
+ scene.userData.vrm = vrm;
} else if (version === 0) {
// Plain-glTF path: VRM 0.x faces -Z, everything else in this app faces +Z.
// Rotating the scene root (rather than the hips) keeps the skeleton's local
diff --git a/src/game/world-objects.js b/src/game/world-objects.js
index 1393e0ff1..52d880a8e 100644
--- a/src/game/world-objects.js
+++ b/src/game/world-objects.js
@@ -26,6 +26,8 @@ import {
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { getMeshoptDecoder } from '../viewer/internal.js';
+import { installVrmPlugin, prepareVrmModel } from './vrm-loader.js';
+import './vrm-boot.js'; // side effect: registers the real @pixiv/three-vrm plugin
import { log } from '../shared/log.js';
// Same lerp constant RemotePlayer uses, so objects glide between server updates
@@ -210,6 +212,7 @@ function propCrystal() {
// ── GLB template cache (shared geometry/materials across instances) ──────────
const _gltf = new GLTFLoader();
+installVrmPlugin(_gltf); // world props can be .vrm uploads too (P3.3/P3.4)
// three.ws GLBs may carry EXT_meshopt_compression — decoder required before load
const _meshoptReady = getMeshoptDecoder().then((d) => _gltf.setMeshoptDecoder(d));
const _glbCache = new Map(); // url → { template, waiters:[] }
@@ -220,6 +223,7 @@ function loadTemplate(url) {
rec = { template: null, failed: false, waiters: [], failures: [] };
_glbCache.set(url, rec);
_meshoptReady.then(() => _gltf.load(url, (gltf) => {
+ prepareVrmModel(gltf);
const root = gltf.scene;
root.traverse((o) => { if (o.isMesh) { o.castShadow = true; o.receiveShadow = true; } });
rec.template = root;
diff --git a/src/viewer.js b/src/viewer.js
index 674c5cbb2..621aa2347 100644
--- a/src/viewer.js
+++ b/src/viewer.js
@@ -57,6 +57,8 @@ 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 {
@@ -1277,11 +1279,13 @@ export class Viewer {
.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 || [];