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
feat(rig): map MikuMikuDance Japanese bone names so MMD avatars animate
nirholas820507af3552
diff --git a/docs/rig-doctor.md b/docs/rig-doctor.mdindex cb36478ad..7d2418ca8 100644--- a/docs/rig-doctor.md+++ b/docs/rig-doctor.md@@ -116,6 +116,7 @@ The convention detector reports which authoring tool your skeleton came from and| Ready Player Me | `Wolf3D_*` mesh nodes over a Mixamo skeleton | `rpm` || Mixamo | `mixamorig:` joint prefix | `mixamo` || VRM / VRoid | `J_Bip_*` humanoid joint names | `vrm-humanoid` |+| MikuMikuDance (PMX/PMD) | Japanese PMX bone names (`センター`, `上半身`, `左腕`) | `custom` || Reallusion Character Creator | `CC_Base_*` joint prefix | `custom` || Unreal Engine mannequin | `pelvis`, `thigh_l`, `clavicle_l` | `custom` || 3ds Max Biped | `Bip01` / `Bip001` prefix | `custom` |diff --git a/src/glb-canonicalize.js b/src/glb-canonicalize.jsindex c36d26e72..26edf9aae 100644--- a/src/glb-canonicalize.js+++ b/src/glb-canonicalize.js@@ -11,6 +11,7 @@// • Unreal mannequin: `pelvis`, `clavicle_l`, `upperarm_l`, `thigh_l`, `calf_l`, … (alias map)// • VRM / VRoid: `J_Bip_C_Hips`, `J_Bip_L_UpperArm`, `J_Bip_L_Little1` (alias map)// • VRM 1.0: `upperChest`, `leftUpperArm`, `leftLowerLeg`, `leftToes` (camelCase)+// • MMD (PMX/PMD): `センター`, `上半身`, `左腕`, `左ひじ`, `左ひざ` (Japanese, 左/右 side prefix)// • Daz / Genesis: `hip`, `abdomen`, `lShldr`, `lForeArm`, `lThigh`, `lShin`, `lCollar`// • MakeHuman: `upperarm.L`, `shin.L`, `clavicle.L` (shared with Unreal/Blender stems)// • Simple rigs: `shoulderL`, `elbowL`, `wristL`, `hipL`, `kneeL`, `ankleL`, `chest`@@ -163,6 +164,36 @@ const EXTRA_ALIASES = (() => {}}+ // MikuMikuDance (PMX/PMD) skeletons name every bone in Japanese, with the+ // side carried by a leading 左 (left) / 右 (right) character. No spelling+ // here shares a stem with any Latin convention, so the whole rig previously+ // mapped zero joints and animated nothing. Sides are listed explicitly+ // rather than derived, because the SIDED table below swaps Latin side+ // tokens (left→right, l→r, L→R) and cannot reach a Japanese prefix.+ //+ // Deliberately NOT mapped: the IK targets (左足IK, 左つま先IK) and the+ // twist bones (左腕捩, 左手捩). Neither is a chain joint. MMD drives the leg+ // chain from the IK target, so binding a clip to it would fight the chain+ // it is supposed to solve, and the twist bones are secondary deformers that+ // tear the mesh when rotated as if they were the limb.+ for (const [v, c] of [+ ['センター', 'Hips'], ['下半身', 'Hips'],+ ['上半身', 'Spine'], ['上半身2', 'Spine1'],+ ['首', 'Neck'], ['頭', 'Head'],+ ]) put(v, c);+ for (const [jp, side] of [['左', 'Left'], ['右', 'Right']]) {+ for (const [v, c] of [+ ['肩', 'Shoulder'], ['腕', 'Arm'], ['ひじ', 'ForeArm'], ['手首', 'Hand'],+ ['足', 'UpLeg'], ['ひざ', 'Leg'], ['足首', 'Foot'], ['つま先', 'ToeBase'],+ ]) put(`${jp}${v}`, `${side}${c}`);+ // MMD finger chains. 親指 (thumb) is numbered 0-2, every other digit 1-3.+ // 人指 is the index finger; some exporters spell it 人差指.+ for (const [jp2, cf] of [['人指', 'Index'], ['人差指', 'Index'], ['中指', 'Middle'], ['薬指', 'Ring'], ['小指', 'Pinky']]) {+ for (let n = 1; n <= 3; n++) put(`${jp}${jp2}${n}`, `${side}Hand${cf}${n}`);+ }+ for (let n = 0; n <= 2; n++) put(`${jp}親指${n}`, `${side}HandThumb${n + 1}`);+ }+// Centre / torso bones with no side (VRM 1.0, Daz, generic single-chest rigs).for (const [v, c] of [['chest', 'Spine1'], ['lowerChest', 'Spine1'], ['chestLower', 'Spine1'],diff --git a/src/rig-report.js b/src/rig-report.jsindex ecb29b772..4da934cbd 100644--- a/src/rig-report.js+++ b/src/rig-report.js@@ -88,6 +88,11 @@ const CONVENTIONS = [test: (ctx) => ctx.joints.some((n) => /^J_(Bip|Sec|Adj)_/i.test(n)),evidence: 'J_Bip_* humanoid joint names',},+ {+ id: 'mmd', label: 'MikuMikuDance (PMX/PMD)', schema: 'custom',+ test: (ctx) => ctx.joints.some((n) => /^(センター|上半身2?|下半身|[左右](腕|ひじ|ひざ|手首|足首))$/.test(n)),+ evidence: 'Japanese PMX bone names (センター / 上半身 / 左腕)',+ },{id: 'reallusion', label: 'Reallusion Character Creator', schema: 'custom',test: (ctx) => ctx.joints.some((n) => /^CC_Base_/i.test(n)),@@ -181,7 +186,7 @@ function jointNodeIndices(json) {return set;}-function detectConvention(ctx) {+export function detectConvention(ctx) {for (const c of CONVENTIONS) {let hit = false;try {diff --git a/tests/glb-canonicalize.test.js b/tests/glb-canonicalize.test.jsindex f65c870ce..85f5996a7 100644--- a/tests/glb-canonicalize.test.js+++ b/tests/glb-canonicalize.test.js@@ -942,6 +942,75 @@ describe('anatomical-Latin skeleton', () => {});});+describe('MMD (MikuMikuDance) Japanese skeleton', () => {+ it.each([+ ['センター', 'Hips'],+ ['下半身', 'Hips'],+ ['上半身', 'Spine'],+ ['上半身2', 'Spine1'],+ ['首', 'Neck'],+ ['頭', 'Head'],+ ])('centre chain: %s → %s', (input, expected) => {+ expect(canonicalizeBoneName(input)).toBe(expected);+ });++ it.each([+ ['左肩', 'LeftShoulder'],+ ['左腕', 'LeftArm'],+ ['左ひじ', 'LeftForeArm'],+ ['左手首', 'LeftHand'],+ ['左足', 'LeftUpLeg'],+ ['左ひざ', 'LeftLeg'],+ ['左足首', 'LeftFoot'],+ ['左つま先', 'LeftToeBase'],+ ['右肩', 'RightShoulder'],+ ['右腕', 'RightArm'],+ ['右ひじ', 'RightForeArm'],+ ['右手首', 'RightHand'],+ ['右足', 'RightUpLeg'],+ ['右ひざ', 'RightLeg'],+ ['右足首', 'RightFoot'],+ ['右つま先', 'RightToeBase'],+ ])('limbs: %s → %s', (input, expected) => {+ expect(canonicalizeBoneName(input)).toBe(expected);+ });++ it.each([+ ['左人指1', 'LeftHandIndex1'],+ ['左人差指2', 'LeftHandIndex2'],+ ['左中指3', 'LeftHandMiddle3'],+ ['左薬指1', 'LeftHandRing1'],+ ['左小指2', 'LeftHandPinky2'],+ ['右人指3', 'RightHandIndex3'],+ ['右小指1', 'RightHandPinky1'],+ ])('finger chains: %s → %s', (input, expected) => {+ expect(canonicalizeBoneName(input)).toBe(expected);+ });++ it('shifts the 0-indexed thumb onto the 1-indexed canonical chain', () => {+ expect(canonicalizeBoneName('左親指0')).toBe('LeftHandThumb1');+ expect(canonicalizeBoneName('左親指1')).toBe('LeftHandThumb2');+ expect(canonicalizeBoneName('左親指2')).toBe('LeftHandThumb3');+ expect(canonicalizeBoneName('右親指0')).toBe('RightHandThumb1');+ });++ it('leaves IK targets, twist bones, and non-joint control bones unmapped', () => {+ for (const name of ['左足IK', '左つま先IK', '右足IK', '左腕捩', '左手捩', '全ての親', 'グルーブ', '両目']) {+ expect(canonicalizeBoneName(name), name).toBeNull();+ }+ });++ it('never crosses sides', () => {+ const left = ['左肩', '左腕', '左ひじ', '左手首', '左足', '左ひざ', '左足首', '左つま先', '左人指1', '左親指0'];+ for (const name of left) {+ expect(canonicalizeBoneName(name)?.startsWith('Left'), name).toBe(true);+ }+ for (const name of left.map((n) => n.replace(/^左/, '右'))) {+ expect(canonicalizeBoneName(name)?.startsWith('Right'), name).toBe(true);+ }+ });+});+describe('canonicalizeJointNodes (in-place rewrite)', () => {it('only touches nodes referenced by skins[].joints', () => {const json = {diff --git a/tests/rig-report.test.js b/tests/rig-report.test.jsindex 0cd3c7862..777bd9eb7 100644--- a/tests/rig-report.test.js+++ b/tests/rig-report.test.js@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';import { dirname, join } from 'node:path';import {analyzeGlb,+ detectConvention,readGlbJson,manifestFromReport,formatBytes,@@ -51,6 +52,24 @@ describe('readGlbJson', () => {});});+describe('detectConvention fingerprints', () => {+ const ctx = (joints, meshNames = []) => ({ joints, meshNames, json: {} });++ it('identifies an MMD rig from its Japanese PMX bone names', () => {+ const c = detectConvention(ctx(['センター', '上半身', '左腕', '左ひじ', '右ひざ']));+ expect(c.id).toBe('mmd');+ expect(c.label).toBe('MikuMikuDance (PMX/PMD)');+ });++ it('does not claim MMD for a Latin-named rig', () => {+ expect(detectConvention(ctx(['Hips', 'Spine', 'LeftArm', 'RightArm'])).id).not.toBe('mmd');+ });++ it('reports unknown rather than guessing when nothing fingerprints', () => {+ expect(detectConvention(ctx(['bone_a', 'bone_b', 'bone_c'])).id).toBe('unknown');+ });+});+describe('analyzeGlb verdicts', () => {it('passes the canonical Avaturn reference rig with every joint mapped', () => {const r = report('cz');