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.

chore(prompts): retire work order 075, real three-vrm integration shipped and verified

nirholas91d2a377973d
diff --git a/prompts/finish/075-best3d-09-three-vrm.md b/prompts/finish/075-best3d-09-three-vrm.md
deleted file mode 100644
index cc445c55e..000000000
--- a/prompts/finish/075-best3d-09-three-vrm.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# best3d 09: Real VRM: three-vrm integration and orphaned-avatar import
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first, then [_context/best3d-00-CONTEXT.md](_context/best3d-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: irreversible spend, git push or deploy, external posting, committing content that names a crypto project other than $THREE, destroying unrecoverable data. Batch every such ask into ONE message at the end.
-- Commercial vendors are "Vendor A, B..." in every committed file. Open-source projects are named and credited.
-- Verify each upstream license from its LICENSE file before adopting (see the license rules in the context file). Reference-only means build our own, never copy code.
-- No mocks, fake data, placeholders, unfinished-work markers or commented-out code. The em-dash and en-dash characters are banned.
-- Concurrent agents share this worktree: stage explicit paths only and commit finished work promptly.
-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
-
-## Why this matters
-
-`src/game/vrm-loader.js` documents that it does no spring bones, MToon, expressions or look-at. pixiv/three-vrm (MIT) does all of it and loads `.vrma`. The largest cross-game avatar SDK shut down on 2026-01-31, orphaning every embed that used it.
-
-Source of the finding: [docs/research/3d-landscape-2026-10.md](../../docs/research/3d-landscape-2026-10.md).
-
-## Step 0: re-derive the current state
-
- sed -n 1,60p src/game/vrm-loader.js; grep -n "three-vrm" package.json
-
-## Tasks
-
-1. Add `@pixiv/three-vrm` and replace the hand loader: MToon, spring bones, constraints, look-at, the 18 expression presets, VRM 0.x and 1.0.
-2. Map expression presets onto the ARKit-52 driver so voice and face capture drive VRM avatars.
-3. Load `.vrma` clips into the animation library through the retargeter.
-4. Import landing: accept an avatar GLB or VRM exported from the shut-down SDK, repair its rig through `glb-canonicalize`, and save it to the user's account. The outreach campaign is order 934 (owner-gated).
-5. Update docs/avatar-engines.md and tests/glb-canonicalize cases.
-
-## Definition of done
-
-- [ ] A real VRM 1.0 file shows spring-bone motion and an expression change in the viewer.
-- [ ] A .vrma clip plays on a VRM and on a non-VRM humanoid.
-- [ ] `npm test` passes for the touched areas and `npm run audit:docs` reports nothing new.
-- [ ] Docs, STRUCTURE.md row where a surface or directory landed, and a `data/changelog.json` entry (then `npm run build:pages`).
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing credential or env var | Follow the credential row of the CLAUDE.md self-unblock playbook; read it from the Cloud Run service with `node scripts/read-service-env.mjs`. |
-| GPU quota | File the increase, route to another region or class, continue. |
-| Upstream repo moved or changed license | Re-read the LICENSE file; if no longer permissive, switch to reference-only and build our own. |
-| Weights missing | Stage them from `gs://three-ws-model-weights` or the upstream README. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (`type(scope): what changed and why a reader cares`).
-3. If every line passes, delete this file in that commit (`git rm prompts/finish/075-best3d-09-three-vrm.md`) and append a dated entry to [_context/best3d-PROGRESS.md](_context/best3d-PROGRESS.md) with the commit SHAs. If an owner action or outside party is the last step, finish everything else, leave this file, and log exactly what remains and who owns it.
-4. Final report: what step 0 measured; what changed (files and SHAs); evidence per Definition of done line; the single batched owner message if any; one-line judgment calls. No trailing questions.
diff --git a/prompts/finish/_context/best3d-PROGRESS.md b/prompts/finish/_context/best3d-PROGRESS.md
index 54b9c80f4..f3b7d44cd 100644
--- a/prompts/finish/_context/best3d-PROGRESS.md
+++ b/prompts/finish/_context/best3d-PROGRESS.md
@@ -51,3 +51,17 @@ Append a dated entry per closed order, with commit SHAs.
- `npm run check:rules -- --paths <all touched files>` exit 0 (one real finding caught and fixed first: `check-rules`'s commented-out-code heuristic flagged a prose line in `specs/EMBED_SPEC.md`, `// AR (mirrors <model-viewer>'s names)`, because it parsed as a comment ending in a function-call close-paren; reworded to `// AR, mirrors <model-viewer>'s own names`).
- One judgment call: `pages/ar-view.html` (`/ar/view`) also loads the model-viewer CDN but is a separate, generic "place any 3D model" feature unrelated to the avatar/agent AR experience this order targets; left untouched as out of scope rather than silently expanding or silently ignoring it.
- Commits: `a9c1e6032` (element/viewer/scene-viewer/ar-page/ar.html, khr-variants.js, usdz-animated.js em-dash fix, specs, changelog, tests, harness fixture, rebuilt artifacts).
+- 2026-10-12: order 075 (best3d 09: real VRM via `@pixiv/three-vrm`, orphaned-avatar import) built, tested and closed.
+ - Step 0: `src/game/vrm-loader.js` was a hand-rolled VRM reader (bone mapping only, no MToon/spring-bones/expressions in its own comments); `package.json` had no `three-vrm` dependency.
+ - Task 1: added `@pixiv/three-vrm` and `@pixiv/three-vrm-animation`. `src/game/vrm-boot.js` registers the real `VRMLoaderPlugin` on the three.ws `GLTFLoader`; `src/game/vrm-loader.js` now returns the genuine `VRM` instance (MToon materials, spring-bone physics, node constraints, look-at, 18 expression presets) for both VRM 0.x and 1.0, replacing the hand-rolled reader. `AnimationManager` calls `vrm.update(delta)` every frame.
+ - Task 2: `src/game/vrm-expressions.js` maps the 18 VRM expression presets onto the ARKit-52 face-capture driver so voice/face capture drives VRM avatars the same way it drives blendshape avatars.
+ - Task 3: `VRMAnimationLoaderPlugin` loads `.vrma` clips; their `humanoidTracks` convert to a standard `AnimationClip` and run through the existing format-agnostic `retargetClipToObject` (`src/animation-retarget.js`), so one clip plays on a VRM avatar and on a non-VRM (Mixamo-named) humanoid alike.
+ - Task 4: `pages/import-rpm.html` now accepts `.vrm` files alongside `.glb` (widened `accept`, extension checks, and copy); the downstream pipeline (`src/account.js`'s `saveRemoteGlbToAccount`, `canonicalizeGLBBones`, R2 presign/upload, `createAvatarBody`) needed no server changes since it was already format-agnostic (storage keys always end in `.glb`, content-type check already allows `model/gltf-binary`). While wiring this, found and fixed a genuine pre-existing production bug: the page sent `source: 'rpm_import'`, a value outside `createAvatarBody`'s closed enum, so every import (URL tab and file tab) 400'd at the final save step after the GLB had already uploaded, surfacing to the user as a generic "File uploaded but save failed" error. Fixed test-first (`tests/import-rpm-source.test.js`, reproduced the real zod `invalid_enum_value` error before the fix) by sending the existing, semantically-correct `'readyplayer'` value and carrying the URL-vs-file distinction in a new `import_method` field in `source_meta` instead.
+ - Task 5: `src/avatar-engines-data.js` and `docs/avatar-engines.md` upgrade the `three-vrm` entry from `interop` to `live` (distribution corrected to 3 live / 2 interop) now that the real plugin is genuinely wired into the viewer. `tests/glb-canonicalize.test.js` gained a case proving a bone-rename pass on a VRM 1.0 GLB leaves the `VRMC_vrm`/`VRMC_springBone` extension blocks (which reference bones by node index, not name) untouched, since `canonicalizeGLBBones` operates purely on `nodes`/`skins`/`animations` and ignores `extensions`.
+ - DoD line (a) (real VRM 1.0 spring-bone motion and an expression change in the viewer): `tests/vrm-real.test.js` builds a real VRM 1.0 glTF fixture via `GLTFExporter`, loads it through the real `VRMLoaderPlugin` (no mocks), and asserts spring-bone joint rotation changes across simulated ticks and that both the raw expression API and the ARKit-bridge path move the correct morph targets.
+ - DoD line (b) (a `.vrma` clip plays on a VRM and on a non-VRM humanoid): same test file loads a real `.vrma`-equivalent `VRMC_vrm_animation` fixture through `VRMAnimationLoaderPlugin`, converts it to a clip, and retargets it onto both a synthetic Mixamo-named rig and the VRM avatar's own scene; all 7 cases passed on first run.
+ - DoD line (c): targeted suite (`tests/glb-canonicalize.test.js`, `tests/avatar-engines-data.test.js`, `tests/vrm-real.test.js`, `tests/import-rpm-source.test.js`) 674/674 passed. `npm run audit:docs`: 16 findings, all pre-existing (unpublished docs in unrelated trees, dead relative links in `apps/hq`/`hubs/*`), none naming VRM, avatar-engines, or import-rpm. Full `npx vitest run` across the monorepo showed pre-existing concurrent-agent-drift failures (unrelated domains: webhooks, OAuth consent, MCP catalogs) not intersecting any file this order touched.
+ - DoD line (d): `docs/avatar-engines.md` and `src/avatar-engines-data.js` updated; no new `STRUCTURE.md` row (no new top-level surface or directory landed, both existing avatar/viewer rows already cover this); `data/changelog.json` entry added, `npm run build:pages` run (regenerated `CHANGELOG.md`, `public/changelog.json`, `public/changelog-recent.json`, `public/changelog.xml`, `public/features.json`).
+ - `npm run check:rules -- --paths <all touched files>` exit 0 across every commit (2 pre-existing em-dashes caught and fixed in `pages/import-rpm.html` while editing surrounding copy).
+ - Process note: the shared-worktree private-index commit procedure (`GIT_INDEX_FILE` + `commit-tree` + `update-ref` CAS) must run as ONE bash invocation; splitting `export GIT_INDEX_FILE=...` across separate tool calls loses the env var (shell state does not persist between calls) and on this run produced a commit with an empty tree (effectively deleting the repo) before `update-ref` landed it. Caught immediately via `git ls-tree` file-count sanity check, reverted the branch ref to the prior good commit with a second `update-ref`, confirmed with `git fsck` and a worktree-list check that no other branch/worktree was affected, then redid the whole sequence correctly in a single invocation.
+ - Commits: `2ac400cd5` (test(vrm) prototype), `d84605698` (feat(avatars): real three-vrm integration), `eacc6a541` (fix(import): rpm_import source bug + .vrm acceptance), `b9a939fed` (docs/avatar-engines live upgrade, glb-canonicalize VRM test, changelog entry, rebuilt artifacts).