gltf-transform-vrm-extensions

External custom VRM and VRMA extensions for @gltf-transform/core.

Install

yarn add @gltf-transform/core gltf-transform-vrm-extensions

Exports

| Export | Purpose | |---|---| | VRMC_VRM_EXTENSIONS | Register all VRM-related custom extensions at once. | | readVRM / readVRMA | Read a document and validate that it is actually VRM / VRMA. | | writeVRM / writeVRMA | Validate a document before writing binary output. | | isVRMDocument / isVRMADocument | Non-throwing type guards for document checks. | | assertVRMDocument / assertVRMADocument | Throwing validation helpers. |

Register Extensions

import { WebIO } from '@gltf-transform/core';
import { VRMC_VRM_EXTENSIONS } from 'gltf-transform-vrm-extensions';

const io = new WebIO().registerExtensions(VRMC_VRM_EXTENSIONS);

Read And Write Helpers

These helpers do not patch WebIO / NodeIO. They wrap the existing read() and writeBinary() flow, then apply VRM-specific validation.

import { WebIO } from '@gltf-transform/core';
import {
  VRMC_VRM_EXTENSIONS,
  readVRM,
  readVRMA,
  writeVRM,
  writeVRMA,
} from 'gltf-transform-vrm-extensions';

const io = new WebIO().registerExtensions(VRMC_VRM_EXTENSIONS);

const vrmDocument = await readVRM(io, 'avatar.vrm');
const vrmaDocument = await readVRMA(io, 'motion.vrma');

const vrmBytes = await writeVRM(io, vrmDocument);
const vrmaBytes = await writeVRMA(io, vrmaDocument);

Validation Helpers

Use these helpers when you already have a Document and only need VRM / VRMA checks.

import {
  assertVRMADocument,
  assertVRMDocument,
  isVRMADocument,
  isVRMDocument,
} from 'gltf-transform-vrm-extensions';

if (isVRMDocument(document)) {
  // Handle VRM document.
}

if (!isVRMADocument(document)) {
  throw new Error('Expected a VRMA document.');
}

assertVRMDocument(document);
assertVRMADocument(document);

Validation rules:

| Helper | Required extension marker | |---|---| | readVRM / writeVRM / assertVRMDocument | VRMC_vrm or VRM | | readVRMA / writeVRMA / assertVRMADocument | VRMC_vrm_animation |

NodeIO Example

import { NodeIO } from '@gltf-transform/core';
import { VRMC_VRM_EXTENSIONS, readVRM } from 'gltf-transform-vrm-extensions';

const io = new NodeIO().registerExtensions(VRMC_VRM_EXTENSIONS);
const document = await readVRM(io, '/absolute/path/avatar.vrm');

Notes

| Item | Detail | |---|---| | Extension registration | Always register VRMC_VRM_EXTENSIONS before reading or writing VRM / VRMA files. | | Runtime requirement | @gltf-transform/core must be installed by the consumer project. |