@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,429 @@
+/**
+ * # One live cloth — the binding between a subtree and a `ClothState`
+ *
+ * Everything {@link ClothSystem} needs to step one {@link Cloth} and put the
+ * answer back where it came from. It is a struct: no behaviour, and every array
+ * is indexed by **node**, which is the entity's position in the subtree walk
+ * rather than its position in the solver.
+ *
+ * ## Two numberings, and why they are not the same one
+ *
+ * `ClothState` permutes its particles into colour order and never gives that up
+ * — the sweep is a pair of counted loops over adjacent indices precisely
+ * because it does. So a node index and a particle index are different things,
+ * and {@link particle_of_node} is the only place they meet. Everything on this
+ * object is in node order; everything in `state` is in particle order; the
+ * write-back crosses once per node per step and nothing else ever does.
+ *
+ * ## The local frame
+ *
+ * Particle positions live in the **anchor's own frame** — rigid, so translation
+ * and rotation but not scale, following the same convention the colliders use.
+ * That is what makes §7 P7's inertia model natural (a cloth that feels none of
+ * its anchor's motion is one whose local coordinates simply do not change) and,
+ * as a consequence rather than as a goal, what makes `Float32` positions ample:
+ * the coordinates are garment-sized rather than world-sized.
+ *
+ * The anchor is node 0, particle `particle_of_node[0]`, sits at the local
+ * origin, and is pinned. §11.1's "the anchor entity itself is the fixed set" is
+ * that sentence.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothInstance {
+    /**
+     * The entity carrying the {@link Cloth} component — the anchor.
+     * @type {number}
+     */
+    entity: number;
+    /**
+     * @type {Cloth|null}
+     */
+    cloth: Cloth | null;
+    /**
+     * The anchor's world transform, which is also the cloth's local frame.
+     * @type {Transform64|null}
+     */
+    transform: Transform64 | null;
+    /**
+     * How deep the anchor sits in the transform hierarchy. Instances step in
+     * ascending depth so that a `Cloth` nested inside another one reads an
+     * anchor the outer solve has already written this step.
+     * @type {number}
+     */
+    depth: number;
+    /**
+     * `false` until the subtree has been walked. Seeding is deferred to the
+     * first step rather than done at link, because a rope's links arrive as
+     * separate entities and the one carrying the `Cloth` has no reason to be
+     * last.
+     * @type {boolean}
+     */
+    seeded: boolean;
+    /**
+     * @type {ClothState|null}
+     */
+    state: ClothState | null;
+    /**
+     * @type {number}
+     */
+    node_count: number;
+    /**
+     * Entity per node, in walk order. Node 0 is the anchor.
+     * @type {Int32Array|null}
+     */
+    node_entity: Int32Array | null;
+    /**
+     * Parent node index, `−1` for the anchor.
+     * @type {Int32Array|null}
+     */
+    node_parent: Int32Array | null;
+    /**
+     * The {@link ClothRig} beside the {@link Cloth}, or `null` for a cloth that
+     * simulates its own entity subtree.
+     *
+     * This is the discriminator, and it is a component's presence rather than
+     * an enum (§3.1). Held here rather than looked up per step because it is
+     * what says which seeder ran and therefore which of the two sets of arrays
+     * below is the live one.
+     * @type {ClothRig|null}
+     */
+    rig: ClothRig | null;
+    /**
+     * Live `Transform64` per node — the component instance, held so the step
+     * does not go through the dataset per node per frame. **Entity path only.**
+     * @type {Transform64[]}
+     */
+    node_transform: Transform64[];
+    /**
+     * Live `Node3D` per node — the joint each node drives. **Rig path only**,
+     * and node 0 is the anchor joint, which is not simulated.
+     *
+     * A joint rather than an entity because a skinned model's joints are not
+     * entities and will not be (D47): they are `Node3D`s inside the entity's
+     * `SceneBundleInstance`, and the only writable handle is
+     * `Node3D.transform_local`.
+     * @type {Node3D[]}
+     */
+    node_joint: Node3D[];
+    /**
+     * The anchor joint's **world** pose, evaluated on the CPU each step from the
+     * clips the entity is playing. **Rig path only.**
+     *
+     * Evaluated rather than read: a joint of an animated skeleton is under
+     * `TransformAuthority.GPU`, so its own `transform_global` is not maintained
+     * on the CPU at all and reading it would place the garment wherever the node
+     * was last posed by hand. `pose_evaluate_world` is the sanctioned answer and
+     * the one a socket on the same skeleton gets, which is what keeps a cape on
+     * the shoulder a scabbard hangs from.
+     * @type {Transform64}
+     */
+    anchor_pose: Transform64;
+    /**
+     * Live `TransformAttachment` per node; `null` for the anchor.
+     *
+     * **While a cloth is live this is its output, not its input.** The
+     * write-back writes the local transform as well as the world one, so that a
+     * hierarchy recomposition reproduces the simulated pose rather than
+     * replacing it with the authored one — which is what makes the cloth's
+     * correctness independent of where the scheduler put it. The authored pose
+     * is captured once, at seed, into {@link rest_local_position} and
+     * {@link rest_local_rotation}, and lives in the cloth from then on.
+     * @type {TransformAttachment[]}
+     */
+    node_attachment: TransformAttachment[];
+    /**
+     * The authored local translation of each node, captured at seed, 3 per node.
+     * Nothing else holds it once the first write-back has run.
+     * @type {Float32Array|null}
+     */
+    rest_local_position: Float32Array | null;
+    /**
+     * The authored local rotation of each node, captured at seed, 4 per node.
+     * @type {Float32Array|null}
+     */
+    rest_local_rotation: Float32Array | null;
+    /**
+     * CSR offsets into {@link node_child}, `node_count + 1` entries.
+     * @type {Int32Array|null}
+     */
+    node_child_offset: Int32Array | null;
+    /**
+     * Simulated children per node, node indices.
+     * @type {Int32Array|null}
+     */
+    node_child: Int32Array | null;
+    /**
+     * Entities the walk pruned — the root of a {@link ClothExclude} subtree, or
+     * a nested {@link Cloth}'s anchor — paired with {@link pruned_parent}.
+     *
+     * They are not particles, and they still have to move: each one composes
+     * against a link the solver just wrote. The write-back therefore poses each
+     * of them by hand and announces there, which reaches everything below them
+     * through the ordinary attachment cascade and reaches nothing above them.
+     * @type {Int32Array|null}
+     */
+    pruned_entity: Int32Array | null;
+    /**
+     * Node each pruned entity hangs off.
+     * @type {Int32Array|null}
+     */
+    pruned_parent: Int32Array | null;
+    /**
+     * @type {number}
+     */
+    pruned_count: number;
+    /**
+     * Live `Transform64` per pruned entity.
+     * @type {Transform64[]}
+     */
+    pruned_transform: Transform64[];
+    /**
+     * Live `TransformAttachment` per pruned entity — the local transform
+     * this pass composes against the link the cloth just solved.
+     * @type {TransformAttachment[]}
+     */
+    pruned_attachment: TransformAttachment[];
+    /**
+     * Solver particle for each node.
+     * @type {Int32Array|null}
+     */
+    particle_of_node: Int32Array | null;
+    /**
+     * Geodesic distance from the anchor to each node, metres — the sum of the
+     * rest link lengths along the path, not the straight-line distance.
+     *
+     * This one array drives the tether radius, the slack profile and the pin,
+     * so the three cannot disagree (§3.4). The anchor's is zero, which is what
+     * makes it the fixed set without a second mechanism saying so.
+     * @type {Float32Array|null}
+     */
+    geodesic: Float32Array | null;
+    /**
+     * The animated pose in the cloth's local frame — position, 3 per node —
+     * composed once at seed from {@link rest_local_position} down the walk.
+     *
+     * **Constant, and that is a property of the entity path rather than an
+     * optimisation.** The subtree's authored pose is rigid relative to its
+     * anchor, so expressed in the anchor's own frame it does not move; the only
+     * thing that changes step to step is where that frame is. A subtree whose
+     * links are themselves animated is not an M1 case — that is the rig path,
+     * where the animated pose comes from the skeleton (§11.2) and is live.
+     * @type {Float32Array|null}
+     */
+    animated_position: Float32Array | null;
+    /**
+     * The animated pose's orientation in the cloth's local frame, 4 per node.
+     * @type {Float32Array|null}
+     */
+    animated_rotation: Float32Array | null;
+    /**
+     * The pose the write-back actually writes: the simulated position lerped
+     * towards the animated one by {@link Cloth#blend}, in node order and in
+     * the local frame, 3 per node.
+     *
+     * It exists as an array rather than as a per-node temporary because the
+     * orientation reconstruction needs a node's *neighbours* in the same
+     * blended pose, and blending them twice — once as a neighbour, once as
+     * themselves — is how a rounding difference becomes a visible kink.
+     * @type {Float64Array|null}
+     */
+    blended_position: Float64Array | null;
+    /**
+     * The orientation the write-back reconstructed for each node, in the cloth's
+     * local frame, 4 per node.
+     *
+     * Kept for the length of the pass because a node's **local** transform is
+     * its pose relative to its parent's, so writing it needs the parent's
+     * reconstructed rotation — and the walk is breadth-first, so by the time a
+     * node is reached its parent is already in here.
+     * @type {Float64Array|null}
+     */
+    blended_rotation: Float64Array | null;
+    /**
+     * Leash row enforcing the slack bound for each node, `−1` where there is
+     * none — the anchor, and any node whose `slack` reaches the bound at which
+     * the row is provably inactive.
+     * @type {Int32Array|null}
+     */
+    slack_row: Int32Array | null;
+    /**
+     * Leash row enforcing the tether bound for each node, `−1` for the anchor.
+     * @type {Int32Array|null}
+     */
+    tether_row: Int32Array | null;
+    /**
+     * Stretch rows carrying the parent link of each node, `−1` for the anchor.
+     * @type {Int32Array|null}
+     */
+    link_row: Int32Array | null;
+    /**
+     * Strain-limit rows on the same links, `−1` when the flag is clear.
+     * @type {Int32Array|null}
+     */
+    strain_row: Int32Array | null;
+    /**
+     * Skip rows — the bending model for a chain, one per node that has a
+     * grandparent. `−1` where there is none.
+     * @type {Int32Array|null}
+     */
+    skip_row: Int32Array | null;
+    /**
+     * Largest {@link geodesic} in the cloth: how far this cloth can reach from
+     * its anchor, and the length scale the anchor limits and the teleport
+     * threshold are derived from.
+     * @type {number}
+     */
+    reach: number;
+    /**
+     * Shortest row in the cloth, metres.
+     *
+     * The trust region caps a vertex update at the shortest row incident on
+     * that particle (§5.3), so this is the smallest distance any particle can
+     * be moved in one iteration — and `shortest_row · substeps · iterations`
+     * is therefore the whole of what one fixed step can undo. The velocity
+     * clamp is a multiple of it.
+     * @type {number}
+     */
+    shortest_row: number;
+    /**
+     * The anchor's world translation as of the previous step, `[x, y, z]`.
+     * @type {Float64Array}
+     */
+    anchor_translation: Float64Array;
+    /**
+     * The anchor's world rotation as of the previous step, `[x, y, z, w]`.
+     * @type {Float64Array}
+     */
+    anchor_rotation: Float64Array;
+    /**
+     * `false` until the first step has recorded an anchor pose to compare
+     * against. The first step feels no inertia, which is correct: there is no
+     * motion yet, only a starting place.
+     * @type {boolean}
+     */
+    anchor_valid: boolean;
+    /**
+     * What {@link Cloth#dynamics} looked like when the rows were last
+     * parameterised. Compared rather than watched — a value object is cheap to
+     * compare and a dirty flag is a second thing to keep true.
+     * @type {ClothDynamics}
+     */
+    dynamics_seen: ClothDynamics;
+    /**
+     * Steps remaining in the post-teleport stabilisation window, during which
+     * the velocity limit ramps back up from nothing (§7 P6). Zero when not
+     * stabilising.
+     * @type {number}
+     */
+    stabilise_remaining: number;
+    /**
+     * Consecutive steps whose largest particle displacement was below the sleep
+     * threshold.
+     * @type {number}
+     */
+    still_steps: number;
+    /**
+     * `true` while the cloth is neither stepped nor written back (§7 P5).
+     *
+     * The write-back is skipped as well as the step, and that is the whole of
+     * what makes P5's "bit-identical across the following 300 steps" a fact
+     * rather than a hope: a pose that is not rewritten cannot drift, and one
+     * that is rewritten from unchanged inputs is only *probably* identical.
+     * @type {boolean}
+     */
+    asleep: boolean;
+    /**
+     * What {@link Cloth#blend} was when the write-back last ran.
+     *
+     * Sleep skips the write-back, so a `blend` written while a cloth is asleep
+     * would otherwise take effect at some arbitrary later moment — the next
+     * time something else happened to wake it. A blend change is a request to
+     * see a different pose, so it wakes the cloth like any other.
+     * @type {number}
+     */
+    blend_seen: number;
+    /**
+     * The colliders overlapping this cloth this step, packed in **its own
+     * frame** rather than the world's — the same layout `ClothColliderIndex`
+     * uses, in `Float32` rather than `Float64` because a cloth-local coordinate
+     * is garment-sized (§12).
+     *
+     * Grown, never shrunk, and rewritten every step by
+     * `cloth_gather_colliders`. It lives on the instance rather than inside
+     * {@link state}'s buffer because its size is a property of the *world* — how
+     * many colliders happen to be near this cloth right now — and `ClothState`'s
+     * one allocation is sized from the cloth. §12 puts it in the shared buffer
+     * when M5 needs it there.
+     * @type {Float32Array|null}
+     */
+    collider_table: Float32Array | null;
+    /**
+     * The index handle behind each record in {@link collider_table}. A record
+     * index is this step's; a handle is the collider's, and it is what a
+     * transient contact's multiplier is warm-started on.
+     * @type {Int32Array|null}
+     */
+    collider_key: Int32Array | null;
+    /**
+     * Live records in {@link collider_table}.
+     * @type {number}
+     */
+    collider_count: number;
+    /**
+     * Which particle pairs a self-collision row must never be built on, because
+     * a persistent row already governs them (§9). CSR, sorted, built at seed and
+     * replaced by a re-seed — it depends only on the row tables, so nothing about
+     * a `ClothDynamics` change can invalidate it short of the rows themselves
+     * changing, and those changes all go through `cloth_build_rows`.
+     * @type {{offset: Int32Array, partner: Int32Array}|null}
+     */
+    self_exclusions: {
+        offset: Int32Array;
+        partner: Int32Array;
+    } | null;
+    /**
+     * How close two particles get in the **bind pose** with no row between them,
+     * metres — or `Infinity` when nothing is within reach of anything.
+     *
+     * The ceiling on a self-collision row's radius, and the reason it is a
+     * measured length rather than a multiple of {@link shortest_row}: on a
+     * triangulated sheet the two agree, and on a rigged garment — strips with
+     * nothing joining one to the next — they do not agree at all.
+     * `CLOTH_SELF_RADIUS_MAX_RATIO` and `MEASUREMENTS.md` §37.
+     * @type {number}
+     */
+    closest_free_pair: number;
+    /**
+     * Self-collision pairs the last step found. Diagnostic, and the one to
+     * watch: a garment pinned at `CLOTH_SELF_PAIRS_PER_PARTICLE` per particle is
+     * one whose pairs are being dropped.
+     * @type {number}
+     */
+    self_pairs: number;
+    /**
+     * Contact rows the last step created. Diagnostic — a garment whose contact
+     * count is pinned at four per particle is one whose collider set has more
+     * overlap than `CLOTH_CONTACT_SLOTS` can express.
+     * @type {number}
+     */
+    contact_count: number;
+    /**
+     * `true` once the system has said why this cloth will not seed and stopped
+     * asking. A proxy that does not fit its skin will not start fitting it, and a
+     * warning a frame is a log nobody reads.
+     * @type {boolean}
+     */
+    refused: boolean;
+    /**
+     * How many times this cloth has been re-seeded by a teleport. Diagnostic:
+     * a cloth resetting every few seconds is being driven by something that
+     * looks like a teleport and is not one.
+     * @type {number}
+     */
+    teleport_count: number;
+}
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { ClothDynamics } from "./ClothDynamics.js";
+//# sourceMappingURL=ClothInstance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ClothInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothInstance.js"],"names":[],"mappings":"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"}