`@pixiv/three-vrm`

Use VRM on three.js

three-vrm

How to Use

from HTML

You will need:

Three.js build
GLTFLoader
A build of @pixiv/three-vrm
- .module ones are ESM, otherwise it's UMD and injects its modules into global THREE
- .min ones are minified (for production), otherwise it's not minified and it comes with source maps

You can import all of them via CDN. See the example below.

Code like this:

<script type="importmap">
  {
    "imports": {
      "three": "https://cdn.jsdelivr.net/npm/three@0.164.1/build/three.module.js",
      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.164.1/examples/jsm/",
      "@pixiv/three-vrm": "three-vrm.module.js"
    }
  }
</script>

<script type="module">
  import * as THREE from 'three';
  import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
  import { VRMLoaderPlugin } from '@pixiv/three-vrm';

  const scene = new THREE.Scene();

  const loader = new GLTFLoader();

  // Install GLTFLoader plugin
  loader.register((parser) => {
    return new VRMLoaderPlugin(parser);
  });

  loader.load(
    // URL of the VRM you want to load
    '/models/VRM1_Constraint_Twist_Sample.vrm',

    // called when the resource is loaded
    (gltf) => {
      // retrieve a VRM instance from gltf
      const vrm = gltf.userData.vrm;

      // add the loaded vrm to the scene
      scene.add(vrm.scene);

      // deal with vrm features
      console.log(vrm);
    },

    // called while loading is progressing
    (progress) => console.log('Loading model...', 100.0 * (progress.loaded / progress.total), '%'),

    // called when loading has errors
    (error) => console.error(error),
  );
</script>

via npm

Install three and @pixiv/three-vrm :

npm install three @pixiv/three-vrm

Code like this:

import * as THREE from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { VRMLoaderPlugin } from '@pixiv/three-vrm';

const scene = new THREE.Scene();

const loader = new GLTFLoader();

// Install GLTFLoader plugin
loader.register((parser) => {
  return new VRMLoaderPlugin(parser);
});

loader.load(
  // URL of the VRM you want to load
  '/models/VRM1_Constraint_Twist_Sample.vrm',

  // called when the resource is loaded
  (gltf) => {
    // retrieve a VRM instance from gltf
    const vrm = gltf.userData.vrm;

    // add the loaded vrm to the scene
    scene.add(vrm.scene);

    // deal with vrm features
    console.log(vrm);
  },

  // called while loading is progressing
  (progress) => console.log('Loading model...', 100.0 * (progress.loaded / progress.total), '%'),

  // called when loading has errors
  (error) => console.error(error),
);

Use with WebGPURenderer

Starting from v3, we provide WebGPURenderer compatibility. To use three-vrm with WebGPURenderer, specify the WebGPU-compatible MToonNodeMaterial for the materialType option of MToonMaterialLoaderPlugin.

MToonNodeMaterial only supports Three.js r161 or later. The NodeMaterial system of Three.js is still under development, so we may break compatibility with older versions of Three.js more frequently than other parts of three-vrm.

import { VRMLoaderPlugin } from '@pixiv/three-vrm';
import { MToonNodeMaterial } from '@pixiv/three-vrm/nodes';

// ...

// Register a VRMLoaderPlugin
loader.register((parser) => {

  // create a WebGPU compatible MToonMaterialLoaderPlugin
  const mtoonMaterialPlugin = new MToonMaterialLoaderPlugin(parser, {

    // set the material type to MToonNodeMaterial
    materialType: MToonNodeMaterial,

  });

  return new VRMLoaderPlugin(parser, {

    // Specify the MToonMaterialLoaderPlugin to use in the VRMLoaderPlugin instance
    mtoonMaterialPlugin,

  });

});

Contributing

See: CONTRIBUTING.md

LICENSE

MIT