@woosh/meep-engine 3.29.0 → 3.31.0

package/src/engine/physics/cloth/ecs/ClothWorld.js

@@ -275,15 +275,19 @@ export class ClothWorld {
      * for a character spawned whole, which is the one case a spec constructs and
      * the least likely one in a scene where a model loads asynchronously.
      *
-     * Both edges re-seed. The removing edge also gives the joints back first,
-     * because the instance that knows which they were is about to stop being a
-     * rig.
+     * Both edges re-seed, and both give back first, because the instance that
+     * knows what the seeding took is about to stop describing it. On the
+     * removing edge that is the joints; on the adding edge it is a whole
+     * transform subtree, whose authored locals `cloth_write_back` has been
+     * overwriting every step and which exist nowhere else — once the rig path
+     * has seeded over them, `#release` dispatches on a rig and can never give
+     * them back.
      * @type {EntityObserver}
      * @private
      */
     __rig_observer = new EntityObserver(
         [Cloth, ClothRig],
-        (cloth, rig, entity) => this.reseed(entity),
+        (cloth, rig, entity) => this.#rig_added(entity),
         (cloth, rig, entity) => this.#rig_removed(entity),
         this
     );
@@ -408,6 +412,32 @@ export class ClothWorld {
         }
     }
 
+    /**
+     * A {@link ClothRig} has arrived at a live cloth: give back whatever the
+     * cloth had already seeded over — a transform subtree, since the instance
+     * cannot have been a rig yet — then re-seed, which with a rig is the rig
+     * path.
+     *
+     * The release has to happen here rather than inside the re-seed: by the
+     * time `#seed` runs, `cloth_seed_rig` has replaced the captured rest locals
+     * with the proxy's bind pose, and the subtree's authored pose — which
+     * `cloth_write_back` overwrote on the hierarchy itself — is gone for good.
+     *
+     * @param {number} entity
+     * @private
+     */
+    #rig_added(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return;
+        }
+
+        this.#release(instance);
+
+        this.reseed(entity);
+    }
+
     /**
      * A {@link ClothRig} has left a live cloth: give its joints back, then
      * re-seed, which without a rig is the entity path.
@@ -549,6 +579,23 @@ export class ClothWorld {
      * @returns {void}
      */
     finish(instance, ecd) {
+        if (!instance.seeded) {
+            /**
+             * The seeding this step ran against is gone. `#rig_removed` nulls `instance.rig` from an
+             * observer callback while every rig-path array is still in place, and `cloth_seed_rig`
+             * leaves the entity-path arrays empty on purpose so a stale write-back cannot reach a
+             * previous seeding's entities — so between the removal and the next `#seed` the writer
+             * this method picks and the arrays it would read disagree.
+             *
+             * Under `ClothSystem` that window never opens: step and finish are one block. Under
+             * `WorkerClothSystem` a whole frame sits between dispatch and join, so taking a cape off
+             * landed the join on `cloth_write_back` reading an `undefined` transform, inside the
+             * fixed pass. `seeded` is the flag that actually tracks the arrays, so it is what this
+             * follows; the result is discarded and the next step re-seeds and steps again.
+             */
+            return;
+        }
+
         const result = instance.state.result;
 
         instance.contact_count = result[ClothStepResult.CONTACT_COUNT];

package/src/engine/physics/cloth/solver/cloth_self_find.js

@@ -445,4 +445,21 @@ const GRID = new PointHashGrid3();
  * @type {Int32Array}
  * @private
  */
+/**
+ * The buckets a neighbourhood walk here has already visited.
+ *
+ * Both passes in this file walk `PointHashGrid3`'s `offset`/`point` arrays directly rather than
+ * calling `forEachNear`, because their inner loops carry a per-candidate budget check that reads
+ * better as a loop condition than as a visitor returning `false`, and because this is the hottest
+ * loop in the solver. That is a contract taken on, not a shortcut — the grid's class docblock states
+ * it: 27 cells, de-duplicate the buckets, check the real distance.
+ *
+ * This array is the de-duplication, and it is the part a direct walker is most likely to leave out:
+ * two of the 27 cells can hash to one bucket, most easily on a small table, and visiting it twice
+ * hands back every point in it twice. `PointHashGrid3.spec` is where the rule is pinned.
+ *
+ * Module scratch because a walk allocates nothing, and safe because the walks do not nest.
+ *
+ * @type {Int32Array}
+ */
 const VISITED = new Int32Array(27);

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

@@ -22,6 +22,7 @@ export const MAX_CONTACTS_PER_MANIFOLD: number;
  *   14    : friction   (already-combined coefficient for THIS contact's
  *                       specific source-collider pair — see combine_material)
  *   15    : restitution(already-combined coefficient for this contact)
+ *   16    : flags      (per-contact bits, see {@link CONTACT_FLAG_SENSOR})
  *
  * Solver uses `(world_a + world_b) * 0.5` as the application point; storing
  * both surface points enables the per-frame warm-start matcher in the
@@ -32,9 +33,25 @@ export const MAX_CONTACTS_PER_MANIFOLD: number;
  * coefficient at each contact: the narrowphase knows the exact source collider
  * on each side of every contact and combines there.
  *
+ * Flags are stored per contact for the same reason materials are: a body's
+ * colliders need not agree about being solid, and the solver cannot tell which
+ * collider pair produced a given contact. The narrowphase can, and stamps it.
+ *
  * @type {number}
  */
 export const CONTACT_STRIDE: number;
+/**
+ * Per-contact flag: this contact came from a collider pair in which at least
+ * one side carries {@link ColliderFlags.IsSensor}. The solver skips its
+ * impulse while the contact still reaches the event diff.
+ * @type {number}
+ */
+export const CONTACT_FLAG_SENSOR: number;
+/**
+ * Per-contact flags offset within {@link CONTACT_STRIDE}.
+ * @type {number}
+ */
+export const CONTACT_FLAGS_OFFSET: number;
 /**
  * Per-contact feature_id offset within {@link CONTACT_STRIDE}.
  * Exposed for the narrowphase matcher; solver code does not read this.
@@ -252,8 +269,10 @@ export class ManifoldStore {
      * @param {number} friction combined friction for this contact's specific
      *   source-collider pair
      * @param {number} restitution combined restitution for this contact
+     * @param {number} flags per-contact bits for this contact's specific
+     *   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): void;
+    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;
     /**
      * 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

@@ -28,6 +28,7 @@ export const MAX_CONTACTS_PER_MANIFOLD = 4;
  *   14    : friction   (already-combined coefficient for THIS contact's
  *                       specific source-collider pair — see combine_material)
  *   15    : restitution(already-combined coefficient for this contact)
+ *   16    : flags      (per-contact bits, see {@link CONTACT_FLAG_SENSOR})
  *
  * Solver uses `(world_a + world_b) * 0.5` as the application point; storing
  * both surface points enables the per-frame warm-start matcher in the
@@ -38,9 +39,27 @@ export const MAX_CONTACTS_PER_MANIFOLD = 4;
  * coefficient at each contact: the narrowphase knows the exact source collider
  * on each side of every contact and combines there.
  *
+ * Flags are stored per contact for the same reason materials are: a body's
+ * colliders need not agree about being solid, and the solver cannot tell which
+ * collider pair produced a given contact. The narrowphase can, and stamps it.
+ *
+ * @type {number}
+ */
+export const CONTACT_STRIDE = 17;
+
+/**
+ * Per-contact flag: this contact came from a collider pair in which at least
+ * one side carries {@link ColliderFlags.IsSensor}. The solver skips its
+ * impulse while the contact still reaches the event diff.
+ * @type {number}
+ */
+export const CONTACT_FLAG_SENSOR = 1;
+
+/**
+ * Per-contact flags offset within {@link CONTACT_STRIDE}.
  * @type {number}
  */
-export const CONTACT_STRIDE = 16;
+export const CONTACT_FLAGS_OFFSET = 16;
 
 /**
  * Per-contact feature_id offset within {@link CONTACT_STRIDE}.
@@ -440,8 +459,10 @@ export class ManifoldStore {
      * @param {number} friction combined friction for this contact's specific
      *   source-collider pair
      * @param {number} restitution combined restitution for this contact
+     * @param {number} flags per-contact bits for this contact's specific
+     *   source-collider pair — see {@link CONTACT_FLAG_SENSOR}
      */
-    set_contact(slot, idx, lax, lay, laz, lbx, lby, lbz, nx, ny, nz, depth, feature_id = 0, friction = 0, restitution = 0) {
+    set_contact(slot, idx, lax, lay, laz, lbx, lby, lbz, nx, ny, nz, depth, feature_id = 0, friction = 0, restitution = 0, flags = 0) {
         const off = slot * SLOT_DATA_STRIDE + idx * CONTACT_STRIDE;
         this.__data[off] = lax;
         this.__data[off + 1] = lay;
@@ -457,6 +478,7 @@ export class ManifoldStore {
         this.__data[off + 13] = feature_id;
         this.__data[off + 14] = friction;
         this.__data[off + 15] = restitution;
+        this.__data[off + CONTACT_FLAGS_OFFSET] = flags;
 
         const meta_off = slot * SLOT_META_STRIDE;
         const count_now = this.__meta[meta_off + 2] & COUNT_MASK;

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

@@ -247,33 +247,24 @@ export class PhysicsSystem extends System<any> {
      * @type {Float64Array}
      */
     __ccd_start_pos: Float64Array;
+    set interpolationLog(log: any);
     /**
-     * Set this to the {@link InterpolationSystem}'s log to get render
-     * interpolation: each step then restores every awake {@link Interpolated}
-     * body's authoritative pose before simulating, and records the result
-     * afterwards. Leave `null` on a headless world — the work is skipped
-     * entirely.
+     * **Deprecated; does nothing.** Physics used to produce render interpolation itself: with this
+     * set to the {@link InterpolationSystem}'s log, each step restored every awake interpolated
+     * body from the previous tick's record and recorded it again afterwards. The
+     * {@link InterpolationSystem} now records and restores every {@link Interpolated} entity on its
+     * own, around the whole fixed step, so there is nothing to wire.
+     *
+     * The move fixed a defect rather than tidying one up: "restore from the previous tick's record"
+     * cannot tell a render blend from a legitimate write, so a network correction — or any other
+     * write made between steps — was put back to the recorded pose at the start of the next step,
+     * indefinitely for a predicted body the host kept correcting.
+     *
+     * Kept so existing wiring keeps working; setting it warns once.
+     * @deprecated
      * @type {InterpolationLog|null}
      */
-    interpolationLog: InterpolationLog | null;
-    /** @private @type {number} valid entries in {@link __interp_recorded} */
-    private __interp_recorded_count;
-    /**
-     * Reusable decode buffer for restoring interpolated snapshots.
-     * @private
-     * @type {BinaryBuffer}
-     */
-    private __interp_scratch;
-    /**
-     * Body indices snapshotted by the LAST {@link __interp_record} — i.e. the awake
-     * Interpolated set as it was at the end of the previous tick. {@link __interp_restore}
-     * iterates THIS set (not the current awake set) so a body that slept on the previous
-     * tick — recorded before it slept, but absent from the current awake set — is still
-     * restored off its render-polluted pose. Sparse: O(interpolated moving bodies).
-     * @private
-     * @type {Uint32Array}
-     */
-    private __interp_recorded;
+    get interpolationLog(): any;
     /**
      * Symmetric layer/mask check + optional user callback. Called per
      * candidate pair during broadphase. Returns `true` to accept the pair.
@@ -290,15 +281,23 @@ export class PhysicsSystem extends System<any> {
      */
     private __pair_filter;
     /**
-     * First attached collider of a body, or `null` if none. Used for
-     * body-level checks that aren't yet per-collider: the sensor flag, the
-     * concave-shape dispatch flag, and the contact-filter callback's
-     * `colliderA` / `colliderB` arguments. Contact **materials** (friction /
-     * restitution) are NOT read here — the narrowphase tracks the specific
-     * source collider on each side of every contact and stamps the combined
-     * coefficients into the manifold per contact, so mixed-material compound
-     * bodies are accurate. (Per-contact source colliders for the filter
-     * callback / sensor flag remain a follow-up.)
+     * First attached collider of a body, or `null` if none. Used for the
+     * contact-filter callback's `colliderA` / `colliderB` arguments, and as a
+     * "does this body have any colliders" test.
+     *
+     * It is NOT how the solver decides anything about a body. Contact
+     * materials (friction / restitution) and the sensor flag are per contact:
+     * the narrowphase tracks the specific source collider on each side of
+     * every contact and stamps the combined coefficients and
+     * {@link CONTACT_FLAG_SENSOR} into the manifold, so a compound body whose
+     * colliders disagree — different materials, or a trigger volume beside a
+     * solid hull — is handled per contact rather than by whichever collider
+     * {@link ColliderObserverSystem} happened to attach first. The remaining
+     * body-level questions read the whole list, through
+     * {@link body_is_wholly_sensor}.
+     *
+     * (Per-contact source colliders for the filter callback remain a
+     * follow-up.)
      *
      * @private
      * @param {number} body_idx
@@ -518,14 +517,16 @@ export class PhysicsSystem extends System<any> {
     /**
      * Teleport a body to a new pose, bypassing integration: writes the body's
      * Transform64 directly and wakes it. For an interpolated body this also flags a
-     * render `snap` on its {@link Interpolated} component, so the producer keeps
-     * this pose (rather than restoring the previous tick over it) and the
-     * renderer shows the new pose without sliding across the jump.
+     * render `snap` on its {@link Interpolated} component, so the interpolation
+     * history is rewritten to the new pose and the renderer shows it without
+     * sliding across the jump.
      *
-     * This is the authoritative way to reposition an interpolated body — a raw
-     * `Transform64` write would be undone by the per-step restore. Velocity is left
-     * as-is; zero it via {@link setLinearVelocity} if the teleport should also
-     * stop the body.
+     * Prefer this to a raw `Transform64` write. On an interpolated body a raw write
+     * made between steps is put back when the next step opens, unless it set `snap`
+     * or restored the interpolation first; and a raw write neither wakes a sleeping
+     * body nor re-homes a non-dynamic body's broadphase leaves. Velocity is left
+     * as-is; zero it via {@link setLinearVelocity} if the teleport should also stop
+     * the body.
      *
      * Works for STATIC bodies too: their broadphase leaves are re-homed to
      * the new pose, and sleepers at both the old and the new location are
@@ -545,6 +546,15 @@ export class PhysicsSystem extends System<any> {
     /**
      * Force the body asleep. Dynamic bodies will not re-enter the active list
      * until a wake event occurs.
+     *
+     * Velocity is zeroed, exactly as {@link __atomic_sleep_island_range} does
+     * when the simulation puts an island down. That is not a courtesy — the
+     * solver gathers a sleeping Dynamic body as a zero-mass anchor and feeds
+     * its velocity to every contact row it appears in, on the invariant that a
+     * sleeping body is at rest. A body forced asleep mid-flight would otherwise
+     * push its awake neighbours around while immovable itself, and discharge
+     * the stored velocity as a lurch on the next wake.
+     *
      * @param {RigidBody} rigidBody
      */
     sleep(rigidBody: RigidBody): void;
@@ -760,59 +770,12 @@ export class PhysicsSystem extends System<any> {
      * @private
      */
     private __dispatch_contact_events;
-    /**
-     * Producer — restore pass. At the top of a fixed step, reset every awake
-     * {@link Interpolated} body's live components to their authoritative state
-     * from the previous tick's snapshot, undoing any render-time interpolation
-     * the {@link InterpolationSystem} wrote between frames so the sim integrates
-     * from truth, not an interpolated pose. A body with no previous snapshot
-     * (first step ever, or just woken) is left as-is — its live state is already
-     * authoritative. No-op unless {@link interpolationLog} is wired.
-     * @private
-     */
-    private __interp_restore;
-    /**
-     * Producer — record pass. At the end of a fixed step, snapshot every awake
-     * {@link Interpolated} body's live components into the shared log under the
-     * current `entityManager.fixedStepTick`. The render-time
-     * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
-     * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
-     * unless {@link interpolationLog} is wired.
-     *
-     * **A body created after this pass has no snapshot for the step it was born on, and renders
-     * from one snapshot for a step.** This pass runs at the end of `fixedUpdate`, and game code
-     * runs after it — that ordering is correct, the sim must read the solved poses — so a body
-     * spawned by game code is invisible to the tick it was spawned into. Its first record is the
-     * NEXT tick, and `InterpolationLog.interpolate` handles the missing half gracefully by falling
-     * back to whichever snapshot exists. That is the right primitive behaviour and it produces a
-     * bad picture: the entity is drawn at the *newer* tick for a whole frame budget, so it appears
-     * to jump a full step's travel and then hold still for one. Measured at 165 Hz by a port
-     * (GAP-036) as four frames of a rocket parked at the muzzle, reported by a player as
-     * "projectiles move with jerks".
-     *
-     * **Why this is documented rather than fixed, which is the part worth knowing.** The obvious
-     * fix — record a body's pose when it links — does not fit this log. {@link InterpolationLog} is
-     * a strictly monotonic tick ring: `begin_tick` throws while a tick is open, pages are
-     * contiguous ranges that the next page's bytes follow immediately, and `#ticks` is keyed by
-     * tick number — so re-opening the closed tick to append one body would overwrite that tick's
-     * metadata for every other body in it. The fix that does work is to move this pass out of
-     * `fixedUpdate` into a system registered after every simulation system, which is what a
-     * consumer hitting this did; that costs a second mandatory registration, which is a trade this
-     * engine has decided against elsewhere. Closing it properly means either a per-body "first
-     * tick" the blend can consult, or a log that accepts an out-of-order record.
-     *
-     * The workaround needs no engine change: put the body on the application's own timeline via a
-     * pose recorder registered last, since `__interp_restore` does not filter by `sourceId` and
-     * `PhysicsSystem` still restores the authoritative pose before it integrates.
-     *
-     * @private
-     */
-    private __interp_record;
     /**
      * @readonly
      * @type {boolean}
      */
     readonly isPhysicsSystem: boolean;
+    #private;
 }
 import { System } from "../../ecs/System.js";
 import { Transform64 } from "../../ecs/transform/Transform64.js";

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

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