@woosh/meep-engine 3.38.0 → 3.40.0

package/src/engine/physics/contact/ManifoldStore.d.ts

@@ -273,6 +273,18 @@ export class ManifoldStore {
      *   source-collider pair — see {@link CONTACT_FLAG_SENSOR}
      */
     set_contact(slot: number, idx: number, lax: number, lay: number, laz: number, lbx: number, lby: number, lbz: number, nx: number, ny: number, nz: number, depth: number, feature_id?: number, friction?: number, restitution?: number, flags?: number): void;
+    /**
+     * {@link set_contact} with the contact read from `source[source_offset ..+13]`, laid out in
+     * set_contact's argument order: A witness, B witness, normal, depth, feature id, friction,
+     * restitution, flags. For the narrowphase's refill, which holds its candidates that way: a call
+     * that is not inlined boxes each number passed to it, fourteen a contact.
+     *
+     * @param {number} slot
+     * @param {number} idx contact index in `[0, MAX_CONTACTS_PER_MANIFOLD)`
+     * @param {Float64Array} source
+     * @param {number} source_offset
+     */
+    set_contact_from(slot: number, idx: number, source: Float64Array, source_offset: number): void;
     /**
      * Read the per-contact combined friction stored at one contact.
      * @param {number} slot

package/src/engine/physics/contact/ManifoldStore.d.ts.map

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

package/src/engine/physics/contact/ManifoldStore.js

@@ -487,6 +487,38 @@ export class ManifoldStore {
         }
     }
 
+    /**
+     * {@link set_contact} with the contact read from `source[source_offset ..+13]`, laid out in
+     * set_contact's argument order: A witness, B witness, normal, depth, feature id, friction,
+     * restitution, flags. For the narrowphase's refill, which holds its candidates that way: a call
+     * that is not inlined boxes each number passed to it, fourteen a contact.
+     *
+     * @param {number} slot
+     * @param {number} idx contact index in `[0, MAX_CONTACTS_PER_MANIFOLD)`
+     * @param {Float64Array} source
+     * @param {number} source_offset
+     */
+    set_contact_from(slot, idx, source, source_offset) {
+        const off = slot * SLOT_DATA_STRIDE + idx * CONTACT_STRIDE;
+        const data = this.__data;
+
+        for (let i = 0; i < 10; i++) {
+            data[off + i] = source[source_offset + i];
+        }
+
+        // j_n, j_t1, j_t2 (offsets 10..12) are warm-start; preserved across calls.
+        data[off + 13] = source[source_offset + 10];
+        data[off + 14] = source[source_offset + 11];
+        data[off + 15] = source[source_offset + 12];
+        data[off + CONTACT_FLAGS_OFFSET] = source[source_offset + 13];
+
+        const meta_off = slot * SLOT_META_STRIDE;
+        const count_now = this.__meta[meta_off + 2] & COUNT_MASK;
+        if (idx + 1 > count_now) {
+            this.__meta[meta_off + 2] = (this.__meta[meta_off + 2] & ~COUNT_MASK) | (idx + 1);
+        }
+    }
+
     /**
      * Read the per-contact combined friction stored at one contact.
      * @param {number} slot

package/src/engine/physics/ecs/BodyKind.d.ts

@@ -5,14 +5,22 @@
  *  - {@link BodyKind.Dynamic }: integrated under forces, gravity and contact impulses. The
  *      common case for game-play objects.
  *  - {@link BodyKind.KinematicVelocity }: driven externally by velocity. Pushes Dynamic
- *      bodies but is not pushed back. Mass effectively infinite for the solver.
- *  - {@link BodyKind.KinematicPosition }: driven externally by direct pose writes.
- *      RESERVED, not yet implemented: per-step velocity derivation is NOT
- *      performed, so pose-driven movers currently present to the solver as
- *      stationary walls that teleport. (Deriving velocity implicitly from
- *      Transform64 deltas is deliberately deferred — without a separate
- *      move/teleport API a spawn snap would read as an enormous velocity and
- *      explode contacts. Prefer KinematicVelocity for movers until then.)
+ *      bodies but is not pushed back. Mass effectively infinite for the solver. Each step
+ *      integrates the velocity written to it; it never sleeps.
+ *  - {@link BodyKind.KinematicPosition }: driven externally by pose. Everything above holds
+ *      for it too — the step integrates whatever velocity it carries — and it is the one kind
+ *      that takes {@link PhysicsSystemsetTargetPose }: the next step derives the linear and
+ *      angular velocity that reach the target over its `dt`, so what rides or meets the body
+ *      is carried and pushed by that motion, and the step ends with the body exactly on the
+ *      target. Those velocities stay on the body afterwards, so with no new target it keeps
+ *      moving at the same rate; a driver that wants it still targets the pose it has. The
+ *      first-person controller drives its player body this way: a target every tick, standing
+ *      still included, and setPose only for a warp. A pose written any other way —
+ *      {@link PhysicsSystemsetPose }, or straight into its Transform64 — is a teleport: no
+ *      velocity is derived from it, and to the solver the body is a stationary wall that jumps.
+ *      (Velocity is deliberately never inferred from Transform64 deltas: a spawn snap would read
+ *      as an enormous velocity. setTargetPose is the explicit move, setPose the explicit
+ *      teleport.)
  *
  * These are plain enum ordinals compared by identity (`=== BodyKind.Dynamic`),
  * NOT a bitmask: Static is 0 (can't participate in a mask) and the values are

package/src/engine/physics/ecs/BodyKind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BodyKind.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/BodyKind.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;uBAqBU,MAAM"}
+{"version":3,"file":"BodyKind.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/BodyKind.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;uBA6BU,MAAM"}

package/src/engine/physics/ecs/BodyKind.js

@@ -5,14 +5,22 @@
  *  - {@link BodyKind.Dynamic}: integrated under forces, gravity and contact impulses. The
  *      common case for game-play objects.
  *  - {@link BodyKind.KinematicVelocity}: driven externally by velocity. Pushes Dynamic
- *      bodies but is not pushed back. Mass effectively infinite for the solver.
- *  - {@link BodyKind.KinematicPosition}: driven externally by direct pose writes.
- *      RESERVED, not yet implemented: per-step velocity derivation is NOT
- *      performed, so pose-driven movers currently present to the solver as
- *      stationary walls that teleport. (Deriving velocity implicitly from
- *      Transform64 deltas is deliberately deferred — without a separate
- *      move/teleport API a spawn snap would read as an enormous velocity and
- *      explode contacts. Prefer KinematicVelocity for movers until then.)
+ *      bodies but is not pushed back. Mass effectively infinite for the solver. Each step
+ *      integrates the velocity written to it; it never sleeps.
+ *  - {@link BodyKind.KinematicPosition}: driven externally by pose. Everything above holds
+ *      for it too — the step integrates whatever velocity it carries — and it is the one kind
+ *      that takes {@link PhysicsSystem#setTargetPose}: the next step derives the linear and
+ *      angular velocity that reach the target over its `dt`, so what rides or meets the body
+ *      is carried and pushed by that motion, and the step ends with the body exactly on the
+ *      target. Those velocities stay on the body afterwards, so with no new target it keeps
+ *      moving at the same rate; a driver that wants it still targets the pose it has. The
+ *      first-person controller drives its player body this way: a target every tick, standing
+ *      still included, and setPose only for a warp. A pose written any other way —
+ *      {@link PhysicsSystem#setPose}, or straight into its Transform64 — is a teleport: no
+ *      velocity is derived from it, and to the solver the body is a stationary wall that jumps.
+ *      (Velocity is deliberately never inferred from Transform64 deltas: a spawn snap would read
+ *      as an enormous velocity. setTargetPose is the explicit move, setPose the explicit
+ *      teleport.)
  *
  * These are plain enum ordinals compared by identity (`=== BodyKind.Dynamic`),
  * NOT a bitmask: Static is 0 (can't participate in a mask) and the values are

package/src/engine/physics/ecs/Collider.d.ts

@@ -35,8 +35,13 @@ export class Collider {
      */
     restitution: number;
     /**
-     * Mass-per-unit-volume. Used by inertia-tensor helpers if the user opts in
-     * to automatic mass computation; otherwise informational.
+     * Mass per unit volume, kg/m³. Stored, serialised and compared, and read by nothing else: the
+     * simulation takes a body's mass and inertia from {@link RigidBody#mass} and
+     * {@link RigidBody#inverseInertiaLocal} as written, never from its colliders. To derive them,
+     * pass this as the density to the shape's mass-properties function in `physics/inertia/`
+     * (`sphere_mass_properties`, `box_mass_properties`, `capsule_mass_properties`,
+     * `cylinder_mass_properties`, `convex_hull_mass_properties`), combine a compound's parts with
+     * `mass_properties_accumulate`, and write the result with `rigid_body_set_mass_properties`.
      * @type {number}
      */
     density: number;

package/src/engine/physics/ecs/Collider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Collider.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Collider.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH;IAEI;;;OAGG;IACH,OAFU,eAAe,CAEU;IAEnC;;;;OAIG;IACH,UAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,OAFU,aAAa,GAAC,MAAM,CAEH;IAE3B;;;OAGG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,cAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;OAGG;IACH,gBAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;;;OAMG;IACH;;;;;MAOC;IAED,0BAKC;IAED;;;;;;;;OAQG;IACH,cAHW,QAAQ,GACN,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFa,MAAM,CASlB;IASL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAZ5B;;kBAIS,MAAM;;gCAvKgB,gDAAgD;8BAElD,oBAAoB"}
+{"version":3,"file":"Collider.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Collider.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH;IAEI;;;OAGG;IACH,OAFU,eAAe,CAEU;IAEnC;;;;OAIG;IACH,UAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;;;;;OASG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,OAFU,aAAa,GAAC,MAAM,CAEH;IAE3B;;;OAGG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,cAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;OAGG;IACH,gBAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;;;OAMG;IACH;;;;;MAOC;IAED,0BAKC;IAED;;;;;;;;OAQG;IACH,cAHW,QAAQ,GACN,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFa,MAAM,CASlB;IASL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAZ5B;;kBAIS,MAAM;;gCA5KgB,gDAAgD;8BAElD,oBAAoB"}

package/src/engine/physics/ecs/Collider.js

@@ -45,8 +45,13 @@ export class Collider {
     restitution = 0;
 
     /**
-     * Mass-per-unit-volume. Used by inertia-tensor helpers if the user opts in
-     * to automatic mass computation; otherwise informational.
+     * Mass per unit volume, kg/m³. Stored, serialised and compared, and read by nothing else: the
+     * simulation takes a body's mass and inertia from {@link RigidBody#mass} and
+     * {@link RigidBody#inverseInertiaLocal} as written, never from its colliders. To derive them,
+     * pass this as the density to the shape's mass-properties function in `physics/inertia/`
+     * (`sphere_mass_properties`, `box_mass_properties`, `capsule_mass_properties`,
+     * `cylinder_mass_properties`, `convex_hull_mass_properties`), combine a compound's parts with
+     * `mass_properties_accumulate`, and write the result with `rigid_body_set_mass_properties`.
      * @type {number}
      */
     density = 1;

package/src/engine/physics/ecs/PhysicsEvents.d.ts

@@ -4,6 +4,19 @@
  * contacting pair. This is the only contact-event path; subscribe per entity
  * with `dataset.addEntityEventListener(entity, name, …)`. The payload is
  * **only valid for the dispatch** — copy any field you need to retain.
+ *
+ * A contact is penetration: the narrowphase reports a pair only while it
+ * overlaps by more than nothing. The one exception is an impact the CCD sweep
+ * stops (`RigidBodyFlags.CCD`): the sweep reports it itself, as a ContactBegin
+ * at depth 0 on the step of the impact, and leaves the body 1e-5 to 1.25e-5 m
+ * clear of a convex collider. Nothing then holds the contact open, so unless
+ * something presses the body back in, the next step ends it: a body stopped
+ * dead and left alone reads Begin, End, and nothing after. One pressed back in
+ * afterwards — landing on a box floor under gravity — reads Begin, End, Begin,
+ * Stay, Stay…: the second Begin is the contact the press makes. On a mesh or
+ * heightmap face the sweep leaves the body on the face to rounding, so whether
+ * the next step reads Stay or End falls as the rounding does (19 of 40 drops
+ * onto a mesh floor stayed); pressed in, it stays.
  */
 export type PhysicsEvents = string;
 export namespace PhysicsEvents {

package/src/engine/physics/ecs/PhysicsEvents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PhysicsEvents.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsEvents.js"],"names":[],"mappings":";;;;;;;4BAQU,MAAM"}
+{"version":3,"file":"PhysicsEvents.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/PhysicsEvents.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;4BAqBU,MAAM"}

package/src/engine/physics/ecs/PhysicsEvents.js

@@ -5,6 +5,19 @@
  * with `dataset.addEntityEventListener(entity, name, …)`. The payload is
  * **only valid for the dispatch** — copy any field you need to retain.
  *
+ * A contact is penetration: the narrowphase reports a pair only while it
+ * overlaps by more than nothing. The one exception is an impact the CCD sweep
+ * stops (`RigidBodyFlags.CCD`): the sweep reports it itself, as a ContactBegin
+ * at depth 0 on the step of the impact, and leaves the body 1e-5 to 1.25e-5 m
+ * clear of a convex collider. Nothing then holds the contact open, so unless
+ * something presses the body back in, the next step ends it: a body stopped
+ * dead and left alone reads Begin, End, and nothing after. One pressed back in
+ * afterwards — landing on a box floor under gravity — reads Begin, End, Begin,
+ * Stay, Stay…: the second Begin is the contact the press makes. On a mesh or
+ * heightmap face the sweep leaves the body on the face to rounding, so whether
+ * the next step reads Stay or End falls as the rounding does (19 of 40 drops
+ * onto a mesh floor stayed); pressed in, it stays.
+ *
  * @readonly
  * @enum {string}
  */