@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/relations/relation_store.d.ts

@@ -0,0 +1,177 @@
+import { EntityID } from '../../core/ecs/entity.js';
+import { SparseComponentDef, SparseComponentStore } from '../../core/ecs/sparse_store.js';
+import { CanonicalPairFn, CanonicalTargetSetFn, MakeSourceID, OnDeleteTarget, RelationStoreView } from '../../core/ecs/relation.js';
+/** One relation's derived side state. **Abstract over cardinality:** the
+ * base owns the cardinality-agnostic **reverse index** (target → sources, keyed
+ * by full `EntityID` so a recycled slot can't alias a dead target's sources) and
+ * a handle on the backing `SparseComponentStore`. The forward representation and
+ * its sparse interaction are owned by the concrete `ExclusiveRelationStore` and
+ * `MultiRelationStore` (built by `createRelationStore`).
+ *
+ * The registry level (`Store` and `RelationService`) owns what is genuinely its
+ * own, entity liveness, registration, and destroy orchestration, and drives
+ * a relation through the virtual `link`,
+ * `unlink`, `purgeSource`, `forEachCanonicalPair` and their peers, without ever
+ * branching on cardinality. Each cardinality keeps the forward link, the reverse
+ * index and the sparse membership in lockstep inside one method on one class, so the
+ * lockstep can't be broken by missing a scattered `if (rs.exclusive)` site. */
+export declare abstract class RelationStore implements RelationStoreView {
+    /** `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. */
+    readonly exclusive: boolean;
+    /** Backing sparse component def: `{ target: f64 }` when exclusive, a tag when
+     * multi. Carries membership (and the target, when exclusive). */
+    readonly sparse: SparseComponentDef;
+    /** 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`. */
+    readonly onDeleteTarget: 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. */
+    protected readonly _store: SparseComponentStore;
+    /** 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`). */
+    private readonly _reverse;
+    constructor(exclusive: boolean, sparse: SparseComponentDef, store: SparseComponentStore, onDeleteTarget: OnDeleteTarget);
+    /** Record that `src` points at `tgt` in the reverse index. */
+    protected _linkReverse(tgt: EntityID, src: EntityID): void;
+    /** 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). */
+    protected _unlinkReverse(tgt: EntityID, src: EntityID): void;
+    /** 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(isAlive: (id: EntityID) => boolean): number;
+    /** Sources that point at `tgt`, ascending by id (deterministic, cold-path
+     * sort), empty when none. */
+    sourcesOf(tgt: EntityID): EntityID[];
+    /** 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(): void;
+    /** Clear this relation's forward representation. Multi clears the side map.
+     * Exclusive clears nothing, because its forward links live in the sparse
+     * store, which `restoreSparseStores` clears. */
+    protected abstract _resetForward(): void;
+    /** Add a `(R, tgt)` link from `src`, keeping the forward link, the membership
+     * row and the reverse index in lockstep. Exclusive: replaces any existing target
+     * (idempotent if `tgt` is already the target). Multi: adds to the set
+     * (idempotent on a duplicate), establishing the membership tag on the first
+     * target. `src` must be live, `Store` checks before delegating. */
+    abstract link(src: EntityID, tgt: EntityID): void;
+    /** Remove `(R, tgt)` from `src`, or, when `tgt` is omitted, every target of
+     * `src`, keeping the forward link, the membership row and the reverse index
+     * in lockstep. A
+     * no-op when the link isn't present. */
+    abstract unlink(src: EntityID, tgt?: EntityID): void;
+    /** Purge a destroyed **source**: drop its forward link(s) and unlink it from
+     * every target's reverse set, but leave the sparse **membership** row alone,
+     * `Store._purgeSparse` drops that (for every store) right after, so this
+     * runs first and must not double-remove. */
+    abstract purgeSource(src: EntityID): void;
+    /** The single target of source `index`, or `undefined`. Exclusive reads the
+     * sparse field. Multi has no single target and returns `undefined` (matching
+     * the production `targetOf`-on-multi read, which the `DEV` guard rejects). */
+    abstract singleTargetAt(index: number): EntityID | undefined;
+    /** All targets of source `index`, ascending by id, one or zero for
+     * exclusive, the full sorted set for multi. The symmetric counterpart to
+     * `sourcesOf`. */
+    abstract targetsAt(index: number): EntityID[];
+    /** Whether source `index` holds any target under this relation (sparse
+     * membership). */
+    abstract hasIndex(index: number): boolean;
+    /** Fold `cb` over this relation's **multi** forward target sets in canonical
+     * order (sources ascending by index, each source's targets ascending by id),
+     * skipping empty sets. The single source of truth for the canonical multi
+     * traversal shared by `stateHash`, `snapshotRelations`, and `pairsOf`.
+     * Exclusive relations contribute via the sparse store, so this
+     * is a no-op for them. */
+    abstract forEachCanonicalTargetSet(cb: CanonicalTargetSetFn): void;
+    /** Fold `cb` over every `(source, target)` pair of this relation in canonical
+     * order, the `(R, *)` wildcard drive order. `createId` maps a source
+     * index to its full `EntityID`. Exclusive rides the backing store's
+     * `canonicalIndices`. Multi rides `forEachCanonicalTargetSet`. */
+    abstract forEachCanonicalPair(createId: MakeSourceID, cb: CanonicalPairFn): void;
+    /** Rebuild the reverse index from the forward links after a restore.
+     * Exclusive reads it back from the newly restored sparse target field (the
+     * reverse index is never serialized). Multi already rebuilt its reverse edges
+     * in `restoreAddTarget`, so this is a no-op for it. `createId` maps a source
+     * index to its full `EntityID`. */
+    abstract rebuildReverse(createId: MakeSourceID): void;
+    /** Restore one decoded multi forward edge `(source index → tgt)` plus its
+     * reverse edge (the source's full `EntityID` is `src`). Multi only, the
+     * snapshot header guards exclusive relations out before this is reached, so
+     * the exclusive override throws defensively. */
+    abstract restoreAddTarget(index: number, tgt: EntityID, src: EntityID): void;
+}
+/** Build the right `RelationStore` for a cardinality. The only construction
+ * site is `Store.registerRelation`, which resolves the backing sparse store and
+ * hands it in so the relation can drive forward and membership rows directly. */
+export declare function createRelationStore(exclusive: boolean, sparse: SparseComponentDef, store: SparseComponentStore, onDeleteTarget: OnDeleteTarget): RelationStore;
+/** Serialize the relation side data that does **not** live in the sparse store,
+ * i.e. each **multi** relation's forward target sets (`Map<source index,
+ * Set<target>>`). Exclusive relations store their target in the backing sparse
+ * field, so they ride `snapshotSparseStores` and contribute only a header
+ * here. The reverse index is fully derivable (from the sparse store for
+ * exclusive, from these sets for multi), so it is never serialized. It is
+ * rebuilt by `restoreRelations` + the caller's exclusive-reverse pass.
+ *
+ * Members are emitted in canonical order (sources ascending by entity index,
+ * each source's targets ascending by id) so the bytes are independent of
+ * add and remove history, the same byte-level determinism invariant the sparse
+ * snapshot holds. Layout (integers little-endian):
+ *
+ *   u32 relationCount
+ *   repeat relationCount times (registration and id order):
+ *     u32 isMulti
+ *     if multi:
+ *       u32 sourceCount
+ *       repeat sourceCount times (ascending source index):
+ *         u32 sourceIndex
+ *         u32 targetCount
+ *         f64 × targetCount   (target EntityIDs, ascending) */
+export declare function snapshotRelations(relations: readonly RelationStoreView[]): Uint8Array;
+/** Rebuild every relation's side indices from a `snapshotRelations` buffer and
+ * the already-restored sparse stores. Each relation's indices are reset first
+ * (idempotent into a dirty world), then:
+ *
+ *  - **multi**, forward target sets and their reverse edges are rebuilt from
+ *    `bytes` (the sets aren't in the sparse store, so the bytes are the only
+ *    source). `createId` maps a source entity index to its full `EntityID`
+ *    (generation from the live slot) so reverse edges key correctly.
+ *  - **exclusive**, only the reset happens here. The reverse index is rebuilt
+ *    by the caller from the backing sparse store (which already round-tripped
+ *    through `restoreSparseStores`), since this function can't read it.
+ *
+ * Throws `SparseRestoreError` on any shape mismatch (relation count, an
+ * exclusive or multi flag that disagrees with the registered relation, a multi
+ * source index past `MAX_INDEX`, or a truncated or over-long buffer) rather than
+ * silently building a corrupt index. */
+export declare function restoreRelations(relations: readonly RelationStoreView[], bytes: Uint8Array, createId: (index: number) => EntityID): void;
+//# sourceMappingURL=relation_store.d.ts.map

