@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/relation_store-BsoegrZh.js

@@ -0,0 +1,313 @@
+import { SparseRestoreError as u } from "../index.js";
+import { u as c } from "./assertions-gtDVfbnQ.js";
+const z = -1;
+Object.freeze(/* @__PURE__ */ Object.create(null));
+const F = 31, E = 20, p = (1 << E) - 1, R = p, $ = F - E, y = (1 << $) - 1, S = y << E | R, B = (a, r) => c(r << E | a), f = (a) => a & p, G = "orphan", C = "target", O = Object.freeze({});
+class U {
+  /** `true` → one target per source, held in the sparse field. `false` →
+   * a set of targets per source. The cardinality discriminant survives as a
+   * field because the snapshot header and the traversal and `targetOf`
+   * mode guards carry it. The forward mechanics stay virtual, never branched
+   * on it. */
+  exclusive;
+  /** Backing sparse component def: `{ target: f64 }` when exclusive, a tag when
+   * multi. Carries membership (and the target, when exclusive). */
+  sparse;
+  /** Cleanup policy applied to this relation's sources when a target is
+   * destroyed. `orphan` (the default) is a no-op, the link dangles
+   * safely. `Store` reads this at destroy-flush off `sourcesOf`. */
+  onDeleteTarget;
+  /** The backing sparse store instance. Owned for registration and liveness by
+   * `Store`, but the relation drives the forward and membership rows on it directly.
+   * That is the cardinality interaction this class now encapsulates. */
+  _store;
+  /** target `EntityID` → set of source `EntityID`s. Keyed by the full id, not
+   * the index, so a recycled target slot can't alias a dead target's sources.
+   * An entry is dropped the moment its set empties (`_unlinkReverse`). */
+  _reverse = /* @__PURE__ */ new Map();
+  constructor(r, t, e, s) {
+    this.exclusive = r, this.sparse = t, this._store = e, this.onDeleteTarget = s;
+  }
+  // --- shared reverse index (cardinality-agnostic) ---
+  /** Record that `src` points at `tgt` in the reverse index. */
+  _linkReverse(r, t) {
+    let e = this._reverse.get(r);
+    e === void 0 && (e = /* @__PURE__ */ new Set(), this._reverse.set(r, e)), e.add(t);
+  }
+  /** Drop the `src → tgt` edge from the reverse index, removing the target's
+   * entry entirely once its last source is gone (so a dead-target key doesn't
+   * linger with an empty set). */
+  _unlinkReverse(r, t) {
+    const e = this._reverse.get(r);
+    e !== void 0 && (e.delete(t), e.size === 0 && this._reverse.delete(r));
+  }
+  /** Drop every reverse-index entry whose **target** is no longer alive,
+   * returning the count dropped. The `orphan` policy intentionally
+   * leaves a destroyed target's reverse entry intact (the link dangles
+   * safely), so a long-lived source that orphan-points at a stream of
+   * short-lived targets and never re-targets or dies accumulates dead-target keys
+   * without bound. This is the reclaim primitive behind `ecs.relations.compact`,
+   * a cold path the host calls at scene and snapshot boundaries. It is
+   * cardinality-free (reverse-index only), so it lives on the base unchanged.
+   *
+   * Pure index reclaim: the **forward** links (the exclusive sparse target
+   * field, the multi forward set) are left untouched, so `targetOf` and
+   * `targetsOf` still return the dangling dead handle exactly as `orphan`
+   * promises. The reverse index is derived, so dropping a dead-target entry
+   * changes nothing observable except `sourcesOf` on that dead handle (which
+   * goes from the dangling sources to `[]`, meaningless either way, the target
+   * is gone) and is faithfully rebuilt by snapshot and restore from the surviving
+   * forward links. Only the **target** role can leak here: a destroyed *source*
+   * is already unlinked from every reverse set by `purgeSource`, so a live
+   * target's set never holds a dead source. `isAlive` is supplied by `Store`,
+   * which owns entity liveness. Deleting during `Map` key iteration is
+   * well-defined, already-visited and not-yet-reached keys are unaffected. */
+  pruneDeadReverse(r) {
+    let t = 0;
+    for (const e of this._reverse.keys())
+      r(c(e)) || (this._reverse.delete(e), t++);
+    return t;
+  }
+  /** Sources that point at `tgt`, ascending by id (deterministic, cold-path
+   * sort), empty when none. */
+  sourcesOf(r) {
+    const t = this._reverse.get(r);
+    if (t === void 0 || t.size === 0) return [];
+    const e = new Array(t.size);
+    let s = 0;
+    return t.forEach((n) => {
+      e[s++] = c(n);
+    }), e.sort((n, o) => n - o), e;
+  }
+  /** Drop every derived side index, the reverse index and (for multi) the
+   * forward target sets. Restore path only (`restoreRelations`): the side
+   * indices are rebuilt from scratch, so they're cleared first to stay
+   * idempotent when restoring into a dirty world. The backing sparse store is
+   * cleared separately by `restoreSparseStores`. */
+  resetIndices() {
+    this._reverse.clear(), this._resetForward();
+  }
+}
+class M extends U {
+  constructor(r, t, e) {
+    super(!0, r, t, e);
+  }
+  _resetForward() {
+  }
+  link(r, t) {
+    const e = f(r), s = this._store.getField(e, 0);
+    if (s !== void 0) {
+      if (s === t) return;
+      this._unlinkReverse(c(s), r);
+    }
+    this._store.setRow(e, { [C]: t }), this._linkReverse(t, r);
+  }
+  unlink(r, t) {
+    const e = f(r), s = this._store.getField(e, 0);
+    s !== void 0 && (t !== void 0 && s !== t || (this._unlinkReverse(c(s), r), this._store.remove(e)));
+  }
+  purgeSource(r) {
+    const t = f(r), e = this._store.getField(t, 0);
+    e !== void 0 && this._unlinkReverse(c(e), r);
+  }
+  singleTargetAt(r) {
+    const t = this._store.getField(r, 0);
+    return t === void 0 ? void 0 : c(t);
+  }
+  targetsAt(r) {
+    const t = this._store.getField(r, 0);
+    return t === void 0 ? [] : [c(t)];
+  }
+  hasIndex(r) {
+    return this._store.has(r);
+  }
+  forEachCanonicalTargetSet(r) {
+  }
+  forEachCanonicalPair(r, t) {
+    const e = this._store.canonicalIndices();
+    for (let s = 0; s < e.length; s++) {
+      const n = e[s];
+      t(r(n), c(this._store.getField(n, 0)));
+    }
+  }
+  rebuildReverse(r) {
+    const t = this._store.indices;
+    for (let e = 0; e < t.length; e++) {
+      const s = t[e];
+      this._linkReverse(c(this._store.getField(s, 0)), r(s));
+    }
+  }
+  restoreAddTarget() {
+    throw new u(
+      "exclusive relation has no multi forward sources to restore (snapshot header should have guarded this)"
+    );
+  }
+}
+class b extends U {
+  /** source entity **index** → set of target `EntityID`s. Keyed by source index
+   * so destroy-purge, which has the freed index, can drop it in O(1). An
+   * entry is removed the moment its set empties. */
+  _forward = /* @__PURE__ */ new Map();
+  constructor(r, t, e) {
+    super(!1, r, t, e);
+  }
+  _resetForward() {
+    this._forward.clear();
+  }
+  link(r, t) {
+    const e = f(r);
+    let s = this._forward.get(e);
+    s === void 0 && (s = /* @__PURE__ */ new Set(), this._forward.set(e, s), this._store.setRow(e, O)), s.add(t), this._linkReverse(t, r);
+  }
+  unlink(r, t) {
+    const e = f(r), s = this._forward.get(e);
+    if (s !== void 0) {
+      if (t === void 0) {
+        this._forward.delete(e), s.forEach((n) => this._unlinkReverse(c(n), r)), this._store.remove(e);
+        return;
+      }
+      s.has(t) && (s.delete(t), this._unlinkReverse(t, r), s.size === 0 && (this._forward.delete(e), this._store.remove(e)));
+    }
+  }
+  purgeSource(r) {
+    const t = f(r), e = this._forward.get(t);
+    e !== void 0 && (this._forward.delete(t), e.forEach((s) => this._unlinkReverse(c(s), r)));
+  }
+  singleTargetAt() {
+  }
+  targetsAt(r) {
+    const t = this._forward.get(r);
+    if (t === void 0 || t.size === 0) return [];
+    const e = new Array(t.size);
+    let s = 0;
+    return t.forEach((n) => {
+      e[s++] = c(n);
+    }), e.sort((n, o) => n - o), e;
+  }
+  hasIndex(r) {
+    return this._store.has(r);
+  }
+  forEachCanonicalTargetSet(r) {
+    const t = Array.from(this._forward.keys()).sort((e, s) => e - s);
+    for (let e = 0; e < t.length; e++) {
+      const s = this.targetsAt(t[e]);
+      s.length !== 0 && r(t[e], s);
+    }
+  }
+  forEachCanonicalPair(r, t) {
+    this.forEachCanonicalTargetSet((e, s) => {
+      const n = r(e);
+      for (let o = 0; o < s.length; o++) t(n, s[o]);
+    });
+  }
+  rebuildReverse() {
+  }
+  restoreAddTarget(r, t, e) {
+    let s = this._forward.get(r);
+    s === void 0 && (s = /* @__PURE__ */ new Set(), this._forward.set(r, s)), s.add(t), this._linkReverse(t, e);
+  }
+}
+function Y(a, r, t, e) {
+  return a ? new M(r, t, e) : new b(r, t, e);
+}
+const k = 4, m = 4, D = 8, w = 8;
+function P(a) {
+  const r = new Array(a.length);
+  let t = 4;
+  for (let o = 0; o < a.length; o++) {
+    t += k;
+    const h = a[o];
+    if (h.exclusive) {
+      r[o] = null;
+      continue;
+    }
+    const i = [];
+    h.forEachCanonicalTargetSet((l, d) => i.push([l, d])), r[o] = i, t += m;
+    for (let l = 0; l < i.length; l++)
+      t += D + i[l][1].length * w;
+  }
+  const e = new Uint8Array(t), s = new DataView(e.buffer);
+  let n = 0;
+  s.setUint32(n, a.length, !0), n += 4;
+  for (let o = 0; o < a.length; o++) {
+    s.setUint32(n, a[o].exclusive ? 0 : 1, !0), n += 4;
+    const h = r[o];
+    if (h !== null) {
+      s.setUint32(n, h.length, !0), n += 4;
+      for (let i = 0; i < h.length; i++) {
+        const l = h[i][0], d = h[i][1];
+        s.setUint32(n, l, !0), n += 4, s.setUint32(n, d.length, !0), n += 4;
+        for (let _ = 0; _ < d.length; _++)
+          s.setFloat64(n, d[_], !0), n += w;
+      }
+    }
+  }
+  return e;
+}
+function j(a, r, t) {
+  const e = new DataView(r.buffer, r.byteOffset, r.byteLength), s = r.byteLength;
+  let n = 0;
+  const o = (i) => {
+    if (n + i > s)
+      throw new u(
+        `relation snapshot truncated: need ${i} more bytes at offset ${n}, have ${s - n}`
+      );
+  };
+  for (let i = 0; i < a.length; i++) a[i].resetIndices();
+  o(4);
+  const h = e.getUint32(n, !0);
+  if (n += 4, h !== a.length)
+    throw new u(
+      `relation count mismatch: snapshot=${h}, registered=${a.length}`
+    );
+  for (let i = 0; i < a.length; i++) {
+    const l = a[i];
+    o(k);
+    const d = e.getUint32(n, !0);
+    if (n += 4, d === 1 === l.exclusive)
+      throw new u(
+        `relation ${i} cardinality mismatch: snapshot ${d ? "multi" : "exclusive"}, registered ${l.exclusive ? "exclusive" : "multi"}`
+      );
+    if (l.exclusive) continue;
+    o(m);
+    const _ = e.getUint32(n, !0);
+    n += 4;
+    for (let T = 0; T < _; T++) {
+      o(D);
+      const g = e.getUint32(n, !0);
+      n += 4;
+      const x = e.getUint32(n, !0);
+      if (n += 4, g > R)
+        throw new u(
+          `relation ${i} source index ${g} exceeds MAX_INDEX (${R})`
+        );
+      o(x * w);
+      const N = t(g);
+      for (let A = 0; A < x; A++) {
+        const I = c(e.getFloat64(n, !0));
+        n += w;
+        const v = I;
+        if (!Number.isInteger(v) || v < 0 || v > S)
+          throw new u(
+            `relation ${i} target ${v} is not a well-formed packed EntityID (expected an integer in [0, ${S}])`
+          );
+        l.restoreAddTarget(g, I, N);
+      }
+    }
+  }
+  if (n !== s)
+    throw new u(
+      `relation snapshot has ${s - n} trailing bytes after the last relation (not a canonical encoding)`
+    );
+}
+export {
+  G as D,
+  R as M,
+  C as R,
+  z as U,
+  Y as a,
+  B as c,
+  f as g,
+  j as r,
+  P as s
+};

