@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/observers.js

@@ -0,0 +1,403 @@
+import { ECSError as g, ECS_ERROR as E } from "../index.js";
+import { u as S } from "./assertions-gtDVfbnQ.js";
+import { componentDebugName as O } from "../internal.js";
+import { r as f } from "./arrays-Dr_1hCjL.js";
+const u = !1, C = (a) => S(a), k = Object.freeze({
+  reads: Object.freeze([]),
+  writes: Object.freeze([]),
+  spawns: Object.freeze([]),
+  despawns: Object.freeze([]),
+  transitions: Object.freeze([]),
+  resourceReads: Object.freeze([]),
+  resourceWrites: Object.freeze([]),
+  sparseReads: Object.freeze([]),
+  sparseWrites: Object.freeze([]),
+  relationReads: Object.freeze([]),
+  relationWrites: Object.freeze([])
+}), b = "observers", m = Symbol.dispose ?? Symbol.for("Symbol.dispose"), y = (1 << 20) - 1;
+let w = 0;
+function v(a, e) {
+  const t = {
+    ...k,
+    ...e,
+    id: C(w++),
+    name: a,
+    fn: A
+  };
+  return Object.freeze(t);
+}
+function A() {
+}
+function x(a) {
+  const e = /* @__PURE__ */ new Set();
+  if (a) for (let t = 0; t < a.length; t++) e.add(a[t].id);
+  return e;
+}
+function B(a) {
+  const e = (n, o) => n.cid - o.cid || n.id - o.id, t = /* @__PURE__ */ new Map(), i = /* @__PURE__ */ new Map();
+  for (const n of a)
+    t.set(n, []), i.set(n, 0);
+  for (const n of a)
+    if (n.writes.size !== 0)
+      for (const o of a) {
+        if (n === o) continue;
+        let d = !1;
+        for (const c of n.writes)
+          if (o.reads.has(c)) {
+            d = !0;
+            break;
+          }
+        d && (t.get(n).push(o), i.set(o, i.get(o) + 1));
+      }
+  const s = a.filter((n) => i.get(n) === 0).sort(e), r = [];
+  for (; s.length > 0; ) {
+    const n = s.shift();
+    r.push(n);
+    for (const o of t.get(n)) {
+      const d = i.get(o) - 1;
+      i.set(o, d), d === 0 && (s.push(o), s.sort(e));
+    }
+  }
+  if (r.length !== a.length) {
+    const n = new Set(r);
+    for (const o of a.slice().sort(e)) n.has(o) || r.push(o);
+  }
+  return r;
+}
+class R {
+  constructor(e, t) {
+    this._store = e, this._ctx = t;
+  }
+  _entries = [];
+  /** ComponentID → its observers (structural + onSet). */
+  _byCid = /* @__PURE__ */ new Map();
+  /** The entity-level onSet observers on sparse components, in registration
+   * order. */
+  _sparseEntries = [];
+  /** Per-`dispatchSet` cache of each sparse component's drain, so two
+   * observers on one sparse component fire over one snapshot. */
+  _sparseDrainCache = /* @__PURE__ */ new Map();
+  /** Cached access-topological order. A register or a dispose invalidates it. */
+  _topo = null;
+  // --- dispatch scratch (reused, never reallocated in the hot loop) ---
+  // Per-component eid buckets for the current structural round, keyed by cid.
+  _addBuckets = /* @__PURE__ */ new Map();
+  _remBuckets = /* @__PURE__ */ new Map();
+  // Disable and enable buckets, populated only on a toggle-drain round
+  // (toggles drain once add, remove and destroy are quiescent, so a round carries
+  // either structural events or toggle events, never both).
+  _disBuckets = /* @__PURE__ */ new Map();
+  _enaBuckets = /* @__PURE__ */ new Map();
+  // The radix scratch is a typed array, grown by doubling, and never a plain
+  // array grown by a length assignment: JavaScriptCore turns the latter into a
+  // sparse store, and each element store in the pass becomes a hash insert.
+  // The drain of a large frame is far slower there for that reason.
+  _radixOut = new Uint32Array(1024);
+  _radixC0 = new Int32Array(1024);
+  _radixC1 = new Int32Array(1024);
+  // Per-`dispatchSet` cache of each component's drain, so a component with
+  // more than one per-entity onSet observer drains exactly once and fans the
+  // same snapshot out to every observer. Cleared at the end of each dispatch.
+  // (Bug: a second per-entity onSet observer on the same component used to
+  // see an empty list.)
+  _setDrainCache = /* @__PURE__ */ new Map();
+  get count() {
+    return this._entries.length + this._sparseEntries.length;
+  }
+  /** The synthesized `SystemDescriptor`s of every registered observer, in
+   * registration order (`dispose()` splices entries out, so none are stale).
+   * Fed into the `startup()` archetype-prewarm closure so an observer's declared
+   * `spawns` and `transitions` create their target archetypes eagerly, exactly as a
+   * system's do. Without this an archetype an observer spawns into or transitions to
+   * first-touches lazily mid-tick, the one asymmetry left in the otherwise
+   * uniform "no lazy archetypes" prewarm. */
+  descriptors() {
+    const e = [];
+    for (let t = 0; t < this._entries.length; t++) e.push(this._entries[t].descriptor);
+    for (let t = 0; t < this._sparseEntries.length; t++)
+      e.push(this._sparseEntries[t].descriptor);
+    return e;
+  }
+  register(e, t) {
+    if (typeof e == "number") return this._registerSparse(e, t);
+    const i = e.id;
+    if (typeof i != "number")
+      throw new g(
+        E.OBSERVER_INVALID_CONFIG,
+        "observe(): the definition is not a registered component. Observe a dense or a sparse component"
+      );
+    const s = t.granularity ?? "archetype", r = t.onSet !== void 0 && s === "entity", n = t.onSet !== void 0 && s !== "entity", o = t.access ?? {}, d = v(
+      t.name ?? `observer(${O(e) ?? i})`,
+      o
+    ), c = {
+      // Share one identity space with the descriptor (used only for the
+      // topo tie-break + diagnostics).
+      id: d.id,
+      cid: i,
+      def: e,
+      onAdd: t.onAdd,
+      onRemove: t.onRemove,
+      onDisable: t.onDisable,
+      onEnable: t.onEnable,
+      onSetEntity: r ? t.onSet : void 0,
+      onSetArch: n ? t.onSet : void 0,
+      descriptor: d,
+      writes: x(o.writes),
+      reads: x(o.reads),
+      yieldExisting: t.yieldExisting ?? !1,
+      lastSetTick: 0,
+      disposed: !1
+    };
+    this._entries.push(c);
+    let l = this._byCid.get(i);
+    l === void 0 && (l = [], this._byCid.set(i, l)), l.push(c), this._topo = null, this._reconfigureComponent(i), c.yieldExisting && c.onAdd !== void 0 && this._yieldExisting(c);
+    const h = () => this._dispose(c);
+    return { dispose: h, [m]: h };
+  }
+  /** The sparse arm of `register`: an entity-level onSet, and nothing else.
+   * A sparse add and remove are immediate and touch no archetype, so there
+   * is no flush boundary to fire a structural observer at, and no archetype
+   * column for the archetype grain. */
+  _registerSparse(e, t) {
+    if (t.onSet === void 0 || t.granularity !== "entity" || t.onAdd !== void 0 || t.onRemove !== void 0 || t.onDisable !== void 0 || t.onEnable !== void 0)
+      throw new g(
+        E.OBSERVER_INVALID_CONFIG,
+        'observe(): a sparse component takes onSet with granularity "entity" and no other callback. Move onAdd, onRemove, onDisable, onEnable and the archetype grain to a dense component'
+      );
+    const i = v(
+      t.name ?? `observer(sparse ${e})`,
+      t.access ?? {}
+    ), s = {
+      id: i.id,
+      sid: e,
+      onSet: t.onSet,
+      descriptor: i,
+      disposed: !1
+    };
+    this._sparseEntries.push(s), this._store.configureSparseObservation(b, e, !0);
+    const r = () => {
+      if (s.disposed) return;
+      s.disposed = !0;
+      const n = this._sparseEntries.indexOf(s);
+      n >= 0 && this._sparseEntries.splice(n, 1);
+      let o = !1;
+      for (let d = 0; d < this._sparseEntries.length; d++)
+        this._sparseEntries[d].sid === e && (o = !0);
+      o || this._store.configureSparseObservation(b, e, !1);
+    };
+    return { dispose: r, [m]: r };
+  }
+  _dispose(e) {
+    if (e.disposed) return;
+    e.disposed = !0;
+    const t = this._entries.indexOf(e);
+    t >= 0 && this._entries.splice(t, 1);
+    const i = this._byCid.get(e.cid);
+    if (i !== void 0) {
+      const s = i.indexOf(e);
+      s >= 0 && i.splice(s, 1), i.length === 0 && this._byCid.delete(e.cid);
+    }
+    this._topo = null, this._reconfigureComponent(e.cid);
+  }
+  /** Recompute the component's hot-path observation flags from its live
+   * observers and push them to the store (which owns the flags + fast-path
+   * counters). */
+  _reconfigureComponent(e) {
+    const t = this._byCid.get(e);
+    let i = !1, s = !1, r = !1, n = !1, o = !1;
+    if (t !== void 0)
+      for (let d = 0; d < t.length; d++) {
+        const c = t[d];
+        c.onAdd !== void 0 && (i = !0), c.onRemove !== void 0 && (s = !0), c.onDisable !== void 0 && (r = !0), c.onEnable !== void 0 && (n = !0), c.onSetEntity !== void 0 && (o = !0);
+      }
+    this._store.configureObservation(b, e, {
+      add: i,
+      remove: s,
+      disable: r,
+      enable: n,
+      set: o
+    });
+  }
+  _getTopo() {
+    return this._topo === null && (this._topo = B(this._entries)), this._topo;
+  }
+  // =======================================================
+  // Structural dispatch (onAdd and onRemove)
+  // =======================================================
+  /**
+   * Fire onAdd, onRemove, onDisable and onEnable for one fixed-point round's
+   * effective events, in canonical order: access-topological across observers,
+   * entity-id order (radix) within each observer. Called through the store's
+   * structural hook after the batch commits. Observer callbacks may
+   * enqueue further structural ops (or toggles) onto the deferred buffers (the
+   * store loops until quiescent).
+   *
+   * The events arrive as flat `(comp, eid)` parallel arrays collected during the
+   * flush. This dispatch buckets by component once (O(K)), then walks observers
+   * in topo order so a producer's writes are visible to a consumer
+   * (glitch-free). A round
+   * carries either structural (add, remove) or toggle (disable, enable) events, never both,
+   * toggles drain only once add, remove and destroy are quiescent (`flushStructural`),
+   * but all four bucket uniformly. The empty pairs are no-ops. Within an
+   * observer the fire order is remove, add, disable, enable (the "leaving" edges
+   * before the "entering" edges).
+   */
+  dispatchStructural(e) {
+    this._bucket(e.addComp, e.addEid, e.addLen, this._addBuckets), this._bucket(e.remComp, e.remEid, e.remLen, this._remBuckets), this._bucket(e.disComp, e.disEid, e.disLen, this._disBuckets), this._bucket(e.enaComp, e.enaEid, e.enaLen, this._enaBuckets);
+    const t = this._getTopo();
+    for (let i = 0; i < t.length; i++) {
+      const s = t[i];
+      if (!s.disposed) {
+        if (s.onRemove !== void 0) {
+          const r = this._remBuckets.get(s.cid);
+          r !== void 0 && r.length > 0 && this._fireEach(s, s.onRemove, r, "remove");
+        }
+        if (s.onAdd !== void 0) {
+          const r = this._addBuckets.get(s.cid);
+          r !== void 0 && r.length > 0 && this._fireEach(s, s.onAdd, r, "add");
+        }
+        if (s.onDisable !== void 0) {
+          const r = this._disBuckets.get(s.cid);
+          r !== void 0 && r.length > 0 && this._fireEach(s, s.onDisable, r, "disable");
+        }
+        if (s.onEnable !== void 0) {
+          const r = this._enaBuckets.get(s.cid);
+          r !== void 0 && r.length > 0 && this._fireEach(s, s.onEnable, r, "enable");
+        }
+      }
+    }
+    this._clearBuckets(this._addBuckets), this._clearBuckets(this._remBuckets), this._clearBuckets(this._disBuckets), this._clearBuckets(this._enaBuckets);
+  }
+  /** Radix-sort `eids` by entity index (canonical within-observer order), then
+   * fire `fn` per entity under the observer's access scope. */
+  _fireEach(e, t, i, s) {
+    this._radixOut = f(i, this._radixOut, this._radixC0, this._radixC1);
+    try {
+      const r = u ? this._store.trace : null;
+      for (let n = 0; n < i.length; n++)
+        t(S(i[n]), this._ctx);
+    } finally {
+    }
+  }
+  _bucket(e, t, i, s) {
+    for (let r = 0; r < i; r++) {
+      const n = e[r];
+      let o = s.get(n);
+      o === void 0 && (o = [], s.set(n, o)), o.push(t[r]);
+    }
+  }
+  _clearBuckets(e) {
+    for (const t of e.values()) t.length = 0;
+  }
+  // =======================================================
+  // onSet dispatch (post-update detection point)
+  // =======================================================
+  /**
+   * Fire onSet observers for the current frame, in canonical order. Per-entity
+   * onSet drains the opt-in dirty list, once for each changed entity.
+   * Archetype-granular onSet scans the change tick, once for each changed
+   * archetype column.
+   * Called through the plugin's settle hook, after every phase of the frame.
+   * `run` is the change tick advanced
+   * for this dispatch: above every system run of the frame, and the baseline
+   * each archetype-granular observer keeps for its next dispatch.
+   */
+  dispatchSet(e) {
+    if (this._entries.length === 0 && this._sparseEntries.length === 0) return;
+    const t = this._getTopo(), i = this._setDrainCache;
+    for (let r = 0; r < t.length; r++) {
+      const n = t[r];
+      n.onSetEntity !== void 0 ? this._dispatchSetEntity(n, i, e) : n.onSetArch !== void 0 && this._dispatchSetArch(n, e);
+    }
+    i.clear();
+    const s = this._sparseEntries;
+    if (s.length !== 0) {
+      const r = this._sparseDrainCache;
+      for (let n = 0; n < s.length; n++) {
+        const o = s[n];
+        o.disposed || this._dispatchSparseSet(o, r, e);
+      }
+      r.clear();
+    }
+  }
+  /** Fire one sparse observer over the members recorded since the last
+   * drain. The store's walk gives alive, member and enabled entities, so no
+   * check remains here. Canonical order by entity index, through the radix. */
+  _dispatchSparseSet(e, t, i) {
+    let s = t.get(e.sid);
+    if (s === void 0 && (s = this._store.drainSparseSet(e.sid, i), this._radixOut = f(s, this._radixOut, this._radixC0, this._radixC1), t.set(e.sid, s)), s.length === 0) return;
+    const r = e.onSet;
+    try {
+      for (let n = 0; n < s.length; n++)
+        r(s[n], this._ctx);
+    } finally {
+    }
+  }
+  _dispatchSetEntity(e, t, i) {
+    let s = t.get(e.cid);
+    s === void 0 && (s = this._store.drainSet(e.cid, i), this._radixOut = f(s.scanned, this._radixOut, this._radixC0, this._radixC1), this._radixOut = f(s.listed, this._radixOut, this._radixC0, this._radixC1), D(s.listed), t.set(e.cid, s));
+    const r = s.scanned, n = s.listed, o = r.length, d = n.length;
+    if (o === 0 && d === 0) return;
+    const c = e.def, l = e.onSetEntity;
+    try {
+      let h = 0, p = 0;
+      for (; h < o || p < d; ) {
+        let _;
+        if (p >= d || h < o && (r[h] & y) < (n[p] & y))
+          _ = r[h++];
+        else if (_ = n[p++], !this._store.isAlive(_) || !this._store.hasComponent(_, c) || this._store.isDisabled(_))
+          continue;
+        l(_, this._ctx);
+      }
+    } finally {
+    }
+  }
+  _dispatchSetArch(e, t) {
+    const i = e.onSetArch, s = e.lastSetTick;
+    try {
+      this._store.forEachChangedArchetype(e.cid, s, (r) => {
+        i(r, this._ctx);
+      });
+    } finally {
+    }
+    e.lastSetTick = t;
+  }
+  // =======================================================
+  // Seeding a new observer with the existing members
+  // =======================================================
+  _yieldExisting(e) {
+    const t = e.onAdd, i = this._store.collectEnabledWith(e.cid);
+    if (i.length !== 0) {
+      this._radixOut = f(i, this._radixOut, this._radixC0, this._radixC1);
+      try {
+        for (let s = 0; s < i.length; s++) t(S(i[s]), this._ctx);
+      } finally {
+      }
+    }
+  }
+}
+function D(a) {
+  const e = a.length;
+  if (e < 2) return;
+  let t = 1;
+  for (let i = 1; i < e; i++)
+    a[i] !== a[t - 1] && (a[t++] = a[i]);
+  a.length = t;
+}
+function N() {
+  return {
+    name: "observers",
+    install(a) {
+      const e = new R(a.store, a.context);
+      return a.onSettle((t) => e.dispatchSet(t)), a.onPrewarm(() => e.descriptors()), a.changes.addStructuralHook((t) => e.dispatchStructural(t)), {
+        observe(t, i) {
+          return e.register(t, i);
+        }
+      };
+    }
+  };
+}
+export {
+  R as ObserverRegistry,
+  N as observers
+};