iris-ecs 0.0.1

package/dist/registry.d.ts

@@ -0,0 +1,118 @@
+import type { Component, Relation, Tag } from "./encoding.js";
+import type { SchemaRecord } from "./schema.js";
+/**
+ * Component metadata.
+ *
+ * Stores component name, optional schema, and relation traits.
+ */
+export type ComponentMeta = {
+    /**
+     * Component name (user-defined).
+     */
+    name: string;
+    /**
+     * Field schemas for data components (undefined for tags).
+     */
+    schema?: SchemaRecord;
+    /**
+     * If true, entity can only have one target at a time for this relation.
+     */
+    exclusive?: boolean;
+    /**
+     * What happens when a pair target is destroyed. Default is "remove".
+     */
+    onDeleteTarget?: "remove" | "delete";
+};
+/**
+ * Options for defining relations.
+ *
+ * Controls relation behavior including exclusivity and delete policies.
+ */
+export type RelationOptions<S extends SchemaRecord = Record<string, never>> = {
+    /**
+     * Field schemas for pair data (optional).
+     */
+    schema?: S;
+    /**
+     * If true, entity can only have one target for this relation.
+     */
+    exclusive?: boolean;
+    /**
+     * What happens when a pair target is destroyed. Default is "remove".
+     */
+    onDeleteTarget?: "remove" | "delete";
+};
+/**
+ * Global singleton storing all component metadata across all worlds.
+ */
+export type ComponentRegistry = {
+    /**
+     * Component metadata lookup (component ID -> metadata).
+     */
+    byId: Map<Tag | Component | Relation, ComponentMeta>;
+    /**
+     * Next raw ID to allocate for tags.
+     */
+    nextTagId: number;
+    /**
+     * Next raw ID to allocate for data components.
+     */
+    nextComponentId: number;
+    /**
+     * Next raw ID to allocate for relations.
+     */
+    nextRelationId: number;
+};
+/**
+ * Global component registry singleton.
+ */
+export declare const COMPONENT_REGISTRY: ComponentRegistry;
+/**
+ * Defines a tag component. Tags are lightweight markers without data.
+ * @param name - Human-readable tag name for debugging
+ * @returns Encoded tag ID
+ * @throws {RangeError} If tag limit (1,048,576) exceeded
+ * @example
+ * const Player = defineTag("Player");
+ * addTag(world, entity, Player);
+ */
+export declare function defineTag(name: string): Tag;
+/**
+ * Defines a data component with a typed schema for storage.
+ * @param name - Human-readable component name for debugging
+ * @param schema - Field schema record defining data layout
+ * @returns Encoded component ID with schema type
+ * @throws {RangeError} If component limit (1,048,576) exceeded
+ * @example
+ * const Position = defineComponent("Position", { x: Type.f32, y: Type.f32 });
+ * set(world, entity, Position, { x: 10, y: 20 });
+ */
+export declare function defineComponent<S extends SchemaRecord>(name: string, schema: S): Component<S>;
+/**
+ * Defines a relation for entity-to-entity relationships.
+ * @param name - Human-readable relation name for debugging
+ * @param options - Configuration: schema for data, exclusive trait, delete behavior
+ * @returns Encoded relation ID with schema type
+ * @throws {RangeError} If relation limit (256) exceeded
+ * @example
+ * const ChildOf = defineRelation("ChildOf", { exclusive: true, onDeleteTarget: "delete" });
+ * addPair(world, child, ChildOf, parent);
+ */
+export declare function defineRelation<S extends SchemaRecord = Record<string, never>>(name: string, options?: RelationOptions<S>): Relation<S>;
+/**
+ * Wildcard relation for query patterns. Reserved as relation ID 0.
+ * - `pair(Wildcard, target)` matches all entities targeting target
+ * - `pair(relation, Wildcard)` matches entities with any target for relation
+ */
+export declare const Wildcard: Relation<Record<string, never>>;
+/**
+ * Marks a relation as exclusive (one target per subject).
+ * Adding a pair with an exclusive relation auto-removes any existing pair with that relation.
+ */
+export declare const Exclusive: Tag;
+/**
+ * Cascade delete subjects when target is destroyed.
+ * When an entity is destroyed, all entities with a pair targeting it are also destroyed.
+ */
+export declare const OnDeleteTarget: Tag;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACtC,CAAC;AAMF;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI;IAC5E;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC;IAEX;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACtC,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,IAAI,EAAE,GAAG,CAAC,GAAG,GAAG,SAAS,GAAG,QAAQ,EAAE,aAAa,CAAC,CAAC;IACrD;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,iBAKhC,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAiB3C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAiB7F;AAMD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC3E,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,QAAQ,CAAC,CAAC,CAAC,CAmBb;AAMD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,iCAA6B,CAAC;AAMnD;;;GAGG;AACH,eAAO,MAAM,SAAS,KAAyB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,cAAc,KAA8B,CAAC"}

