@woosh/meep-engine 3.14.4 → 3.14.5

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.14.4",
+  "version": "3.14.5",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/geom/3d/mat4/m4_rigidity_defect.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How far a matrix's linear part is from a rotation — zero for a rigid motion, and growing with
+ * whatever else is in there.
+ *
+ * A rigid motion's upper 3×3 is orthonormal: three unit columns, mutually perpendicular. The defect
+ * is the largest violation of that, over the six facts it comes down to — three lengths against 1,
+ * three pairwise dot products against 0 — so it is scale-free in the sense that matters: a matrix
+ * scaled by `s` reports `|s − 1|`, and a shear reports the cosine of how far the columns have fallen
+ * out of square, whatever the scale.
+ *
+ * Not a norm and not a distance to the nearest rotation. It is a **test statistic**: one number that
+ * is zero exactly when the matrix is rigid, that grows monotonically with the thing you would want
+ * to see, and that can be compared against a tolerance without knowing what shape the matrix is. The
+ * translation is not read — a translation is rigid.
+ *
+ * ## Why this exists
+ *
+ * `dual_quat_from_m4` reads a matrix's upper 3×3 as if it were a rotation. Handed anything else it
+ * answers a rotation anyway — a wrong one, from `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms the
+ * scale has swamped — with no signal that it did. This is how a caller finds out first. See
+ * `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
+ * A **reflection** reports zero: it is orthonormal, and this measures orthonormality. Callers who
+ * care about handedness want the determinant's sign, which is a different question.
+ *
+ * @param {ArrayLike<number>} mat4 column-major, 16 elements
+ * @returns {number} 0 for a rigid motion; larger the further from one
+ */
+export function m4_rigidity_defect(mat4: ArrayLike<number>): number;
+//# sourceMappingURL=m4_rigidity_defect.d.ts.map

package/src/core/geom/3d/mat4/m4_rigidity_defect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m4_rigidity_defect.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/mat4/m4_rigidity_defect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,yCAHW,UAAU,MAAM,CAAC,GACf,MAAM,CA0ClB"}

package/src/core/geom/3d/mat4/m4_rigidity_defect.js

@@ -0,0 +1,71 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * How far a matrix's linear part is from a rotation — zero for a rigid motion, and growing with
+ * whatever else is in there.
+ *
+ * A rigid motion's upper 3×3 is orthonormal: three unit columns, mutually perpendicular. The defect
+ * is the largest violation of that, over the six facts it comes down to — three lengths against 1,
+ * three pairwise dot products against 0 — so it is scale-free in the sense that matters: a matrix
+ * scaled by `s` reports `|s − 1|`, and a shear reports the cosine of how far the columns have fallen
+ * out of square, whatever the scale.
+ *
+ * Not a norm and not a distance to the nearest rotation. It is a **test statistic**: one number that
+ * is zero exactly when the matrix is rigid, that grows monotonically with the thing you would want
+ * to see, and that can be compared against a tolerance without knowing what shape the matrix is. The
+ * translation is not read — a translation is rigid.
+ *
+ * ## Why this exists
+ *
+ * `dual_quat_from_m4` reads a matrix's upper 3×3 as if it were a rotation. Handed anything else it
+ * answers a rotation anyway — a wrong one, from `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms the
+ * scale has swamped — with no signal that it did. This is how a caller finds out first. See
+ * `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
+ * A **reflection** reports zero: it is orthonormal, and this measures orthonormality. Callers who
+ * care about handedness want the determinant's sign, which is a different question.
+ *
+ * @param {ArrayLike<number>} mat4 column-major, 16 elements
+ * @returns {number} 0 for a rigid motion; larger the further from one
+ */
+export function m4_rigidity_defect(mat4) {
+    assert.isArrayLike(mat4, 'mat4');
+
+    const x0 = mat4[0], x1 = mat4[1], x2 = mat4[2];
+    const y0 = mat4[4], y1 = mat4[5], y2 = mat4[6];
+    const z0 = mat4[8], z1 = mat4[9], z2 = mat4[10];
+
+    const length_x = Math.sqrt(x0 * x0 + x1 * x1 + x2 * x2);
+    const length_y = Math.sqrt(y0 * y0 + y1 * y1 + y2 * y2);
+    const length_z = Math.sqrt(z0 * z0 + z1 * z1 + z2 * z2);
+
+    let defect = Math.abs(length_x - 1);
+
+    defect = Math.max(defect, Math.abs(length_y - 1));
+    defect = Math.max(defect, Math.abs(length_z - 1));
+
+    /*
+     The dot products are normalized by the column lengths so that the two halves of the answer are
+     in the same units — a cosine rather than a product of magnitudes. Without it a matrix at a large
+     scale would report its shear multiplied by that scale squared, and a tolerance chosen for one
+     model would mean something else on the next. A degenerate column has no direction to be square
+     to; its zero length has already been counted.
+    */
+    const scale_xy = length_x * length_y;
+    const scale_yz = length_y * length_z;
+    const scale_zx = length_z * length_x;
+
+    if (scale_xy > 0) {
+        defect = Math.max(defect, Math.abs(x0 * y0 + x1 * y1 + x2 * y2) / scale_xy);
+    }
+
+    if (scale_yz > 0) {
+        defect = Math.max(defect, Math.abs(y0 * z0 + y1 * z1 + y2 * z2) / scale_yz);
+    }
+
+    if (scale_zx > 0) {
+        defect = Math.max(defect, Math.abs(z0 * x0 + z1 * x1 + z2 * x2) / scale_zx);
+    }
+
+    return defect;
+}

package/src/engine/network/orchestrator/NetworkPeer.d.ts

