@woosh/meep-engine 2.138.0 → 2.138.1

package/src/engine/network/ecs/NetworkSystem.js

@@ -0,0 +1,84 @@
+import { assert } from "../../../core/assert.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../ecs/System.js";
+import { NetworkIdentity } from "./components/NetworkIdentity.js";
+
+/**
+ * ECS system that owns the per-entity replication lifecycle.
+ *
+ * Responsibilities:
+ *   - When an entity gains a {@link NetworkIdentity}, allocate a `network_id`
+ *     in the peer's slot table (or honour an explicit pre-set one — used by
+ *     `Snapshotter` and incoming-packet flows).
+ *   - When an entity loses its `NetworkIdentity` (or is destroyed), free the
+ *     slot.
+ *
+ * **Not** responsible for the per-tick `begin_tick` / `end_tick` cadence —
+ * the engine's `EntityManager` doesn't expose pre/post-simulate hooks, so the
+ * application code wraps its `engine.simulate(dt)` call:
+ *
+ * ```js
+ *   peer.begin_tick(frame_number);
+ *   engine.simulate(dt);
+ *   peer.end_tick();
+ * ```
+ *
+ * Add this system to the engine once per `NetworkPeer` instance:
+ *
+ * ```js
+ *   const peer = new NetworkPeer({ ... });
+ *   const network_system = new NetworkSystem(peer);
+ *   engine.entityManager.addSystem(network_system);
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class NetworkSystem extends System {
+
+    dependencies = [NetworkIdentity];
+
+    components_used = [
+        ResourceAccessSpecification.from(NetworkIdentity, ResourceAccessKind.Write),
+    ];
+
+    /**
+     * @param {NetworkPeer} peer
+     */
+    constructor(peer) {
+        super();
+        assert.ok(peer && peer.slot_table, 'NetworkSystem: peer must be a NetworkPeer instance with a slot_table');
+
+        /**
+         * @type {NetworkPeer}
+         */
+        this.peer = peer;
+    }
+
+    /**
+     * @param {NetworkIdentity} identity
+     * @param {number} entity
+     */
+    link(identity, entity) {
+        if (identity.network_id < 0) {
+            // Local spawn: allocate a fresh network_id.
+            identity.network_id = this.peer.slot_table.allocate(entity);
+        } else {
+            // Pre-set (e.g. from a Snapshotter or a remote peer's spawn action).
+            // Honour the explicit ID so both sides share the same slot.
+            this.peer.slot_table.allocate_at(identity.network_id, entity);
+        }
+    }
+
+    /**
+     * @param {NetworkIdentity} identity
+     * @param {number} entity
+     */
+    unlink(identity, entity) {
+        if (identity.network_id >= 0) {
+            this.peer.slot_table.free(identity.network_id);
+            identity.network_id = -1;
+        }
+    }
+}

package/src/engine/network/ecs/components/NetworkIdentity.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Marks an entity as replicated and stores its peer-shared `network_id`.
+ *
+ * Replication is opt-in: only entities with this component are visible to
+ * the network layer. Add it before adding any other replicated component;
+ * remove it to stop replication (the entity stays alive locally).
+ *
+ * `network_id` is assigned automatically by {@link NetworkSystem.link} when
+ * the component is added to an entity. If the value is non-negative at link
+ * time, the system uses it as an explicit hint (typical when a packet from a
+ * remote peer carries a `network_id` that must map to a fresh local entity).
+ *
+ * `owner_peer_id` is the peer that has authority over this entity. Default
+ * value `-1` means "the local peer" (server-spawned entities on the server,
+ * or unowned). Game logic uses this to decide whether to trust incoming
+ * mutations or to predict locally.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class NetworkIdentity {
+    /**
+     * Peer-shared identifier. Negative until {@link NetworkSystem.link} runs.
+     * @type {number}
+     */
+    network_id: number;
+    /**
+     * Peer that authoritatively owns this entity, or -1 for "local / server-owned".
+     * @type {number}
+     */
+    owner_peer_id: number;
+    /**
+     * Reserved for game-defined replication policy bits (priority class,
+     * always-relevant flag, interpolation profile, etc.). Layout is up to the game.
+     * @type {number}
+     */
+    replication_flags: number;
+    /**
+     *
+     * @param {NetworkIdentity} other
+     * @returns {boolean}
+     */
+    equals(other: NetworkIdentity): boolean;
+    /**
+     *
+     * @returns {number}
+     */
+    hash(): number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isNetworkIdentity: boolean;
+}
+export namespace NetworkIdentity {
+    let typeName: string;
+}
+//# sourceMappingURL=NetworkIdentity.d.ts.map

package/src/engine/network/ecs/components/NetworkIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkIdentity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/ecs/components/NetworkIdentity.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI;;;OAGG;IACH,YAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,eAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAOnB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IASL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAZ1C;;kBAIS,MAAM"}

package/src/engine/network/ecs/components/NetworkIdentity.js