package/dist/registry.js

@@ -0,0 +1,112 @@
+import { encodeComponent, encodeRelation, encodeTag, ID_MASK_8, ID_MASK_20 } from "./encoding.js";
+/**
+ * Global component registry singleton.
+ */
+export const COMPONENT_REGISTRY = {
+    byId: new Map(),
+    nextTagId: 0,
+    nextComponentId: 0,
+    nextRelationId: 0,
+};
+// ============================================================================
+// Tag Definition
+// ============================================================================
+/**
+ * Defines a tag component. Tags are lightweight markers without data.
+ * @param name - Human-readable tag name for debugging
+ * @returns Encoded tag ID
+ * @throws {RangeError} If tag limit (1,048,576) exceeded
+ * @example
+ * const Player = defineTag("Player");
+ * addTag(world, entity, Player);
+ */
+export function defineTag(name) {
+    const rawId = COMPONENT_REGISTRY.nextTagId;
+    if (rawId > ID_MASK_20) {
+        throw new RangeError(`Tag limit exceeded (max ${ID_MASK_20})`);
+    }
+    const tagId = encodeTag(rawId);
+    COMPONENT_REGISTRY.byId.set(tagId, {
+        name,
+        schema: undefined,
+    });
+    COMPONENT_REGISTRY.nextTagId++;
+    return tagId;
+}
+// ============================================================================
+// Component Definition
+// ============================================================================
+/**
+ * Defines a data component with a typed schema for storage.
+ * @param name - Human-readable component name for debugging
+ * @param schema - Field schema record defining data layout
+ * @returns Encoded component ID with schema type
+ * @throws {RangeError} If component limit (1,048,576) exceeded
+ * @example
+ * const Position = defineComponent("Position", { x: Type.f32, y: Type.f32 });
+ * set(world, entity, Position, { x: 10, y: 20 });
+ */
+export function defineComponent(name, schema) {
+    const rawId = COMPONENT_REGISTRY.nextComponentId;
+    if (rawId > ID_MASK_20) {
+        throw new RangeError(`Component limit exceeded (max ${ID_MASK_20})`);
+    }
+    const componentId = encodeComponent(rawId);
+    COMPONENT_REGISTRY.byId.set(componentId, {
+        name,
+        schema,
+    });
+    COMPONENT_REGISTRY.nextComponentId++;
+    return componentId;
+}
+// ============================================================================
+// Relation Definition
+// ============================================================================
+/**
+ * Defines a relation for entity-to-entity relationships.
+ * @param name - Human-readable relation name for debugging
+ * @param options - Configuration: schema for data, exclusive trait, delete behavior
+ * @returns Encoded relation ID with schema type
+ * @throws {RangeError} If relation limit (256) exceeded
+ * @example
+ * const ChildOf = defineRelation("ChildOf", { exclusive: true, onDeleteTarget: "delete" });
+ * addPair(world, child, ChildOf, parent);
+ */
+export function defineRelation(name, options) {
+    const rawId = COMPONENT_REGISTRY.nextRelationId;
+    if (rawId > ID_MASK_8) {
+        throw new RangeError(`Relation limit exceeded (max ${ID_MASK_8})`);
+    }
+    const relationId = encodeRelation(rawId);
+    COMPONENT_REGISTRY.byId.set(relationId, {
+        name,
+        schema: options?.schema,
+        exclusive: options?.exclusive,
+        onDeleteTarget: options?.onDeleteTarget,
+    });
+    COMPONENT_REGISTRY.nextRelationId++;
+    return relationId;
+}
+// ============================================================================
+// Built-in Relations
+// ============================================================================
+/**
+ * Wildcard relation for query patterns. Reserved as relation ID 0.
+ * - `pair(Wildcard, target)` matches all entities targeting target
+ * - `pair(relation, Wildcard)` matches entities with any target for relation
+ */
+export const Wildcard = defineRelation("Wildcard");
+// ============================================================================
+// Relation Trait Tags
+// ============================================================================
+/**
+ * Marks a relation as exclusive (one target per subject).
+ * Adding a pair with an exclusive relation auto-removes any existing pair with that relation.
+ */
+export const Exclusive = defineTag("Exclusive");
+/**
+ * Cascade delete subjects when target is destroyed.
+ * When an entity is destroyed, all entities with a pair targeting it are also destroyed.
+ */
+export const OnDeleteTarget = defineTag("OnDeleteTarget");
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAsFlG;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,IAAI,EAAE,IAAI,GAAG,EAAE;IACf,SAAS,EAAE,CAAC;IACZ,eAAe,EAAE,CAAC;IAClB,cAAc,EAAE,CAAC;CAClB,CAAC;AAEF,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,CAAC;IAE3C,IAAI,KAAK,GAAG,UAAU,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,2BAA2B,UAAU,GAAG,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAE/B,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE;QACjC,IAAI;QACJ,MAAM,EAAE,SAAS;KAClB,CAAC,CAAC;IAEH,kBAAkB,CAAC,SAAS,EAAE,CAAC;IAE/B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAyB,IAAY,EAAE,MAAS;IAC7E,MAAM,KAAK,GAAG,kBAAkB,CAAC,eAAe,CAAC;IAEjD,IAAI,KAAK,GAAG,UAAU,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,iCAAiC,UAAU,GAAG,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,WAAW,GAAG,eAAe,CAAI,KAAK,CAAC,CAAC;IAE9C,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;QACvC,IAAI;QACJ,MAAM;KACP,CAAC,CAAC;IAEH,kBAAkB,CAAC,eAAe,EAAE,CAAC;IAErC,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,OAA4B;IAE5B,MAAM,KAAK,GAAG,kBAAkB,CAAC,cAAc,CAAC;IAEhD,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAAC,gCAAgC,SAAS,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,UAAU,GAAG,cAAc,CAAI,KAAK,CAAC,CAAC;IAE5C,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE;QACtC,IAAI;QACJ,MAAM,EAAE,OAAO,EAAE,MAAM;QACvB,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,cAAc,EAAE,OAAO,EAAE,cAAc;KACxC,CAAC,CAAC;IAEH,kBAAkB,CAAC,cAAc,EAAE,CAAC;IAEpC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AAEnD,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,gBAAgB,CAAC,CAAC"}

