$ show pixiv/three-vrm
A monorepo providing `@pixiv/three-vrm`, a library for loading, controlling, and rendering VRM (Virtual Reality Model) avatars in three.js. It implements VRM 1.0 and partial VRM 0.0 specifications, handling humanoid bone mapping, facial expressions, eye gaze control (lookAt), first-person mesh culling, spring bone physics simulation, node constraints (aim, roll, rotation), and MToon toon material rendering. The library is structured as a collection of GLTFLoader plugins that parse VRM extensions from `.vrm` files. Core modules include `VRMLoaderPlugin` (orchestrating sub-plugins), `VRMCore` (humanoid, expressions, lookAt, firstPerson), `VRMSpringBoneManager` (verlet physics), `VRMNodeConstraintManager` (topological sort for constraints), and `MToonMaterial`/`MToonNodeMaterial` (custom shader/material for toon rendering). Both WebGL and experimental WebGPU renderers are supported. The codebase includes thorough examples, CI/CD, and compatibility shims for multiple three.js revisions (r123 through r180).
The LLM identified 4 files worth highlighting for reuse:
A proxy-based cache for Matrix4 inverses. Wraps a THREE.Matrix4 and lazily computes its inverse only when the original matrix changes (via a dirty flag). Uses a JavaScript Proxy to intercept element access, returning cached inverse values. This avoids repeated costly matrix inversions in physics and constraint systems. Can be extracted as a standalone utility for any three.js project needing cached matrix inverses.
A pure utility function that splits an array into chunks of a given size. Used internally by VRM animation parsing to process interleaved keyframe data. No dependencies on internal VRM or three.js modules – fully extractable for any JavaScript or TypeScript project needing array chunking.
A pure math utility that calculates azimuth and altitude angles from a direction vector relative to a reference forward/up vectors. Used to drive eye gaze (lookAt) systems. No VRM-specific imports – can be reused in any 3D math context requiring spherical coordinate conversion.
A utility function that traverses ancestors of a THREE.Object3D from the root of the scene graph down to the node itself. Used by node constraint system to compute world transforms efficiently. Simple, generic tree traversal pattern extractable for any three.js scene graph task.