@driftengine/physics 4.13.3 → 4.13.5

package/dist/clothLimits.d.ts

@@ -10,11 +10,12 @@
  * Allocation-free, and each function a kernel the GPU solver mirrors.
  */
 /**
- * Every free particle drawn toward its skinned position, keeping `keep` of its offset: the share a
- * substep keeps under the garment's `pull`, `1 / (1 + pull · h²)`. A kinematic particle is already
- * there.
+ * Every free particle drawn toward its skinned position under the garment's `pull`: `stiffness` is
+ * `pull · h²`, each particle's weighted by `weights` (all 1 where null), and a particle keeps
+ * `1 / (1 + w · stiffness)` of its offset. A kinematic particle is already there, and one weighted
+ * 0 is left as it is: `t + (p − t)` is not `p` in floats.
  */
-export declare function applyPull(position: Float32Array, inverseMass: Float32Array, target: Float32Array, keep: number): void;
+export declare function applyPull(position: Float32Array, inverseMass: Float32Array, target: Float32Array, weights: Float32Array | null, stiffness: number): void;
 /** A particle further than `maxDistance[i] · scale` from its skinned position is put back on that sphere. */
 export declare function applyMaxDistance(position: Float32Array, inverseMass: Float32Array, target: Float32Array, maxDistance: Float32Array, scale: number): void;
 /**

package/dist/clothLimits.js

@@ -10,14 +10,19 @@
  * Allocation-free, and each function a kernel the GPU solver mirrors.
  */
 /**
- * Every free particle drawn toward its skinned position, keeping `keep` of its offset: the share a
- * substep keeps under the garment's `pull`, `1 / (1 + pull · h²)`. A kinematic particle is already
- * there.
+ * Every free particle drawn toward its skinned position under the garment's `pull`: `stiffness` is
+ * `pull · h²`, each particle's weighted by `weights` (all 1 where null), and a particle keeps
+ * `1 / (1 + w · stiffness)` of its offset. A kinematic particle is already there, and one weighted
+ * 0 is left as it is: `t + (p − t)` is not `p` in floats.
  */