package/dist/relation.d.ts

@@ -0,0 +1,60 @@
+import type { EntityId, Pair, Relation, RelationTargetId } from "./encoding.js";
+import type { World } from "./world.js";
+/**
+ * Create a pair from a relation and target.
+ *
+ * @param relation - Relation ID
+ * @param target - Target entity, tag, component, or relation
+ * @returns Encoded pair ID that can be used as a component
+ *
+ * @example
+ * const childOf = pair(ChildOf, parent);
+ * addComponent(world, child, childOf);
+ */
+export declare function pair<R extends Relation>(relation: R, target: RelationTargetId): Pair<R>;
+/**
+ * Extract the relation component from a pair.
+ *
+ * @param pairId - Encoded pair ID
+ * @returns The relation ID
+ *
+ * @example
+ * const rel = getPairRelation(pair(ChildOf, parent)); // ChildOf
+ */
+export declare function getPairRelation<R extends Relation>(pairId: Pair<R>): R;
+/**
+ * Extract the target from a pair.
+ *
+ * For entity targets, looks up current generation for weak reference semantics.
+ *
+ * @param world - World instance
+ * @param pairId - Encoded pair ID
+ * @returns Target entity, tag, component, or relation
+ *
+ * @example
+ * const target = getPairTarget(world, pair(ChildOf, parent)); // parent
+ */
+export declare function getPairTarget(world: World, pairId: Pair): RelationTargetId;
+/**
+ * Get all targets for a relation on an entity.
+ *
+ * @param world - World instance
+ * @param entityId - Entity to query
+ * @param relation - Relation to find targets for
+ * @returns Array of target IDs
+ *
+ * @example
+ * const parents = getRelationTargets(world, child, ChildOf);
+ */
+export declare function getRelationTargets(world: World, entityId: EntityId, relation: Relation): RelationTargetId[];
+/**
+ * Clean up all pairs targeting a specific entity when it is destroyed.
+ *
+ * Handles OnDeleteTarget cascade policy by collecting and destroying subjects
+ * that have pairs with the target entity.
+ *
+ * @param world - World instance
+ * @param targetEntity - Entity being destroyed that may be a target
+ */
+export declare function cleanupPairsTargetingEntity(world: World, targetEntity: EntityId): void;
+//# sourceMappingURL=relation.d.ts.map

