Skip to content

Repository files navigation

@anhldh/gltf-animation-pointer-extensions

npm version npm downloads license

Support for the glTF KHR_animation_pointer extension on both sides of the pipeline:

  • Runtime (three.js): load models that use KHR_animation_pointer with GLTFLoader (and drei's useGLTF). three.js does not support it by default, so those animations simply don't play.
  • Build-time (gltf-transform): preserve KHR_animation_pointer channels while processing/optimizing a model. gltf-transform drops them by default.

🔎 Try it online — gltf.info

Want to check a model before writing any code? Open gltf.info and drop in your .glb / .gltf file to preview it in the browser, including animations that use KHR_animation_pointer.

What is KHR_animation_pointer?

The extension lets an animation target almost any property of a model via a JSON pointer. Beyond node transforms, it can animate material factors and texture transforms, light parameters (KHR_lights_punctual), cameras, morph weights, visibility, and more. Because it lives outside "classic" animation, both three.js and gltf-transform ignore it unless a dedicated extension handles it.

Installation

pnpm add @anhldh/gltf-animation-pointer-extensions

Peer dependencies are optional. Install only the side you use:

# runtime (three.js)
pnpm add three

# build-time (gltf-transform)
pnpm add @gltf-transform/core @gltf-transform/extensions

Usage: three.js

Plain GLTFLoader

import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
import { GLTFAnimationPointerExtension } from "@anhldh/gltf-animation-pointer-extensions";

const loader = new GLTFLoader();
loader.register((p) => new GLTFAnimationPointerExtension(p));

const gltf = await loader.loadAsync("model.glb");
// gltf.animations now contains tracks generated from KHR_animation_pointer

React Three Fiber (drei useGLTF)

The 4th argument of useGLTF is extendLoader, which is where you register the extension:

import { useGLTF } from "@react-three/drei";
import type {
  GLTFLoader,
  GLTFParser,
} from "three/examples/jsm/loaders/GLTFLoader.js";
import { GLTFAnimationPointerExtension } from "@anhldh/gltf-animation-pointer-extensions";

const gltf = useGLTF(url, true, true, (loader) => {
  // drei uses the three-stdlib GLTFLoader -> cast to three/examples.
  const l = loader as unknown as GLTFLoader;
  l.register((p: GLTFParser) => new GLTFAnimationPointerExtension(p));
});

useGLTF caches by URL, so extendLoader only runs on the first load of each URL.

Usage: gltf-transform

When you run a gltf-transform pipeline (weld, dedup, draco, resample, prune, ...), KHR_animation_pointer channels are dropped by default. Register KHRAnimationPointer to read and write them back correctly. It automatically remaps pointers to the new node/material indices after transforms.

import { WebIO } from "@gltf-transform/core";
import { ALL_EXTENSIONS } from "@gltf-transform/extensions";
import { KHRAnimationPointer } from "@anhldh/gltf-animation-pointer-extensions/transform";

const io = new WebIO().registerExtensions([
  ...ALL_EXTENSIONS,
  KHRAnimationPointer,
]);

const doc = await io.read(url); // preread: maps pointer -> Node/Material
// ...doc.transform(...)...        // pointers follow Node/Material, stay correct
const glb = await io.writeBinary(doc); // write: emits pointer with new indices

On Node, use NodeIO instead of WebIO:

import { NodeIO } from "@gltf-transform/core";
import { ALL_EXTENSIONS } from "@gltf-transform/extensions";
import { KHRAnimationPointer } from "@anhldh/gltf-animation-pointer-extensions/transform";

const io = new NodeIO().registerExtensions([
  ...ALL_EXTENSIONS,
  KHRAnimationPointer,
]);

const doc = await io.read("in.glb");
await io.write("out.glb", doc);

API

three.js side, from @anhldh/gltf-animation-pointer-extensions:

  • GLTFAnimationPointerExtension: plugin registered via GLTFLoader.register(...).
  • .setAnimationPointerResolver(resolver): customize how a pointer path maps to a three.js property.
  • invalidateMaterialCache(root): clear the material cache when materials are swapped/cloned at runtime.
  • type AnimationPointerResolver.

gltf-transform side, from @anhldh/gltf-animation-pointer-extensions/transform:

  • KHRAnimationPointer: Extension registered on the IO (WebIO / NodeIO).
  • AnimationPointer: ExtensionProperty attached to an AnimationChannel.
  • KHR_ANIMATION_POINTER: the extension-name constant ("KHR_animation_pointer").

Notes

  • The three.js side patches PropertyBinding.findNode (global, once, guarded) so pointers can bind to material / texture / light / camera. Textures shared across materials are cloned before binding to avoid animating the wrong one.
  • If an animation fails, the extension returns an empty clip instead of breaking the whole model. The model still loads; only that animation is lost.
  • Published builds are minified. Read the source on GitHub.
  • The two sides are separate entry points: . (three.js) and /transform (gltf-transform). Importing one never loads the other's peer dependency, so you only need the peer dep of the side you actually import.

Related packages

Author

Made by Hoàng Anh (@anhldh)

Issues and pull requests are welcome on GitHub.

License

MIT © Hoàng Anh

Releases

Packages

Contributors

Languages