package/dist/plugins/relations/relation_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation_store.d.ts","sourceRoot":"","sources":["../../../src/plugins/relations/relation_store.ts"],"names":[],"mappings":"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"}

package/dist/plugins/relations.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("./relation_store-DQKSnxsm.cjs"),w=require("./arrays-Dt-Joc4i.cjs"),I=require("../index.cjs"),y=require("./assertions-z5GQd_bB.cjs");class D{constructor(t){this._host=t}_relations=[];_hasTargetCleanup=!1;_hierarchyRadixOut=new Uint32Array(1024);_hierarchyRadixC0=new Int32Array(1024);_hierarchyRadixC1=new Int32Array(1024);get stores(){return this._relations}get count(){return this._relations.length}get hasTargetCleanup(){return this._hasTargetCleanup}registerRelation(t){const e=t?.multi===!0,s=t?.exclusive===!0;if(e&&s)throw new I.ECSError(I.ECS_ERROR.RELATION_MODE_INVALID,"relations.register: a relation cannot be both exclusive and multi-target");const r=!e,i=t?.onDeleteTarget??l.DEFAULT_ON_DELETE_TARGET,n=r?this._host.pushSparseStore([l.RELATION_TARGET_FIELD],["f64"]):this._host.pushSparseStore([],[]),o=this._relations.length;return this._relations.push(l.createRelationStore(r,n,this._host.sparseStoreOf(n),i)),i!=="orphan"&&(this._hasTargetCleanup=!0),y.unsafeCast(o)}_relationOf(t){const e=t,s=this._relations[e];if(s===void 0)throw new I.ECSError(I.ECS_ERROR.RELATION_NOT_REGISTERED,`relation ${e} is not registered`);return s}addRelation(t,e,s){const r=this._relationOf(e);this._host.isAlive(t)&&this._host.isAlive(s)&&r.link(t,s)}removeRelation(t,e,s){const r=this._relationOf(e);this._host.isAlive(t)&&r.unlink(t,s)}targetOf(t,e){return this._relationOf(e).singleTargetAt(l.getEntityIndex(t))}targetsOf(t,e){return this._relationOf(e).targetsAt(l.getEntityIndex(t))}sourcesOf(t,e){return this._relationOf(e).sourcesOf(t)}hasRelation(t,e){return this._host.hasSparse(t,this._relationOf(e).sparse)}pairsOf(t){const e=this._relationOf(t),s=[],r=this._host.generations();return e.forEachCanonicalPair(i=>l.createEntityId(i,r[i]),(i,n)=>s.push([i,n])),s}sourcesOfAny(t){const e=[],s=this._relations;for(let r=0;r<s.length;r++){const i=y.unsafeCast(r),n=s[r].sourcesOf(t);for(let o=0;o<n.length;o++)e.push([i,n[o]])}return e}relationBackingSparseId(t){return this._relationOf(t).sparse}forEachTargetMatch(t,e,s,r,i,n){const{sparseIncludes:o,sparseExcludes:u,includesDisabled:a}=i,c=this._relations;if(c.length===0)return;const g=new Set;for(let h=0;h<c.length;h++){const f=c[h].sourcesOf(t);for(let p=0;p<f.length;p++)g.add(f[p])}if(g.size===0)return;const v=Array.from(g).sort((h,f)=>h-f),S=this._host.sparseStores(),R=this._host.entityArchetypes(),_=this._host.entityRows(),O=this._host.archetypes();for(let h=0;h<v.length;h++){const f=y.unsafeCast(v[h]),p=l.getEntityIndex(f),T=R[p];if(T===l.UNASSIGNED)continue;const C=O[T],A=C.mask;if(!A.contains(e)||s!==null&&A.overlaps(s)||r!==null&&!A.overlaps(r))continue;let x=!0;for(let d=0;d<o.length;d++)if(!S[o[d]].has(p)){x=!1;break}if(x){for(let d=0;d<u.length;d++)if(S[u[d]].has(p)){x=!1;break}if(x){if(!a){const d=_[p];if(d!==l.UNASSIGNED&&d>=C.enabledCount)continue}n(f)}}}}compactRelations(){const t=this._relations;if(t.length===0)return 0;const e=r=>this._host.isAlive(r);let s=0;for(let r=0;r<t.length;r++)s+=t[r].pruneDeadReverse(e);return s}ancestorsOf(t,e){const s=this._relationOf(e),r=this._host.sparseStoreOf(s.sparse),i=[t],n=new Set([l.getEntityIndex(t)]);let o=t;for(;;){const u=r.getField(l.getEntityIndex(o),0);if(u===void 0)break;const a=y.unsafeCast(u);if(!this._host.isAlive(a)){i.push(a);break}const c=l.getEntityIndex(a);if(n.has(c))break;n.add(c),o=a,i.push(o)}return i}rootOf(t,e){const s=this.ancestorsOf(t,e);return s[s.length-1]}cascadeOf(t,e){const s=this._relationOf(e),r=[t],i=new Set([l.getEntityIndex(t)]);for(let n=0;n<r.length;n++){const o=s.sourcesOf(r[n]);for(let u=0;u<o.length;u++){const a=o[u],c=l.getEntityIndex(a);i.has(c)||(i.add(c),r.push(a))}}return r}purgeSource(t){const e=this._relations;for(let s=0;s<e.length;s++)e[s].purgeSource(t)}cleanupTarget(t,e){const s=this._relations;for(let r=0;r<s.length;r++){const i=s[r];if(i.onDeleteTarget==="orphan")continue;const n=i.sourcesOf(t);if(n.length!==0){if(i.onDeleteTarget==="delete"){for(let o=0;o<n.length;o++)e.push(n[o]);continue}for(let o=0;o<n.length;o++)i.unlink(n[o],t)}}}forEachHierarchyMatch(t,e,s,r,i,n,o,u){const a=this._relationOf(n),c=[];if(this._host.forEachSparseMatch(t,e,s,r,i,_=>c.push(_)),c.length===0)return;this._hierarchyRadixOut=w.radixSortByIndex(c,this._hierarchyRadixOut,this._hierarchyRadixC0,this._hierarchyRadixC1);const g=this._host.sparseStoreOf(a.sparse),v=new Map,S=new Set,R=[];for(let _=0;_<c.length;_++){const O=c[_],h=this._hierarchyDepthOf(l.getEntityIndex(O),g,v,S);if(h>o)continue;let f=R[h];f===void 0&&(f=[],R[h]=f),f.push(O)}for(let _=0;_<R.length;_++){const O=R[_];if(O!==void 0)for(let h=0;h<O.length;h++)u(O[h])}}_hierarchyDepthOf(t,e,s,r){const i=[];let n=t,o=0;for(;;){const a=s.get(n);if(a!==void 0){o=a;break}const c=e.getField(n,0);let g=-1;if(c!==void 0){const v=y.unsafeCast(c);this._host.isAlive(v)&&(g=l.getEntityIndex(v))}if(g===-1){s.set(n,0),o=0;break}if(r.has(g)){s.set(n,0),o=0;break}i.push(n),r.add(n),n=g}let u=o;for(let a=i.length-1;a>=0;a--)u+=1,s.set(i[a],u),r.delete(i[a]);return s.get(t)}}class k{_service;constructor(t){this._service=t}register(t){return this._service.registerRelation(t)}get count(){return this._service.count}add(t,e,s){return this._service.addRelation(t,e,s),this}remove(t,e,s){return this._service.removeRelation(t,e,s),this}has(t,e){return this._service.hasRelation(t,e)}targetOf(t,e){return this._service.targetOf(t,e)}targetsOf(t,e){return this._service.targetsOf(t,e)}sourcesOf(t,e){return this._service.sourcesOf(t,e)}pairsOf(t){return this._service.pairsOf(t)}sourcesOfAny(t){return this._service.sourcesOfAny(t)}ancestorsOf(t,e){return this._service.ancestorsOf(t,e)}rootOf(t,e){return this._service.rootOf(t,e)}cascadeOf(t,e){return this._service.cascadeOf(t,e)}compact(){return this._service.compactRelations()}}function b(E,t){return E.relations.register({exclusive:!0,onDeleteTarget:t?.onDeleteTarget??"clear"})}function N(E,t){return E.relations.register({exclusive:!0,onDeleteTarget:t?.onDeleteTarget??"delete"})}function M(){return{name:"relations",install(E){const t=E.store,e=new D(t.relationHost());return t.installRelations(e),{relations:new k(e)}}}}exports.ECSRelations=k;exports.registerChildOf=N;exports.registerIsA=b;exports.relations=M;