package/dist/relation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation.d.ts","sourceRoot":"","sources":["../src/relation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAmBhF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC,CAAC,CAAC,CAEvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAItE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAG,gBAAgB,CA2B1E;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,EAAE,CA4B3G;AAMD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,GAAG,IAAI,CAkEtF"}

package/dist/relation.js

@@ -0,0 +1,171 @@
+import { hasComponent } from "./component.js";
+import { COMPONENT_TYPE, ENTITY_TYPE, encodeComponent, encodeEntity, encodePair, encodeRelation, encodeTag, extractId, extractPairRelationId, extractPairTargetId, extractPairTargetType, isPair, RELATIONSHIP_TYPE, TAG_TYPE, } from "./encoding.js";
+import { destroyEntity, ensureEntity, isEntityAlive } from "./entity.js";
+import { OnDeleteTarget, Wildcard } from "./registry.js";
+// ============================================================================
+// Pair Creation and Extraction
+// ============================================================================
+/**
+ * Create a pair from a relation and target.
+ *
+ * @param relation - Relation ID
+ * @param target - Target entity, tag, component, or relation
+ * @returns Encoded pair ID that can be used as a component
+ *
+ * @example
+ * const childOf = pair(ChildOf, parent);
+ * addComponent(world, child, childOf);
+ */
+export function pair(relation, target) {
+    return encodePair(relation, target);
+}
+/**
+ * Extract the relation component from a pair.
+ *
+ * @param pairId - Encoded pair ID
+ * @returns The relation ID
+ *
+ * @example
+ * const rel = getPairRelation(pair(ChildOf, parent)); // ChildOf
+ */
+export function getPairRelation(pairId) {
+    const relationRawId = extractPairRelationId(pairId);
+    return encodeRelation(relationRawId);
+}
+/**
+ * Extract the target from a pair.
+ *
+ * For entity targets, looks up current generation for weak reference semantics.
+ *
+ * @param world - World instance
+ * @param pairId - Encoded pair ID
+ * @returns Target entity, tag, component, or relation
+ *
+ * @example
+ * const target = getPairTarget(world, pair(ChildOf, parent)); // parent
+ */
+export function getPairTarget(world, pairId) {
+    const targetRawId = extractPairTargetId(pairId);
+    const targetType = extractPairTargetType(pairId);
+    switch (targetType) {
+        case ENTITY_TYPE: {
+            // Entity targets use weak reference semantics - look up current generation
+            const generation = world.entities.generations.get(targetRawId);
+            return encodeEntity(targetRawId, generation);
+        }
+        case TAG_TYPE: {
+            return encodeTag(targetRawId);
+        }
+        case COMPONENT_TYPE: {
+            return encodeComponent(targetRawId);
+        }
+        case RELATIONSHIP_TYPE: {
+            return encodeRelation(targetRawId);
+        }
+        default:
+            throw new Error(`Invalid target type in pair: ${targetType}`);
+    }
+}
+// ============================================================================
+// Relation Queries
+// ============================================================================
+/**
+ * Get all targets for a relation on an entity.
+ *
+ * @param world - World instance
+ * @param entityId - Entity to query
+ * @param relation - Relation to find targets for
+ * @returns Array of target IDs
+ *
+ * @example
+ * const parents = getRelationTargets(world, child, ChildOf);
+ */
+export function getRelationTargets(world, entityId, relation) {
+    const meta = ensureEntity(world, entityId);
+    const relationRawId = extractId(relation);
+    const relationWildcardPair = encodePair(relation, Wildcard);
+    const targets = [];
+    for (const typeId of meta.archetype.types) {
+        if (!isPair(typeId)) {
+            continue;
+        }
+        // Skip wildcard pair (pair(relation, Wildcard))
+        if (typeId === relationWildcardPair) {
+            continue;
+        }
+        const pairRelationRawId = extractPairRelationId(typeId);
+        if (pairRelationRawId !== relationRawId) {
+            continue;
+        }
+        targets.push(getPairTarget(world, typeId));
+    }
+    return targets;
+}
+// ============================================================================
+// Cleanup
+// ============================================================================
+/**
+ * Clean up all pairs targeting a specific entity when it is destroyed.
+ *
+ * Handles OnDeleteTarget cascade policy by collecting and destroying subjects
+ * that have pairs with the target entity.
+ *
+ * @param world - World instance
+ * @param targetEntity - Entity being destroyed that may be a target
+ */
+export function cleanupPairsTargetingEntity(world, targetEntity) {
+    // Pairs themselves cannot be targets of other pairs
+    if (isPair(targetEntity)) {
+        return;
+    }
+    // Use wildcard pair to find all archetypes containing pairs with this target
+    const wildcardTargetPair = encodePair(Wildcard, targetEntity);
+    if (!isEntityAlive(world, wildcardTargetPair)) {
+        // Entity was never used as a target, nothing to clean up
+        return;
+    }
+    const wildcardMeta = ensureEntity(world, wildcardTargetPair);
+    // Separate pairs by their OnDeleteTarget policy:
+    // - pairsToRemove: Just destroy the pair entity (default behavior)
+    // - pairsToDelete: Cascade delete to subjects holding the pair
+    const pairsToRemove = new Set([wildcardTargetPair]);
+    const pairsToDelete = new Set();
+    for (const archetype of wildcardMeta.records) {
+        for (const typeId of archetype.types) {
+            if (typeId === wildcardTargetPair || !isPair(typeId) || getPairTarget(world, typeId) !== targetEntity) {
+                continue;
+            }
+            const relation = getPairRelation(typeId);
+            if (hasComponent(world, relation, OnDeleteTarget)) {
+                pairsToDelete.add(typeId);
+            }
+            else {
+                pairsToRemove.add(typeId);
+            }
+        }
+    }
+    // Phase 1: Collect subjects for cascade delete before destroying pairs
+    // Using Set prevents duplicates when entity has multiple cascading pairs
+    const subjectsToDelete = new Set();
+    for (const pairId of pairsToDelete) {
+        const pairMeta = ensureEntity(world, pairId);
+        for (const archetype of pairMeta.records) {
+            for (const entityId of archetype.entities) {
+                subjectsToDelete.add(entityId);
+            }
+        }
+    }
+    // Phase 2: Destroy non-cascading pair entities (removes pairs from subjects)
+    for (const pairId of pairsToRemove) {
+        destroyEntity(world, pairId);
+    }
+    // Phase 3: Destroy cascading pair entities
+    for (const pairId of pairsToDelete) {
+        destroyEntity(world, pairId);
+    }
+    // Phase 4: Delete subjects that had cascading pairs (may trigger recursive cascades)
+    for (const entityId of subjectsToDelete) {
+        destroyEntity(world, entityId);
+    }
+}
+//# sourceMappingURL=relation.js.map

