@relu-interactives/spatial-ecs 0.11.0 → 0.11.1

package/dist/index.cjs

@@ -3147,6 +3147,21 @@ function createXRAnchorComponent(world, entityId, ...args) {
 __name(createXRAnchorComponent, "createXRAnchorComponent");
 
 // core/components/BoneAttachment.ts
+var xyz = /* @__PURE__ */ __name((value) => {
+  const v = value;
+  return typeof v?.x === "number" && typeof v.y === "number" && typeof v.z === "number" ? { x: v.x, y: v.y, z: v.z } : null;
+}, "xyz");
+function normalizeBoneHold(hold) {
+  return {
+    clips: Array.isArray(hold.clips) ? hold.clips.filter((c) => typeof c === "string") : [],
+    bone: typeof hold.bone === "string" && hold.bone ? hold.bone : null,
+    humanoid: typeof hold.humanoid === "string" && hold.humanoid ? hold.humanoid : null,
+    hidden: hold.hidden === true,
+    position: xyz(hold.position),
+    rotation: xyz(hold.rotation)
+  };
+}
+__name(normalizeBoneHold, "normalizeBoneHold");
 var _BoneAttachmentComponent = class _BoneAttachmentComponent extends Component {
   constructor(options) {
     super();
@@ -3154,6 +3169,8 @@ var _BoneAttachmentComponent = class _BoneAttachmentComponent extends Component
     this.humanoid = options?.humanoid ?? null;
     this.compensateScale = options?.compensateScale ?? true;
     this.enabled = options?.enabled ?? true;
+    this.holds = (options?.holds ?? []).map(normalizeBoneHold);
+    this.hideInOtherClips = options?.hideInOtherClips ?? false;
   }
 };
 __name(_BoneAttachmentComponent, "BoneAttachmentComponent");
@@ -3176,7 +3193,9 @@ function normalizeIKChain(chain) {
     pole: typeof chain.pole === "number" ? chain.pole : null,
     weight: Math.min(1, Math.max(0, weight)),
     matchRotation: chain.matchRotation ?? false,
-    enabled: chain.enabled ?? true
+    enabled: chain.enabled ?? true,
+    clips: Array.isArray(chain.clips) ? chain.clips.filter((c) => typeof c === "string") : null,
+    fade: typeof chain.fade === "number" && Number.isFinite(chain.fade) && chain.fade >= 0 ? chain.fade : null
   };
 }
 __name(normalizeIKChain, "normalizeIKChain");
@@ -3864,6 +3883,7 @@ function restPositions(root) {
   return out;
 }
 __name(restPositions, "restPositions");
