@woosh/meep-engine 3.22.0 → 3.23.0

package/src/engine/physics/cloth/ecs/cloth_write_back.d.ts

@@ -1,3 +1,53 @@
+/**
+ * # Putting the answer back onto entities — §11.1
+ *
+ * `cloth_reconstruct_pose.js` turns particles into a pose in the cloth's own
+ * frame — positions blended towards the animated ones, orientations
+ * reconstructed as a swing on the animated orientation. This file is what puts
+ * that pose onto **entities**; `cloth_write_back_rig.js` is what puts the same
+ * pose onto a skinned model's joints, and the split is M3's, made when the
+ * second writer arrived rather than by anticipating it.
+ *
+ * ## Both transforms are written, and that is what makes ordering harmless
+ *
+ * Each simulated node gets its **world** `Transform64` and its **local**
+ * `TransformAttachment#transform`, and the two agree. Writing only the world
+ * one is cheaper and is a trap: the attachment system recomposes a child from
+ * its local whenever the parent announces, so any announcement arriving after
+ * cloth had written would replace the simulated pose with the authored one for
+ * the rest of the frame — and where in the fixed step cloth ran would be a
+ * correctness question. With the local written too, **a recomposition
+ * reproduces exactly what cloth just wrote**, and cloth's placement costs at
+ * worst a shape one fixed step stale.
+ *
+ * That is also the shape of the engine's own precedent:
+ * `InverseKinematicsSystem` reads world transforms the hierarchy has composed
+ * and writes local ones back, and §11.2's rig path writes
+ * `Node3D.transform_local` for the same reason — a local transform is what a
+ * joint angle *is*.
+ *
+ * A node's local transform is its pose relative to its **parent's**, so this
+ * needs the parent's reconstructed rotation as well as its position — which is
+ * what {@link ClothInstance#blended_rotation} is for, and why the pass runs in
+ * the walk's breadth-first order.
+ *
+ * The authored pose is not lost by being overwritten: it was captured at seed
+ * and lives in the cloth (`cloth_seed_subtree.js`), which is what `blend = 0`
+ * returns to and what the leash centres are measured from.
+ *
+ * ## What is announced
+ *
+ * Nothing on a simulated node: every one of its simulated children has already
+ * been written by this same pass, so the cascade would recompute a pose that is
+ * already correct, once per level, quadratically for a chain. What *is*
+ * announced is each pruned boundary — the root of a `ClothExclude` subtree, or
+ * a nested `Cloth`'s anchor — which this pass poses by hand against the link it
+ * hangs from, so everything below the cut follows the simulation through the
+ * ordinary attachment cascade and nothing above it is disturbed.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
 /**
  * Write one cloth's solved pose onto its subtree.
  *
@@ -6,4 +56,15 @@
  * @returns {void}
  */
 export function cloth_write_back(instance: ClothInstance, ecd: EntityComponentDataset): void;
+/**
+ * One node's pose relative to its parent's, in whatever `Transform64` the
+ * caller holds. Both writers need it and neither owns it.
+ *
+ * @param {Transform64} local written in place, matrix included
+ * @param {ClothInstance} instance
+ * @param {number} node
+ * @param {number} parent
+ * @returns {void}
+ */
+export function cloth_write_local_pose(local: Transform64, instance: ClothInstance, node: number, parent: number): void;
 //# sourceMappingURL=cloth_write_back.d.ts.map

package/src/engine/physics/cloth/ecs/cloth_write_back.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_write_back.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_write_back.js"],"names":[],"mappings":"AAwGA;;;;;;GAMG;AACH,wFAFa,IAAI,CA+GhB"}
+{"version":3,"file":"cloth_write_back.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_write_back.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH;;;;;;GAMG;AACH,wFAFa,IAAI,CAmDhB;AAyBD;;;;;;;;;GASG;AACH,0FAJW,MAAM,UACN,MAAM,GACJ,IAAI,CA4BhB"}