package/dist/plugins/relation_store-DQKSnxsm.cjs

@@ -0,0 +1 @@
+"use strict";const d=require("../index.cjs"),c=require("./assertions-z5GQd_bB.cjs"),y=-1;Object.freeze(Object.create(null));const O=31,R=20,p=(1<<R)-1,v=p,L=O-R,$=(1<<L)-1,x=$<<R|v,m=(a,r)=>c.unsafeCast(r<<R|a),f=a=>a&p,M="orphan",C="target",b=Object.freeze({});class N{exclusive;sparse;onDeleteTarget;_store;_reverse=new Map;constructor(r,t,e,s){this.exclusive=r,this.sparse=t,this._store=e,this.onDeleteTarget=s}_linkReverse(r,t){let e=this._reverse.get(r);e===void 0&&(e=new Set,this._reverse.set(r,e)),e.add(t)}_unlinkReverse(r,t){const e=this._reverse.get(r);e!==void 0&&(e.delete(t),e.size===0&&this._reverse.delete(r))}pruneDeadReverse(r){let t=0;for(const e of this._reverse.keys())r(c.unsafeCast(e))||(this._reverse.delete(e),t++);return t}sourcesOf(r){const t=this._reverse.get(r);if(t===void 0||t.size===0)return[];const e=new Array(t.size);let s=0;return t.forEach(n=>{e[s++]=c.unsafeCast(n)}),e.sort((n,o)=>n-o),e}resetIndices(){this._reverse.clear(),this._resetForward()}}class X extends N{constructor(r,t,e){super(!0,r,t,e)}_resetForward(){}link(r,t){const e=f(r),s=this._store.getField(e,0);if(s!==void 0){if(s===t)return;this._unlinkReverse(c.unsafeCast(s),r)}this._store.setRow(e,{[C]:t}),this._linkReverse(t,r)}unlink(r,t){const e=f(r),s=this._store.getField(e,0);s!==void 0&&(t!==void 0&&s!==t||(this._unlinkReverse(c.unsafeCast(s),r),this._store.remove(e)))}purgeSource(r){const t=f(r),e=this._store.getField(t,0);e!==void 0&&this._unlinkReverse(c.unsafeCast(e),r)}singleTargetAt(r){const t=this._store.getField(r,0);return t===void 0?void 0:c.unsafeCast(t)}targetsAt(r){const t=this._store.getField(r,0);return t===void 0?[]:[c.unsafeCast(t)]}hasIndex(r){return this._store.has(r)}forEachCanonicalTargetSet(r){}forEachCanonicalPair(r,t){const e=this._store.canonicalIndices();for(let s=0;s<e.length;s++){const n=e[s];t(r(n),c.unsafeCast(this._store.getField(n,0)))}}rebuildReverse(r){const t=this._store.indices;for(let e=0;e<t.length;e++){const s=t[e];this._linkReverse(c.unsafeCast(this._store.getField(s,0)),r(s))}}restoreAddTarget(){throw new d.SparseRestoreError("exclusive relation has no multi forward sources to restore (snapshot header should have guarded this)")}}class G extends N{_forward=new Map;constructor(r,t,e){super(!1,r,t,e)}_resetForward(){this._forward.clear()}link(r,t){const e=f(r);let s=this._forward.get(e);s===void 0&&(s=new Set,this._forward.set(e,s),this._store.setRow(e,b)),s.add(t),this._linkReverse(t,r)}unlink(r,t){const e=f(r),s=this._forward.get(e);if(s!==void 0){if(t===void 0){this._forward.delete(e),s.forEach(n=>this._unlinkReverse(c.unsafeCast(n),r)),this._store.remove(e);return}s.has(t)&&(s.delete(t),this._unlinkReverse(t,r),s.size===0&&(this._forward.delete(e),this._store.remove(e)))}}purgeSource(r){const t=f(r),e=this._forward.get(t);e!==void 0&&(this._forward.delete(t),e.forEach(s=>this._unlinkReverse(c.unsafeCast(s),r)))}singleTargetAt(){}targetsAt(r){const t=this._forward.get(r);if(t===void 0||t.size===0)return[];const e=new Array(t.size);let s=0;return t.forEach(n=>{e[s++]=c.unsafeCast(n)}),e.sort((n,o)=>n-o),e}hasIndex(r){return this._store.has(r)}forEachCanonicalTargetSet(r){const t=Array.from(this._forward.keys()).sort((e,s)=>e-s);for(let e=0;e<t.length;e++){const s=this.targetsAt(t[e]);s.length!==0&&r(t[e],s)}}forEachCanonicalPair(r,t){this.forEachCanonicalTargetSet((e,s)=>{const n=r(e);for(let o=0;o<s.length;o++)t(n,s[o])})}rebuildReverse(){}restoreAddTarget(r,t,e){let s=this._forward.get(r);s===void 0&&(s=new Set,this._forward.set(r,s)),s.add(t),this._linkReverse(t,e)}}function z(a,r,t,e){return a?new X(r,t,e):new G(r,t,e)}const D=4,U=4,k=8,w=8;function B(a){const r=new Array(a.length);let t=4;for(let o=0;o<a.length;o++){t+=D;const u=a[o];if(u.exclusive){r[o]=null;continue}const i=[];u.forEachCanonicalTargetSet((l,h)=>i.push([l,h])),r[o]=i,t+=U;for(let l=0;l<i.length;l++)t+=k+i[l][1].length*w}const e=new Uint8Array(t),s=new DataView(e.buffer);let n=0;s.setUint32(n,a.length,!0),n+=4;for(let o=0;o<a.length;o++){s.setUint32(n,a[o].exclusive?0:1,!0),n+=4;const u=r[o];if(u!==null){s.setUint32(n,u.length,!0),n+=4;for(let i=0;i<u.length;i++){const l=u[i][0],h=u[i][1];s.setUint32(n,l,!0),n+=4,s.setUint32(n,h.length,!0),n+=4;for(let _=0;_<h.length;_++)s.setFloat64(n,h[_],!0),n+=w}}}return e}function Y(a,r,t){const e=new DataView(r.buffer,r.byteOffset,r.byteLength),s=r.byteLength;let n=0;const o=i=>{if(n+i>s)throw new d.SparseRestoreError(`relation snapshot truncated: need ${i} more bytes at offset ${n}, have ${s-n}`)};for(let i=0;i<a.length;i++)a[i].resetIndices();o(4);const u=e.getUint32(n,!0);if(n+=4,u!==a.length)throw new d.SparseRestoreError(`relation count mismatch: snapshot=${u}, registered=${a.length}`);for(let i=0;i<a.length;i++){const l=a[i];o(D);const h=e.getUint32(n,!0);if(n+=4,h===1===l.exclusive)throw new d.SparseRestoreError(`relation ${i} cardinality mismatch: snapshot ${h?"multi":"exclusive"}, registered ${l.exclusive?"exclusive":"multi"}`);if(l.exclusive)continue;o(U);const _=e.getUint32(n,!0);n+=4;for(let T=0;T<_;T++){o(k);const g=e.getUint32(n,!0);n+=4;const A=e.getUint32(n,!0);if(n+=4,g>v)throw new d.SparseRestoreError(`relation ${i} source index ${g} exceeds MAX_INDEX (${v})`);o(A*w);const F=t(g);for(let S=0;S<A;S++){const I=c.unsafeCast(e.getFloat64(n,!0));n+=w;const E=I;if(!Number.isInteger(E)||E<0||E>x)throw new d.SparseRestoreError(`relation ${i} target ${E} is not a well-formed packed EntityID (expected an integer in [0, ${x}])`);l.restoreAddTarget(g,I,F)}}}if(n!==s)throw new d.SparseRestoreError(`relation snapshot has ${s-n} trailing bytes after the last relation (not a canonical encoding)`)}exports.DEFAULT_ON_DELETE_TARGET=M;exports.MAX_INDEX=v;exports.RELATION_TARGET_FIELD=C;exports.UNASSIGNED=y;exports.createEntityId=m;exports.createRelationStore=z;exports.getEntityIndex=f;exports.restoreRelations=Y;exports.snapshotRelations=B;