+var NUMBERED_NAME = /_\d+$/;
 function splitBoneName(raw) {
   let n = raw.replace(/^.*[:|]/, "").replace(/^(mixamorig\d*|def[-_]|org[-_]|mch[-_]|bip\d*[ _]|b[-_])/i, "").trim();
   let side = null;
@@ -3965,6 +3985,37 @@ function findHips(root) {
 __name(findHips, "findHips");
 var isSpineLike = /* @__PURE__ */ __name((base) => /^(spine|chest|upperchest|torso|back)\d*$/.test(base), "isSpineLike");
 function detectRig(root) {
+  const plain = readRig(root);
+  if (plain.missing.length === 0) return plain;
+  const stems = /* @__PURE__ */ new Map();
+  const count = /* @__PURE__ */ __name((n) => {
+    const stem = n.name.replace(NUMBERED_NAME, "");
+    stems.set(stem, (stems.get(stem) ?? 0) + 1);
+    n.children.forEach(count);
+  }, "count");
+  count(root);
+  const real = /* @__PURE__ */ new Map();
+  const strip = /* @__PURE__ */ __name((n) => {
+    const stem = n.name.replace(NUMBERED_NAME, "");
+    const name = stems.get(stem) === 1 ? stem : n.name;
+    real.set(name, n.name);
+    return { ...n, name, children: n.children.map(strip) };
+  }, "strip");
+  const found = readRig(strip(root));
+  if (found.missing.length >= plain.missing.length) return plain;
+  const realName = /* @__PURE__ */ __name((name) => real.get(name) ?? name, "realName");
+  const bones = {};
+  for (const [bone, name] of Object.entries(found.bones)) {
+    bones[bone] = realName(name);
+  }
+  return {
+    ...found,
+    bones,
+    byName: new Map([...found.byName].map(([name, bone]) => [realName(name), bone]))
+  };
+}
+__name(detectRig, "detectRig");
+function readRig(root) {
   const all = [];
   const collect = /* @__PURE__ */ __name((n) => {
     all.push(n);
@@ -4038,7 +4089,7 @@ function detectRig(root) {
     missing: REQUIRED_HUMANOID_BONES.filter((b) => !bones[b])
   };
 }
-__name(detectRig, "detectRig");
+__name(readRig, "readRig");
 function skeletonFromObject3D(object) {
   const o = object;
   return {
@@ -4264,6 +4315,7 @@ __export(components_exports, {
   createHandPoseEntry: () => createHandPoseEntry,
   defaultMaterialValue: () => defaultMaterialValue,
   handPoseDefinitionFor: () => handPoseDefinitionFor,
+  normalizeBoneHold: () => normalizeBoneHold,
   normalizeEnvironmentLighting: () => normalizeEnvironmentLighting,
   normalizeIKChain: () => normalizeIKChain,
   normalizePhysicsState: () => normalizePhysicsState,
@@ -4435,6 +4487,15 @@ __name(reloadModelEntity, "reloadModelEntity");
 var BONE_SOCKET_FLAG = "__reluBoneSocket";
 var _boneScale = new THREE67__namespace.Vector3();
 var _anchorScale = new THREE67__namespace.Vector3();
+var _holdPosition = new THREE67__namespace.Vector3();
+var _holdRotation = new THREE67__namespace.Quaternion();
+var _heldPosition = new THREE67__namespace.Vector3();
+var _heldRotation = new THREE67__namespace.Quaternion();
+var _holdMatrix = new THREE67__namespace.Matrix4();
+var _heldMatrix = new THREE67__namespace.Matrix4();
+var _holdEuler = new THREE67__namespace.Euler();
+var _unitScale = new THREE67__namespace.Vector3(1, 1, 1);
+var _ignoredScale = new THREE67__namespace.Vector3();
 function createTransform(input) {
   return new TransformComponent(input);
 }
@@ -4461,6 +4522,8 @@ var _ObjectManagementSystem = class _ObjectManagementSystem {
     this.boneSockets = /* @__PURE__ */ new Map();
     /** Attachments whose bone wasn't found in a given model (skip re-searching every frame). */
     this.boneMisses = /* @__PURE__ */ new Map();
+    /** Attachments with holds, and which one the current clip calls for (`null`: none). */
+    this.boneHolds = /* @__PURE__ */ new Map();
     this.scene = scene;
     this.camera = camera;
     this.isEditor = isEditor;
@@ -4647,6 +4710,9 @@ var _ObjectManagementSystem = class _ObjectManagementSystem {
     for (const entityId of [...this.boneSockets.keys()]) {
       if (!world.hasEntity(entityId)) this.dropBoneSocket(entityId);
     }
+    for (const entityId of [...this.boneHolds.keys()]) {
+      if (!world.hasEntity(entityId)) this.boneHolds.delete(entityId);
+    }
     for (const [entityId, object] of worldObjects.entries()) {
       const parentEntityId = world.getComponent(entityId, ParentId)?.value;
       const parentObject = typeof parentEntityId === "number" ? worldObjects.get(parentEntityId) : void 0;
@@ -4680,6 +4746,7 @@ var _ObjectManagementSystem = class _ObjectManagementSystem {
     if (!attachment) {
       if (this.boneSockets.has(entityId)) this.dropBoneSocket(entityId);
       this.boneMisses.delete(entityId);
+      this.boneHolds.delete(entityId);
       return null;
     }
     const root = attachment.enabled && parentEntityId !== null ? world.getComponent(parentEntityId, ModelComponent)?.object ?? null : null;
@@ -4687,7 +4754,9 @@ var _ObjectManagementSystem = class _ObjectManagementSystem {
       this.dropBoneSocket(entityId);
       return null;
     }
-    const key = `${attachment.bone}|${attachment.humanoid ?? ""}|${attachment.compensateScale}`;
+    const hold = this.boneHolds.get(entityId);
+    const ref = hold?.bone || hold?.humanoid ? hold : attachment;
+    const key = `${ref.bone ?? ""}|${ref.humanoid ?? ""}|${attachment.compensateScale}`;
     const current = this.boneSockets.get(entityId);
     if (current && current.modelUuid === root.uuid && current.key === key && current.socket.parent === current.bone) {
       this.fitSocketScale(world, current, parentEntityId, attachment.compensateScale);
@@ -4696,7 +4765,7 @@ var _ObjectManagementSystem = class _ObjectManagementSystem {
     this.dropBoneSocket(entityId);
     const missKey = `${root.uuid}|${key}`;
     if (this.boneMisses.get(entityId) === missKey) return null;
-    const bone = findModelBone(root, attachment);
+    const bone = findModelBone(root, ref);
     if (!bone) {
       this.boneMisses.set(entityId, missKey);
       return null;
@@ -4734,6 +4803,50 @@ var _ObjectManagementSystem = class _ObjectManagementSystem {
       _anchorScale.z / safe(_boneScale.z)
     );
   }
+  /** Whether {@link applyBoneHold} is managing this attachment. */
+  hasBoneHold(entityId) {
+    return this.boneHolds.has(entityId);
+  }
+  /**
+   * Put an attachment in a hold for the clip now playing (`hold` null: the
+   * attachment's own bone and Transform), moving it to the hold's bone if that
+   * changed. Called each frame, since a socket can be rebuilt under it.
+   */
+  applyBoneHold(world, entityId, hold, hidden) {
+    const before = this.boneHolds.get(entityId) ?? null;
+    this.boneHolds.set(entityId, hold);
+    if ((before?.bone ?? null) !== (hold?.bone ?? null) || (before?.humanoid ?? null) !== (hold?.humanoid ?? null)) {
+      this.boneMisses.delete(entityId);
+      this.reconcileSceneFromWorld(world);
+    }
+    const socket = this.boneSockets.get(entityId)?.socket;
+    if (!socket) return;
+    socket.visible = !hidden;
+    if (!hold?.position && !hold?.rotation) {
+      socket.position.set(0, 0, 0);
+      socket.quaternion.identity();
+      return;
+    }
+    const held = world.getComponent(entityId, TransformComponent);
+    if (!held) return;
+    const own = held.position;
+    _heldPosition.set(own.x, own.y, own.z);
+    _heldRotation.setFromEuler(_holdEuler.set(held.rotation.x, held.rotation.y, held.rotation.z));
+    if (hold.position) _holdPosition.set(hold.position.x, hold.position.y, hold.position.z);
+    else _holdPosition.copy(_heldPosition);
+    if (hold.rotation) {
+      _holdRotation.setFromEuler(_holdEuler.set(hold.rotation.x, hold.rotation.y, hold.rotation.z));
+    } else {
+      _holdRotation.copy(_heldRotation);
+    }
+    _holdMatrix.compose(_holdPosition, _holdRotation, _unitScale).multiply(_heldMatrix.compose(_heldPosition, _heldRotation, _unitScale).invert()).decompose(socket.position, socket.quaternion, _ignoredScale);
+    socket.position.multiply(socket.scale);
+  }
+  /** Stop managing an attachment that no longer has holds, and put it back. */
+  releaseBoneHold(world, entityId) {
+    this.applyBoneHold(world, entityId, null, false);
+    this.boneHolds.delete(entityId);
+  }
   /**
    * Load a model entity's file again and swap it in (the file was rewritten);
    * the entity, its components and children stay, attachments re-home.
@@ -6840,6 +6953,10 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       if (typeof source.humanoid === "string" || source.humanoid === null) attachment.humanoid = source.humanoid;
       if (typeof source.compensateScale === "boolean") attachment.compensateScale = source.compensateScale;
       if (typeof source.enabled === "boolean") attachment.enabled = source.enabled;
+      if (Array.isArray(source.holds)) {
+        attachment.holds = source.holds.map((raw) => asRecord3(raw)).filter((h) => !!h).map((h) => normalizeBoneHold(h));
+      }
+      if (typeof source.hideInOtherClips === "boolean") attachment.hideInOtherClips = source.hideInOtherClips;
     }
   }
   if (values.networkIdentityValues.has(sourceEntityId) && !world.getComponent(targetEntityId, NetworkIdentityComponent)) {
@@ -17864,6 +17981,29 @@ var _XRAnchorSystem = class _XRAnchorSystem {
 };
 __name(_XRAnchorSystem, "XRAnchorSystem");
 var XRAnchorSystem = _XRAnchorSystem;
+
+// core/systems/BoneHoldSystem.ts
+var _BoneHoldSystem = class _BoneHoldSystem {
+  update(world) {
+    const oms = world.getObjectManagementSystem();
+    if (!oms) return;
+    for (const id of world.query(BoneAttachmentComponent)) {
+      const attachment = world.getComponent(id, BoneAttachmentComponent);
+      if (!attachment) continue;
+      if (attachment.holds.length === 0 && !attachment.hideInOtherClips) {
+        if (oms.hasBoneHold(id)) oms.releaseBoneHold(world, id);
+        continue;
+      }
+      const character = world.getComponent(id, ParentId)?.value;
+      const clip = typeof character === "number" ? world.getComponent(character, AnimationComponent)?.active?.clip.name : void 0;
+      const hold = clip === void 0 ? void 0 : attachment.holds.find((h) => h.clips.includes(clip));
+      const hidden = hold ? hold.hidden : clip !== void 0 && attachment.hideInOtherClips;
+      oms.applyBoneHold(world, id, hold ?? null, hidden);
+    }
+  }
+};
+__name(_BoneHoldSystem, "BoneHoldSystem");
+var BoneHoldSystem = _BoneHoldSystem;
 var _q = new THREE67__namespace.Quaternion();
 var _q2 = new THREE67__namespace.Quaternion();
 var _s = new THREE67__namespace.Vector3();
@@ -17871,6 +18011,7 @@ var _e = new THREE67__namespace.Vector3();
 var _w = new THREE67__namespace.Vector3();
 var _v = new THREE67__namespace.Vector3();
 var _p = new THREE67__namespace.Vector3();
+var FORWARD = new THREE67__namespace.Vector3(0, 0, 1);
 function setWorldQuaternion(o, q) {
   if (o.parent) {
     o.parent.getWorldQuaternion(_q2).invert();
@@ -17886,7 +18027,7 @@ function turn(o, q) {
   setWorldQuaternion(o, q.clone().multiply(_q));
 }
 __name(turn, "turn");
-function twoBoneIK(upper, lower, end, target, pole) {
+function twoBoneIK(upper, lower, end, target, pole, forward = FORWARD) {
   upper.getWorldPosition(_s);
   lower.getWorldPosition(_e);
   end.getWorldPosition(_w);
@@ -17899,7 +18040,10 @@ function twoBoneIK(upper, lower, end, target, pole) {
   const dir = toT.divideScalar(want || 1).clone();
   const pv = _p.subVectors(pole, _s);
   pv.addScaledVector(dir, -pv.dot(dir));
-  if (pv.lengthSq() < 1e-8) pv.set(0, -1, 0).addScaledVector(dir, dir.y);
+  if (pv.lengthSq() < 1e-8) {
+    if (Math.abs(dir.y) > 0.9) pv.copy(forward).addScaledVector(dir, -dir.dot(forward));
+    else pv.set(0, -1, 0).addScaledVector(dir, dir.y);
+  }
   pv.normalize();
   const cosA = THREE67__namespace.MathUtils.clamp((a * a + c * c - b * b) / (2 * a * c), -1, 1);
   const joint = _s.clone().addScaledVector(dir, a * cosA).addScaledVector(pv, a * Math.sqrt(1 - cosA * cosA));
@@ -17934,6 +18078,7 @@ var _t = new THREE67__namespace.Vector3();
 var _p2 = new THREE67__namespace.Vector3();
 var _q3 = new THREE67__namespace.Quaternion();
 var _pq = new THREE67__namespace.Quaternion();
+var _forward = new THREE67__namespace.Vector3();
 var _IKSystem = class _IKSystem {
   constructor() {
     this.runtimes = /* @__PURE__ */ new Map();
@@ -17951,7 +18096,18 @@ var _IKSystem = class _IKSystem {
     }
     runtime.written.clear();
   }
-  update(world) {
+  /** How strongly a chain applies now, moving its fade on by `deltaTime`. */
+  fadeOf(runtime, chain, animation, deltaTime) {
+    if (!chain.clips) return 1;
+    const clip = animation?.active?.clip.name;
+    const wanted = clip !== void 0 && chain.clips.includes(clip) ? 1 : 0;
+    const was = runtime.fades.get(chain);
+    const seconds = chain.fade ?? animation?.crossFadeDuration ?? 0;
+    const next = was === void 0 || seconds <= 0 ? wanted : was + Math.sign(wanted - was) * Math.min(Math.abs(wanted - was), deltaTime / seconds);
+    runtime.fades.set(chain, next);
+    return THREE67__namespace.MathUtils.smoothstep(next, 0, 1);
+  }
+  update(world, deltaTime = 0) {
     const ids = world.query(IKComponent, ModelComponent);
     const alive = new Set(ids);
     for (const [id, runtime] of this.runtimes) {
@@ -17969,7 +18125,7 @@ var _IKSystem = class _IKSystem {
       let runtime = this.runtimes.get(id);
       if (!runtime || runtime.rootUuid !== root.uuid) {
         if (runtime) this.restore(runtime);
-        runtime = { rootUuid: root.uuid, limbs: /* @__PURE__ */ new Map(), written: /* @__PURE__ */ new Map(), reach: /* @__PURE__ */ new Map() };
+        runtime = { rootUuid: root.uuid, limbs: /* @__PURE__ */ new Map(), written: /* @__PURE__ */ new Map(), reach: /* @__PURE__ */ new Map(), fades: /* @__PURE__ */ new WeakMap() };
         this.runtimes.set(id, runtime);
       }
       for (const [bone, w] of runtime.written) {
@@ -17978,13 +18134,15 @@ var _IKSystem = class _IKSystem {
       runtime.written.clear();
       runtime.reach.clear();
       if (!ik.enabled) continue;
-      const active = ik.chains.filter((c) => c.enabled && c.weight > 0 && typeof c.target === "number");
+      const animation = world.getComponent(id, AnimationComponent);
+      const active = ik.chains.map((chain) => ({ chain, weight: chain.weight * this.fadeOf(runtime, chain, animation, deltaTime) })).filter(({ chain, weight }) => chain.enabled && weight > 0 && typeof chain.target === "number");
       if (active.length === 0) continue;
       if (!matricesFresh) {
         world.getScene().updateMatrixWorld(true);
         matricesFresh = true;
       }
-      for (const chain of active) {
+      root.getWorldDirection(_forward);
+      for (const { chain, weight } of active) {
         let limb = runtime.limbs.get(chain.limb);
         if (!limb) {
           const names = LIMB_BONES[chain.limb];
@@ -18005,16 +18163,16 @@ var _IKSystem = class _IKSystem {
         const poleObject = typeof chain.pole === "number" ? world.getComponent(chain.pole, Object3DRef)?.object : null;
         if (poleObject) poleObject.getWorldPosition(_p2);
         else lower.getWorldPosition(_p2);
-        const miss = twoBoneIK(upper, lower, end, _t, _p2);
+        const miss = twoBoneIK(upper, lower, end, _t, _p2, _forward);
         runtime.reach.set(chain.limb, Math.max(0, miss));
         if (chain.matchRotation) {
           target.getWorldQuaternion(_q3);
           end.parent?.getWorldQuaternion(_pq);
           end.quaternion.copy(_pq.invert().multiply(_q3));
         }
-        if (chain.weight < 1) {
+        if (weight < 1) {
           [upper, lower, end].forEach((bone, i) => {
-            bone.quaternion.copy(animated[i].slerp(bone.quaternion, chain.weight));
+            bone.quaternion.copy(animated[i].slerp(bone.quaternion, weight));
           });
         }
         for (const bone of [upper, lower, end]) {
@@ -19647,6 +19805,7 @@ var _World = class _World {
       isEditor: isEditor ?? false
     });
     const animationSystem = new AnimationSystem();
+    const boneHoldSystem = new BoneHoldSystem();
     const ikSystem = new IKSystem();
     const audioSystem = new AudioSystem({ isEditor: isEditor ?? false });
     const videoSystem = new VideoSystem({ isEditor: isEditor ?? false });
@@ -19681,6 +19840,7 @@ var _World = class _World {
       lightSyncSystem,
       materialSyncSystem,
       animationSystem,
+      boneHoldSystem,
       ikSystem,
       audioSystem,
       videoSystem,
@@ -20846,6 +21006,7 @@ exports.AnimationSystem = AnimationSystem;
 exports.AudioMixer = AudioMixer;
 exports.AudioSystem = AudioSystem;
 exports.Behaviour = Behaviour;
+exports.BoneHoldSystem = BoneHoldSystem;
 exports.CURLED_COS = CURLED_COS;
 exports.CameraSyncSystem = CameraSyncSystem;
 exports.Component = Component;