@needle-tools/three-animation-pointer 1.0.0 → 1.0.1-next.1a466a6

package/CHANGELOG.md

@@ -4,5 +4,5 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2025-08-27
+## [1.0.1] - 2025-08-27
 - Initial release

package/README.md

@@ -2,7 +2,25 @@
 
 This package adds a [three.js](https://github.com/mrdoob/three.js) GLTFLoader plugin for [KHR_animation_pointer](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_animation_pointer) support.
 
-### Usage
+### Animate anything
+- all material properties 💎 (including texture transforms) 
+- cameras 🎥
+- lights 💡
+- custom code/scripts 📄
+
+
+### Three.js Example
+<a href="https://threejs.org/examples/?q=gltf#webgl_loader_gltf_animation_pointer" target="_blank">
+<img width="1240" height="696" alt="image" src="https://github.com/user-attachments/assets/baa109d8-974b-4c97-9ae9-31a4391e651b" />
+</a>
+
+https://github.com/user-attachments/assets/13fe4102-00ee-430f-9a17-9611fa543f77
+
+[three.js Example](https://threejs.org/examples/?q=gltf#webgl_loader_gltf_animation_pointer)
+
+
+
+### How to use
 
 Install the package:   
 `npm i @needle-tools/three-animation-pointer`
@@ -16,9 +34,26 @@ import { GLTFAnimationPointerExtension } from "@needle-tools/three-animation-poi
 const loader = new GLTFLoader();
 loader.register(p => {
     return new GLTFAnimationPointerExtension(p);
-}
+});
 ```
 
+### How to create glTF files using KHR_animation_pointer 
+
+You can use one of the listed tools below to export glTF animations in the right format
+
+- [Blender 4.3](https://www.blender.org/) and newer - *experimental KHR_animation_pointer support, currently only in 'scene animation' mode ([#2285](https://github.com/KhronosGroup/glTF-Blender-IO/issues/2285))*
+- [Needle Engine for Unity](https://engine.needle.tools/docs/unity/) - defaults to KHR_animation_pointer and battle tested since 2022
+- [UnityGLTF](https://github.com/KhronosGroup/UnityGLTF)
+
+
+**Mini Unity Tutorial**
+
+https://github.com/user-attachments/assets/e118a33d-9725-4313-b1d4-b4dbfc7a5a48
+
+*Note: If you use UnityGLTF for exporting the glTF file make sure to enable the `KHR_animation_pointer` option in the UnityGLTF export settings.*
+
+
+
 ## Links
 
 - [Khronos KHR_animation_pointer spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_animation_pointer)

package/dist/three-animation-pointer.js

@@ -0,0 +1,343 @@
+import { SkinnedMesh as S, InterpolateDiscrete as M, InterpolateLinear as F, AnimationClip as W, PropertyBinding as C, QuaternionKeyframeTrack as w, ColorKeyframeTrack as D, VectorKeyframeTrack as E, NumberKeyframeTrack as O } from "three";
+const f = {
+  node: "node",
+  material: "material",
+  camera: "camera",
+  light: "light"
+}, R = "KHR_animation_pointer", U = {
+  // We use a custom interpolant (GLTFCubicSplineInterpolation) for CUBICSPLINE tracks. Each
+  // keyframe track will be initialized with a default interpolation type, then modified.
+  CUBICSPLINE: void 0,
+  LINEAR: F,
+  STEP: M
+};
+class j {
+  /** @type {import("three/examples/jsm/loaders/GLTFLoader").GLTFParser} */
+  constructor(r) {
+    this.name = R, this.parser = r, this.animationPointerResolver = null;
+  }
+  /** 
+   * @param {import("..").AnimationPointerResolver | null} animationPointerResolver
+   */
+  setAnimationPointerResolver(r) {
+    return this.animationPointerResolver = r, this;
+  }
+  /* DUPLICATE of functionality in GLTFLoader */
+  loadAnimationTargetFromChannel(r) {
+    const s = r.target, a = s.node !== void 0 ? s.node : s.id;
+    return this.parser.getDependency("node", a);
+  }
+  loadAnimationTargetFromChannelWithAnimationPointer(r) {
+    var c;
+    B();
+    const s = r.target, a = s.extensions && s.extensions[R] && s.path && s.path === "pointer";
+    if (!a) return null;
+    let e, t = f.node, n;
+    if (a) {
+      const m = s.extensions[R];
+      let o = m.pointer;
+      if (!o) {
+        console.warn("Invalid path", m, s);
+        return;
+      }
+      if (o.startsWith("/materials/") ? t = f.material : o.startsWith("/extensions/KHR_lights_punctual/lights/") ? t = f.light : o.startsWith("/cameras/") && (t = f.camera), n = this._tryResolveTargetId(o, t), n === null || isNaN(n)) {
+        console.warn("Failed resolving animation node id: " + n, o);
+        return;
+      }
+      switch (t) {
+        case f.material:
+          const x = ("/materials/" + n.toString() + "/").length, h = o.substring(0, x);
+          switch (e = o.substring(x), e) {
+            case "pbrMetallicRoughness/baseColorFactor":
+              e = "color";
+              break;
+            case "pbrMetallicRoughness/roughnessFactor":
+              e = "roughness";
+              break;
+            case "pbrMetallicRoughness/metallicFactor":
+              e = "metalness";
+              break;
+            case "emissiveFactor":
+              e = "emissive";
+              break;
+            case "alphaCutoff":
+              e = "alphaTest";
+              break;
+            case "occlusionTexture/strength":
+              e = "aoMapIntensity";
+              break;
+            case "normalTexture/scale":
+              e = "normalScale";
+              break;
+            case "pbrMetallicRoughness/baseColorTexture/extensions/KHR_texture_transform/scale":
+              e = "map/repeat";
+              break;
+            case "pbrMetallicRoughness/baseColorTexture/extensions/KHR_texture_transform/offset":
+              e = "map/offset";
+              break;
+            case "emissiveTexture/extensions/KHR_texture_transform/scale":
+              e = "emissiveMap/repeat";
+              break;
+            case "emissiveTexture/extensions/KHR_texture_transform/offset":
+              e = "emissiveMap/offset";
+              break;
+            case "extensions/KHR_materials_emissive_strength/emissiveStrength":
+              e = "emissiveIntensity";
+              break;
+            case "extensions/KHR_materials_transmission/transmissionFactor":
+              e = "transmission";
+              break;
+            case "extensions/KHR_materials_ior/ior":
+              e = "ior";
+              break;
+            case "extensions/KHR_materials_volume/thicknessFactor":
+              e = "thickness";
+              break;
+            case "extensions/KHR_materials_volume/attenuationColor":
+              e = "attenuationColor";
+              break;
+            case "extensions/KHR_materials_volume/attenuationDistance":
+              e = "attenuationDistance";
+              break;
+            case "extensions/KHR_materials_iridescence/iridescenceFactor":
+              e = "iridescence";
+              break;
+            case "extensions/KHR_materials_iridescence/iridescenceIor":
+              e = "iridescenceIOR";
+              break;
+            case "extensions/KHR_materials_iridescence/iridescenceThicknessMinimum":
+              e = "iridescenceThicknessRange[0]";
+              break;
+            case "extensions/KHR_materials_iridescence/iridescenceThicknessMaximum":
+              e = "iridescenceThicknessRange[1]";
+              break;
+            case "extensions/KHR_materials_clearcoat/clearcoatFactor":
+              e = "clearcoat";
+              break;
+            case "extensions/KHR_materials_clearcoat/clearcoatRoughnessFactor":
+              e = "clearcoatRoughness";
+              break;
+            case "extensions/KHR_materials_sheen/sheenColorFactor":
+              e = "sheenColor";
+              break;
+            case "extensions/KHR_materials_sheen/sheenRoughnessFactor":
+              e = "sheenRoughness";
+              break;
+            case "extensions/KHR_materials_specular/specularFactor":
+              e = "specularIntensity";
+              break;
+            case "extensions/KHR_materials_specular/specularColorFactor":
+              e = "specularColor";
+              break;
+          }
+          o = h + e;
+          break;
+        case f.node:
+          const u = ("/nodes/" + n.toString() + "/").length, l = o.substring(0, u);
+          switch (e = o.substring(u), e) {
+            case "translation":
+              e = "position";
+              break;
+            case "rotation":
+              e = "quaternion";
+              break;
+            case "scale":
+              e = "scale";
+              break;
+            case "weights":
+              e = "morphTargetInfluences";
+              break;
+          }
+          o = l + e;
+          break;
+        case f.light:
+          const p = ("/extensions/KHR_lights_punctual/lights/" + n.toString() + "/").length;
+          switch (e = o.substring(p), e) {
+            case "color":
+              break;
+            case "intensity":
+              break;
+            case "spot/innerConeAngle":
+              e = "penumbra";
+              break;
+            case "spot/outerConeAngle":
+              e = "angle";
+              break;
+            case "range":
+              e = "distance";
+              break;
+          }
+          o = "/lights/" + n.toString() + "/" + e;
+          break;
+        case f.camera:
+          const g = ("/cameras/" + n.toString() + "/").length, b = o.substring(0, g);
+          switch (e = o.substring(g), e) {
+            case "perspective/yfov":
+              e = "fov";
+              break;
+            case "perspective/znear":
+            case "orthographic/znear":
+              e = "near";
+              break;
+            case "perspective/zfar":
+            case "orthographic/zfar":
+              e = "far";
+              break;
+            case "perspective/aspect":
+              e = "aspect";
+              break;
+            case "orthographic/xmag":
+              e = "zoom";
+              break;
+            case "orthographic/ymag":
+              e = "zoom";
+              break;
+          }
+          o = b + e;
+          break;
+      }
+      (c = this.animationPointerResolver) != null && c.resolvePath && (o = this.animationPointerResolver.resolvePath(o)), s.extensions[R].pointer = o;
+    }
+    if (n == null || isNaN(n)) {
+      console.warn("Failed resolving animation node id: " + n, s);
+      return;
+    }
+    let i;
+    return t === f.node ? i = this.parser.getDependency("node", n) : t === f.material ? i = this.parser.getDependency("material", n) : t === f.light ? i = this.parser.getDependency("light", n) : t === f.camera ? i = this.parser.getDependency("camera", n) : console.error("Unhandled type", t), i;
+  }
+  createAnimationTracksWithAnimationPointer(r, s, a, e, t) {
+    if (!(t.extensions && t.extensions[R] && t.path && t.path === "pointer")) return null;
+    let i = t.extensions[R].pointer;
+    if (!i) return null;
+    const c = [];
+    i = i.replaceAll("/", ".");
+    const m = i.split(".");
+    var x = r.name !== void 0 && r.name !== null ? r.name : r.uuid;
+    if (m[2] = x, m[3] === "morphTargetInfluences" && r.type === "Group") {
+      for (const u of r.children)
+        u instanceof S && u.morphTargetInfluences && (m[3] = u.name, m[4] = "morphTargetInfluences", h(this.parser));
+      return c;
+    }
+    h(this.parser);
+    function h(u) {
+      i = m.join(".");
+      let l;
+      switch (a.itemSize) {
+        case 1:
+          l = O;
+          break;
+        case 2:
+        case 3:
+          l = E;
+          break;
+        case 4:
+          i.endsWith(".quaternion") ? l = w : l = D;
+          break;
+      }
+      if (!l) {
+        console.warn("Unsupported output accessor format", a);
+        return;
+      }
+      const p = e.interpolation !== void 0 ? U[e.interpolation] : F;
+      let g = u._getArrayFromAccessor(a);
+      i.endsWith(".fov") && (g = g.map((k) => k / Math.PI * 180));
+      const b = new l(
+        i,
+        s.array,
+        g,
+        p
+      );
+      if (p === "CUBICSPLINE" && u._createCubicSplineTrackInterpolant(b), c.push(b), i && a.itemSize === 4 && i.startsWith(".materials.") && i.endsWith(".color")) {
+        const k = new Float32Array(g.length / 4);
+        for (let T = 0, _ = g.length / 4; T < _; T += 1)
+          k[T] = g[T * 4 + 3];
+        const d = new l(
+          i.replace(".color", ".opacity"),
+          s.array,
+          k,
+          p
+        );
+        p === "CUBICSPLINE" && u._createCubicSplineTrackInterpolant(b), c.push(d);
+      }
+    }
+    return c;
+  }
+  _tryResolveTargetId(r, s) {
+    let a = "";
+    return s === "node" ? a = r.substring(7) : s === "material" ? a = r.substring(11) : s === "light" ? a = r.substring(39) : s === "camera" && (a = r.substring(9)), a = a.substring(0, a.indexOf("/")), Number.parseInt(a);
+  }
+  /* MOSTLY DUPLICATE of GLTFLoader.loadAnimation, but also tries to resolve KHR_animation_pointer. */
+  /**
+   * Specification: https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#animations
+   * @param {number} animationIndex
+   * @return {Promise<AnimationClip>}
+   */
+  loadAnimation(r) {
+    const s = this, a = this.parser.json, e = this.parser, t = a.animations[r], n = t.name ? t.name : "animation_" + r, i = [], c = [], m = [], o = [], x = [];
+    for (let h = 0, u = t.channels.length; h < u; h++) {
+      const l = t.channels[h], p = t.samplers[l.sampler], g = l.target, b = t.parameters !== void 0 ? t.parameters[p.input] : p.input, k = t.parameters !== void 0 ? t.parameters[p.output] : p.output;
+      let d = s.loadAnimationTargetFromChannelWithAnimationPointer(l);
+      d || (d = s.loadAnimationTargetFromChannel(l)), i.push(d), c.push(e.getDependency("accessor", b)), m.push(e.getDependency("accessor", k)), o.push(p), x.push(g);
+    }
+    return Promise.all([
+      Promise.all(i),
+      Promise.all(c),
+      Promise.all(m),
+      Promise.all(o),
+      Promise.all(x)
+    ]).then(function(h) {
+      const u = h[0], l = h[1], p = h[2], g = h[3], b = h[4], k = [];
+      for (let d = 0, T = u.length; d < T; d++) {
+        const _ = u[d], v = l[d], A = p[d], N = g[d], K = b[d];
+        if (_ === void 0) continue;
+        _.updateMatrix && (_.updateMatrix(), _.matrixAutoUpdate = !0);
+        let y = s.createAnimationTracksWithAnimationPointer(_, v, A, N, K);
+        if (y || (y = e._createAnimationTracks(_, v, A, N, K)), y)
+          for (let P = 0; P < y.length; P++)
+            k.push(y[P]);
+      }
+      return new W(n, void 0, k);
+    });
+  }
+}
+let H = !1, z = null;
+function B() {
+  if (H) return;
+  H = !0;
+  const I = z || (z = C.findNode);
+  C.findNode = function(r, s) {
+    if (s.startsWith(".materials.")) {
+      const a = s.substring(11).substring(s.indexOf(".")), e = a.indexOf("."), t = e < 0 ? a : a.substring(0, e);
+      let n = null;
+      return r.traverse((i) => {
+        n !== null || i.type !== "Mesh" && i.type !== "SkinnedMesh" || i.material && (i.material.uuid === t || i.material.name === t) && (n = i.material, n !== null && (a.endsWith(".map") ? n = n.map : a.endsWith(".emissiveMap") && (n = n.emissiveMap)));
+      }), n;
+    } else if (s.startsWith(".nodes.") || s.startsWith(".lights.") || s.startsWith(".cameras.")) {
+      const a = s.split(".");
+      let e;
+      for (let t = 1; t < a.length; t++) {
+        const n = a[t];
+        if (n.length == 36)
+          e = r.getObjectByProperty("uuid", n);
+        else if (e && e[n]) {
+          const c = Number.parseInt(n);
+          let m = n;
+          c >= 0 && (m = c), e = e[m];
+        } else {
+          const c = r.getObjectByName(n);
+          c && (e = c);
+        }
+      }
+      if (!e) {
+        const t = I(r, a[2]);
+        return t || console.warn(R + ": Property binding not found", s, r, r.name, a), t;
+      }
+      return e;
+    }
+    return I(r, s);
+  };
+}
+export {
+  j as GLTFAnimationPointerExtension,
+  j as default
+};

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@needle-tools/three-animation-pointer",
-  "version": "1.0.0",
+  "version": "1.0.1-next.1a466a6",
   "description": "KHR_animation_pointer support for three.js",
   "type": "module",
-  "main": "src/index.js",
+  "main": "dist/three-animation-pointer.js",
+  "module": "dist/three-animation-pointer.js",
   "types": "types/index.d.ts",
   "exports": {
     ".": {
-      "import": "./src/index.js"
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.js"
     }
   },
   "files": [
     "src",
+    "dist",
     "types",
     "package.json",
     "README.md",
@@ -27,8 +31,13 @@
     "url": "https://github.com/needle-tools/three-animation-pointer"
   },
   "license": "MIT",
+  "scripts": {
+    "build": "vite build",
+    "prepublishOnly": "npm run build"
+  },
   "devDependencies": {
-    "three": ">=0.179.1"
+    "three": ">=0.179.1",
+    "vite": "^5.0.0"
   },
   "peerDependencies": {
     "three": ">=0.165.0"
@@ -37,4 +46,4 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   }
-}
+}