package/dist/relation.js.map

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

package/dist/removal.d.ts

@@ -0,0 +1,27 @@
+import type { EntityId } from "./encoding.js";
+import type { Event } from "./event.js";
+import type { World } from "./world.js";
+/**
+ * Schema for removal events containing the entity that had a component removed.
+ */
+declare const RemovalEventSchema: {
+    entity: import("./schema.js").Schema<number>;
+};
+/**
+ * Gets the removal event for a component, creating it lazily if needed.
+ * @param componentId - Component to track removals for
+ * @returns Event that fires when the component is removed from any entity
+ * @example
+ * for (const { entity } of fetchEvents(world, removed(Health))) {
+ *   playDeathEffect(entity);
+ * }
+ */
+export declare function removed(componentId: EntityId): Event<typeof RemovalEventSchema>;
+/**
+ * Initializes removal tracking by registering observers for component removals.
+ * @param world - World instance to initialize
+ * @internal
+ */
+export declare function initRemovalSystem(world: World): void;
+export {};
+//# sourceMappingURL=removal.d.ts.map

package/dist/removal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"removal.d.ts","sourceRoot":"","sources":["../src/removal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;GAEG;AACH,QAAA,MAAM,kBAAkB;;CAEvB,CAAC;AAeF;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,WAAW,EAAE,QAAQ,GAAG,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAS/E;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAmBpD"}

