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(rig): map MikuMikuDance Japanese bone names so MMD avatars animate

nirholas820507af3552
diff --git a/docs/rig-doctor.md b/docs/rig-doctor.md
index 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.js
index 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.js
index 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.js
index 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.js
index 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');