Extensions

Extensions enhance a glTF Document with additional features and schema, beyond the core glTF specification. For example, extensions to Material properties might include additional textures or scalar properties affecting the Material's appearance in a specific way.

Common extensions may be imported from the @gltf-transform/extensions package, or custom extensions may be created by extending the Extension base class. No extensions are included in the default @gltf-transform/core package, in order to (1) minimize the code size, and (2) ensure that any extension can be implemented externally.

Because extensions rely on the same underlying graph structure as the core specification, references to Texture, Accessor, and other resources will be managed automatically, even by scripts or transforms written without prior knowledge of the extension. An extension is added to a Document by calling Document.createExtension with the extension constructor. The extension object may then be used to construct ExtensionProperty instances, which are attached to properties throughout the Document as prescribed by the extension itself.

Khronos Extensions

NOTICE: Khronos extensions are widely supported and recommended for general use.

• KHR_draco_mesh_compression
• KHR_lights_punctual
• KHR_materials_clearcoat
• KHR_materials_emissive_strength ⚠️ experimental
• KHR_materials_ior
• KHR_materials_iridescence ⚠️ experimental
• KHR_materials_pbrSpecularGlossiness
• KHR_materials_sheen
• KHR_materials_specular
• KHR_materials_transmission
• KHR_materials_unlit
• KHR_materials_variants
• KHR_materials_volume
• KHR_mesh_quantization
• KHR_texture_basisu
• KHR_texture_transform
• KHR_xmp_json_ld

Vendor Extensions

• EXT_texture_webp
• EXT_mesh_gpu_instancing
• EXT_meshopt_compression

Installation

To use extensions, first install the @gltf-transform/extensions package:

npm install --save @gltf-transform/extensions

To open files containing an Extension, the Extension constructor must be registered with the PlatformIO instance used to read the file.

// Register all Khronos Group (KHR_) extensions.
import { WebIO } from '@gltf-transform/core';
import { KHRONOS_EXTENSIONS } from '@gltf-transform/extensions';
const io = new WebIO().registerExtensions(KHRONOS_EXTENSIONS);

// Register an individual extension.
import { WebIO } from '@gltf-transform/core';
import { MaterialsUnlit } from '@gltf-transform/extensions';
const io = new WebIO().registerExtensions([MaterialsUnlit]);

// Read a file that requires the KHR_materials_unlit extension.
const document = await io.readGLB('unlit.glb');

Reading or writing files requires registering the necessary Extensions with the I/O class. Some extensions may require installing dependencies:

import { NodeIO } from '@gltf-transform/core';
import { KHRONOS_EXTENSIONS } from '@gltf-transform/extensions';

import draco3d from 'draco3dgltf';

// ...

const io = new NodeIO()
  .registerExtensions(KHRONOS_EXTENSIONS)
  .registerDependencies({
    'draco3d.decoder': await draco3d.createDecoderModule(), // Optional.
    'draco3d.encoder': await draco3d.createEncoderModule(), // Optional.
  });

const document = await io.read('compressed.glb');

Custom extensions

In addition to the official Khronos and multi-vendor extensions, the glTF format can be extended with custom extensions for specific applications. glTF-Transform supports reading/writing custom extensions, without modifications to the core codebase. Any extension implemented correctly and registered with the I/O instance may be read from a file, modified programmatically, and written back to a file.

For implementation examples, see packages/extensions. For further details on the general Extension API, see Extension and ExtensionProperty.