@woosh/meep-engine 3.14.5 → 3.14.6

package/src/engine/navigation/mesh/NavigationMesh.d.ts

@@ -1,3 +1,56 @@
+/**
+ * A navigable surface, plus queries over it.
+ *
+ * ## What the builder expects, and how to check that you gave it that
+ *
+ * {@link build} wants a **manifold walkable surface**. Two things follow from that, and neither is
+ * enforced here, because a full manifold check costs more than most builds and whether to pay it is
+ * the caller's call — not something every valid input should be charged for. What follows is how to
+ * pay it when you want to.
+ *
+ * **1. A surface, not a pile of solids.** Level geometry from a brush-based editor is a set of
+ * interpenetrating closed VOLUMES: a floor brush is not a floor, it is a sealed box whose top
+ * happens to be one, with the wall brush beside it buried in its side. Feeding those in directly
+ * produces a navmesh that routes almost nothing — measured at 5% of spawn pairs on one map, and 32%
+ * on another. Extracting the walkable surface first is two filters and about forty lines: keep
+ * triangles whose normal passes your walk threshold (0.7 is the usual constant, and is what
+ * `agent_max_climb_angle` defaults near), and drop those whose space above is solid. That moved the
+ * same map from 5% to 48%.
+ *
+ * Render geometry is not a substitute. On the same measurement it produced an EMPTY navmesh, from
+ * an input that repair had made near-perfect — 8 islands over 3,301 faces with 99% in the largest.
+ * An empty build is a legitimate answer to bad input and is reported as zero faces.
+ *
+ * **2. Manifold, and welded.** `core/geom/3d/topology` is the repair toolkit and the order matters:
+ * `bt_merge_vertices_by_distance`, then `bt_mesh_fuse_duplicate_edges`, then
+ * `bt_mesh_resolve_t_junctions` — whose own docblock states both the problem (faces of differing
+ * sizes touching at a single vertex are DISCONNECTED to edge-based neighbour queries) and the
+ * recipe (run it after an initial merge/fuse, then fuse again; the mesh must be triangulated).
+ * `bt_mesh_vertex_merge_distance` documents why a hand-rolled snap is worse than the tool: below
+ * the float32 step a tolerance silently degenerates into an exact-bits match and leaves the surface
+ * cracked.
+ *
+ * Note that repair cannot invent connectivity that is not in its input. `bt_mesh_resolve_t_junctions`
+ * splits BOUNDARY edges — ones with exactly one face — so a soup of closed convex brushes has none
+ * and it reports zero splits, correctly. And welding cannot UNION overlapping coplanar patches: two
+ * floor brushes that overlap contribute two surfaces occupying the same space, they do not abut, and
+ * no vertex merge joins them. Closing that needs a boolean union or a voxel rasterisation, which is
+ * upstream of this class.
+ *
+ * **3. Check it, if you want to.** `bt_mesh_validate` and `bt_mesh_is_manifold` answer the question
+ * directly. Running one of them at build time is worth it, because {@link find_path} on a
+ * non-manifold surface can read a released vertex and **throw from inside Polyanya** rather than
+ * report no path — measured at 17 of 72 spawn pairs on one map's unrepaired brushes.
+ *
+ * **4. And consider whether you want a navmesh at all.** For brush-based level geometry a waypoint
+ * graph built by *tracing* — asking the collision system whether a player-sized box gets from here
+ * to there — routed 100% of spawn pairs where the repaired navmesh routed 48%, because a trace does
+ * not care whether the world is one surface or a hundred overlapping ones. That is available to
+ * anyone whose engine has a shape cast, which is everyone reading this.
+ *
+ * All of the above is measured; it is the substance of GAP-016, reported from a port that got it
+ * wrong twice before getting it right.
+ */
 export class NavigationMesh {
     topology: BinaryTopology;
     /**
@@ -6,16 +59,36 @@ export class NavigationMesh {
      */
     bvh: BVH;
     /**
-     * Build from given scene geometry
-     * @param {BinaryTopology} source
-     * @param {number} [agent_radius]
-     * @param {number} [agent_height]
-     * @param {number} [agent_max_step_height] agent can bridge vertical gaps in topology, such as stepping up a stair
-     * @param {number} [agent_max_step_distance] agent can bridge lateral gaps in topology, such as stepping over a hole in the floor
-     * @param {number} [agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
-     * @param {Vector3} [up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
+     * Build from given scene geometry.
+     *
+     * The source is expected to be a manifold walkable SURFACE, not a soup of
+     * solids: a build over interpenetrating closed volumes produces few or no
+     * connected faces, and an input that is not manifold can make
+     * {@link find_path} read a released vertex and throw from inside Polyanya.
+     * `core/geom/3d/topology` carries both the repair tools
+     * (`bt_merge_vertices_by_distance`, `bt_mesh_fuse_duplicate_edges`,
+     * `bt_mesh_resolve_t_junctions`) and the checks (`bt_mesh_validate`,
+     * `bt_mesh_is_manifold`). Neither is run here — a full manifold check costs
+     * more than most builds, and whether to pay it is the caller's call.
+     *
+     * @param {Object} options
+     * @param {BinaryTopology} options.source
+     * @param {number} [options.agent_radius]
+     * @param {number} [options.agent_height]
+     * @param {number} [options.agent_max_step_height] agent can bridge vertical gaps in topology, such as stepping up a stair
+     * @param {number} [options.agent_max_step_distance] agent can bridge lateral gaps in topology, such as stepping over a hole in the floor
+     * @param {number} [options.agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
+     * @param {Vector3} [options.up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
      */
-    build({ source, agent_radius, agent_height, agent_max_step_height, agent_max_step_distance, agent_max_climb_angle, up, }: BinaryTopology): void;
+    build({ source, agent_radius, agent_height, agent_max_step_height, agent_max_step_distance, agent_max_climb_angle, up, }: {
+        source: BinaryTopology;
+        agent_radius?: number;
+        agent_height?: number;
+        agent_max_step_height?: number;
+        agent_max_step_distance?: number;
+        agent_max_climb_angle?: number;
+        up?: Vector3;
+    }): void;
     /**
      * Compute a walkable path between the two points.
      * The result is a sequence of 3d points written into `output`. The first and last points are the
@@ -28,6 +101,13 @@ export class NavigationMesh {
      * through folds. It is intrinsic to the surface — no global "up" is assumed — so it is correct on
      * sloped and folded navmeshes as well as flat ones.
      *
+     * **PRECONDITION: the surface is manifold.** This is not checked — the check costs more than
+     * most queries and charging every valid call for it is the wrong trade — but a non-manifold
+     * surface can make this read a released vertex and THROW from four frames inside Polyanya
+     * rather than return 0. If you are not certain of your input, run `bt_mesh_validate` /
+     * `bt_mesh_is_manifold` once at build time rather than defensively here. See the class
+     * docblock for the repair order.
+     *
      * @param {Float32Array} output packed XYZ triples
      * @param {number} start_x
      * @param {number} start_y
@@ -41,4 +121,5 @@ export class NavigationMesh {
 }
 import { BinaryTopology } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
+import Vector3 from "../../../core/geom/Vector3.js";
 //# sourceMappingURL=NavigationMesh.d.ts.map

package/src/engine/navigation/mesh/NavigationMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAyCA;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;;;OASG;IACH,0HARW,cAAc,QA8BxB;IAGD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAqClB;CAEJ;+BA/I4C,gEAAgE;oBADzF,gCAAgC"}
+{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QARmC,MAAM,EAA9B,cAAc;QACG,YAAY,GAA7B,MAAM;QACW,YAAY,GAA7B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QACW,uBAAuB,GAAxC,MAAM;QACW,qBAAqB,GAAtC,MAAM;QACY,EAAE,GAApB,OAAO;aAwBjB;IAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAqClB;CAEJ;+BAvN4C,gEAAgE;oBADzF,gCAAgC;oBAEhC,+BAA+B"}

package/src/engine/navigation/mesh/NavigationMesh.js

@@ -39,6 +39,59 @@ function nudge_into_face(mesh, face, point) {
     point[2] += (cz - point[2]) * FACE_INTERIOR_PULL;
 }
 
+/**
+ * A navigable surface, plus queries over it.
+ *
+ * ## What the builder expects, and how to check that you gave it that
+ *
+ * {@link build} wants a **manifold walkable surface**. Two things follow from that, and neither is
+ * enforced here, because a full manifold check costs more than most builds and whether to pay it is
+ * the caller's call — not something every valid input should be charged for. What follows is how to
+ * pay it when you want to.
+ *
+ * **1. A surface, not a pile of solids.** Level geometry from a brush-based editor is a set of
+ * interpenetrating closed VOLUMES: a floor brush is not a floor, it is a sealed box whose top
+ * happens to be one, with the wall brush beside it buried in its side. Feeding those in directly
+ * produces a navmesh that routes almost nothing — measured at 5% of spawn pairs on one map, and 32%
+ * on another. Extracting the walkable surface first is two filters and about forty lines: keep
+ * triangles whose normal passes your walk threshold (0.7 is the usual constant, and is what
+ * `agent_max_climb_angle` defaults near), and drop those whose space above is solid. That moved the
+ * same map from 5% to 48%.
+ *
+ * Render geometry is not a substitute. On the same measurement it produced an EMPTY navmesh, from
+ * an input that repair had made near-perfect — 8 islands over 3,301 faces with 99% in the largest.
+ * An empty build is a legitimate answer to bad input and is reported as zero faces.
+ *
+ * **2. Manifold, and welded.** `core/geom/3d/topology` is the repair toolkit and the order matters:
+ * `bt_merge_vertices_by_distance`, then `bt_mesh_fuse_duplicate_edges`, then
+ * `bt_mesh_resolve_t_junctions` — whose own docblock states both the problem (faces of differing
+ * sizes touching at a single vertex are DISCONNECTED to edge-based neighbour queries) and the
+ * recipe (run it after an initial merge/fuse, then fuse again; the mesh must be triangulated).
+ * `bt_mesh_vertex_merge_distance` documents why a hand-rolled snap is worse than the tool: below
+ * the float32 step a tolerance silently degenerates into an exact-bits match and leaves the surface
+ * cracked.
+ *
+ * Note that repair cannot invent connectivity that is not in its input. `bt_mesh_resolve_t_junctions`
+ * splits BOUNDARY edges — ones with exactly one face — so a soup of closed convex brushes has none
+ * and it reports zero splits, correctly. And welding cannot UNION overlapping coplanar patches: two
+ * floor brushes that overlap contribute two surfaces occupying the same space, they do not abut, and
+ * no vertex merge joins them. Closing that needs a boolean union or a voxel rasterisation, which is
+ * upstream of this class.
+ *
+ * **3. Check it, if you want to.** `bt_mesh_validate` and `bt_mesh_is_manifold` answer the question
+ * directly. Running one of them at build time is worth it, because {@link find_path} on a
+ * non-manifold surface can read a released vertex and **throw from inside Polyanya** rather than
+ * report no path — measured at 17 of 72 spawn pairs on one map's unrepaired brushes.
+ *
+ * **4. And consider whether you want a navmesh at all.** For brush-based level geometry a waypoint
+ * graph built by *tracing* — asking the collision system whether a player-sized box gets from here
+ * to there — routed 100% of spawn pairs where the repaired navmesh routed 48%, because a trace does
+ * not care whether the world is one surface or a hundred overlapping ones. That is available to
+ * anyone whose engine has a shape cast, which is everyone reading this.
+ *
+ * All of the above is measured; it is the substance of GAP-016, reported from a port that got it
+ * wrong twice before getting it right.
+ */
 export class NavigationMesh {
 
     topology = new BinaryTopology();
@@ -50,14 +103,26 @@ export class NavigationMesh {
     bvh = new BVH();
 
     /**
-     * Build from given scene geometry
-     * @param {BinaryTopology} source
-     * @param {number} [agent_radius]
-     * @param {number} [agent_height]
-     * @param {number} [agent_max_step_height] agent can bridge vertical gaps in topology, such as stepping up a stair
-     * @param {number} [agent_max_step_distance] agent can bridge lateral gaps in topology, such as stepping over a hole in the floor
-     * @param {number} [agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
-     * @param {Vector3} [up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
+     * Build from given scene geometry.
+     *
+     * The source is expected to be a manifold walkable SURFACE, not a soup of
+     * solids: a build over interpenetrating closed volumes produces few or no
+     * connected faces, and an input that is not manifold can make
+     * {@link find_path} read a released vertex and throw from inside Polyanya.
+     * `core/geom/3d/topology` carries both the repair tools
+     * (`bt_merge_vertices_by_distance`, `bt_mesh_fuse_duplicate_edges`,
+     * `bt_mesh_resolve_t_junctions`) and the checks (`bt_mesh_validate`,
+     * `bt_mesh_is_manifold`). Neither is run here — a full manifold check costs
+     * more than most builds, and whether to pay it is the caller's call.
+     *
+     * @param {Object} options
+     * @param {BinaryTopology} options.source
+     * @param {number} [options.agent_radius]
+     * @param {number} [options.agent_height]
+     * @param {number} [options.agent_max_step_height] agent can bridge vertical gaps in topology, such as stepping up a stair
+     * @param {number} [options.agent_max_step_distance] agent can bridge lateral gaps in topology, such as stepping over a hole in the floor
+     * @param {number} [options.agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
+     * @param {Vector3} [options.up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
      */
     build({
               source,
@@ -96,6 +161,13 @@ export class NavigationMesh {
      * through folds. It is intrinsic to the surface — no global "up" is assumed — so it is correct on
      * sloped and folded navmeshes as well as flat ones.
      *
+     * **PRECONDITION: the surface is manifold.** This is not checked — the check costs more than
+     * most queries and charging every valid call for it is the wrong trade — but a non-manifold
+     * surface can make this read a released vertex and THROW from four frames inside Polyanya
+     * rather than return 0. If you are not certain of your input, run `bt_mesh_validate` /
+     * `bt_mesh_is_manifold` once at build time rather than defensively here. See the class
+     * docblock for the repair order.
+     *
      * @param {Float32Array} output packed XYZ triples
      * @param {number} start_x
      * @param {number} start_y

package/src/engine/network/NetworkSession.d.ts

@@ -419,10 +419,70 @@ export class NetworkSession {
      * @returns {TimeDilation}
      */
     get time_dilation(): TimeDilation;
+    /**
+     * How many entities this session treats as somebody else's — the set that is blended at render
+     * time and normalized before simulation.
+     *
+     * Exposed because its being empty is the observable symptom of a client that thinks it owns the
+     * host's world, and there was no way to see it from outside. Zero here on a connected client
+     * that has received a snapshot means nothing will be interpolated and the client is about to
+     * send the host its own state back.
+     *
+     * @returns {number}
+     */
+    get remote_entity_count(): number;
+    /**
+     * Per-peer delivery accounting, for a game that wants to know whether the wire is actually
+     * delivering what it was handed.
+     *
+     * `skipped_unapplied` should be zero. It counts frames that reached this peer and were dropped
+     * below the applied watermark without ever running — which happens when slices reorder on a
+     * sender pinned to the ring floor, and which the sender cannot see, because the channel-level
+     * ack for the packet returns either way and credits those frames as delivered.
+     *
+     * Until this existed the shortfall was invisible from both ends: it was found by a consumer
+     * counting events dispatched on the host against events applied on the client, and a missing
+     * explosion looks like a rendering bug. Set `max_packets_per_tick: 1` and this climbs under
+     * jitter; on the default it should stay at zero.
+     *
+     * `skipped_duplicate` is the healthy counterpart and is expected to be large — it is the action
+     * stream's own redundancy arriving and being correctly ignored.
+     *
+     * @param {number} peer_id
+     * @returns {{skipped_unapplied: number, skipped_duplicate: number}}
+     */
+    delivery_stats(peer_id: number): {
+        skipped_unapplied: number;
+        skipped_duplicate: number;
+    };
     /**
      * Most recent locally-completed sim frame.
      */
     get current_frame(): number;
+    /**
+     * Move this session's frame counter to `frame`.
+     *
+     * **Joining a match in progress needs this and there was no way to do it.** The host is at
+     * frame 6,000; a client has to start tagging its inputs near 6,000 or the host discards every
+     * one of them — `ServerAuthoritativeServer.tick` trims pending actions older than
+     * `sim_frame - frame_capacity + 1`, and a client tagging frame 0 against a host at 6,000 has
+     * every input dropped **silently**. It moves on its own screen, never moves on the host's, and
+     * no signal fires: `onPendingActionDropped` covers the future-lead and capacity bounds, not
+     * this one.
+     *
+     * Everything needed was already there except the setter. INITIAL_SYNC carries the host's frame,
+     * `NetworkPeer` writes it, and `onInitialSync` dispatches it — and the handler named it
+     * `_frame_number` and dropped it on the floor. `#local_frame` being `#`-private meant an
+     * application could not set it either, so the only lever left was ticking the session forward
+     * with the input sampler silenced until its counter caught up: 28,801 calls and 62 ms of wall
+     * clock for an hour-old host. Reported as GAP-042.
+     *
+     * A client now seeks automatically on INITIAL_SYNC. This is the manual door, for a caller that
+     * computes its own lead.
+     *
+     * @param {number} frame
+     */
+    seek_to_frame(frame: number): void;
     #private;
 }
 import { UUID } from "../ecs/guid/UUID.js";

package/src/engine/network/NetworkSession.d.ts.map

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

package/src/engine/network/NetworkSession.js

@@ -792,10 +792,26 @@ export class NetworkSession {
         // action-stream processing, and finalize any in-flight Tier-3
         // resync state.
         if (this.role === NetworkSessionRole.Client) {
-            this.#peer.onInitialSync.add((_peer_id, session_token, _frame_number, buf, payload_end) => {
+            this.#peer.onInitialSync.add((_peer_id, session_token, frame_number, buf, payload_end) => {
                 const token = new UUID();
                 token.data = session_token;
                 this.session_token = token;
+
+                /*
+                 Align to the host's clock. This argument has always been on the wire and in this
+                 signature -- it was named `_frame_number` and dropped -- and without it a client
+                 joining a match in progress tags its inputs from 0 against a host at frame 6,000,
+                 which trims every one of them silently. GAP-042.
+
+                 The lead is the buffer depth the time dilation is already steering toward: an
+                 input authored now arrives in the host's future, and this is how far ahead it has
+                 to be tagged to land in the window rather than behind it. It only has to be in the
+                 right neighbourhood -- `TimeDilation` converges on the real depth from the host's
+                 feedback within a second or two -- but starting six thousand frames out is not a
+                 neighbourhood, which is what made this total rather than approximate.
+                */
+                this.seek_to_frame(frame_number + 1 + this.#time_dilation.target_buffer_depth);
+
                 this.#apply_initial_sync(buf, payload_end);
                 // Reconnecting counts as well as Resyncing: a host that has
                 // finished with our old session readmits us as a fresh peer,
@@ -1236,6 +1252,45 @@ export class NetworkSession {
         return this.#time_dilation;
     }
 
+    /**
+     * How many entities this session treats as somebody else's — the set that is blended at render
+     * time and normalized before simulation.
+     *
+     * Exposed because its being empty is the observable symptom of a client that thinks it owns the
+     * host's world, and there was no way to see it from outside. Zero here on a connected client
+     * that has received a snapshot means nothing will be interpolated and the client is about to
+     * send the host its own state back.
+     *
+     * @returns {number}
+     */
+    get remote_entity_count() {
+        return this.#remote_entities.size;
+    }
+
+    /**
+     * Per-peer delivery accounting, for a game that wants to know whether the wire is actually
+     * delivering what it was handed.
+     *
+     * `skipped_unapplied` should be zero. It counts frames that reached this peer and were dropped
+     * below the applied watermark without ever running — which happens when slices reorder on a
+     * sender pinned to the ring floor, and which the sender cannot see, because the channel-level
+     * ack for the packet returns either way and credits those frames as delivered.
+     *
+     * Until this existed the shortfall was invisible from both ends: it was found by a consumer
+     * counting events dispatched on the host against events applied on the client, and a missing
+     * explosion looks like a rendering bug. Set `max_packets_per_tick: 1` and this climbs under
+     * jitter; on the default it should stay at zero.
+     *
+     * `skipped_duplicate` is the healthy counterpart and is expected to be large — it is the action
+     * stream's own redundancy arriving and being correctly ignored.
+     *
+     * @param {number} peer_id
+     * @returns {{skipped_unapplied: number, skipped_duplicate: number}}
+     */
+    delivery_stats(peer_id) {
+        return this.#peer.replicator.delivery_stats(peer_id);
+    }
+
     /**
      * Most recent locally-completed sim frame.
      */
@@ -1244,6 +1299,36 @@ export class NetworkSession {
         return this.#local_frame - 1;
     }
 
+    /**
+     * Move this session's frame counter to `frame`.
+     *
+     * **Joining a match in progress needs this and there was no way to do it.** The host is at
+     * frame 6,000; a client has to start tagging its inputs near 6,000 or the host discards every
+     * one of them — `ServerAuthoritativeServer.tick` trims pending actions older than
+     * `sim_frame - frame_capacity + 1`, and a client tagging frame 0 against a host at 6,000 has
+     * every input dropped **silently**. It moves on its own screen, never moves on the host's, and
+     * no signal fires: `onPendingActionDropped` covers the future-lead and capacity bounds, not
+     * this one.
+     *
+     * Everything needed was already there except the setter. INITIAL_SYNC carries the host's frame,
+     * `NetworkPeer` writes it, and `onInitialSync` dispatches it — and the handler named it
+     * `_frame_number` and dropped it on the floor. `#local_frame` being `#`-private meant an
+     * application could not set it either, so the only lever left was ticking the session forward
+     * with the input sampler silenced until its counter caught up: 28,801 calls and 62 ms of wall
+     * clock for an hour-old host. Reported as GAP-042.
+     *
+     * A client now seeks automatically on INITIAL_SYNC. This is the manual door, for a caller that
+     * computes its own lead.
+     *
+     * @param {number} frame
+     */
+    seek_to_frame(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+
+        this.#local_frame = frame;
+        this.#local_frame_accum = 0;
+    }
+
     // ----------------------------------------------------------------
     //  Internal: identity observer (component-driven spawn/despawn)
     // ----------------------------------------------------------------
@@ -1555,6 +1640,33 @@ export class NetworkSession {
                     this.world.addComponentToEntity(local_entity_id, component);
                 } else {
                     adapter.deserialize(buffer, existing);
+
+                    /*
+                     Re-decide what this entity is to us.
+
+                     Ownership DOES arrive — `NetworkIdentity` is auto-replicated as type_id 0 and
+                     the snapshot carries `owner_peer_id` in its payload. What did not happen is the
+                     consequence: `#on_identity_attached` computes remote-set membership once, when
+                     the component is ATTACHED, and this branch runs for an entity that already had
+                     one. So the field was corrected and the decision it feeds was not.
+
+                     That branch is not an edge case, it is the normal one for any client that
+                     pre-builds its entities — which every client must, because nothing is
+                     replicated into existence (GAP-038). The client fills a pool before connecting,
+                     `#on_identity_attached` fills each negative owner with the LOCAL peer's id, the
+                     snapshot then corrects every one of them, and `#remote_entities` stays empty.
+
+                     Two silent failures follow, and neither names ownership. Nothing is
+                     interpolated. And the client's outbound stream carries the host's own state
+                     back to it a few frames stale — the replicator logs every action it APPLIES,
+                     correctly, and `flush_outbound` packs that same log for every peer — so the
+                     host applies its own state to itself. Observed by the reporting port as the
+                     host's player teleporting 64 units downward and falling out of the level, which
+                     reads as a physics bug for as long as you let it. GAP-040.
+                    */
+                    if (ComponentClass === NetworkIdentity) {
+                        this.#apply_ownership(local_entity_id, existing.owner_peer_id);
+                    }
                 }
             }
 
@@ -1564,6 +1676,34 @@ export class NetworkSession {
         }
     }
 
+    /**
+     * Set an entity's owner and bring the remote-entity set into line with it.
+     *
+     * Ownership decides two separate things — whether the entity is blended at render time
+     * (`#remote_entities`) and whether it is sent to a given peer (`OwnerAwareScope`) — and only the
+     * second one re-reads the field. This keeps the first honest when ownership arrives, or changes,
+     * after the component was attached.
+     *
+     * @param {number} entity_id
+     * @param {number} owner_peer_id
+     * @private
+     */
+    #apply_ownership(entity_id, owner_peer_id) {
+        const identity = this.world.getComponent(entity_id, NetworkIdentity);
+
+        if (identity === undefined || identity === null) {
+            return;
+        }
+
+        identity.owner_peer_id = owner_peer_id;
+
+        if (owner_peer_id === this.local_peer_id) {
+            this.#remote_entities.delete(entity_id);
+        } else {
+            this.#remote_entities.add(entity_id);
+        }
+    }
+
     /**
      *
      * @param {number} peer_id

package/src/engine/network/replication/Replicator.d.ts

@@ -52,6 +52,24 @@ export class Replicator {
             is_entity_in_scope(peer_id: number, network_id: number): boolean;
         };
     });
+    /**
+     * Per-peer delivery accounting. Read it, log it, put it on a HUD, fail a test on it.
+     *
+     * `skipped_unapplied` is the one that matters: frames that reached this receiver and were
+     * dropped below the watermark without ever being applied. It should be zero. It is not zero
+     * when slices reorder on a sender pinned to the ring floor, which is what
+     * `max_packets_per_tick: 1` produces under jitter.
+     *
+     * `skipped_duplicate` is the healthy counterpart — the action stream's own redundancy arriving
+     * and being correctly ignored — and is expected to be large.
+     *
+     * @param {number} peer_id
+     * @returns {{skipped_unapplied: number, skipped_duplicate: number}}
+     */
+    delivery_stats(peer_id: number): {
+        skipped_unapplied: number;
+        skipped_duplicate: number;
+    };
     /**
      * Fired after each per-frame action group is fully applied via
      * {@link unpack_from_peer}. Args: `(peer_id, frame_number)`.

package/src/engine/network/replication/Replicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IAkFI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IA/ED;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,aAAa,YAAY,kBAAkB,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAmBrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CA4ElB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0BALW,MAAM,aACN,YAAY,iBACZ,MAAM,UACN;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI,QAmEtE;IAyLD;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBAxlBkB,uCAAuC;6BAD7B,sCAAsC"}
+{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IA4JI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IA/HD;;;;;;;;;;;;;OAaG;IACH,wBAHW,MAAM,GACJ;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,CAUlE;IA0BD;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,aAAa,YAAY,kBAAkB,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAmBrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CA4ElB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0BALW,MAAM,aACN,YAAY,iBACZ,MAAM,UACN;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI,QAmEtE;IAiND;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBA1rBkB,uCAAuC;6BAD7B,sCAAsC"}

package/src/engine/network/replication/Replicator.js

@@ -93,6 +93,80 @@ export class Replicator {
      */
     #inbound = new Map();
 
+    /**
+     * Frames that arrived and were never applied, per peer, and the ones that were.
+     *
+     * **A skipped frame is not the same thing as a lost one, and until now neither was counted.**
+     * The action stream re-sends every unconfirmed frame each tick, so a frame arrives several
+     * times before its ack round-trips and every arrival after the first is skipped — correctly,
+     * and constantly. That is the normal case and it must not be counted as loss.
+     *
+     * What must be counted is the other one: a slice that arrives *after* a newer slice has raised
+     * the watermark past it, whose frames were therefore never applied and never will be, because
+     * its channel-level ack tells the sender they were delivered and nothing re-sends them. That is
+     * the failure `fb116d3a4` fixed for the default configuration and which
+     * `max_packets_per_tick: 1` still reproduces exactly — and the thing that made it expensive to
+     * find is that it is *silent*: a missing explosion looks like a rendering bug and nothing
+     * anywhere reports a shortfall.
+     *
+     * Telling the two apart needs one bit per frame in the window. `applied` is a ring of frame
+     * numbers indexed by `frame % capacity`, holding the frame that last wrote each slot, so a
+     * skipped frame can ask "was I ever applied?" in constant time and constant memory. A frame
+     * older than the window answers "no", which is right: it is beyond recovery either way.
+     *
+     * @type {Map<number, {applied: Int32Array, skipped_unapplied: number, skipped_duplicate: number}>}
+     * @private
+     */
+    #delivery = new Map();
+
+    /**
+     * Per-peer delivery accounting. Read it, log it, put it on a HUD, fail a test on it.
+     *
+     * `skipped_unapplied` is the one that matters: frames that reached this receiver and were
+     * dropped below the watermark without ever being applied. It should be zero. It is not zero
+     * when slices reorder on a sender pinned to the ring floor, which is what
+     * `max_packets_per_tick: 1` produces under jitter.
+     *
+     * `skipped_duplicate` is the healthy counterpart — the action stream's own redundancy arriving
+     * and being correctly ignored — and is expected to be large.
+     *
+     * @param {number} peer_id
+     * @returns {{skipped_unapplied: number, skipped_duplicate: number}}
+     */
+    delivery_stats(peer_id) {
+        const d = this.#delivery.get(peer_id);
+
+        if (d === undefined) {
+            return { skipped_unapplied: 0, skipped_duplicate: 0 };
+        }
+
+        return { skipped_unapplied: d.skipped_unapplied, skipped_duplicate: d.skipped_duplicate };
+    }
+
+    /**
+     * @param {number} peer_id
+     * @returns {{applied: Int32Array, skipped_unapplied: number, skipped_duplicate: number}}
+     * @private
+     */
+    #delivery_state(peer_id) {
+        let d = this.#delivery.get(peer_id);
+
+        if (d === undefined) {
+            const capacity = this.action_log.frame_capacity;
+
+            d = {
+                // -1 is "no frame has occupied this slot"; frame numbers are non-negative
+                applied: new Int32Array(capacity).fill(-1),
+                skipped_unapplied: 0,
+                skipped_duplicate: 0
+            };
+
+            this.#delivery.set(peer_id, d);
+        }
+
+        return d;
+    }
+
     /**
      * Fired after each per-frame action group is fully applied via
      * {@link unpack_from_peer}. Args: `(peer_id, frame_number)`.
@@ -396,6 +470,25 @@ export class Replicator {
             // corrupt the action-log prior-state capture (see #inbound).
             // The read cursor must still advance past this frame's actions.
             if (frame_number < min_frame) {
+                /*
+                 Was this one already applied, or is it being lost right now?
+
+                 Both look identical here — a frame below the watermark, walked past to keep the
+                 read cursor aligned — and the difference is the whole of GAP-043's residual. The
+                 ring says which: a slot still holding this frame number means it was applied and
+                 this is the action stream's own redundancy doing its job; anything else means the
+                 watermark moved past a frame that never ran, and nothing will re-send it because
+                 its channel-level ack already told the sender it arrived.
+                */
+                const delivery = this.#delivery_state(peer_id);
+                const slot = frame_number % delivery.applied.length;
+
+                if (delivery.applied[slot] === frame_number) {
+                    delivery.skipped_duplicate++;
+                } else {
+                    delivery.skipped_unapplied++;
+                }
+
                 for (let i = 0; i < action_count; i++) {
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {
                         throw new MalformedPacketError(`Replicator.unpack_from_peer: action header overruns packet (skip; frame ${frame_number}, action ${i}/${action_count})`);
@@ -443,6 +536,11 @@ export class Replicator {
                 this.action_log.end_frame();
             }
 
+            // Record that it ran, so a later arrival of the same frame is counted as the action
+            // stream's redundancy rather than as a loss. See #delivery.
+            const delivery = this.#delivery_state(peer_id);
+            delivery.applied[frame_number % delivery.applied.length] = frame_number;
+
             // Fire AFTER end_frame so handlers see consistent state and can
             // safely query the action log for the just-applied frame.
             this.onFrameApplied.send2(peer_id, frame_number);