@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) | ⚠️ parser API | ❌ | | DirectX .x (accessory) | ⚠️ parser API | ❌ | | VAC (accessory placement) | ⚠️ parser API | ❌ |

Features

| Feature | Status | | --- | --- | | Parser | ✅ PMX / PMD / VMD / VPD; ⚠️ PMM / .x / .vac expose structured parsing APIs only | | Deform / skinning | ✅ BDEF1/2/4, SDEF, QDEF | | MMD material / toon shader | ✅ Toon textures, alpha blending decisions, render ordering, self shadow, and TSL (WebGPU/WebGL) support | | IK / append-transform rigging | ✅ Verified through the mmd-anim/WASM-backed path | | VMD Camera / Light | ✅ Applies to Three.js Camera and DirectionalLight | | Physics | ✅ MMD-focused Bullet Physics. | | Soft Body | ⚠️ PMX data parsed; runtime simulation is not planned |

The main PMX parser, structured PMM / .x / .vac parsing, and animation path 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);
}

Usage - Physics

Physics is abstracted behind MmdPhysicsBackend so the physics library can be swapped. The default path is the MMD-focused prebuilt Bullet Physics backend.

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

// Default: MMD-focused Bullet Physics backend.
const mmdBullet = await loadCustomBulletMmdModule();
const directPhysicsBackend = createCustomBulletMmdPhysicsBackend(mmdBullet);

Experimental - WebGPU / TSL

This is an experimental TSL implementation. The TSL API evolves quickly and may change on the Three.js side, so use it with caution.

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

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 1000);
const renderer = new THREE.WebGPURenderer({ antialias: true });
const clock = new THREE.Clock();

const light = new THREE.DirectionalLight(0xffffff, 2);
light.castShadow = true;
scene.add(light, light.target);

const pipeline = await createMmdTslPipeline(renderer, {
  light,
  selfShadowEnabled: true
});

const loader = new ThreeMmdLoader();
const model = await loader.loadModel("model.pmx", pipeline.createModelLoadOptions());
scene.add(model.root);
pipeline.attach(model);

renderer.setAnimationLoop(() => {
  model.update(clock.getElapsedTime());
  pipeline.render(scene, camera);
});

Development

Development notes are in docs/DEVELOPMENT.md.