@driftengine/physics 4.13.1 → 4.13.3

package/dist/clothLimits.d.ts

@@ -9,6 +9,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.
+ */
+export declare function applyPull(position: Float32Array, inverseMass: Float32Array, target: Float32Array, keep: 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

@@ -9,6 +9,22 @@
  *
  * 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.
+ */
+export function applyPull(position, inverseMass, target, keep) {
+    for (let i = 0; i < inverseMass.length; i++) {
+        if (inverseMass[i] === 0)
+            continue;
+        const at = i * 3;
+        for (let k = at; k < at + 3; k++) {
+            const t = target[k];
+            position[k] = t + (position[k] - t) * keep;
+        }
+    }
+}
 /** A particle further than `maxDistance[i] · scale` from its skinned position is put back on that sphere. */
 export function applyMaxDistance(position, inverseMass, target, maxDistance, scale) {
     for (let i = 0; i < inverseMass.length; i++) {

package/dist/skinnedCloth.d.ts

@@ -54,7 +54,10 @@ export declare class SkinnedCloth {
      * each predicted, constrained, limited and turned into velocities.
      */
     private stepAt;
-    /** The limits and the colliders, after the constraints, so a garment pulling into the body loses. */
+    /**
+     * 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;
     /** After a reset, the share of the simulation drawn grows from nothing to all over the blend. */
     private blend;

package/dist/skinnedCloth.js

@@ -17,7 +17,7 @@
  */
 import { batchesOf } from './clothBatches.js';
 import { ClothControl } from './clothControl.js';
-import { applyColliders, applyMaxDistance, applyStops } from './clothLimits.js';
+import { applyColliders, applyMaxDistance, applyPull, applyStops } from './clothLimits.js';
 import { carryParticles } from './clothPose.js';
 import { exactExp } from './exact.js';
 import { finishParticles, predictParticles, solveBendingBatch, solveDistanceBatch, solveTethers, } from './skinnedClothSolve.js';
@@ -149,6 +149,8 @@ export class SkinnedCloth {
         const invH2 = invH * invH;
         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);
         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);
@@ -162,16 +164,21 @@ export class SkinnedCloth {
                     solveTethers(this.positions, tethers.particles, tethers.anchors, tethers.lengths);
                 }
             }
-            this.limit();
+            this.limit(pullKeep);
             finishParticles(this.positions, this.substepStart, this.velocities, this.inverseMass, invH);
         }
         if (blend > 0)
             this.blend(blend);
     }