-export function applyPull(position, inverseMass, target, keep) {
+export function applyPull(position, inverseMass, target, weights, stiffness) {
     for (let i = 0; i < inverseMass.length; i++) {
         if (inverseMass[i] === 0)
             continue;
+        const pull = weights === null ? stiffness : weights[i] * stiffness;
+        if (!(pull > 0))
+            continue;
+        const keep = 1 / (1 + pull);
         const at = i * 3;
         for (let k = at; k < at + 3; k++) {
             const t = target[k];

package/dist/skinnedCloth.d.ts

@@ -24,6 +24,7 @@ export declare class SkinnedCloth {
     private readonly control;
     private readonly targets;
     private readonly limits;
+    private readonly pullWeights;
     private readonly colliders;
     /** The air the cloth drags toward, metres a second: the set-up's until `setWind` says otherwise. */
     private readonly wind;

package/dist/skinnedCloth.js

@@ -51,6 +51,7 @@ export class SkinnedCloth {
     control;
     targets;
     limits;
+    pullWeights;
     colliders;
     /** The air the cloth drags toward, metres a second: the set-up's until `setWind` says otherwise. */
     wind;
@@ -70,6 +71,7 @@ export class SkinnedCloth {
                 : solvable('bending', bending.quads, 4, bending.rest, bending.compliance, this.inverseMass, bending.batches);
         this.tethers = setup.tethers ?? null;
         this.limits = setup.limits ?? {};
+        this.pullWeights = setup.pullWeights ?? null;
         this.colliders = setup.colliders?.length ?? 0;
         /* Made once, so a step builds nothing: the control calls back into the private step. */
         const device = {
@@ -150,7 +152,7 @@ export class SkinnedCloth {
         const keep = exactExp(damping * h);
         const dragKeep = exactExp(drag * h);
         /* A compliant constraint's step toward the skinned place: see `SkinnedClothParameters.pull`. */
-        const pullKeep = 1 / (1 + this.parameters.pull * h * h);
+        const pullStep = this.parameters.pull * h * h;
         for (let s = 0; s < substeps; s++) {
             predictParticles(this.positions, this.substepStart, this.velocities, this.inverseMass, h, keep, dragKeep, gravity, wind);
             this.distance.lambda.fill(0);
@@ -164,7 +166,7 @@ export class SkinnedCloth {
                     solveTethers(this.positions, tethers.particles, tethers.anchors, tethers.lengths);
                 }
             }
-            this.limit(pullKeep);
+            this.limit(pullStep);
             finishParticles(this.positions, this.substepStart, this.velocities, this.inverseMass, invH);
         }
         if (blend > 0)
@@ -174,11 +176,12 @@ export class SkinnedCloth {
      * The pull, the limits and the colliders, after the constraints, so a garment pulling into the body
      * loses. The pull first, so the hard limits have the last word.
      */
-    limit(pullKeep) {
+    limit(pullStep) {
         const { positions, inverseMass, targets, limits } = this;
         const { maxDistanceScale, margin } = this.parameters;
-        if (pullKeep < 1)
-            applyPull(positions, inverseMass, targets.position, pullKeep);
+        if (pullStep > 0) {
+            applyPull(positions, inverseMass, targets.position, this.pullWeights, pullStep);
+        }
         if (limits.maxDistance !== undefined) {
             applyMaxDistance(positions, inverseMass, targets.position, limits.maxDistance, maxDistanceScale);
         }

package/dist/skinnedClothSetup.d.ts

@@ -114,10 +114,10 @@ export interface SkinnedClothParameters {
      * A share scaled by the step as `damping` is would hold a sag proportional to the step: hair
      * authored to keep 0.7 of its offset a 1/60 step sags 6.36, 3.49 and 1.83 mm at 1/60, 1/120 and
      * 1/240 that way, where this holds 6.36 mm at all three. A share `k` kept a step at a step `s` is `(1 / k − 1) / s²` here, and keeps
-     * exactly `k` at that step. **What it gives up**: one pull for the whole garment, so roots that
-     * should hold harder than tips hold them as hard; it is a pull rather than a limit, so a hard blow
-     * still takes a particle out of shape for a moment; and with no `damping` a stiff one rings, at a
-     * rate a coarse step damps more than a fine one does.
+     * exactly `k` at that step. `SkinnedClothSetup.pullWeights` weighs it particle by particle, so a
+     * strap can be held at its root and hang free at its tip. **What it gives up**: it is a pull
+     * rather than a limit, so a hard blow still takes a particle out of shape for a moment; and with
+     * no `damping` a stiff one rings, at a rate a coarse step damps more than a fine one does.
      */
     readonly pull?: number;
     /**
@@ -166,6 +166,14 @@ export interface SkinnedClothSetup {
     readonly inverseBind?: Float32Array;
     readonly limits?: ClothLimits;
     readonly colliders?: readonly ClothCollider[];
+    /**
+     * One a particle, 0 to 1: how much of the garment's `pull` draws it toward its skinned place,
+     * each substep keeping `1 / (1 + w · pull · h²)` of its offset. Absent, every particle takes the
+     * whole pull. **For a garment held unevenly**: a strap held at its root and free at its tip, a
+     * styled fringe held nearly whole while the body of a coat swings free. A weight of 0 is no pull
+     * at all, which is a free particle, not a kinematic one: `inverseMass` is what pins.
+     */
+    readonly pullWeights?: Float32Array;
 }
 /** The parameters with every default filled in. */
 export interface ResolvedClothParameters {

package/dist/skinnedClothSetup.js

@@ -96,6 +96,13 @@ export function validateClothSetup(setup) {
     per('limits.frontstop', setup.limits?.frontstop, 2);
     per('limits.thickness', setup.limits?.thickness, 1);
     per('limits.selfCollision', setup.limits?.selfCollision, 1);
+    per('pullWeights', setup.pullWeights, 1);
+    const weights = setup.pullWeights;
+    for (let i = 0; weights !== undefined && i < weights.length; i++) {
+        const w = weights[i];
+        if (!(w >= 0 && w <= 1))
+            fail(`pullWeights[${i}] is ${w}: a share of the pull, 0 to 1`);
+    }
     if ((setup.joints === undefined) !== (setup.weights === undefined))
         fail('joints without weights, or weights without joints');
     if ((setup.joints2 === undefined) !== (setup.weights2 === undefined))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/physics",
-  "version": "4.13.3",
+  "version": "4.13.5",
   "description": "Collision shapes, spatial queries and swept kinematic collision",
   "license": "Apache-2.0",
   "type": "module",

package/src/clothLimits.ts

@@ -11,18 +11,23 @@
  */
 
 /**
- * Every free particle drawn toward its skinned position, keeping `keep` of its offset: the share a
- * substep keeps under the garment's `pull`, `1 / (1 + pull · h²)`. A kinematic particle is already
- * there.
+ * Every free particle drawn toward its skinned position under the garment's `pull`: `stiffness` is
+ * `pull · h²`, each particle's weighted by `weights` (all 1 where null), and a particle keeps
+ * `1 / (1 + w · stiffness)` of its offset. A kinematic particle is already there, and one weighted
+ * 0 is left as it is: `t + (p − t)` is not `p` in floats.
  */
 export function applyPull(
   position: Float32Array,
   inverseMass: Float32Array,
   target: Float32Array,
-  keep: number,
+  weights: Float32Array | null,
+  stiffness: number,
 ): void {
   for (let i = 0; i < inverseMass.length; i++) {
     if ((inverseMass[i] as number) === 0) continue;
+    const pull = weights === null ? stiffness : (weights[i] as number) * stiffness;
+    if (!(pull > 0)) continue;
+    const keep = 1 / (1 + pull);
     const at = i * 3;
     for (let k = at; k < at + 3; k++) {
       const t = target[k] as number;

package/src/skinnedCloth.ts

@@ -86,6 +86,7 @@ export class SkinnedCloth {
   private readonly control: ClothControl;
   private readonly targets: ClothTargets;
   private readonly limits: ClothLimits;
+  private readonly pullWeights: Float32Array | null;
   private readonly colliders: number;
   /** The air the cloth drags toward, metres a second: the set-up's until `setWind` says otherwise. */
   private readonly wind: [number, number, number];
@@ -122,6 +123,7 @@ export class SkinnedCloth {
           );
     this.tethers = setup.tethers ?? null;
     this.limits = setup.limits ?? {};
+    this.pullWeights = setup.pullWeights ?? null;
     this.colliders = setup.colliders?.length ?? 0;
     /* Made once, so a step builds nothing: the control calls back into the private step. */
     const device: ClothDevice = {
@@ -219,7 +221,7 @@ export class SkinnedCloth {
     const keep = exactExp(damping * h);
     const dragKeep = exactExp(drag * h);
     /* A compliant constraint's step toward the skinned place: see `SkinnedClothParameters.pull`. */
-    const pullKeep = 1 / (1 + this.parameters.pull * h * h);
+    const pullStep = this.parameters.pull * h * h;
     for (let s = 0; s < substeps; s++) {
       predictParticles(
         this.positions,
@@ -242,7 +244,7 @@ export class SkinnedCloth {
           solveTethers(this.positions, tethers.particles, tethers.anchors, tethers.lengths);
         }
       }
-      this.limit(pullKeep);
+      this.limit(pullStep);
       finishParticles(this.positions, this.substepStart, this.velocities, this.inverseMass, invH);
     }
     if (blend > 0) this.blend(blend);
@@ -252,10 +254,12 @@ export class SkinnedCloth {
    * The pull, the limits and the colliders, after the constraints, so a garment pulling into the body
    * loses. The pull first, so the hard limits have the last word.
    */
-  private limit(pullKeep: number): void {
+  private limit(pullStep: number): void {
     const { positions, inverseMass, targets, limits } = this;
     const { maxDistanceScale, margin } = this.parameters;
-    if (pullKeep < 1) applyPull(positions, inverseMass, targets.position, pullKeep);
+    if (pullStep > 0) {
+      applyPull(positions, inverseMass, targets.position, this.pullWeights, pullStep);
+    }
     if (limits.maxDistance !== undefined) {
       applyMaxDistance(
         positions,

package/src/skinnedClothSetup.ts

@@ -120,10 +120,10 @@ export interface SkinnedClothParameters {
    * A share scaled by the step as `damping` is would hold a sag proportional to the step: hair
    * authored to keep 0.7 of its offset a 1/60 step sags 6.36, 3.49 and 1.83 mm at 1/60, 1/120 and
    * 1/240 that way, where this holds 6.36 mm at all three. A share `k` kept a step at a step `s` is `(1 / k − 1) / s²` here, and keeps
-   * exactly `k` at that step. **What it gives up**: one pull for the whole garment, so roots that
-   * should hold harder than tips hold them as hard; it is a pull rather than a limit, so a hard blow
-   * still takes a particle out of shape for a moment; and with no `damping` a stiff one rings, at a
-   * rate a coarse step damps more than a fine one does.
+   * exactly `k` at that step. `SkinnedClothSetup.pullWeights` weighs it particle by particle, so a
+   * strap can be held at its root and hang free at its tip. **What it gives up**: it is a pull
+   * rather than a limit, so a hard blow still takes a particle out of shape for a moment; and with
+   * no `damping` a stiff one rings, at a rate a coarse step damps more than a fine one does.
    */
   readonly pull?: number;
   /**
@@ -173,6 +173,14 @@ export interface SkinnedClothSetup {
   readonly inverseBind?: Float32Array;
   readonly limits?: ClothLimits;
   readonly colliders?: readonly ClothCollider[];
+  /**
+   * One a particle, 0 to 1: how much of the garment's `pull` draws it toward its skinned place,
+   * each substep keeping `1 / (1 + w · pull · h²)` of its offset. Absent, every particle takes the
+   * whole pull. **For a garment held unevenly**: a strap held at its root and free at its tip, a
+   * styled fringe held nearly whole while the body of a coat swings free. A weight of 0 is no pull
+   * at all, which is a free particle, not a kinematic one: `inverseMass` is what pins.
+   */
+  readonly pullWeights?: Float32Array;
 }
 
 /** The parameters with every default filled in. */
@@ -284,6 +292,12 @@ export function validateClothSetup(setup: SkinnedClothSetup): void {
   per('limits.frontstop', setup.limits?.frontstop, 2);
   per('limits.thickness', setup.limits?.thickness, 1);
   per('limits.selfCollision', setup.limits?.selfCollision, 1);
+  per('pullWeights', setup.pullWeights, 1);
+  const weights = setup.pullWeights;
+  for (let i = 0; weights !== undefined && i < weights.length; i++) {
+    const w = weights[i] as number;
+    if (!(w >= 0 && w <= 1)) fail(`pullWeights[${i}] is ${w}: a share of the pull, 0 to 1`);
+  }
   if ((setup.joints === undefined) !== (setup.weights === undefined))
     fail('joints without weights, or weights without joints');
   if ((setup.joints2 === undefined) !== (setup.weights2 === undefined))