package/dist/plugins/relation_store-RBhpcE28.cjs

@@ -0,0 +1 @@
+"use strict";const l=require("../index.development.cjs"),c=require("./assertions-z5GQd_bB.cjs"),k=-1;Object.freeze(Object.create(null));const L=31,g=20,p=(1<<g)-1,E=p,M=L-g,N=(1<<M)-1,x=N<<g|E,m=(o,e)=>{{if(o<0||o>E)throw new l.ECSError(l.ECS_ERROR.EID_MAX_INDEX_OVERFLOW);if(e<0||e>N)throw new l.ECSError(l.ECS_ERROR.EID_MAX_GEN_OVERFLOW)}return c.unsafeCast(e<<g|o)},d=o=>o&p,C=o=>o>>g,X=(o,e,r)=>new l.ECSError(l.ECS_ERROR.ENTITY_NOT_ALIVE,`${o}: entity ${e} (index ${d(e)}, generation ${C(e)}) is not alive${r?`, ${r}`:""}. It was destroyed, never created, or the handle is stale. Guard with isAlive() first`,{entity:e,index:d(e),generation:C(e),op:o}),b="orphan",D="target",G=Object.freeze({});class O{exclusive;sparse;onDeleteTarget;_store;_reverse=new Map;constructor(e,r,t,s){this.exclusive=e,this.sparse=r,this._store=t,this.onDeleteTarget=s}_linkReverse(e,r){let t=this._reverse.get(e);t===void 0&&(t=new Set,this._reverse.set(e,t)),t.add(r)}_unlinkReverse(e,r){const t=this._reverse.get(e);t!==void 0&&(t.delete(r),t.size===0&&this._reverse.delete(e))}pruneDeadReverse(e){let r=0;for(const t of this._reverse.keys())e(c.unsafeCast(t))||(this._reverse.delete(t),r++);return r}sourcesOf(e){const r=this._reverse.get(e);if(r===void 0||r.size===0)return[];const t=new Array(r.size);let s=0;return r.forEach(n=>{t[s++]=c.unsafeCast(n)}),t.sort((n,i)=>n-i),t}resetIndices(){this._reverse.clear(),this._resetForward()}}class z extends O{constructor(e,r,t){super(!0,e,r,t)}_resetForward(){}link(e,r){const t=d(e),s=this._store.getField(t,0);if(s!==void 0){if(s===r)return;this._unlinkReverse(c.unsafeCast(s),e)}this._store.setRow(t,{[D]:r}),this._linkReverse(r,e)}unlink(e,r){const t=d(e),s=this._store.getField(t,0);s!==void 0&&(r!==void 0&&s!==r||(this._unlinkReverse(c.unsafeCast(s),e),this._store.remove(t)))}purgeSource(e){const r=d(e),t=this._store.getField(r,0);t!==void 0&&this._unlinkReverse(c.unsafeCast(t),e)}singleTargetAt(e){const r=this._store.getField(e,0);return r===void 0?void 0:c.unsafeCast(r)}targetsAt(e){const r=this._store.getField(e,0);return r===void 0?[]:[c.unsafeCast(r)]}hasIndex(e){return this._store.has(e)}forEachCanonicalTargetSet(e){}forEachCanonicalPair(e,r){const t=this._store.canonicalIndices();for(let s=0;s<t.length;s++){const n=t[s];r(e(n),c.unsafeCast(this._store.getField(n,0)))}}rebuildReverse(e){const r=this._store.indices;for(let t=0;t<r.length;t++){const s=r[t];this._linkReverse(c.unsafeCast(this._store.getField(s,0)),e(s))}}restoreAddTarget(){throw new l.SparseRestoreError("exclusive relation has no multi forward sources to restore (snapshot header should have guarded this)")}}class B extends O{_forward=new Map;constructor(e,r,t){super(!1,e,r,t)}_resetForward(){this._forward.clear()}link(e,r){const t=d(e);let s=this._forward.get(t);s===void 0&&(s=new Set,this._forward.set(t,s),this._store.setRow(t,G)),s.add(r),this._linkReverse(r,e)}unlink(e,r){const t=d(e),s=this._forward.get(t);if(s!==void 0){if(r===void 0){this._forward.delete(t),s.forEach(n=>this._unlinkReverse(c.unsafeCast(n),e)),this._store.remove(t);return}s.has(r)&&(s.delete(r),this._unlinkReverse(r,e),s.size===0&&(this._forward.delete(t),this._store.remove(t)))}}purgeSource(e){const r=d(e),t=this._forward.get(r);t!==void 0&&(this._forward.delete(r),t.forEach(s=>this._unlinkReverse(c.unsafeCast(s),e)))}singleTargetAt(){}targetsAt(e){const r=this._forward.get(e);if(r===void 0||r.size===0)return[];const t=new Array(r.size);let s=0;return r.forEach(n=>{t[s++]=c.unsafeCast(n)}),t.sort((n,i)=>n-i),t}hasIndex(e){return this._store.has(e)}forEachCanonicalTargetSet(e){const r=Array.from(this._forward.keys()).sort((t,s)=>t-s);for(let t=0;t<r.length;t++){const s=this.targetsAt(r[t]);s.length!==0&&e(r[t],s)}}forEachCanonicalPair(e,r){this.forEachCanonicalTargetSet((t,s)=>{const n=e(t);for(let i=0;i<s.length;i++)r(n,s[i])})}rebuildReverse(){}restoreAddTarget(e,r,t){let s=this._forward.get(e);s===void 0&&(s=new Set,this._forward.set(e,s)),s.add(r),this._linkReverse(r,t)}}function Y(o,e,r,t){return o?new z(e,r,t):new B(e,r,t)}const y=4,U=4,$=8,R=8;function V(o){const e=new Array(o.length);let r=4;for(let i=0;i<o.length;i++){r+=y;const u=o[i];if(u.exclusive){e[i]=null;continue}const a=[];u.forEachCanonicalTargetSet((h,f)=>a.push([h,f])),e[i]=a,r+=U;for(let h=0;h<a.length;h++)r+=$+a[h][1].length*R}const t=new Uint8Array(r),s=new DataView(t.buffer);let n=0;s.setUint32(n,o.length,!0),n+=4;for(let i=0;i<o.length;i++){s.setUint32(n,o[i].exclusive?0:1,!0),n+=4;const u=e[i];if(u!==null){s.setUint32(n,u.length,!0),n+=4;for(let a=0;a<u.length;a++){const h=u[a][0],f=u[a][1];s.setUint32(n,h,!0),n+=4,s.setUint32(n,f.length,!0),n+=4;for(let _=0;_<f.length;_++)s.setFloat64(n,f[_],!0),n+=R}}}return t}function P(o,e,r){const t=new DataView(e.buffer,e.byteOffset,e.byteLength),s=e.byteLength;let n=0;const i=a=>{if(n+a>s)throw new l.SparseRestoreError(`relation snapshot truncated: need ${a} more bytes at offset ${n}, have ${s-n}`)};for(let a=0;a<o.length;a++)o[a].resetIndices();i(4);const u=t.getUint32(n,!0);if(n+=4,u!==o.length)throw new l.SparseRestoreError(`relation count mismatch: snapshot=${u}, registered=${o.length}`);for(let a=0;a<o.length;a++){const h=o[a];i(y);const f=t.getUint32(n,!0);if(n+=4,f===1===h.exclusive)throw new l.SparseRestoreError(`relation ${a} cardinality mismatch: snapshot ${f?"multi":"exclusive"}, registered ${h.exclusive?"exclusive":"multi"}`);if(h.exclusive)continue;i(U);const _=t.getUint32(n,!0);n+=4;for(let T=0;T<_;T++){i($);const v=t.getUint32(n,!0);n+=4;const A=t.getUint32(n,!0);if(n+=4,v>E)throw new l.SparseRestoreError(`relation ${a} source index ${v} exceeds MAX_INDEX (${E})`);i(A*R);const F=r(v);for(let S=0;S<A;S++){const I=c.unsafeCast(t.getFloat64(n,!0));n+=R;const w=I;if(!Number.isInteger(w)||w<0||w>x)throw new l.SparseRestoreError(`relation ${a} target ${w} is not a well-formed packed EntityID (expected an integer in [0, ${x}])`);h.restoreAddTarget(v,I,F)}}}if(n!==s)throw new l.SparseRestoreError(`relation snapshot has ${s-n} trailing bytes after the last relation (not a canonical encoding)`)}exports.DEFAULT_ON_DELETE_TARGET=b;exports.MAX_INDEX=E;exports.RELATION_TARGET_FIELD=D;exports.UNASSIGNED=k;exports.createEntityId=m;exports.createRelationStore=Y;exports.entityNotAliveError=X;exports.getEntityIndex=d;exports.restoreRelations=P;exports.snapshotRelations=V;