package/dist/removal.js

@@ -0,0 +1,66 @@
+import { defineEvent, emitEvent } from "./event.js";
+import { registerObserverCallback } from "./observer.js";
+import { Type } from "./schema.js";
+// ============================================================================
+// Removal Event Schema
+// ============================================================================
+/**
+ * Schema for removal events containing the entity that had a component removed.
+ */
+const RemovalEventSchema = {
+    entity: Type.i32(),
+};
+// ============================================================================
+// Global Removal Event Registry
+// ============================================================================
+/**
+ * Maps component IDs to their lazily-created removal events.
+ */
+const removalEvents = new Map();
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Gets the removal event for a component, creating it lazily if needed.
+ * @param componentId - Component to track removals for
+ * @returns Event that fires when the component is removed from any entity
+ * @example
+ * for (const { entity } of fetchEvents(world, removed(Health))) {
+ *   playDeathEffect(entity);
+ * }
+ */
+export function removed(componentId) {
+    let event = removalEvents.get(componentId);
+    if (!event) {
+        event = defineEvent(`Removed<${componentId}>`, RemovalEventSchema);
+        removalEvents.set(componentId, event);
+    }
+    return event;
+}
+// ============================================================================
+// Initialization
+// ============================================================================
+/**
+ * Initializes removal tracking by registering observers for component removals.
+ * @param world - World instance to initialize
+ * @internal
+ */
+export function initRemovalSystem(world) {
+    // Handle explicit component removal via removeComponent()
+    registerObserverCallback(world, "componentRemoved", (componentId, entityId) => {
+        emitEvent(world, removed(componentId), { entity: entityId });
+    });
+    // Handle entity destruction - destroyEntity() doesn't call removeComponent() for each
+    // component, so we emit removal events for all components on the entity here
+    registerObserverCallback(world, "entityDestroyed", (entityId) => {
+        // Observer fires before entity metadata is deleted, so meta is guaranteed to exist
+        const meta = world.entities.byId.get(entityId);
+        for (const componentId of meta.archetype.types) {
+            // Skip the entity's own ID (entities are components in ECS)
+            if (componentId !== entityId) {
+                emitEvent(world, removed(componentId), { entity: entityId });
+            }
+        }
+    });
+}
+//# sourceMappingURL=removal.js.map

