repository·dev·Indexed 24 days ago
https://github.com/pixiv/three-vrmA library for using VRM humanoid 3D model formats within the Three.js ecosystem. It provides loaders and plugins to handle VRM-specific features such as MToon materials, spring bones, and constraints. The library includes support for WebGPURenderer (requiring Three.js r167+), a compatibility layer for VRM 0.0 materials, and a comprehensive set of TypeScript type definitions for various VRMC schemas including animation, node constraints, and spring bones.
@pixiv/three-vrm-core package provides the core implementation of VRM features used by the main @pixiv/three-vrm package. It serves as the foundational layer for VRM model handling within the three-vrm ecosystem.This package provides only the TypeScript type definitions for the VRM_vrm_animation 1.0 schema. It does not contain any runtime implementation logic. Use this package when you need type safety for VRM animation data structures following the official VRM specification.
The extension root identifier used in the schema is VRMCVRMAnimation.
The @pixiv/types-vrmc-springbone-1.0 package provides only the TypeScript type definitions for the VRMC_springBone 1.0 schema. It does not contain any runtime implementation logic. This package is intended for use when you need to ensure type safety when working with the VRMCSpringBone extension in VRM models.
Key details:
VRMCSpringBoneThe @pixiv/types-vrmc-vrm-1.0 package provides strictly type definitions for the VRM_vrm 1.0 schema. It contains no runtime implementation logic. This package is used to ensure type safety when working with the VRM 1.0 specification within TypeScript projects.
Key details:
VRMCVRM.The @pixiv/types-vrmc-node-constraint-1.0 package provides only the TypeScript type definitions for the VRMC_node_constraint 1.0 schema. It does not contain any runtime implementation logic. This package is used to ensure type safety when working with the VRMCNodeConstraint extension root in VRM models.
For the full specification of this schema, refer to the VRM Specification.
@pixiv/types-vrm-0.0 package provides pure TypeScript type definitions for the VRM 0.0 schema. It contains no implementation logic; it is strictly used for type safety when working with the VRM 0.0 specification. The extension root for this schema is named VRM.The @pixiv/types-vrmc-materials-hdr-emissive-multiplier-1.0 package provides TypeScript type definitions for the VRMC_materials_hdr_emissiveMultiplier 1.0 schema.
Note: This package contains no implementation logic; it is strictly for type safety and schema compliance when working with this specific VRM extension.
The extension root is identified by the name VRMCMaterialsHDREmissiveMultiplier.
This package provides only the TypeScript type definitions for the VRMC_materials_mtoon 1.0 schema. It does not contain any runtime implementation. It is intended to be used for type-safe handling of MToon material data according to the VRM specification.
Note: The documentation mentions the extension root is named VRMCSpringBone, which appears to be a potential typo in the source documentation as it contradicts the package name VRMC_materials_mtoon. Users should verify the specific extension root name via the official VRM specification or the API reference.
@pixiv/three-vrm-materials-v0compat package is a plugin designed to provide a compatibility layer for VRM 0.0 materials when using @pixiv/three-vrm. It allows models using older VRM 0.0 material specifications to be rendered correctly within the modern @pixiv/three-vrm ecosystem.When constraints depend on one another, they must be updated in a specific order to prevent circular dependencies and ensure correct transformations. The system uses a recursive update pattern with a pending set to detect cycles.
To update a constraint, the system checks if it has already been processed. If not, it recursively updates all of its dependencies before processing the constraint itself. If a constraint is encountered that is already in the pending set, a circular dependency error is thrown.
let constraintsPending = empty set of Constraint
let constraintsDone = empty set of Constraint
function updateConstraint( constraint )
if not constraintsDone.has( constraint ) then
if constraintPending.has( constraint ) then
throw "Circular dependency detected"
end if
constraintsPending.add( constraint )
foreach dependency in constraint.dependencies do
updateConstraint( dependency )
end foreach
constraintsPending.delete( constraint )
process constraint
constraintsDone.add( constraint )
end if
end function
function updateConstraints
foreach constraint in constraints do
updateConstraint( constraint )
end foreach
end functionVRM1.0 allows for non-normalized bone orientations. To maintain compatibility across models, VRMHumanoid provides access to "normalized" bones, which have an identity orientation ([0, 0, 0; 1] in quaternion) in their rest pose.
VRMHumanoid.getRawBoneNode for the original bone orientation.VRMHumanoid.getNormalizedBoneNode for the normalized orientation.Operations applied to normalized bones are automatically synced to raw bones during VRM.update or VRMHumanoid.update. You can disable this automatic syncing by setting VRMHumanoid.autoUpdateHumanBones to false.
In VRM1.0, the meta structure was reworked. VRM.meta can be either VRM0Meta or VRM1Meta. Use the .metaVersion property to distinguish between them: '0' for VRM0.0 and '1' for VRM1.0.
// vrm.meta: VRM0Meta | VRM1Meta
if (vrm.meta.metaVersion === '0') {
// vrm.meta: VRM0Meta
} else if (vrm.meta.metaVersion === '1') {
// vrm.meta: VRM1Meta
}