reze-engine 0.33.2 → 0.35.0

package/src/physics/world.ts

@@ -10,6 +10,30 @@ import { findContacts, type ContactPool } from "./contact"
 // integrate; the parent class syncs them from bones around the step. The
 // solver pass runs on all bodies — kinematic ones have invMass = 0 and
 // act as anchors.
+/**
+ * Air movement across the whole world.
+ *
+ * Applied as an acceleration alongside gravity, which is the same shape MMD's
+ * own wind plugins take and keeps it free: gravity and wind are summed once per
+ * substep, so the per-body predict loop is untouched. Terminal velocity comes
+ * out of the existing per-body damping rather than a drag model — PMX authors
+ * already tune that damping to get the hang they want, and a second, hidden
+ * drag term would fight it.
+ */
+export interface WindOptions {
+  /** Direction the air travels. Normalised on assignment; a zero vector is off. */
+  direction: Vec3
+  /** Acceleration along it, in gravity's units — the built-in gravity is 98. */
+  strength: number
+  /** Gust depth, clamped to 0–1. 0 is a steady breeze; 1 swings between still
+   *  and double. It is a clamp rather than a free scalar because past 1 the
+   *  swing goes negative and the wind blows backwards on every other beat,
+   *  which is never what a caller meant by "more turbulent". */
+  turbulence?: number
+  /** Gusts per second. */
+  frequency?: number
+}
+
 export class World {
   readonly gravity: Vec3
   solverIterations = 10
@@ -20,6 +44,17 @@ export class World {
   private linDampFactor: Float32Array | null = null
   private angDampFactor: Float32Array | null = null
 
+  // Wind, resolved to a direction × strength at construction of the options so
+  // the step loop only multiplies by a gust scalar.
+  private windX = 0
+  private windY = 0
+  private windZ = 0
+  private windTurbulence = 0
+  private windFrequency = 0.35
+  /** Advances with simulated time, not wall time, so a scrubbed or exported
+   *  take gusts identically to a live one. */
+  private windClock = 0
+
   constructor(gravity: Vec3) {
     this.gravity = new Vec3(gravity.x, gravity.y, gravity.z)
   }
@@ -30,6 +65,37 @@ export class World {
     this.gravity.z = g.z
   }
 
+  setWind(wind: WindOptions | null): void {
+    // Shape first, and unconditionally: bailing out early on a zero strength
+    // used to leave turbulence and frequency holding whatever a previous call
+    // set, so raising the strength again resurrected settings the caller had
+    // since replaced.
+    this.windTurbulence = Math.min(1, Math.max(0, wind?.turbulence ?? 0))
+    this.windFrequency = Math.max(0, wind?.frequency ?? 0.35)
+
+    const d = wind?.direction
+    const len = d ? Math.hypot(d.x, d.y, d.z) : 0
+    if (!wind || !d || len < 1e-9 || wind.strength === 0) {
+      this.windX = this.windY = this.windZ = 0
+      return
+    }
+    const s = wind.strength / len
+    this.windX = d.x * s
+    this.windY = d.y * s
+    this.windZ = d.z * s
+  }
+
+  getWind(): WindOptions | null {
+    const strength = Math.hypot(this.windX, this.windY, this.windZ)
+    if (strength === 0) return null
+    return {
+      direction: new Vec3(this.windX / strength, this.windY / strength, this.windZ / strength),
+      strength,
+      turbulence: this.windTurbulence,
+      frequency: this.windFrequency,
+    }
+  }
+
   step(
     store: RigidBodyStore,
     constraints: SixDofSpringConstraint[],
@@ -49,9 +115,24 @@ export class World {
     const adamp = store.angularDamping
     const invMass = store.invMass
 
-    const gx = this.gravity.x
-    const gy = this.gravity.y
-    const gz = this.gravity.z
+    // Gravity and wind are the same kind of term, so they are summed here and
+    // the predict loop below never learns wind exists.
+    let gx = this.gravity.x
+    let gy = this.gravity.y
+    let gz = this.gravity.z
+    if (this.windX !== 0 || this.windY !== 0 || this.windZ !== 0) {
+      this.windClock += dt
+      let gust = 1
+      if (this.windTurbulence > 0 && this.windFrequency > 0) {
+        // Two incommensurate sines: a single one is a metronome, and real gusts
+        // do not repeat on a bar line. Stays within 1 ± turbulence.
+        const t = this.windClock * this.windFrequency * Math.PI * 2
+        gust = 1 + this.windTurbulence * 0.5 * (Math.sin(t) + Math.sin(t * 0.37 + 1.3))
+      }
+      gx += this.windX * gust
+      gy += this.windY * gust
+      gz += this.windZ * gust
+    }
 
     // 1. Predict — gravity + damping. The pow form (vs the linear
     //    1−damping·dt approximation) stays stable at high PMX damping