-    /** The limits and the colliders, after the constraints, so a garment pulling into the body loses. */
-    limit() {
+    /**
+     * 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) {
         const { positions, inverseMass, targets, limits } = this;
         const { maxDistanceScale, margin } = this.parameters;
+        if (pullKeep < 1)
+            applyPull(positions, inverseMass, targets.position, pullKeep);
         if (limits.maxDistance !== undefined) {
             applyMaxDistance(positions, inverseMass, targets.position, limits.maxDistance, maxDistanceScale);
         }

package/dist/skinnedClothSetup.d.ts

@@ -97,6 +97,29 @@ export interface SkinnedClothParameters {
     readonly damping?: number;
     /** The same, of the velocity relative to the wind: how fast the air takes the cloth with it. */
     readonly drag?: number;
+    /**
+     * How hard each particle is drawn back toward where skinning puts it, as a stiffness: metres a
+     * second squared toward its skinned position for every metre it is away from it. Zero, the
+     * default, is none. A particle at rest under gravity alone sits `9.81 / pull` metres below its
+     * skinned place, whatever the step.
+     *
+     * **For a garment made to hold a shape gravity would undo**: styled hair held by a few pinned
+     * particles at its roots keeps the shape it was made in at rest and swings out of it only as the
+     * body moves, then settles back. The hard limits cannot do that: a max distance is a sphere a
+     * particle may fall anywhere inside, so hair falls to its edge and hangs.
+     *
+     * **A stiffness, not a share of the offset kept a second as `damping` is.** Applied first among
+     * the limits, after the constraints, each substep keeping `1 / (1 + pull · h²)` of the offset: a
+     * compliant constraint's step, so the shape it holds against gravity is one length at every step.
+     * 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.
+     */
+    readonly pull?: number;
     /**
      * Metres a second, world space: the air the cloth starts in. Default still air. A garment in a
      * scene follows the scene's wind a frame at a time, through `setWind`.
@@ -153,6 +176,7 @@ export interface ResolvedClothParameters {
     readonly gravity: readonly [number, number, number];
     readonly damping: number;
     readonly drag: number;
+    readonly pull: number;
     readonly wind: readonly [number, number, number];
     readonly linearInertia: number;
     readonly angularInertia: number;

package/dist/skinnedClothSetup.js

@@ -20,6 +20,7 @@ export function resolveClothParameters(parameters) {
         gravity: parameters.gravity ?? [0, -9.81, 0],
         damping: parameters.damping ?? 0,
         drag: parameters.drag ?? 0,
+        pull: parameters.pull ?? 0,
         wind: parameters.wind ?? [0, 0, 0],
         linearInertia: Math.min(1, Math.max(0, parameters.linearInertia ?? 1)),
         angularInertia: Math.min(1, Math.max(0, parameters.angularInertia ?? 1)),
@@ -76,6 +77,10 @@ export function validateClothSetup(setup) {
     const step = parameters.step ?? 1 / 60;
     if (!(step > 0))
         fail(`a step of ${step} seconds`);
+    /* A stiffness below zero pushes a particle away from its skinned place rather than toward it. */
+    const pull = parameters.pull ?? 0;
+    if (!(pull >= 0 && pull < Infinity))
+        fail(`a pull of ${pull}: a stiffness, zero or above`);
     const per = (name, values, width) => {
         if (values !== undefined && values.length !== count * width) {
             fail(`${name} has ${values.length} entries for ${count} particles of ${width}`);

package/package.json

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

package/src/clothLimits.ts

@@ -10,6 +10,27 @@
  * 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.
+ */
+export function applyPull(
+  position: Float32Array,
+  inverseMass: Float32Array,
+  target: Float32Array,
+  keep: number,
+): void {
+  for (let i = 0; i < inverseMass.length; i++) {
+    if ((inverseMass[i] as number) === 0) continue;
+    const at = i * 3;
+    for (let k = at; k < at + 3; k++) {
+      const t = target[k] as number;
+      position[k] = t + ((position[k] as number) - t) * keep;
+    }
+  }
+}
+
 /** A particle further than `maxDistance[i] · scale` from its skinned position is put back on that sphere. */
 export function applyMaxDistance(
   position: Float32Array,

package/src/skinnedCloth.ts

@@ -18,7 +18,7 @@
 import { batchesOf } from './clothBatches.ts';
 import { ClothControl } from './clothControl.ts';
 import type { ClothDevice } from './clothControl.ts';
-import { applyColliders, applyMaxDistance, applyStops } from './clothLimits.ts';
+import { applyColliders, applyMaxDistance, applyPull, applyStops } from './clothLimits.ts';
 import { carryParticles } from './clothPose.ts';
 import type { ClothTargets } from './clothTargets.ts';
 import { exactExp } from './exact.ts';
@@ -218,6 +218,8 @@ export class SkinnedCloth {
     const invH2 = invH * invH;
     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);
     for (let s = 0; s < substeps; s++) {
       predictParticles(
         this.positions,
@@ -240,16 +242,20 @@ export class SkinnedCloth {
           solveTethers(this.positions, tethers.particles, tethers.anchors, tethers.lengths);
         }
       }
-      this.limit();
+      this.limit(pullKeep);
       finishParticles(this.positions, this.substepStart, this.velocities, this.inverseMass, invH);
     }
     if (blend > 0) this.blend(blend);
   }
 
-  /** The limits and the colliders, after the constraints, so a garment pulling into the body loses. */
-  private limit(): void {
+  /**
+   * 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 {
     const { positions, inverseMass, targets, limits } = this;
     const { maxDistanceScale, margin } = this.parameters;
+    if (pullKeep < 1) applyPull(positions, inverseMass, targets.position, pullKeep);
     if (limits.maxDistance !== undefined) {
       applyMaxDistance(
         positions,

package/src/skinnedClothSetup.ts

@@ -103,6 +103,29 @@ export interface SkinnedClothParameters {
   readonly damping?: number;
   /** The same, of the velocity relative to the wind: how fast the air takes the cloth with it. */
   readonly drag?: number;
+  /**
+   * How hard each particle is drawn back toward where skinning puts it, as a stiffness: metres a
+   * second squared toward its skinned position for every metre it is away from it. Zero, the
+   * default, is none. A particle at rest under gravity alone sits `9.81 / pull` metres below its
+   * skinned place, whatever the step.
+   *
+   * **For a garment made to hold a shape gravity would undo**: styled hair held by a few pinned
+   * particles at its roots keeps the shape it was made in at rest and swings out of it only as the
+   * body moves, then settles back. The hard limits cannot do that: a max distance is a sphere a
+   * particle may fall anywhere inside, so hair falls to its edge and hangs.
+   *
+   * **A stiffness, not a share of the offset kept a second as `damping` is.** Applied first among
+   * the limits, after the constraints, each substep keeping `1 / (1 + pull · h²)` of the offset: a
+   * compliant constraint's step, so the shape it holds against gravity is one length at every step.
+   * 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.
+   */
+  readonly pull?: number;
   /**
    * Metres a second, world space: the air the cloth starts in. Default still air. A garment in a
    * scene follows the scene's wind a frame at a time, through `setWind`.
@@ -161,6 +184,7 @@ export interface ResolvedClothParameters {
   readonly gravity: readonly [number, number, number];
   readonly damping: number;
   readonly drag: number;
+  readonly pull: number;
   readonly wind: readonly [number, number, number];
   readonly linearInertia: number;
   readonly angularInertia: number;
@@ -183,6 +207,7 @@ export function resolveClothParameters(
     gravity: parameters.gravity ?? [0, -9.81, 0],
     damping: parameters.damping ?? 0,
     drag: parameters.drag ?? 0,
+    pull: parameters.pull ?? 0,
     wind: parameters.wind ?? [0, 0, 0],
     linearInertia: Math.min(1, Math.max(0, parameters.linearInertia ?? 1)),
     angularInertia: Math.min(1, Math.max(0, parameters.angularInertia ?? 1)),
@@ -241,6 +266,9 @@ export function validateClothSetup(setup: SkinnedClothSetup): void {
   }
   const step = parameters.step ?? 1 / 60;
   if (!(step > 0)) fail(`a step of ${step} seconds`);
+  /* A stiffness below zero pushes a particle away from its skinned place rather than toward it. */
+  const pull = parameters.pull ?? 0;
+  if (!(pull >= 0 && pull < Infinity)) fail(`a pull of ${pull}: a stiffness, zero or above`);
   const per = (name: string, values: ArrayLike<number> | undefined, width: number): void => {
     if (values !== undefined && values.length !== count * width) {
       fail(`${name} has ${values.length} entries for ${count} particles of ${width}`);