package/dist/removal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"removal.js","sourceRoot":"","sources":["../src/removal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAGnC,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,kBAAkB,GAAG;IACzB,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE;CACnB,CAAC;AAEF,+EAA+E;AAC/E,gCAAgC;AAChC,+EAA+E;AAE/E;;GAEG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,EAA8C,CAAC;AAE5E,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,WAAqB;IAC3C,IAAI,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,WAAW,CAAC,WAAW,WAAW,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACnE,aAAa,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAY;IAC5C,0DAA0D;IAC1D,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,EAAE;QAC5E,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,QAAkB,EAAE,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,sFAAsF;IACtF,6EAA6E;IAC7E,wBAAwB,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE;QAC9D,mFAAmF;QACnF,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;QAEhD,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YAC/C,4DAA4D;YAC5D,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;gBAC7B,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,QAAkB,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/resource.d.ts

@@ -0,0 +1,78 @@
+import type { Component, EntityId } from "./encoding.js";
+import type { InferSchema, InferSchemaRecord, SchemaRecord } from "./schema.js";
+import type { World } from "./world.js";
+/**
+ * Adds a global resource (singleton) to the world using the component-on-self pattern.
+ *
+ * Resources are stored by adding the component to itself as an entity. Idempotent if already present.
+ *
+ * @param world - World instance
+ * @param component - Component definition to use as resource
+ * @param data - Initial values for the resource
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * const Time = defineComponent("Time", { delta: Type.f32() });
+ * addResource(world, Time, { delta: 0.016 });
+ * ```
+ */
+export declare function addResource<S extends SchemaRecord>(world: World, component: Component<S>, data: InferSchemaRecord<S>): void;
+/**
+ * Removes a global resource from the world.
+ *
+ * @param world - World instance
+ * @param component - Component definition (acting as resource handle)
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * removeResource(world, Time);
+ * ```
+ */
+export declare function removeResource(world: World, component: EntityId): void;
+/**
+ * Checks if a global resource exists in the world.
+ *
+ * @param world - World instance
+ * @param component - Component definition (acting as resource handle)
+ * @returns True if the resource exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasResource(world, Time)) {
+ *   // Time resource is available
+ * }
+ * ```
+ */
+export declare function hasResource(world: World, component: EntityId): boolean;
+/**
+ * Gets the value of a specific field on a global resource.
+ *
+ * @param world - World instance
+ * @param component - Component definition
+ * @param key - Field name to retrieve
+ * @returns The field value, or undefined if the resource is not present
+ *
+ * @example
+ * ```typescript
+ * const dt = getResourceValue(world, Time, "delta");
+ * ```
+ */
+export declare function getResourceValue<S extends SchemaRecord, K extends keyof S>(world: World, component: Component<S>, key: K): InferSchema<S[K]> | undefined;
+/**
+ * Sets the value of a specific field on a global resource.
+ *
+ * @param world - World instance
+ * @param component - Component definition
+ * @param key - Field name to set
+ * @param value - New value for the field
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * setResourceValue(world, Time, "delta", 0.033);
+ * ```
+ */
+export declare function setResourceValue<S extends SchemaRecord, K extends keyof S>(world: World, component: Component<S>, key: K, value: InferSchema<S[K]>): void;
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,YAAY,EAChD,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACzB,IAAI,CAEN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,GAAG,IAAI,CAEtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,GAAG,OAAO,CAEtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,EACxE,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,GAAG,EAAE,CAAC,GACL,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAE/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,EACxE,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACvB,IAAI,CAEN"}