package/dist/plugins/relations.d.cts

@@ -0,0 +1 @@
+export * from "./relations/index.cjs";

package/dist/plugins/relations.d.ts

@@ -0,0 +1 @@
+export * from "./relations/index.js";

package/dist/plugins/relations.development.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("./relation_store-RBhpcE28.cjs"),D=require("./arrays-Dt-Joc4i.cjs"),l=require("../index.development.cjs"),A=require("./assertions-z5GQd_bB.cjs");class N{constructor(e){this._host=e}_relations=[];_hasTargetCleanup=!1;_hierarchyRadixOut=new Uint32Array(1024);_hierarchyRadixC0=new Int32Array(1024);_hierarchyRadixC1=new Int32Array(1024);get stores(){return this._relations}get count(){return this._relations.length}get hasTargetCleanup(){return this._hasTargetCleanup}registerRelation(e){const t=e?.multi===!0,r=e?.exclusive===!0;if(t&&r)throw new l.ECSError(l.ECS_ERROR.RELATION_MODE_INVALID,"relations.register: a relation cannot be both exclusive and multi-target");const s=!t,i=e?.onDeleteTarget??a.DEFAULT_ON_DELETE_TARGET,n=s?this._host.pushSparseStore([a.RELATION_TARGET_FIELD],["f64"]):this._host.pushSparseStore([],[]),o=this._relations.length;return this._relations.push(a.createRelationStore(s,n,this._host.sparseStoreOf(n),i)),i!=="orphan"&&(this._hasTargetCleanup=!0),A.unsafeCast(o)}_relationOf(e){const t=e,r=this._relations[t];if(r===void 0)throw new l.ECSError(l.ECS_ERROR.RELATION_NOT_REGISTERED,`relation ${t} is not registered`);return r}addRelation(e,t,r){const s=this._relationOf(t);if(!this._host.isAlive(e))throw a.entityNotAliveError("addRelation",e,"source");if(!this._host.isAlive(r))throw a.entityNotAliveError("addRelation",r,"target");s.link(e,r)}removeRelation(e,t,r){const s=this._relationOf(t);if(!this._host.isAlive(e))throw a.entityNotAliveError("removeRelation",e,"source");s.unlink(e,r)}targetOf(e,t){const r=this._relationOf(t);{if(!r.exclusive)throw new l.ECSError(l.ECS_ERROR.RELATION_MODE_MISMATCH,"targetOf: relation is multi-target, use targetsOf");if(!this._host.isAlive(e))throw a.entityNotAliveError("targetOf",e)}return r.singleTargetAt(a.getEntityIndex(e))}targetsOf(e,t){const r=this._relationOf(t);if(!this._host.isAlive(e))throw a.entityNotAliveError("targetsOf",e);return r.targetsAt(a.getEntityIndex(e))}sourcesOf(e,t){return this._relationOf(t).sourcesOf(e)}hasRelation(e,t){return this._host.hasSparse(e,this._relationOf(t).sparse)}pairsOf(e){const t=this._relationOf(e),r=[],s=this._host.generations();return t.forEachCanonicalPair(i=>a.createEntityId(i,s[i]),(i,n)=>r.push([i,n])),r}sourcesOfAny(e){const t=[],r=this._relations;for(let s=0;s<r.length;s++){const i=A.unsafeCast(s),n=r[s].sourcesOf(e);for(let o=0;o<n.length;o++)t.push([i,n[o]])}return t}relationBackingSparseId(e){return this._relationOf(e).sparse}forEachTargetMatch(e,t,r,s,i,n){const{sparseIncludes:o,sparseExcludes:f,includesDisabled:c}=i,h=this._relations;if(h.length===0)return;const d=new Set;for(let u=0;u<h.length;u++){const _=h[u].sourcesOf(e);for(let R=0;R<_.length;R++)d.add(_[R])}if(d.size===0)return;const p=Array.from(d).sort((u,_)=>u-_),S=this._host.sparseStores(),y=this._host.entityArchetypes(),E=this._host.entityRows(),O=this._host.archetypes();for(let u=0;u<p.length;u++){const _=A.unsafeCast(p[u]),R=a.getEntityIndex(_),x=y[R];if(x===a.UNASSIGNED)continue;const w=O[x],I=w.mask;if(!I.contains(t)||r!==null&&I.overlaps(r)||s!==null&&!I.overlaps(s))continue;let C=!0;for(let g=0;g<o.length;g++)if(!S[o[g]].has(R)){C=!1;break}if(C){for(let g=0;g<f.length;g++)if(S[f[g]].has(R)){C=!1;break}if(C){if(!c){const g=E[R];if(g!==a.UNASSIGNED&&g>=w.enabledCount)continue}n(_)}}}}compactRelations(){const e=this._relations;if(e.length===0)return 0;const t=s=>this._host.isAlive(s);let r=0;for(let s=0;s<e.length;s++)r+=e[s].pruneDeadReverse(t);return r}ancestorsOf(e,t){const r=this._relationOf(t);{if(!r.exclusive)throw new l.ECSError(l.ECS_ERROR.RELATION_MODE_MISMATCH,"ancestorsOf: relation is multi-target, traversal needs an exclusive (parent) chain");if(!this._host.isAlive(e))throw a.entityNotAliveError("ancestorsOf",e)}const s=this._host.sparseStoreOf(r.sparse),i=[e],n=new Set([a.getEntityIndex(e)]);let o=e;for(;;){const f=s.getField(a.getEntityIndex(o),0);if(f===void 0)break;const c=A.unsafeCast(f);if(!this._host.isAlive(c)){i.push(c);break}const h=a.getEntityIndex(c);if(n.has(h))throw new l.ECSError(l.ECS_ERROR.RELATION_CYCLE,`ancestorsOf: cycle in relation chain at entity index ${h}`);n.add(h),o=c,i.push(o)}return i}rootOf(e,t){const r=this.ancestorsOf(e,t);return r[r.length-1]}cascadeOf(e,t){const r=this._relationOf(t);{if(!r.exclusive)throw new l.ECSError(l.ECS_ERROR.RELATION_MODE_MISMATCH,"cascadeOf: relation is multi-target, traversal needs an exclusive (parent) chain");if(!this._host.isAlive(e))throw a.entityNotAliveError("cascadeOf",e)}const s=[e],i=new Set([a.getEntityIndex(e)]);for(let n=0;n<s.length;n++){const o=r.sourcesOf(s[n]);for(let f=0;f<o.length;f++){const c=o[f],h=a.getEntityIndex(c);if(i.has(h))throw new l.ECSError(l.ECS_ERROR.RELATION_CYCLE,`cascadeOf: cycle in relation chain at entity index ${h}`);i.add(h),s.push(c)}}return s}purgeSource(e){const t=this._relations;for(let r=0;r<t.length;r++)t[r].purgeSource(e)}cleanupTarget(e,t){const r=this._relations;for(let s=0;s<r.length;s++){const i=r[s];if(i.onDeleteTarget==="orphan")continue;const n=i.sourcesOf(e);if(n.length!==0){if(i.onDeleteTarget==="delete"){for(let o=0;o<n.length;o++)t.push(n[o]);continue}for(let o=0;o<n.length;o++)i.unlink(n[o],e)}}}forEachHierarchyMatch(e,t,r,s,i,n,o,f){const c=this._relationOf(n);if(!c.exclusive)throw new l.ECSError(l.ECS_ERROR.RELATION_MODE_MISMATCH,"hierarchy(): relation is multi-target, depth ordering needs an exclusive (parent) chain");const h=[];if(this._host.forEachSparseMatch(e,t,r,s,i,E=>h.push(E)),h.length===0)return;this._hierarchyRadixOut=D.radixSortByIndex(h,this._hierarchyRadixOut,this._hierarchyRadixC0,this._hierarchyRadixC1);const d=this._host.sparseStoreOf(c.sparse),p=new Map,S=new Set,y=[];for(let E=0;E<h.length;E++){const O=h[E],u=this._hierarchyDepthOf(a.getEntityIndex(O),d,p,S);if(u>o)continue;let _=y[u];_===void 0&&(_=[],y[u]=_),_.push(O)}for(let E=0;E<y.length;E++){const O=y[E];if(O!==void 0)for(let u=0;u<O.length;u++)f(O[u])}}_hierarchyDepthOf(e,t,r,s){const i=[];let n=e,o=0;for(;;){const c=r.get(n);if(c!==void 0){o=c;break}const h=t.getField(n,0);let d=-1;if(h!==void 0){const p=A.unsafeCast(h);this._host.isAlive(p)&&(d=a.getEntityIndex(p))}if(d===-1){r.set(n,0),o=0;break}if(s.has(d))throw new l.ECSError(l.ECS_ERROR.RELATION_CYCLE,`hierarchy(): cycle in relation chain at entity index ${d}`);i.push(n),s.add(n),n=d}let f=o;for(let c=i.length-1;c>=0;c--)f+=1,r.set(i[c],f),s.delete(i[c]);return r.get(e)}}class T{_service;constructor(e){this._service=e}register(e){return this._service.registerRelation(e)}get count(){return this._service.count}add(e,t,r){return this._service.addRelation(e,t,r),this}remove(e,t,r){return this._service.removeRelation(e,t,r),this}has(e,t){return this._service.hasRelation(e,t)}targetOf(e,t){return this._service.targetOf(e,t)}targetsOf(e,t){return this._service.targetsOf(e,t)}sourcesOf(e,t){return this._service.sourcesOf(e,t)}pairsOf(e){return this._service.pairsOf(e)}sourcesOfAny(e){return this._service.sourcesOfAny(e)}ancestorsOf(e,t){return this._service.ancestorsOf(e,t)}rootOf(e,t){return this._service.rootOf(e,t)}cascadeOf(e,t){return this._service.cascadeOf(e,t)}compact(){return this._service.compactRelations()}}function M(v,e){return v.relations.register({exclusive:!0,onDeleteTarget:e?.onDeleteTarget??"clear"})}function k(v,e){return v.relations.register({exclusive:!0,onDeleteTarget:e?.onDeleteTarget??"delete"})}function L(){return{name:"relations",install(v){const e=v.store,t=new N(e.relationHost());return e.installRelations(t),{relations:new T(t)}}}}exports.ECSRelations=T;exports.registerChildOf=k;exports.registerIsA=M;exports.relations=L;