@yohawing/three-mmd-loader

A library for loading and playing back MMD models and motions on Three.js.

日本語 / Live demo

Screenshot assets: model Tda式初音ミク V4X by Tda, motion ラビットホール by mobiusP.

Compatibility Matrix

Formats

Format	Parse	Runtime apply
PMX (model)	✅	✅
PMD (model)	✅	✅
VMD (motion)	✅	✅
VPD (pose)	✅	✅
PMM (project)	❌	❌
.x / .vac (accessory)	❌	❌
.emm / .emd (effect project)	❌	❌
.fx (MME effect)	❌	❌

Features

Feature	Status
Parser	✅ PMX / PMD / VMD / VPD TypeScript parser
Deform / skinning	✅ BDEF1/2/4, SDEF, QDEF
MMD material / toon shader	✅ Toon textures, alpha blending decisions, and material render ordering
Append transform	✅ PMX layer order
IK link angle limits	✅ PMX / PMD link limits with parent-local Euler clamp
VMD Camera / Light	✅ Applies to Three.js Camera and DirectionalLight
Self Shadow	✅ Three.js shadow-map path with VMD self-shadow sampling
Physics	✅ MMD-optimized prebuilt Bullet Physics; Ammo.js backend is deprecated compatibility path
Soft Body	⚠️ PMX data parsed; runtime simulation not implemented

The default PMX runtime and WASM parser are backed by yohawing/mmd-anim.

Acknowledgements

This project was developed with reference to:

• Babylon-MMD
• saba
• nanoem

---

Install

npm install @yohawing/three-mmd-loader three

Usage - Model Loading

import { ThreeMmdLoader } from "@yohawing/three-mmd-loader";

const loader = new ThreeMmdLoader();
const model = await loader.loadModel(source); // Uint8Array | ArrayBuffer | File | string (URL/path resolved via fetch)
scene.add(model.root);

Usage - Animation

import * as THREE from "three";
import { applyMmdCameraStateToThreeCamera } from "@yohawing/three-mmd-loader";

const model = await loader.loadModel(modelSource);
const { animation } = await loader.loadAnimation(vmdSource);
model.setAnimation(animation);

const perspectiveCamera = new THREE.PerspectiveCamera();

// Per frame.
model.update(currentSeconds);
const cameraState = model.runtime.cameraState();
if (cameraState) {
  const activeCamera = applyMmdCameraStateToThreeCamera(perspectiveCamera, cameraState, {
    aspect: renderer.domElement.clientWidth / renderer.domElement.clientHeight
  });
  renderer.render(scene, activeCamera);
}

applyMmdCameraStateToThreeCamera(...) converts MMD camera coordinates for Three.js and returns the active camera.

Usage - Pose (VPD)

const { pose } = await loader.loadPose(vpdSource);
const { animation } = await loader.loadPoseAnimation(vpdSource, "myPose");
model.setAnimation(animation);

Usage - Physics

Physics is abstracted behind MmdPhysicsBackend so the physics library can be swapped. We recommend the MMD-optimized prebuilt Bullet Physics path. The Ammo.js backend remains available as a compatibility path, but it is deprecated and planned for removal from the default guidance.

import {
  createCustomBulletMmdPhysicsBackend,
  loadCustomBulletMmdModule
} from "@yohawing/three-mmd-loader/physics";

// Recommended: MMD-optimized prebuilt Bullet Physics.
const mmdBullet = await loadCustomBulletMmdModule();
const directPhysicsBackend = createCustomBulletMmdPhysicsBackend(mmdBullet);

Development

Development notes for tests, scripts, and fixtures are in docs/DEVELOPMENT.md, including mmd-anim / Yw MMD and MMD-optimized Bullet Physics build notes. The release checklist is in docs/RELEASE.md.