iris-ecs 0.0.1

package/dist/filters.js

@@ -0,0 +1,202 @@
+import { ensureEntity } from "./entity.js";
+import { fireObserverEvent, registerObserverCallback, unregisterObserverCallback } from "./observer.js";
+// ============================================================================
+// Filter Hashing
+// ============================================================================
+/**
+ * Generates a unique hash string for filter terms.
+ *
+ * @param terms - Filter terms containing include/exclude type arrays
+ * @returns Deterministic hash string (e.g., "+1:5:12|-3:7")
+ *
+ * @example
+ * const hash = hashFilterTerms({ include: [5, 1, 12], exclude: [7, 3] });
+ * // Returns "+1:5:12|-3:7" (sorted for consistency)
+ */
+export function hashFilterTerms(terms) {
+    // Sort to ensure same terms always produce same hash regardless of input order
+    const includeHash = terms.include.toSorted((a, b) => a - b).join(":");
+    const excludeHash = terms.exclude.toSorted((a, b) => a - b).join(":");
+    return `+${includeHash}|-${excludeHash}`;
+}
+// ============================================================================
+// Archetype Matching
+// ============================================================================
+/**
+ * Tests whether an archetype satisfies the given filter terms.
+ *
+ * @param archetype - Archetype to test against filter
+ * @param terms - Filter terms with include/exclude type constraints
+ * @returns True if archetype contains ALL included types and NONE of excluded types
+ *
+ * @example
+ * const matches = matchesFilterTerms(archetype, {
+ *   include: [PositionType, VelocityType],
+ *   exclude: [DisabledType]
+ * });
+ */
+export function matchesFilterTerms(archetype, terms) {
+    // Verify ALL required types are present
+    for (let i = 0; i < terms.include.length; i++) {
+        const typeId = terms.include[i];
+        if (!archetype.typesSet.has(typeId)) {
+            return false;
+        }
+    }
+    // Verify NONE of excluded types are present
+    for (let i = 0; i < terms.exclude.length; i++) {
+        const typeId = terms.exclude[i];
+        if (archetype.typesSet.has(typeId)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Finds all archetypes matching filter terms using rarest-type optimization.
+ *
+ * Uses the "rarest type first" strategy: starts with the type that appears in
+ * the fewest archetypes, then filters that smaller set. This minimizes the
+ * number of archetypes we need to check.
+ *
+ * @param world - World instance containing archetype registry
+ * @param terms - Filter terms with include/exclude type constraints
+ * @returns Array of archetypes that match all filter criteria
+ *
+ * @example
+ * const archetypes = findMatchingArchetypes(world, {
+ *   include: [PositionType, VelocityType],
+ *   exclude: []
+ * });
+ */
+export function findMatchingArchetypes(world, terms) {
+    // Empty include list is a degenerate case - return no matches
+    if (terms.include.length === 0) {
+        return [];
+    }
+    // Find the rarest type (appears in fewest archetypes) for optimal iteration
+    let rarestId = terms.include[0];
+    let minCount = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < terms.include.length; i++) {
+        const typeId = terms.include[i];
+        const meta = ensureEntity(world, typeId);
+        const count = meta.records.length;
+        if (count === 0) {
+            // If any required type has zero archetypes, no matches are possible
+            return [];
+        }
+        if (count < minCount) {
+            rarestId = typeId;
+            minCount = count;
+        }
+    }
+    // Only iterate archetypes containing the rarest type, then filter further
+    const rarestMeta = ensureEntity(world, rarestId);
+    const archetypes = rarestMeta.records;
+    const matches = [];
+    for (let a = 0; a < archetypes.length; a++) {
+        const archetype = archetypes[a];
+        if (matchesFilterTerms(archetype, terms)) {
+            matches.push(archetype);
+        }
+    }
+    return matches;
+}
+// ============================================================================
+// Filter Registry
+// ============================================================================
+/**
+ * Destroys a filter and cleans up its observer callbacks.
+ * Called when a filter's archetype cache becomes empty.
+ */
+function destroyFilter(world, filterId) {
+    const filter = world.filters.byId.get(filterId);
+    // Unregister callbacks to prevent memory leaks and stale references
+    unregisterObserverCallback(world, "archetypeCreated", filter.onArchetypeCreate);
+    unregisterObserverCallback(world, "archetypeDestroyed", filter.onArchetypeDelete);
+    fireObserverEvent(world, "filterDestroyed", filter);
+    world.filters.byId.delete(filterId);
+}
+/**
+ * Gets or creates a filter with observer-based cache invalidation.
+ *
+ * Filters are cached by their terms hash. When created, observers are registered
+ * to automatically update the cached archetype list as archetypes are created
+ * or destroyed.
+ *
+ * @param world - World instance containing filter registry
+ * @param terms - Filter terms defining which archetypes to match
+ * @returns FilterMeta with cached matching archetypes
+ *
+ * @example
+ * const filter = ensureFilter(world, {
+ *   include: [PositionType, VelocityType],
+ *   exclude: [DisabledType]
+ * });
+ * // filter.archetypes contains all matching archetypes
+ */
+export function ensureFilter(world, terms) {
+    const filterId = hashFilterTerms(terms);
+    let filterMeta = world.filters.byId.get(filterId);
+    if (!filterMeta) {
+        // Create new filter with observer callbacks that close over terms and filterMeta
+        filterMeta = {
+            terms,
+            archetypes: findMatchingArchetypes(world, terms),
+            // Called when a new archetype is created - add to cache if it matches
+            onArchetypeCreate: (archetype) => {
+                if (!matchesFilterTerms(archetype, terms)) {
+                    return;
+                }
+                filterMeta.archetypes.push(archetype);
+            },
+            // Called when an archetype is destroyed - remove from cache, cleanup if empty
+            onArchetypeDelete: (archetype) => {
+                const idx = filterMeta.archetypes.indexOf(archetype);
+                if (idx !== -1) {
+                    filterMeta.archetypes.splice(idx, 1);
+                }
+                // Auto-cleanup: destroy filter when it has no matching archetypes
+                if (filterMeta.archetypes.length === 0) {
+                    destroyFilter(world, filterId);
+                }
+            },
+        };
+        world.filters.byId.set(filterId, filterMeta);
+        // Register observers to keep archetype cache in sync
+        registerObserverCallback(world, "archetypeCreated", filterMeta.onArchetypeCreate);
+        registerObserverCallback(world, "archetypeDestroyed", filterMeta.onArchetypeDelete);
+        fireObserverEvent(world, "filterCreated", filterMeta);
+    }
+    return filterMeta;
+}
+// ============================================================================
+// Filter Iteration
+// ============================================================================
+/**
+ * Iterates all entities matching a filter in reverse order.
+ *
+ * Reverse iteration allows safe entity deletion during iteration without
+ * skipping entities or invalidating indices.
+ *
+ * @param filter - Filter metadata containing cached matching archetypes
+ * @returns Generator yielding entity IDs from all matching archetypes
+ *
+ * @example
+ * for (const entity of iterateFilterEntities(filter)) {
+ *   // Safe to delete entity here due to reverse iteration
+ *   destroyEntity(world, entity);
+ * }
+ */
+export function* iterateFilterEntities(filter) {
+    const archetypes = filter.archetypes;
+    for (let a = 0; a < archetypes.length; a++) {
+        const archetype = archetypes[a];
+        const entities = archetype.entities;
+        // Reverse iteration enables safe deletion during traversal
+        for (let i = entities.length - 1; i >= 0; i--) {
+            yield entities[i];
+        }
+    }
+}
+//# sourceMappingURL=filters.js.map

package/dist/filters.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export { createWorld, resetWorld } from "./world.js";
+export { createEntity, destroyEntity, isEntityAlive } from "./entity.js";
+export { addComponent, emitComponentChanged, getComponentValue, hasComponent, removeComponent, setComponentValue, } from "./component.js";
+export { defineComponent, defineRelation, defineTag, Wildcard } from "./registry.js";
+export { getPairRelation, getPairTarget, getRelationTargets, pair } from "./relation.js";
+export { addResource, getResourceValue, hasResource, removeResource, setResourceValue, } from "./resource.js";
+export { getName, lookupByName, Name, removeName, setName } from "./name.js";
+export { added, changed, destroyQuery, ensureQuery, fetchEntities, fetchEntitiesWithQuery, fetchFirstEntity, not, } from "./query.js";
+export { addSystem, buildSchedule, executeSchedule, executeScheduleAsync, } from "./scheduler.js";
+export type { ActionGetter, ActionInitializer, Actions } from "./actions.js";
+export type { Component, Entity, EntityId, Pair, Relation, RelationTargetId, Tag } from "./encoding.js";
+export type { Event, EventSchema } from "./event.js";
+export type { FilterTerms } from "./filters.js";
+export type { AddedModifier, ChangedModifier, ModifierType, NotModifier, QueryMeta, QueryModifier } from "./query.js";
+export type { ScheduleId, SystemMeta, SystemOptions, SystemRunner } from "./scheduler.js";
+export type { InferSchemaRecord, Schema, SchemaRecord } from "./schema.js";
+export type { World } from "./world.js";
+export { clearEvents, countEvents, defineEvent, EVENT_EXPIRY_TICKS, emitEvent, fetchEvents, fetchLastEvent, hasEvents, } from "./event.js";
+export { removed } from "./removal.js";
+export type { EventPayloads, EventType, Observer, ObserverMeta } from "./observer.js";
+export { registerObserverCallback, unregisterObserverCallback } from "./observer.js";
+export { Type } from "./schema.js";
+export { defineActions } from "./actions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAMrD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMzE,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAMrF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAMzF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAM7E,OAAO,EACL,KAAK,EACL,OAAO,EACP,YAAY,EACZ,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,GAAG,GACJ,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAMxB,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACxG,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtH,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,cAAc,EACd,SAAS,GACV,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAMvC,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAMrF,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAMnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,54 @@
+// ============================================================================
+// World Operations
+// ============================================================================
+export { createWorld, resetWorld } from "./world.js";
+// ============================================================================
+// Entity Operations
+// ============================================================================
+export { createEntity, destroyEntity, isEntityAlive } from "./entity.js";
+// ============================================================================
+// Component Operations
+// ============================================================================
+export { addComponent, emitComponentChanged, getComponentValue, hasComponent, removeComponent, setComponentValue, } from "./component.js";
+// ============================================================================
+// Registry Operations
+// ============================================================================
+export { defineComponent, defineRelation, defineTag, Wildcard } from "./registry.js";
+// ============================================================================
+// Relation Operations
+// ============================================================================
+export { getPairRelation, getPairTarget, getRelationTargets, pair } from "./relation.js";
+// ============================================================================
+// Resource Operations
+// ============================================================================
+export { addResource, getResourceValue, hasResource, removeResource, setResourceValue, } from "./resource.js";
+// ============================================================================
+// Name System
+// ============================================================================
+export { getName, lookupByName, Name, removeName, setName } from "./name.js";
+// ============================================================================
+// Query Operations
+// ============================================================================
+export { added, changed, destroyQuery, ensureQuery, fetchEntities, fetchEntitiesWithQuery, fetchFirstEntity, not, } from "./query.js";
+// ============================================================================
+// System Operations
+// ============================================================================
+export { addSystem, buildSchedule, executeSchedule, executeScheduleAsync, } from "./scheduler.js";
+// ============================================================================
+// Event System
+// ============================================================================
+export { clearEvents, countEvents, defineEvent, EVENT_EXPIRY_TICKS, emitEvent, fetchEvents, fetchLastEvent, hasEvents, } from "./event.js";
+// ============================================================================
+// Removal Detection
+// ============================================================================
+export { removed } from "./removal.js";
+export { registerObserverCallback, unregisterObserverCallback } from "./observer.js";
+// ============================================================================
+// Schema Factories
+// ============================================================================
+export { Type } from "./schema.js";
+// ============================================================================
+// Actions
+// ============================================================================
+export { defineActions } from "./actions.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAErD,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzE,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAErF,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAEzF,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7E,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,OAAO,EACL,KAAK,EACL,OAAO,EACP,YAAY,EACZ,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,GAAG,GACJ,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAexB,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,cAAc,EACd,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAOvC,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAErF,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/name.d.ts

@@ -0,0 +1,70 @@
+import type { EntityId } from "./encoding.js";
+import type { World } from "./world.js";
+/**
+ * Name component for entity identification.
+ *
+ * Stores a single string value that must be unique within the world.
+ *
+ * @example
+ * ```typescript
+ * addComponent(world, entity, Name, { value: "player-1" });
+ * const name = getComponentValue(world, entity, Name, "value");
+ * ```
+ */
+export declare const Name: import("./encoding.js").Component<{
+    value: import("./schema.js").Schema<string>;
+}>;
+/**
+ * Initializes the name system for a world by setting up the dual-index registry
+ * and observer callbacks that keep name mappings synchronized with entity lifecycle.
+ * Called automatically by createWorld().
+ * @internal
+ */
+export declare function initNameSystem(world: World): void;
+/**
+ * Gets the name of an entity.
+ * @param world - World instance
+ * @param entityId - Entity to get name from
+ * @returns Entity name or undefined if not named
+ * @example
+ * ```ts
+ * const name = getName(world, entity);
+ * ```
+ */
+export declare function getName(world: World, entityId: EntityId): string | undefined;
+/**
+ * Sets or updates the name of an entity.
+ * @param world - World instance
+ * @param entityId - Entity to name
+ * @param name - Name to assign (must be unique and non-empty)
+ * @throws Error if name is empty or already exists
+ * @example
+ * ```ts
+ * setName(world, player, "player-1");
+ * ```
+ */
+export declare function setName(world: World, entityId: EntityId, name: string): void;
+/**
+ * Removes the name from an entity.
+ * @param world - World instance
+ * @param entityId - Entity to remove name from
+ * @example
+ * ```ts
+ * removeName(world, entity);
+ * ```
+ */
+export declare function removeName(world: World, entityId: EntityId): void;
+/**
+ * Looks up an entity by name, optionally validating required components.
+ * @param world - World instance
+ * @param name - Name to look up
+ * @param components - Optional components to validate presence
+ * @returns Entity ID or undefined if not found or missing required components
+ * @example
+ * ```ts
+ * const player = lookupByName(world, "player-1");
+ * const player = lookupByName(world, "player-1", Position, Health);
+ * ```
+ */
+export declare function lookupByName(world: World, name: string, ...components: EntityId[]): EntityId | undefined;
+//# sourceMappingURL=name.d.ts.map

package/dist/name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.d.ts","sourceRoot":"","sources":["../src/name.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAK9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI;;EAAoD,CAAC;AActE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CA0EjD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAO5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAMjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,QAAQ,EAAE,GAAG,QAAQ,GAAG,SAAS,CAexG"}

package/dist/name.js

@@ -0,0 +1,172 @@
+import { addComponent, getComponentValue, hasComponent, removeComponent, setComponentValue } from "./component.js";
+import { registerObserverCallback } from "./observer.js";
+import { defineComponent } from "./registry.js";
+import { addResource, getResourceValue } from "./resource.js";
+import { Type } from "./schema.js";
+// ============================================================================
+// Component Definitions
+// ============================================================================
+/**
+ * Name component for entity identification.
+ *
+ * Stores a single string value that must be unique within the world.
+ *
+ * @example
+ * ```typescript
+ * addComponent(world, entity, Name, { value: "player-1" });
+ * const name = getComponentValue(world, entity, Name, "value");
+ * ```
+ */
+export const Name = defineComponent("Name", { value: Type.string() });
+/**
+ * Dual-index registry for O(1) lookups in both directions. Stored as a world resource.
+ */
+const NameRegistry = defineComponent("NameRegistry", {
+    nameToEntity: Type.object(),
+    entityToName: Type.object(),
+});
+// ============================================================================
+// Initialization
+// ============================================================================
+/**
+ * Initializes the name system for a world by setting up the dual-index registry
+ * and observer callbacks that keep name mappings synchronized with entity lifecycle.
+ * Called automatically by createWorld().
+ * @internal
+ */
+export function initNameSystem(world) {
+    addResource(world, NameRegistry, {
+        nameToEntity: new Map(),
+        entityToName: new Map(),
+    });
+    // Clean up registry when Name component is removed from an entity
+    registerObserverCallback(world, "componentRemoved", (componentId, entityId) => {
+        if (componentId !== Name) {
+            return;
+        }
+        const nameToEntity = getResourceValue(world, NameRegistry, "nameToEntity");
+        const entityToName = getResourceValue(world, NameRegistry, "entityToName");
+        const name = entityToName.get(entityId);
+        nameToEntity.delete(name);
+        entityToName.delete(entityId);
+    });
+    // Sync registry when Name component is added or its value changes.
+    // Validates uniqueness and non-empty constraints before updating mappings.
+    registerObserverCallback(world, "componentChanged", (componentId, entityId) => {
+        if (componentId !== Name) {
+            return;
+        }
+        const nameToEntity = getResourceValue(world, NameRegistry, "nameToEntity");
+        const entityToName = getResourceValue(world, NameRegistry, "entityToName");
+        const previous = entityToName.get(entityId);
+        const current = getComponentValue(world, entityId, Name, "value");
+        if (previous === current) {
+            return;
+        }
+        if (!current) {
+            throw new Error("Name cannot be empty");
+        }
+        if (nameToEntity.has(current)) {
+            throw new Error(`Name "${current}" already exists`);
+        }
+        // Remove old mapping if renaming an entity
+        if (previous !== undefined) {
+            nameToEntity.delete(previous);
+        }
+        nameToEntity.set(current, entityId);
+        entityToName.set(entityId, current);
+    });
+    // Clean up registry when a named entity is destroyed
+    registerObserverCallback(world, "entityDestroyed", (entityId) => {
+        const nameToEntity = getResourceValue(world, NameRegistry, "nameToEntity");
+        const entityToName = getResourceValue(world, NameRegistry, "entityToName");
+        const name = entityToName.get(entityId);
+        if (name === undefined) {
+            return;
+        }
+        nameToEntity.delete(name);
+        entityToName.delete(entityId);
+    });
+    // Recreate fresh registry when world is reset
+    registerObserverCallback(world, "worldReset", () => {
+        addResource(world, NameRegistry, {
+            nameToEntity: new Map(),
+            entityToName: new Map(),
+        });
+    });
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Gets the name of an entity.
+ * @param world - World instance
+ * @param entityId - Entity to get name from
+ * @returns Entity name or undefined if not named
+ * @example
+ * ```ts
+ * const name = getName(world, entity);
+ * ```
+ */
+export function getName(world, entityId) {
+    return getComponentValue(world, entityId, Name, "value");
+}
+/**
+ * Sets or updates the name of an entity.
+ * @param world - World instance
+ * @param entityId - Entity to name
+ * @param name - Name to assign (must be unique and non-empty)
+ * @throws Error if name is empty or already exists
+ * @example
+ * ```ts
+ * setName(world, player, "player-1");
+ * ```
+ */
+export function setName(world, entityId, name) {
+    if (!hasComponent(world, entityId, Name)) {
+        addComponent(world, entityId, Name, { value: name });
+        return;
+    }
+    setComponentValue(world, entityId, Name, "value", name);
+}
+/**
+ * Removes the name from an entity.
+ * @param world - World instance
+ * @param entityId - Entity to remove name from
+ * @example
+ * ```ts
+ * removeName(world, entity);
+ * ```
+ */
+export function removeName(world, entityId) {
+    if (!hasComponent(world, entityId, Name)) {
+        return;
+    }
+    removeComponent(world, entityId, Name);
+}
+/**
+ * Looks up an entity by name, optionally validating required components.
+ * @param world - World instance
+ * @param name - Name to look up
+ * @param components - Optional components to validate presence
+ * @returns Entity ID or undefined if not found or missing required components
+ * @example
+ * ```ts
+ * const player = lookupByName(world, "player-1");
+ * const player = lookupByName(world, "player-1", Position, Health);
+ * ```
+ */
+export function lookupByName(world, name, ...components) {
+    const nameToEntity = getResourceValue(world, NameRegistry, "nameToEntity");
+    const entityId = nameToEntity.get(name);
+    if (!entityId) {
+        return;
+    }
+    for (const component of components) {
+        if (!hasComponent(world, entityId, component)) {
+            return;
+        }
+    }
+    return entityId;
+}
+//# sourceMappingURL=name.js.map

package/dist/name.js.map

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

package/dist/observer.d.ts

@@ -0,0 +1,83 @@
+import type { Archetype } from "./archetype.js";
+import type { Entity, EntityId } from "./encoding.js";
+import type { FilterMeta } from "./filters.js";
+import type { World } from "./world.js";
+/**
+ * Event payload type mapping.
+ *
+ * Maps event names to argument tuples for type-safe observer callbacks.
+ */
+export type EventPayloads = {
+    archetypeCreated: [archetype: Archetype];
+    archetypeDestroyed: [archetype: Archetype];
+    filterCreated: [filter: FilterMeta];
+    filterDestroyed: [filter: FilterMeta];
+    entityCreated: [entityId: Entity];
+    entityDestroyed: [entityId: EntityId];
+    componentAdded: [componentId: EntityId, entityId: EntityId];
+    componentRemoved: [componentId: EntityId, entityId: EntityId];
+    componentChanged: [componentId: EntityId, entityId: EntityId];
+    worldReset: [world: World];
+};
+/**
+ * Event type keys.
+ */
+export type EventType = keyof EventPayloads;
+/**
+ * Observer callback function.
+ */
+export type Observer<T extends EventType> = (...args: EventPayloads[T]) => void;
+/**
+ * Observer metadata for single event type.
+ */
+export type ObserverMeta<T extends EventType> = {
+    /**
+     * Callbacks fired on event.
+     */
+    callbacks: Observer<T>[];
+};
+/**
+ * Registers a callback to be invoked when an event of the specified type is fired.
+ *
+ * @param world - The world instance containing observer state
+ * @param eventType - The event type to listen for
+ * @param callback - Function to invoke when the event fires
+ *
+ * @example
+ * ```ts
+ * registerObserverCallback(world, "onAdd", (entity, componentId, value) => {
+ *   console.log(`Component ${componentId} added to entity ${entity}`);
+ * });
+ * ```
+ */
+export declare function registerObserverCallback<T extends EventType>(world: World, eventType: T, callback: Observer<T>): void;
+/**
+ * Removes a previously registered callback for the specified event type.
+ *
+ * @param world - The world instance containing observer state
+ * @param eventType - The event type to stop listening for
+ * @param callback - The exact callback reference to remove
+ *
+ * @example
+ * ```ts
+ * const handler = (entity, componentId, value) => { ... };
+ * registerObserverCallback(world, "onAdd", handler);
+ * // Later:
+ * unregisterObserverCallback(world, "onAdd", handler);
+ * ```
+ */
+export declare function unregisterObserverCallback<T extends EventType>(world: World, eventType: T, callback: Observer<T>): void;
+/**
+ * Dispatches an event to all registered callbacks for the specified event type.
+ *
+ * @param world - The world instance containing observer state
+ * @param eventType - The event type to dispatch
+ * @param args - Arguments to pass to each callback (varies by event type)
+ *
+ * @example
+ * ```ts
+ * fireObserverEvent(world, "onAdd", entity, componentId, componentValue);
+ * ```
+ */
+export declare function fireObserverEvent<T extends EventType>(world: World, eventType: T, ...args: EventPayloads[T]): void;
+//# sourceMappingURL=observer.d.ts.map

package/dist/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../src/observer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,gBAAgB,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACzC,kBAAkB,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC3C,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,eAAe,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClC,eAAe,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACtC,cAAc,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC5D,gBAAgB,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9D,gBAAgB,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9D,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,GAAG,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEhF;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,IAAI;IAC9C;;OAEG;IACH,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;CAC1B,CAAC;AAMF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAErH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,SAAS,EAC5D,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GACpB,IAAI,CAON;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAOlH"}