@@ -59,10 +59,20 @@ export const ResumeRejectReason: Readonly<{
  * range is confirmed only when `unacked` reaches zero without `abandoned`
  * having been set by a loss along the way.
  *
- * @typedef {{frame_end: number, unacked: number, abandoned: boolean}} PendingAck
- * @property {number} frame_end  last frame in the packed range `[start, frame_end]`
- * @property {number} unacked    seqs of this send not yet acked or declared lost
- * @property {boolean} abandoned at least one seq was declared lost, so the
+ * A tick may make several sends to one peer, each carrying the next slice of
+ * the owed range (see {@link NetworkPeer#flush_outbound}). They confirm
+ * independently, and the baseline advances only through slices confirmed in
+ * order — a later slice landing says nothing about an earlier one still in
+ * flight. `head` marks the first slice of a tick, whose start is the pack
+ * start itself; see {@link NetworkPeer#__credit_confirmed}.
+ *
+ * @typedef {{frame_start: number, frame_end: number, head: boolean, unacked: number, abandoned: boolean}} PendingAck
+ * @property {number} frame_start first frame in the packed range
+ * @property {number} frame_end   last frame in the packed range
+ * @property {boolean} head       this send began at the pack start, so nothing
+ *   sendable lies before it and its confirmation credits outright
+ * @property {number} unacked     seqs of this send not yet acked or declared lost
+ * @property {boolean} abandoned  at least one seq was declared lost, so the
  *   message is forfeit and must never advance the baseline
  */
 /**
@@ -102,9 +112,10 @@ export class NetworkPeer {
      *   initial_buffer_size?: number,
      *   mutation_ledger?: MutationLedger|null,
      *   changed_set_capacity?: number,
+     *   max_packets_per_tick?: number,
      * }} options
      */
-    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, mutation_ledger, changed_set_capacity, }: {
+    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, mutation_ledger, changed_set_capacity, max_packets_per_tick, }: {
         world: EntityComponentDataset;
         binary_registry: BinarySerializationRegistry;
         replicated_components: Function[];
@@ -116,6 +127,7 @@ export class NetworkPeer {
         initial_buffer_size?: number;
         mutation_ledger?: MutationLedger | null;
         changed_set_capacity?: number;
+        max_packets_per_tick?: number;
     });
     /** @type {EntityComponentDataset} */
     world: EntityComponentDataset;
@@ -127,6 +139,32 @@ export class NetworkPeer {
     slot_table: ReplicationSlotTable;
     /** @type {ActionLog} */
     action_log: ActionLog;
+    /**
+     * Most action-stream packets {@link flush_outbound} may send one peer
+     * in a tick. Each carries the next slice of what the peer is owed and
+     * is confirmed on its own, so this caps how fast a peer that has
+     * fallen behind catches up: a slice is re-sent every tick until its ack
+     * returns, so a peer is confirmed at most this many packets of frames
+     * per round trip, against the one frame per tick the simulation
+     * produces. One packet a tick keeps up only while a round trip's frames
+     * fit one packet; past that the owed range grows until it meets the
+     * ring floor and frames are lost.
+     *
+     * It is also the bandwidth ceiling under catch-up — this many MTUs per
+     * tick per peer — and it has to stay inside the channel's ack window.
+     * A peer's ack header covers its latest 33 seqs, so with a peer that
+     * replies once a tick, `33 / max_packets_per_tick` consecutive lost
+     * replies leave a delivered packet outside the window and it is
+     * declared lost: a wasted re-send rather than a defect, since the
+     * receiver skips frames it has already applied. Eight tolerates three
+     * such losses in a row (one tick in sixteen at 50% loss, one in ten
+     * thousand at 10%), and lets a 60 Hz stream at 100 ms RTT carry a full
+     * packet of actions per frame. Lower it for peers that reply less often
+     * than every tick.
+     *
+     * @type {number}
+     */
+    max_packets_per_tick: number;
     /**
      * Optional per-tick mutation tracker. When a `MutationLedger` is supplied,
      * this peer records each tick's affected network IDs into a fresh
@@ -325,9 +363,10 @@ export class NetworkPeer {
      * by the caller. Records the tick's accumulated mutations into the
      * MutationLedger (if configured), then packs frames
      * `[last_acked+1, current_frame]` for each peer via
-     * `Replicator.pack_for_peer`, bounded to one channel packet. Empty packs
-     * (no in-scope actions) are not sent. Clears the per-tick changed-entity
-     * set after recording.
+     * `Replicator.pack_for_peer` into up to {@link max_packets_per_tick}
+     * channel packets, each the next slice of that range. Empty packs (no
+     * in-scope actions) are not sent. Clears the per-tick changed-entity set
+     * after recording.
      *
      * @param {number} current_frame
      */
@@ -456,9 +495,18 @@ export class NetworkPeer {
  * the receiver reassembles a fragmented message all-or-nothing, so the frame
  * range is confirmed only when `unacked` reaches zero without `abandoned`
  * having been set by a loss along the way.
+ *
+ * A tick may make several sends to one peer, each carrying the next slice of
+ * the owed range (see {@link NetworkPeerflush_outbound }). They confirm
+ * independently, and the baseline advances only through slices confirmed in
+ * order — a later slice landing says nothing about an earlier one still in
+ * flight. `head` marks the first slice of a tick, whose start is the pack
+ * start itself; see {@link NetworkPeer__credit_confirmed }.
  */
 export type PendingAck = {
+    frame_start: number;
     frame_end: number;
+    head: boolean;
     unacked: number;
     abandoned: boolean;
 };

package/src/engine/network/orchestrator/NetworkPeer.d.ts.map

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