@@ -0,0 +1,73 @@
+/**
+ * Marks an entity as replicated and stores its peer-shared `network_id`.
+ *
+ * Replication is opt-in: only entities with this component are visible to
+ * the network layer. Add it before adding any other replicated component;
+ * remove it to stop replication (the entity stays alive locally).
+ *
+ * `network_id` is assigned automatically by {@link NetworkSystem.link} when
+ * the component is added to an entity. If the value is non-negative at link
+ * time, the system uses it as an explicit hint (typical when a packet from a
+ * remote peer carries a `network_id` that must map to a fresh local entity).
+ *
+ * `owner_peer_id` is the peer that has authority over this entity. Default
+ * value `-1` means "the local peer" (server-spawned entities on the server,
+ * or unowned). Game logic uses this to decide whether to trust incoming
+ * mutations or to predict locally.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class NetworkIdentity {
+
+    /**
+     * Peer-shared identifier. Negative until {@link NetworkSystem.link} runs.
+     * @type {number}
+     */
+    network_id = -1;
+
+    /**
+     * Peer that authoritatively owns this entity, or -1 for "local / server-owned".
+     * @type {number}
+     */
+    owner_peer_id = -1;
+
+    /**
+     * Reserved for game-defined replication policy bits (priority class,
+     * always-relevant flag, interpolation profile, etc.). Layout is up to the game.
+     * @type {number}
+     */
+    replication_flags = 0;
+
+    /**
+     *
+     * @param {NetworkIdentity} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.network_id === other.network_id
+            && this.owner_peer_id === other.owner_peer_id
+            && this.replication_flags === other.replication_flags
+            ;
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    hash() {
+        return this.network_id ^ this.owner_peer_id ^ this.replication_flags;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+NetworkIdentity.typeName = "NetworkIdentity";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+NetworkIdentity.prototype.isNetworkIdentity = true;

package/src/engine/network/ecs/serialization/NetworkIdentitySerializationAdapter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Highest `owner_peer_id` value the wire format can faithfully represent.
+ * Above this the +1 bias would alias into the "unowned" sentinel encoding.
+ * Documented here so callers can see the limit without spelunking the
+ * adapter internals.
+ *
+ * @type {number}
+ */
+export const MAX_OWNER_PEER_ID: number;
+/**
+ * Save-game adapter for {@link NetworkIdentity}.
+ *
+ * Wire layout: `network_id_varint, owner_peer_id_uint16, replication_flags_uint8`.
+ *
+ * Note: this is for *save-game* persistence, not the per-tick replication
+ * stream. Network packets carry `network_id` inside individual `SimAction`
+ * payloads; the component itself doesn't go on the wire (the receiver creates
+ * a fresh NetworkIdentity locally).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class NetworkIdentitySerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof NetworkIdentity;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {NetworkIdentity} value
+     */
+    serialize(buffer: BinaryBuffer, value: NetworkIdentity): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {NetworkIdentity} value
+     */
+    deserialize(buffer: BinaryBuffer, value: NetworkIdentity): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { NetworkIdentity } from "../components/NetworkIdentity.js";
+//# sourceMappingURL=NetworkIdentitySerializationAdapter.d.ts.map

package/src/engine/network/ecs/serialization/NetworkIdentitySerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkIdentitySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/ecs/serialization/NetworkIdentitySerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,gCAFU,MAAM,CAEwB;AAExC;;;;;;;;;;;;GAYG;AACH;;IAEI,8BAAwB;IACxB,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,eAAe,QAmBzB;IAED;;;OAGG;IACH,yCAFW,eAAe,QAMzB;CACJ;gDA/D+C,gEAAgE;gCAChF,kCAAkC"}

package/src/engine/network/ecs/serialization/NetworkIdentitySerializationAdapter.js

@@ -0,0 +1,64 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { NetworkIdentity } from "../components/NetworkIdentity.js";
+
+/**
+ * Highest `owner_peer_id` value the wire format can faithfully represent.
+ * Above this the +1 bias would alias into the "unowned" sentinel encoding.
+ * Documented here so callers can see the limit without spelunking the
+ * adapter internals.
+ *
+ * @type {number}
+ */
+export const MAX_OWNER_PEER_ID = 0xFFFD;
+
+/**
+ * Save-game adapter for {@link NetworkIdentity}.
+ *
+ * Wire layout: `network_id_varint, owner_peer_id_uint16, replication_flags_uint8`.
+ *
+ * Note: this is for *save-game* persistence, not the per-tick replication
+ * stream. Network packets carry `network_id` inside individual `SimAction`
+ * payloads; the component itself doesn't go on the wire (the receiver creates
+ * a fresh NetworkIdentity locally).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class NetworkIdentitySerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = NetworkIdentity;
+    version = 1;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {NetworkIdentity} value
+     */
+    serialize(buffer, value) {
+        // network_id can be -1 (unassigned). Bias by 1 so the varint stays small.
+        buffer.writeUintVar(value.network_id + 1);
+        // owner_peer_id can also be -1; bias by 1 into uint16 range. Mask
+        // would silently alias values >= 0xFFFE into the "unowned" sentinel.
+        // We throw instead so the truncation can't slip through in a
+        // production bundle (where assertions are stripped). Lift to a
+        // wider field on the wire if we ever expect more than ~65k
+        // concurrent peers.
+        if (value.owner_peer_id > MAX_OWNER_PEER_ID) {
+            throw new Error(
+                `NetworkIdentitySerializationAdapter: owner_peer_id ${value.owner_peer_id} exceeds the wire format limit (${MAX_OWNER_PEER_ID}); ` +
+                `widen the wire format if more peers are needed`
+            );
+        }
+        buffer.writeUint16((value.owner_peer_id + 1) & 0xFFFF);
+        buffer.writeUint8(value.replication_flags & 0xFF);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {NetworkIdentity} value
+     */
+    deserialize(buffer, value) {
+        value.network_id = buffer.readUintVar() - 1;
+        value.owner_peer_id = buffer.readUint16() - 1;
+        value.replication_flags = buffer.readUint8();
+    }
+}