@needle-tools/three-animation-pointer 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.1.3]
+- Fix: morph target (blend shape) weight animation bound to the wrong object when a multi-material mesh is used by multiple nodes. three.js clones a shared mesh per node, so every node's `Group` has identically named submeshes; the submesh segment of `.nodes.<node>.<submesh>.morphTargetInfluences` was looked up from the mixer root instead of inside `<node>`, so all tracks bound to the first node's submeshes. Child names are now resolved within the already resolved node.
+
+## [1.1.2] - 2026-06-17
+- Fix: don't mutate the `KHR_animation_pointer.pointer` value in `parser.json`. The resolved three.js property path is now kept in plugin-local state, so other plugins / app code can still read the original spec-defined pointer after load — by @0b5vr in [#2](https://github.com/needle-tools/three-animation-pointer/pull/2)
+
 ## [1.1.1] - 2026-06-12
 - Fix: morph target (blend shape) weight animation was silently dropped for multi-material meshes without skin/bones. The multi-material morph branch only bound children that were `SkinnedMesh`; such meshes load as a `Group` of plain `Mesh` children, so no track was created (and the empty-but-truthy result skipped the fallback). Now any child with `morphTargetInfluences` is bound.
 

package/dist/three-animation-pointer.js

@@ -1,53 +1,53 @@
-import { InterpolateDiscrete as w, InterpolateLinear as F, AnimationClip as S, PropertyBinding as C, QuaternionKeyframeTrack as M, ColorKeyframeTrack as W, VectorKeyframeTrack as B, BooleanKeyframeTrack as D, NumberKeyframeTrack as E } from "three";
-const d = {
+import { InterpolateDiscrete as M, InterpolateLinear as F, AnimationClip as w, PropertyBinding as C, QuaternionKeyframeTrack as S, ColorKeyframeTrack as W, VectorKeyframeTrack as B, BooleanKeyframeTrack as D, NumberKeyframeTrack as O } from "three";
+const k = {
   node: "node",
   material: "material",
   camera: "camera",
   light: "light"
-}, y = "KHR_animation_pointer", O = {
+}, R = "KHR_animation_pointer", E = {
   // 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: w
+  STEP: M
 };
-class z {
+class G {
   /** @type {import("three/examples/jsm/loaders/GLTFLoader").GLTFParser} */
-  constructor(a) {
-    this.name = y, this.parser = a, this.animationPointerResolver = null;
+  constructor(r) {
+    this.name = R, this.parser = r, this.animationPointerResolver = null, this.pointerPathMap = /* @__PURE__ */ new Map();
   }
   /** 
    * @param {import("..").AnimationPointerResolver | null} animationPointerResolver
    */
-  setAnimationPointerResolver(a) {
-    return this.animationPointerResolver = a, this;
+  setAnimationPointerResolver(r) {
+    return this.animationPointerResolver = r, this;
   }
   /* DUPLICATE of functionality in GLTFLoader */
-  loadAnimationTargetFromChannel(a) {
-    const t = a.target, r = t.node !== void 0 ? t.node : t.id;
-    return this.parser.getDependency("node", r);
+  loadAnimationTargetFromChannel(r) {
+    const t = r.target, a = t.node !== void 0 ? t.node : t.id;
+    return this.parser.getDependency("node", a);
   }
-  loadAnimationTargetFromChannelWithAnimationPointer(a) {
-    var m;
+  loadAnimationTargetFromChannelWithAnimationPointer(r) {
+    var o;
     L();
-    const t = a.target, r = t.extensions && t.extensions[y] && t.path && t.path === "pointer";
-    if (!r) return null;
-    let e, s = d.node, n;
-    if (r) {
-      const h = t.extensions[y];
-      let o = h.pointer;
-      if (!o) {
-        console.warn("Invalid path", h, t);
+    const t = r.target, a = t.extensions && t.extensions[R] && t.path && t.path === "pointer";
+    if (!a) return null;
+    let e, s = k.node, n;
+    if (a) {
+      const m = t.extensions[R];
+      let i = m.pointer;
+      if (!i) {
+        console.warn("Invalid path", m, t);
         return;
       }
-      if (o.startsWith("/materials/") ? s = d.material : o.startsWith("/extensions/KHR_lights_punctual/lights/") ? s = d.light : o.startsWith("/cameras/") && (s = d.camera), n = this._tryResolveTargetId(o, s), n === null || isNaN(n)) {
-        console.warn("Failed resolving animation node id: " + n, o);
+      if (i.startsWith("/materials/") ? s = k.material : i.startsWith("/extensions/KHR_lights_punctual/lights/") ? s = k.light : i.startsWith("/cameras/") && (s = k.camera), n = this._tryResolveTargetId(i, s), n === null || isNaN(n)) {
+        console.warn("Failed resolving animation node id: " + n, i);
         return;
       }
       switch (s) {
-        case d.material:
-          const T = ("/materials/" + n.toString() + "/").length, g = o.substring(0, T);
-          switch (e = o.substring(T), e) {
+        case k.material:
+          const h = ("/materials/" + n.toString() + "/").length, y = i.substring(0, h);
+          switch (e = i.substring(h), e) {
             case "pbrMetallicRoughness/baseColorFactor":
               e = "color";
               break;
@@ -130,13 +130,13 @@ class z {
               e = "specularColor";
               break;
           }
-          o = g + e;
+          i = y + e;
           break;
-        case d.node:
-          const _ = ("/nodes/" + n.toString() + "/").length, b = o.substring(0, _);
-          if (e = o.substring(_), e.startsWith("weights/")) {
-            const f = e.substring(8);
-            /^\d+$/.test(f) ? e = "morphTargetInfluences[" + f + "]" : console.warn(y + ": invalid weight index", e, o);
+        case k.node:
+          const g = ("/nodes/" + n.toString() + "/").length, d = i.substring(0, g);
+          if (e = i.substring(g), e.startsWith("weights/")) {
+            const l = e.substring(8);
+            /^\d+$/.test(l) ? e = "morphTargetInfluences[" + l + "]" : console.warn(R + ": invalid weight index", e, i);
           } else
             switch (e) {
               case "translation":
@@ -155,11 +155,11 @@ class z {
                 e = "visible";
                 break;
             }
-          o = b + e;
+          i = d + e;
           break;
-        case d.light:
-          const u = ("/extensions/KHR_lights_punctual/lights/" + n.toString() + "/").length;
-          switch (e = o.substring(u), e) {
+        case k.light:
+          const p = ("/extensions/KHR_lights_punctual/lights/" + n.toString() + "/").length;
+          switch (e = i.substring(p), e) {
             case "color":
               break;
             case "intensity":
@@ -174,11 +174,11 @@ class z {
               e = "distance";
               break;
           }
-          o = "/lights/" + n.toString() + "/" + e;
+          i = "/lights/" + n.toString() + "/" + e;
           break;
-        case d.camera:
-          const l = ("/cameras/" + n.toString() + "/").length, k = o.substring(0, l);
-          switch (e = o.substring(l), e) {
+        case k.camera:
+          const c = ("/cameras/" + n.toString() + "/").length, b = i.substring(0, c);
+          switch (e = i.substring(c), e) {
             case "perspective/yfov":
               e = "fov";
               break;
@@ -200,91 +200,94 @@ class z {
               e = "zoom";
               break;
           }
-          o = k + e;
+          i = b + e;
           break;
       }
-      (m = this.animationPointerResolver) != null && m.resolvePath && (o = this.animationPointerResolver.resolvePath(o)), t.extensions[y].pointer = o;
+      (o = this.animationPointerResolver) != null && o.resolvePath && (i = this.animationPointerResolver.resolvePath(i));
+      const I = m.pointer;
+      this.pointerPathMap.set(I, i);
     }
     if (n == null || isNaN(n)) {
       console.warn("Failed resolving animation node id: " + n, t);
       return;
     }
-    let i;
-    return s === d.node ? i = this.parser.getDependency("node", n) : s === d.material ? i = this.parser.getDependency("material", n) : s === d.light ? i = this.parser.getDependency("light", n) : s === d.camera ? i = this.parser.getDependency("camera", n) : console.error("Unhandled type", s), i;
+    let u;
+    return s === k.node ? u = this.parser.getDependency("node", n) : s === k.material ? u = this.parser.getDependency("material", n) : s === k.light ? u = this.parser.getDependency("light", n) : s === k.camera ? u = this.parser.getDependency("camera", n) : console.error("Unhandled type", s), u;
   }
-  createAnimationTracksWithAnimationPointer(a, t, r, e, s) {
-    var b;
-    if (!(s.extensions && s.extensions[y] && s.path && s.path === "pointer")) return null;
-    let i = s.extensions[y].pointer;
-    if (!i) return null;
+  createAnimationTracksWithAnimationPointer(r, t, a, e, s) {
+    var d;
+    if (!(s.extensions && s.extensions[R] && s.path && s.path === "pointer")) return null;
+    const u = s.extensions[R].pointer;
+    let o = this.pointerPathMap.get(u);
+    if (!o) return null;
     const m = [];
-    i = i.replaceAll("/", ".");
-    const h = i.split(".");
-    var T = a.name !== void 0 && a.name !== null ? a.name : a.uuid;
-    if (h[2] = T, (b = h[3]) != null && b.startsWith("morphTargetInfluences")) {
-      const u = h[3];
-      if (a.type === "Group") {
-        for (const l of a.children)
-          l.morphTargetInfluences && (h[3] = l.name, h[4] = u, _(this.parser));
+    o = o.replaceAll("/", ".");
+    const i = o.split(".");
+    var h = r.name !== void 0 && r.name !== null ? r.name : r.uuid;
+    if (i[2] = h, (d = i[3]) != null && d.startsWith("morphTargetInfluences")) {
+      const p = i[3];
+      if (r.type === "Group") {
+        for (const c of r.children)
+          c.morphTargetInfluences && (i[3] = c.name, i[4] = p, g(this.parser));
         return m;
       }
     }
-    _(this.parser);
-    function g(u, l) {
+    g(this.parser);
+    function y(p, c) {
       try {
-        const k = l.split(".").filter(Boolean), c = k[k.length - 1].replace(/\[.*\]$/, "");
-        return c in u ? typeof u[c] == "boolean" : !1;
+        const b = c.split(".").filter(Boolean), f = b[b.length - 1].replace(/\[.*\]$/, "");
+        return f in p ? typeof p[f] == "boolean" : !1;
       } catch {
         return !1;
       }
     }
-    function _(u) {
-      i = h.join(".");
-      let l, k = !1;
-      switch (r.itemSize) {
+    function g(p) {
+      o = i.join(".");
+      let c, b = !1;
+      switch (a.itemSize) {
         case 1:
-          Object.prototype.toString.call(r.array) === "[object Uint8Array]" && // UNSIGNED_BYTE as a strong hint
-          g(a, i) ? (l = D, k = !0) : l = E;
+          Object.prototype.toString.call(a.array) === "[object Uint8Array]" && // UNSIGNED_BYTE as a strong hint
+          y(r, o) ? (c = D, b = !0) : c = O;
           break;
         case 2:
         case 3:
-          l = B;
+          c = B;
           break;
         case 4:
-          i.endsWith(".quaternion") ? l = M : l = W;
+          o.endsWith(".quaternion") ? c = S : c = W;
           break;
       }
-      if (!l) {
-        console.warn("Unsupported output accessor format", r);
+      if (!c) {
+        console.warn("Unsupported output accessor format", a);
         return;
       }
-      const f = e.interpolation !== void 0 ? O[e.interpolation] : F;
-      let c = u._getArrayFromAccessor(r);
-      i.endsWith(".fov") && (c = c.map((p) => p / Math.PI * 180)), k && (c = c.map((p) => p > 0));
-      const R = new l(
-        i,
+      const l = e.interpolation !== void 0 ? E[e.interpolation] : F;
+      let f = p._getArrayFromAccessor(a);
+      o.endsWith(".fov") && (f = f.map((x) => x / Math.PI * 180)), b && (f = f.map((x) => x > 0));
+      const _ = new c(
+        o,
         t.array,
-        c,
-        f
+        f,
+        l
       );
-      if (f === "CUBICSPLINE" && u._createCubicSplineTrackInterpolant(R), m.push(R), i && r.itemSize === 4 && i.startsWith(".materials.") && i.endsWith(".color")) {
-        const p = new Float32Array(c.length / 4);
-        for (let x = 0, A = c.length / 4; x < A; x += 1)
-          p[x] = c[x * 4 + 3];
-        const v = new l(
-          i.replace(".color", ".opacity"),
+      if (l === "CUBICSPLINE" && p._createCubicSplineTrackInterpolant(_), m.push(_), o && a.itemSize === 4 && o.startsWith(".materials.") && o.endsWith(".color")) {
+        const x = new Float32Array(f.length / 4);
+        for (let T = 0, A = f.length / 4; T < A; T += 1)
+          x[T] = f[T * 4 + 3];
+        const P = new c(
+          o.replace(".color", ".opacity"),
           t.array,
-          p,
-          f
+          x,
+          l
         );
-        f === "CUBICSPLINE" && u._createCubicSplineTrackInterpolant(R), m.push(v);
+        l === "CUBICSPLINE" && p._createCubicSplineTrackInterpolant(_), m.push(P);
       }
     }
     return m;
   }
-  _tryResolveTargetId(a, t) {
-    let r = "";
-    return t === "node" ? r = a.substring(7) : t === "material" ? r = a.substring(11) : t === "light" ? r = a.substring(39) : t === "camera" && (r = a.substring(9)), r = r.substring(0, r.indexOf("/")), Number.parseInt(r);
+  _tryResolveTargetId(r, t) {
+    let a = "";
+    return t === "node" ? a = r.substring(7) : t === "material" ? a = r.substring(11) : t === "light" ? a = r.substring(39) : t === "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. */
   /**
@@ -292,73 +295,82 @@ class z {
    * @param {number} animationIndex
    * @return {Promise<AnimationClip>}
    */
-  loadAnimation(a) {
-    const t = this, r = this.parser.json, e = this.parser, s = r.animations[a], n = s.name ? s.name : "animation_" + a, i = [], m = [], h = [], o = [], T = [];
-    for (let g = 0, _ = s.channels.length; g < _; g++) {
-      const b = s.channels[g], u = s.samplers[b.sampler], l = b.target, k = s.parameters !== void 0 ? s.parameters[u.input] : u.input, f = s.parameters !== void 0 ? s.parameters[u.output] : u.output;
-      let c = t.loadAnimationTargetFromChannelWithAnimationPointer(b);
-      c || (c = t.loadAnimationTargetFromChannel(b)), i.push(c), m.push(e.getDependency("accessor", k)), h.push(e.getDependency("accessor", f)), o.push(u), T.push(l);
+  loadAnimation(r) {
+    const t = this, a = this.parser.json, e = this.parser, s = a.animations[r], n = s.name ? s.name : "animation_" + r, u = [], o = [], m = [], i = [], I = [];
+    for (let h = 0, y = s.channels.length; h < y; h++) {
+      const g = s.channels[h], d = s.samplers[g.sampler], p = g.target, c = s.parameters !== void 0 ? s.parameters[d.input] : d.input, b = s.parameters !== void 0 ? s.parameters[d.output] : d.output;
+      let l = t.loadAnimationTargetFromChannelWithAnimationPointer(g);
+      l || (l = t.loadAnimationTargetFromChannel(g)), u.push(l), o.push(e.getDependency("accessor", c)), m.push(e.getDependency("accessor", b)), i.push(d), I.push(p);
     }
     return Promise.all([
-      Promise.all(i),
-      Promise.all(m),
-      Promise.all(h),
+      Promise.all(u),
       Promise.all(o),
-      Promise.all(T)
-    ]).then(function(g) {
-      const _ = g[0], b = g[1], u = g[2], l = g[3], k = g[4], f = [];
-      for (let c = 0, R = _.length; c < R; c++) {
-        const p = _[c], v = b[c], x = u[c], A = l[c], N = k[c];
-        if (p === void 0) continue;
-        p.updateMatrix && (p.updateMatrix(), p.matrixAutoUpdate = !0);
-        let I = t.createAnimationTracksWithAnimationPointer(p, v, x, A, N);
-        if (I || (I = e._createAnimationTracks(p, v, x, A, N)), I)
-          for (let K = 0; K < I.length; K++)
-            f.push(I[K]);
+      Promise.all(m),
+      Promise.all(i),
+      Promise.all(I)
+    ]).then(function(h) {
+      const y = h[0], g = h[1], d = h[2], p = h[3], c = h[4], b = [];
+      for (let l = 0, f = y.length; l < f; l++) {
+        const _ = y[l], x = g[l], P = d[l], T = p[l], A = c[l];
+        if (_ === void 0) continue;
+        _.updateMatrix && (_.updateMatrix(), _.matrixAutoUpdate = !0);
+        let N = t.createAnimationTracksWithAnimationPointer(_, x, P, T, A);
+        if (N || (N = e._createAnimationTracks(_, x, P, T, A)), N)
+          for (let K = 0; K < N.length; K++)
+            b.push(N[K]);
       }
-      return new S(n, void 0, f);
+      return new w(n, void 0, b);
     });
   }
 }
-let H = !1, U = null;
+function U(v, r) {
+  for (const t of v.children) {
+    const a = t.getObjectByName(r);
+    if (a) return a;
+  }
+}
+let H = !1, j = null;
 function L() {
   if (H) return;
   H = !0;
-  const P = U || (U = C.findNode);
-  C.findNode = function(a, t) {
-    if (!t) return P(a, t);
+  const v = j || (j = C.findNode);
+  C.findNode = function(r, t) {
+    if (!t) return v(r, t);
     if (t.startsWith(".materials.")) {
-      const r = t.substring(11).substring(t.indexOf(".")), e = r.indexOf("."), s = e < 0 ? r : r.substring(0, e);
+      const a = t.substring(11).substring(t.indexOf(".")), e = a.indexOf("."), s = e < 0 ? a : a.substring(0, e);
       let n = null;
-      return a.traverse((i) => {
-        n !== null || i.type !== "Mesh" && i.type !== "SkinnedMesh" || i.material && (i.material.uuid === s || i.material.name === s) && (n = i.material, n !== null && (r.endsWith(".map") ? n = n.map : r.endsWith(".emissiveMap") && (n = n.emissiveMap)));
+      return r.traverse((u) => {
+        n !== null || u.type !== "Mesh" && u.type !== "SkinnedMesh" || u.material && (u.material.uuid === s || u.material.name === s) && (n = u.material, n !== null && (a.endsWith(".map") ? n = n.map : a.endsWith(".emissiveMap") && (n = n.emissiveMap)));
       }), n;
     } else if (t.startsWith(".nodes.") || t.startsWith(".lights.") || t.startsWith(".cameras.")) {
-      const r = t.split(".");
+      const a = t.split(".");
       let e;
-      for (let s = 1; s < r.length; s++) {
-        const n = r[s];
+      for (let s = 1; s < a.length; s++) {
+        const n = a[s];
         if (n.length == 36)
-          e = a.getObjectByProperty("uuid", n);
+          e = r.getObjectByProperty("uuid", n);
         else if (e && e[n]) {
-          const m = Number.parseInt(n);
-          let h = n;
-          m >= 0 && (h = m), e = e[h];
+          const o = Number.parseInt(n);
+          let m = n;
+          o >= 0 && (m = o), e = e[m];
+        } else if (e && e.isObject3D) {
+          const o = U(e, n);
+          o && (e = o);
         } else {
-          const m = a.getObjectByName(n);
-          m && (e = m);
+          const o = r.getObjectByName(n);
+          o && (e = o);
         }
       }
       if (!e) {
-        const s = P(a, r[2]);
-        return s || console.warn(y + ": Property binding not found", t, a, a.name, r), s;
+        const s = v(r, a[2]);
+        return s || console.warn(R + ": Property binding not found", t, r, r.name, a), s;
       }
       return e;
     }
-    return P(a, t);
+    return v(r, t);
   };
 }
 export {
-  z as GLTFAnimationPointerExtension,
-  z as default
+  G as GLTFAnimationPointerExtension,
+  G as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/three-animation-pointer",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "KHR_animation_pointer support for three.js",
   "type": "module",
   "main": "dist/three-animation-pointer.js",

package/src/GLTFLoaderAnimationPointer.js

@@ -54,6 +54,12 @@ export class GLTFAnimationPointerExtension {
 		/** @type {import("..").AnimationPointerResolver | null} */
 		this.animationPointerResolver = null;
 
+		/**
+		 * @type {Map<string, string>}
+		 * Maps from original pointer paths to resolved three.js property paths.
+		 */
+		this.pointerPathMap = new Map();
+
 	}
 
 	/** 
@@ -351,7 +357,8 @@ export class GLTFAnimationPointerExtension {
 
 			}
 
-			target.extensions[ KHR_ANIMATION_POINTER ].pointer = path;
+			const pointer = ext.pointer;
+			this.pointerPathMap.set( pointer, path );
 
 		}
 
@@ -384,7 +391,8 @@ export class GLTFAnimationPointerExtension {
 		const useExtension = target.extensions && target.extensions[ KHR_ANIMATION_POINTER ] && target.path && target.path === 'pointer';
 		if ( ! useExtension ) return null;
 
-		let animationPointerPropertyPath = target.extensions[ KHR_ANIMATION_POINTER ].pointer;
+		const pointer = target.extensions[ KHR_ANIMATION_POINTER ].pointer;
+		let animationPointerPropertyPath = this.pointerPathMap.get( pointer );
 		if ( ! animationPointerPropertyPath ) return null;
 
 		const tracks = [];
@@ -698,6 +706,25 @@ export class GLTFAnimationPointerExtension {
 
 
 
+/**
+ * Like Object3D.getObjectByName, but does not match the object itself.
+ * @param {import("three").Object3D} parent
+ * @param {string} name
+ * @returns {import("three").Object3D | undefined}
+ */
+function _findDescendantByName( parent, name ) {
+
+	for ( const child of parent.children ) {
+
+		const found = child.getObjectByName( name );
+		if ( found ) return found;
+
+	}
+
+	return undefined;
+
+}
+
 let _havePatchedPropertyBindings = false;
 
 // HACK monkey patching findNode to ensure we can map to other types required by KHR_animation_pointer.
@@ -776,6 +803,17 @@ function _ensurePropertyBindingPatch() {
 					if (_animationPointerDebug)
 						console.log(currentTarget);
 
+				} else if (currentTarget && currentTarget.isObject3D) {
+
+					// access by child node name, e.g. the submeshes of a multi-material mesh:
+					// `.nodes.<node>.<submesh>.morphTargetInfluences`.
+					// Must resolve inside the already resolved node: a glTF mesh used by multiple nodes
+					// is cloned per node, so every node has identically named submeshes.
+					const foundNode = _findDescendantByName(currentTarget, val);
+
+					if (foundNode)
+						currentTarget = foundNode;
+
 				} else {
 
 					// access by node name
@@ -810,4 +848,4 @@ function _ensurePropertyBindingPatch() {
 
 	};
 
-}
+}