package/dist/plugins/relation_store-RqW5Snx6.js

@@ -0,0 +1,328 @@
+import { ECSError as T, ECS_ERROR as A, SparseRestoreError as f } from "../index.development.js";
+import { u as c } from "./assertions-gtDVfbnQ.js";
+const Y = -1;
+Object.freeze(/* @__PURE__ */ Object.create(null));
+const C = 31, g = 20, D = (1 << g) - 1, w = D, M = C - g, O = (1 << M) - 1, N = O << g | w, V = (o, e) => {
+  {
+    if (o < 0 || o > w)
+      throw new T(A.EID_MAX_INDEX_OVERFLOW);
+    if (e < 0 || e > O)
+      throw new T(A.EID_MAX_GEN_OVERFLOW);
+  }
+  return c(e << g | o);
+}, d = (o) => o & D, $ = (o) => o >> g, P = (o, e, r) => new T(
+  A.ENTITY_NOT_ALIVE,
+  `${o}: entity ${e} (index ${d(e)}, generation ${$(
+    e
+  )}) is not alive${r ? `, ${r}` : ""}. It was destroyed, never created, or the handle is stale. Guard with isAlive() first`,
+  { entity: e, index: d(e), generation: $(e), op: o }
+), j = "orphan", L = "target", b = Object.freeze({});
+class U {
+  /** `true` → one target per source, held in the sparse field. `false` →
+   * a set of targets per source. The cardinality discriminant survives as a
+   * field because the snapshot header and the traversal and `targetOf`
+   * mode guards carry it. The forward mechanics stay virtual, never branched
+   * on it. */
+  exclusive;
+  /** Backing sparse component def: `{ target: f64 }` when exclusive, a tag when
+   * multi. Carries membership (and the target, when exclusive). */
+  sparse;
+  /** Cleanup policy applied to this relation's sources when a target is
+   * destroyed. `orphan` (the default) is a no-op, the link dangles
+   * safely. `Store` reads this at destroy-flush off `sourcesOf`. */
+  onDeleteTarget;
+  /** The backing sparse store instance. Owned for registration and liveness by
+   * `Store`, but the relation drives the forward and membership rows on it directly.
+   * That is the cardinality interaction this class now encapsulates. */
+  _store;
+  /** target `EntityID` → set of source `EntityID`s. Keyed by the full id, not
+   * the index, so a recycled target slot can't alias a dead target's sources.
+   * An entry is dropped the moment its set empties (`_unlinkReverse`). */
+  _reverse = /* @__PURE__ */ new Map();
+  constructor(e, r, t, s) {
+    this.exclusive = e, this.sparse = r, this._store = t, this.onDeleteTarget = s;
+  }
+  // --- shared reverse index (cardinality-agnostic) ---
+  /** Record that `src` points at `tgt` in the reverse index. */
+  _linkReverse(e, r) {
+    let t = this._reverse.get(e);
+    t === void 0 && (t = /* @__PURE__ */ new Set(), this._reverse.set(e, t)), t.add(r);
+  }
+  /** Drop the `src → tgt` edge from the reverse index, removing the target's
+   * entry entirely once its last source is gone (so a dead-target key doesn't
+   * linger with an empty set). */
+  _unlinkReverse(e, r) {
+    const t = this._reverse.get(e);
+    t !== void 0 && (t.delete(r), t.size === 0 && this._reverse.delete(e));
+  }
+  /** Drop every reverse-index entry whose **target** is no longer alive,
+   * returning the count dropped. The `orphan` policy intentionally
+   * leaves a destroyed target's reverse entry intact (the link dangles
+   * safely), so a long-lived source that orphan-points at a stream of
+   * short-lived targets and never re-targets or dies accumulates dead-target keys
+   * without bound. This is the reclaim primitive behind `ecs.relations.compact`,
+   * a cold path the host calls at scene and snapshot boundaries. It is
+   * cardinality-free (reverse-index only), so it lives on the base unchanged.
+   *
+   * Pure index reclaim: the **forward** links (the exclusive sparse target
+   * field, the multi forward set) are left untouched, so `targetOf` and
+   * `targetsOf` still return the dangling dead handle exactly as `orphan`
+   * promises. The reverse index is derived, so dropping a dead-target entry
+   * changes nothing observable except `sourcesOf` on that dead handle (which
+   * goes from the dangling sources to `[]`, meaningless either way, the target
+   * is gone) and is faithfully rebuilt by snapshot and restore from the surviving
+   * forward links. Only the **target** role can leak here: a destroyed *source*
+   * is already unlinked from every reverse set by `purgeSource`, so a live
+   * target's set never holds a dead source. `isAlive` is supplied by `Store`,
+   * which owns entity liveness. Deleting during `Map` key iteration is
+   * well-defined, already-visited and not-yet-reached keys are unaffected. */
+  pruneDeadReverse(e) {
+    let r = 0;
+    for (const t of this._reverse.keys())
+      e(c(t)) || (this._reverse.delete(t), r++);
+    return r;
+  }
+  /** Sources that point at `tgt`, ascending by id (deterministic, cold-path
+   * sort), empty when none. */
+  sourcesOf(e) {
+    const r = this._reverse.get(e);
+    if (r === void 0 || r.size === 0) return [];
+    const t = new Array(r.size);
+    let s = 0;
+    return r.forEach((n) => {
+      t[s++] = c(n);
+    }), t.sort((n, i) => n - i), t;
+  }
+  /** Drop every derived side index, the reverse index and (for multi) the
+   * forward target sets. Restore path only (`restoreRelations`): the side
+   * indices are rebuilt from scratch, so they're cleared first to stay
+   * idempotent when restoring into a dirty world. The backing sparse store is
+   * cleared separately by `restoreSparseStores`. */
+  resetIndices() {
+    this._reverse.clear(), this._resetForward();
+  }
+}
+class X extends U {
+  constructor(e, r, t) {
+    super(!0, e, r, t);
+  }
+  _resetForward() {
+  }
+  link(e, r) {
+    const t = d(e), s = this._store.getField(t, 0);
+    if (s !== void 0) {
+      if (s === r) return;
+      this._unlinkReverse(c(s), e);
+    }
+    this._store.setRow(t, { [L]: r }), this._linkReverse(r, e);
+  }
+  unlink(e, r) {
+    const t = d(e), s = this._store.getField(t, 0);
+    s !== void 0 && (r !== void 0 && s !== r || (this._unlinkReverse(c(s), e), this._store.remove(t)));
+  }
+  purgeSource(e) {
+    const r = d(e), t = this._store.getField(r, 0);
+    t !== void 0 && this._unlinkReverse(c(t), e);
+  }
+  singleTargetAt(e) {
+    const r = this._store.getField(e, 0);
+    return r === void 0 ? void 0 : c(r);
+  }
+  targetsAt(e) {
+    const r = this._store.getField(e, 0);
+    return r === void 0 ? [] : [c(r)];
+  }
+  hasIndex(e) {
+    return this._store.has(e);
+  }
+  forEachCanonicalTargetSet(e) {
+  }
+  forEachCanonicalPair(e, r) {
+    const t = this._store.canonicalIndices();
+    for (let s = 0; s < t.length; s++) {
+      const n = t[s];
+      r(e(n), c(this._store.getField(n, 0)));
+    }
+  }
+  rebuildReverse(e) {
+    const r = this._store.indices;
+    for (let t = 0; t < r.length; t++) {
+      const s = r[t];
+      this._linkReverse(c(this._store.getField(s, 0)), e(s));
+    }
+  }
+  restoreAddTarget() {
+    throw new f(
+      "exclusive relation has no multi forward sources to restore (snapshot header should have guarded this)"
+    );
+  }
+}
+class G extends U {
+  /** source entity **index** → set of target `EntityID`s. Keyed by source index
+   * so destroy-purge, which has the freed index, can drop it in O(1). An
+   * entry is removed the moment its set empties. */
+  _forward = /* @__PURE__ */ new Map();
+  constructor(e, r, t) {
+    super(!1, e, r, t);
+  }
+  _resetForward() {
+    this._forward.clear();
+  }
+  link(e, r) {
+    const t = d(e);
+    let s = this._forward.get(t);
+    s === void 0 && (s = /* @__PURE__ */ new Set(), this._forward.set(t, s), this._store.setRow(t, b)), s.add(r), this._linkReverse(r, e);
+  }
+  unlink(e, r) {
+    const t = d(e), s = this._forward.get(t);
+    if (s !== void 0) {
+      if (r === void 0) {
+        this._forward.delete(t), s.forEach((n) => this._unlinkReverse(c(n), e)), this._store.remove(t);
+        return;
+      }
+      s.has(r) && (s.delete(r), this._unlinkReverse(r, e), s.size === 0 && (this._forward.delete(t), this._store.remove(t)));
+    }
+  }
+  purgeSource(e) {
+    const r = d(e), t = this._forward.get(r);
+    t !== void 0 && (this._forward.delete(r), t.forEach((s) => this._unlinkReverse(c(s), e)));
+  }
+  singleTargetAt() {
+  }
+  targetsAt(e) {
+    const r = this._forward.get(e);
+    if (r === void 0 || r.size === 0) return [];
+    const t = new Array(r.size);
+    let s = 0;
+    return r.forEach((n) => {
+      t[s++] = c(n);
+    }), t.sort((n, i) => n - i), t;
+  }
+  hasIndex(e) {
+    return this._store.has(e);
+  }
+  forEachCanonicalTargetSet(e) {
+    const r = Array.from(this._forward.keys()).sort((t, s) => t - s);
+    for (let t = 0; t < r.length; t++) {
+      const s = this.targetsAt(r[t]);
+      s.length !== 0 && e(r[t], s);
+    }
+  }
+  forEachCanonicalPair(e, r) {
+    this.forEachCanonicalTargetSet((t, s) => {
+      const n = e(t);
+      for (let i = 0; i < s.length; i++) r(n, s[i]);
+    });
+  }
+  rebuildReverse() {
+  }
+  restoreAddTarget(e, r, t) {
+    let s = this._forward.get(e);
+    s === void 0 && (s = /* @__PURE__ */ new Set(), this._forward.set(e, s)), s.add(r), this._linkReverse(r, t);
+  }
+}
+function K(o, e, r, t) {
+  return o ? new X(e, r, t) : new G(e, r, t);
+}
+const k = 4, y = 4, m = 8, R = 8;
+function W(o) {
+  const e = new Array(o.length);
+  let r = 4;
+  for (let i = 0; i < o.length; i++) {
+    r += k;
+    const h = o[i];
+    if (h.exclusive) {
+      e[i] = null;
+      continue;
+    }
+    const a = [];
+    h.forEachCanonicalTargetSet((l, u) => a.push([l, u])), e[i] = a, r += y;
+    for (let l = 0; l < a.length; l++)
+      r += m + a[l][1].length * R;
+  }
+  const t = new Uint8Array(r), s = new DataView(t.buffer);
+  let n = 0;
+  s.setUint32(n, o.length, !0), n += 4;
+  for (let i = 0; i < o.length; i++) {
+    s.setUint32(n, o[i].exclusive ? 0 : 1, !0), n += 4;
+    const h = e[i];
+    if (h !== null) {
+      s.setUint32(n, h.length, !0), n += 4;
+      for (let a = 0; a < h.length; a++) {
+        const l = h[a][0], u = h[a][1];
+        s.setUint32(n, l, !0), n += 4, s.setUint32(n, u.length, !0), n += 4;
+        for (let _ = 0; _ < u.length; _++)
+          s.setFloat64(n, u[_], !0), n += R;
+      }
+    }
+  }
+  return t;
+}
+function H(o, e, r) {
+  const t = new DataView(e.buffer, e.byteOffset, e.byteLength), s = e.byteLength;
+  let n = 0;
+  const i = (a) => {
+    if (n + a > s)
+      throw new f(
+        `relation snapshot truncated: need ${a} more bytes at offset ${n}, have ${s - n}`
+      );
+  };
+  for (let a = 0; a < o.length; a++) o[a].resetIndices();
+  i(4);
+  const h = t.getUint32(n, !0);
+  if (n += 4, h !== o.length)
+    throw new f(
+      `relation count mismatch: snapshot=${h}, registered=${o.length}`
+    );
+  for (let a = 0; a < o.length; a++) {
+    const l = o[a];
+    i(k);
+    const u = t.getUint32(n, !0);
+    if (n += 4, u === 1 === l.exclusive)
+      throw new f(
+        `relation ${a} cardinality mismatch: snapshot ${u ? "multi" : "exclusive"}, registered ${l.exclusive ? "exclusive" : "multi"}`
+      );
+    if (l.exclusive) continue;
+    i(y);
+    const _ = t.getUint32(n, !0);
+    n += 4;
+    for (let I = 0; I < _; I++) {
+      i(m);
+      const v = t.getUint32(n, !0);
+      n += 4;
+      const x = t.getUint32(n, !0);
+      if (n += 4, v > w)
+        throw new f(
+          `relation ${a} source index ${v} exceeds MAX_INDEX (${w})`
+        );
+      i(x * R);
+      const F = r(v);
+      for (let S = 0; S < x; S++) {
+        const p = c(t.getFloat64(n, !0));
+        n += R;
+        const E = p;
+        if (!Number.isInteger(E) || E < 0 || E > N)
+          throw new f(
+            `relation ${a} target ${E} is not a well-formed packed EntityID (expected an integer in [0, ${N}])`
+          );
+        l.restoreAddTarget(v, p, F);
+      }
+    }
+  }
+  if (n !== s)
+    throw new f(
+      `relation snapshot has ${s - n} trailing bytes after the last relation (not a canonical encoding)`
+    );
+}
+export {
+  j as D,
+  w as M,
+  L as R,
+  Y as U,
+  K as a,
+  V as c,
+  P as e,
+  d as g,
+  H as r,
+  W as s
+};