https://github.com/pixiv/three-vrm
Use VRM on Three.js
https://github.com/pixiv/three-vrm
3d avatar gltf threejs vrm webgl
Last synced: 14 days ago
JSON representation
Use VRM on Three.js
- Host: GitHub
- URL: https://github.com/pixiv/three-vrm
- Owner: pixiv
- License: mit
- Created: 2019-06-04T08:25:28.000Z (almost 6 years ago)
- Default Branch: dev
- Last Pushed: 2025-03-31T00:30:29.000Z (23 days ago)
- Last Synced: 2025-04-02T01:03:24.350Z (21 days ago)
- Topics: 3d, avatar, gltf, threejs, vrm, webgl
- Language: TypeScript
- Homepage:
- Size: 119 MB
- Stars: 1,420
- Watchers: 84
- Forks: 122
- Open Issues: 46
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome - pixiv/three-vrm - Use VRM on Three.js (TypeScript)
- awesome - pixiv/three-vrm - Use VRM on Three.js (TypeScript)
README
# `@pixiv/three-vrm`
[](https://www.npmjs.com/package/@pixiv/three-vrm)
Use [VRM](https://vrm.dev/) on [three.js](https://threejs.org/)

[GitHub Repository](https://github.com/pixiv/three-vrm/)
[Examples](https://pixiv.github.io/three-vrm/packages/three-vrm/examples)
[Guides](https://github.com/pixiv/three-vrm/tree/dev/guides)
[API Reference](https://pixiv.github.io/three-vrm/docs/modules/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 mapsYou can import all the dependencies via CDN like [jsDelivr](https://www.jsdelivr.com/).
```html
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
"@pixiv/three-vrm": "https://cdn.jsdelivr.net/npm/@pixiv/three-vrm@3/lib/three-vrm.module.min.js"
}
}import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { VRMLoaderPlugin } from '@pixiv/three-vrm';// ... Setup renderer, camera, scene ...
// Create a GLTFLoader - The loader for loading VRM models
const loader = new GLTFLoader();// Install a GLTFLoader plugin that enables VRM support
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),
);// ... Perform the render loop ...
```
See the Three.js document if you are not familiar with Three.js yet: https://threejs.org/docs/#manual/en/introduction/Creating-a-scene
See the example for the complete code: https://github.com/pixiv/three-vrm/blob/release/packages/three-vrm/examples/basic.html
### via npm
Install [`three`](https://www.npmjs.com/package/three) and [`@pixiv/three-vrm`](https://www.npmjs.com/package/@pixiv/three-vrm) :
```sh
npm install three @pixiv/three-vrm
```### Use with WebGPURenderer
Starting from v3, we provide [WebGPURenderer](https://github.com/mrdoob/three.js/blob/master/examples/jsm/renderers/webgpu/WebGPURenderer.js) compatibility.
To use three-vrm with WebGPURenderer, specify the WebGPU-compatible `MToonNodeMaterial` for the `materialType` option of `MToonMaterialLoaderPlugin`.`MToonNodeMaterial` only supports Three.js r167 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.```js
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { MToonMaterialLoaderPlugin, VRMLoaderPlugin } from '@pixiv/three-vrm';
import { MToonNodeMaterial } from '@pixiv/three-vrm/nodes';// ... Setup renderer, camera, scene ...
// Create a GLTFLoader
const loader = new GLTFLoader();// 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,});
});
// ... Load the VRM and perform the render loop ...
```See the example for the complete code: https://github.com/pixiv/three-vrm/blob/release/packages/three-vrm/examples/webgpu-dnd.html
## Contributing
See: [CONTRIBUTING.md](CONTRIBUTING.md)
## LICENSE
[MIT](LICENSE)