iris-ecs 0.0.1

package/dist/encoding.js

@@ -0,0 +1,215 @@
+// ============================================================================
+// Type Constants
+// ============================================================================
+/**
+ * Entity type constant (0x1).
+ */
+export const ENTITY_TYPE = 0x1;
+/**
+ * Tag type constant (0x2).
+ */
+export const TAG_TYPE = 0x2;
+/**
+ * Component type constant (0x3).
+ */
+export const COMPONENT_TYPE = 0x3;
+/**
+ * Relationship type constant (0x4).
+ */
+export const RELATIONSHIP_TYPE = 0x4;
+// ============================================================================
+// ID Limits
+// ============================================================================
+/**
+ * Maximum raw ID for entities, components, and tags (20-bit).
+ */
+export const ID_MASK_20 = 0xfffff;
+/**
+ * Maximum raw ID for relationships (8-bit).
+ */
+export const ID_MASK_8 = 0xff;
+// ============================================================================
+// Common Bit Positions
+// ============================================================================
+/**
+ * Pair flag bit position (bit 31).
+ */
+export const PAIR_FLAG_SHIFT = 31;
+/**
+ * Type bits position (bits 30-28).
+ */
+export const TYPE_SHIFT = 28;
+/**
+ * Type mask (3 bits).
+ */
+export const TYPE_MASK = 0x7;
+// ============================================================================
+// Bit Field Constants (Internal)
+// ============================================================================
+const ID_SHIFT_20 = 0;
+const ID_SHIFT_8 = 0;
+const META_SHIFT_8 = 20;
+const META_MASK_8 = 0xff;
+const META_SHIFT_20 = 8;
+const META_MASK_20 = 0xfffff;
+// ============================================================================
+// Encoding Functions
+// ============================================================================
+/**
+ * Type-aware encoding using type-specific bit layouts.
+ */
+function encode(type, rawId, meta) {
+    switch (type) {
+        case RELATIONSHIP_TYPE:
+            // Relationship: [0][TYPE][META_20][ID_8]
+            return (0 << PAIR_FLAG_SHIFT) | (type << TYPE_SHIFT) | (meta << META_SHIFT_20) | (rawId << ID_SHIFT_8);
+        case ENTITY_TYPE:
+        case TAG_TYPE:
+        case COMPONENT_TYPE:
+        default:
+            // Entity/Component/Tag: [0][TYPE][META_8][ID_20]
+            return (0 << PAIR_FLAG_SHIFT) | (type << TYPE_SHIFT) | (meta << META_SHIFT_8) | (rawId << ID_SHIFT_20);
+    }
+}
+/**
+ * Encode entity ID from raw ID and generation.
+ *
+ * @param rawId - Raw entity ID (0 to 1,048,575)
+ * @param generation - Generation number (0 to 255)
+ * @returns Encoded 32-bit entity ID
+ */
+export function encodeEntity(rawId, generation) {
+    return encode(ENTITY_TYPE, rawId, generation);
+}
+/**
+ * Encode component ID from raw ID.
+ *
+ * @param rawId - Raw component ID (0 to 1,048,575)
+ * @returns Encoded 32-bit component ID
+ */
+export function encodeComponent(rawId) {
+    return encode(COMPONENT_TYPE, rawId, 0);
+}
+/**
+ * Encode tag ID from raw ID.
+ *
+ * @param rawId - Raw tag ID (0 to 1,048,575)
+ * @returns Encoded 32-bit tag ID
+ */
+export function encodeTag(rawId) {
+    return encode(TAG_TYPE, rawId, 0);
+}
+/**
+ * Encode relation ID from raw ID.
+ *
+ * @param rawId - Raw relation ID (0 to 255)
+ * @returns Encoded 32-bit relation ID
+ */
+export function encodeRelation(rawId) {
+    return encode(RELATIONSHIP_TYPE, rawId, 0);
+}
+/**
+ * Encode a pair from relation and target.
+ *
+ * @param relation - Relation ID
+ * @param target - Target ID (entity, tag, component, or relation)
+ * @returns Encoded pair ID
+ */
+export function encodePair(relation, target) {
+    const relationRawId = extractId(relation);
+    const targetType = extractType(target);
+    const targetRawId = extractId(target);
+    return ((1 << PAIR_FLAG_SHIFT) |
+        (targetType << TYPE_SHIFT) |
+        (targetRawId << META_SHIFT_20) |
+        relationRawId);
+}
+// ============================================================================
+// Decoding Functions
+// ============================================================================
+/**
+ * Extract type bits from encoded ID.
+ *
+ * @param id - Encoded ID
+ * @returns Type bits (0x0 - 0x7)
+ */
+export function extractType(id) {
+    return (id >>> TYPE_SHIFT) & TYPE_MASK;
+}
+/**
+ * Extract raw ID from encoded ID (type-aware).
+ *
+ * @param id - Encoded ID (any non-pair type)
+ * @returns Raw ID (20-bit for entities/components/tags, 8-bit for relationships)
+ */
+export function extractId(id) {
+    const type = extractType(id);
+    switch (type) {
+        case RELATIONSHIP_TYPE:
+            // Relationship: 8-bit ID at bits 7-0
+            return (id >>> ID_SHIFT_8) & ID_MASK_8;
+        case ENTITY_TYPE:
+        case TAG_TYPE:
+        case COMPONENT_TYPE:
+        default:
+            // Entity/Component/Tag: 20-bit ID at bits 19-0
+            return (id >>> ID_SHIFT_20) & ID_MASK_20;
+    }
+}
+/**
+ * Extract meta field from encoded ID (type-aware).
+ *
+ * @param id - Encoded ID (any non-pair type)
+ * @returns Meta value (generation for entities, 0 for components/tags/relationships)
+ */
+export function extractMeta(id) {
+    const type = extractType(id);
+    switch (type) {
+        case RELATIONSHIP_TYPE:
+            // Relationship: 20-bit meta at bits 27-8 (unused, always 0)
+            return (id >>> META_SHIFT_20) & META_MASK_20;
+        case ENTITY_TYPE:
+        case TAG_TYPE:
+        case COMPONENT_TYPE:
+        default:
+            // Entity/Component/Tag: 8-bit meta at bits 27-20
+            return (id >>> META_SHIFT_8) & META_MASK_8;
+    }
+}
+/**
+ * Check if ID is a pair.
+ *
+ * @param id - Encoded ID
+ * @returns True if bit 31 is set, false otherwise
+ */
+export function isPair(id) {
+    return id >>> PAIR_FLAG_SHIFT === 1;
+}
+/**
+ * Extract relation raw ID from pair.
+ *
+ * @param pairId - Encoded pair ID
+ * @returns Relation raw ID (8-bit)
+ */
+export function extractPairRelationId(pairId) {
+    return pairId & ID_MASK_8;
+}
+/**
+ * Extract target raw ID from pair.
+ *
+ * @param pairId - Encoded pair ID
+ * @returns Target raw ID (20-bit)
+ */
+export function extractPairTargetId(pairId) {
+    return (pairId >>> META_SHIFT_20) & ID_MASK_20;
+}
+/**
+ * Extract target type from pair.
+ *
+ * @param pairId - Encoded pair ID
+ * @returns Target type bits (3-bit)
+ */
+export function extractPairTargetType(pairId) {
+    return (pairId >>> TYPE_SHIFT) & TYPE_MASK;
+}
+//# sourceMappingURL=encoding.js.map

package/dist/encoding.js.map

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

package/dist/entity.d.ts

@@ -0,0 +1,129 @@
+import type { Archetype } from "./archetype.js";
+import type { Entity, EntityId } from "./encoding.js";
+import type { SchemaRecord } from "./schema.js";
+import type { World } from "./world.js";
+/**
+ * Entity metadata.
+ *
+ * Stores entity's current location (archetype + row) and component records.
+ */
+export type EntityMeta = {
+    /**
+     * Current archetype (direct reference).
+     */
+    archetype: Archetype;
+    /**
+     * Row index in archetype.entities.
+     */
+    row: number;
+    /**
+     * Component records: which archetypes contain this entity as a component.
+     */
+    records: Archetype[];
+    /**
+     * Schema when this entity is used as a component (undefined for regular entities).
+     */
+    schema?: SchemaRecord;
+    /**
+     * Cycle protection flag during cascade delete.
+     */
+    destroying?: boolean;
+};
+/**
+ * Ensures entity exists in world, auto-registering components/tags/relations if needed.
+ *
+ * @param world - World instance
+ * @param entityId - Entity or component ID
+ * @returns Entity metadata
+ * @throws {Error} If entity not registered (ENTITY_TYPE) or unknown type
+ *
+ * @example
+ * ```typescript
+ * const meta = ensureEntity(world, Position);
+ * console.log(meta.archetype);
+ * ```
+ */
+export declare function ensureEntity(world: World, entityId: EntityId): EntityMeta;
+/**
+ * Creates a new entity in the world.
+ *
+ * @param world - World instance
+ * @returns Encoded entity ID
+ * @throws {RangeError} If entity limit (1,048,576) exceeded
+ *
+ * @example
+ * ```typescript
+ * const entity = createEntity(world);
+ * addComponent(world, entity, Position, { x: 0, y: 0 });
+ * ```
+ */
+export declare function createEntity(world: World): Entity;
+/**
+ * Destroys an entity and recycles its ID for reuse.
+ *
+ * @param world - World instance
+ * @param entityId - Entity to destroy
+ *
+ * @example
+ * ```typescript
+ * destroyEntity(world, entity);
+ * isEntityAlive(world, entity); // false
+ * ```
+ */
+export declare function destroyEntity(world: World, entityId: EntityId): void;
+/**
+ * Checks if an entity is currently alive in the world.
+ *
+ * @param world - World instance
+ * @param entity - Entity ID to check
+ * @returns True if entity exists and is alive
+ *
+ * @example
+ * ```typescript
+ * isEntityAlive(world, entity); // true
+ * destroyEntity(world, entity);
+ * isEntityAlive(world, entity); // false
+ * ```
+ */
+export declare function isEntityAlive(world: World, entity: EntityId): boolean;
+/**
+ * Moves entity to a different archetype, transferring component data.
+ *
+ * @param world - World instance
+ * @param entityId - Entity to move
+ * @param toArchetype - Target archetype
+ *
+ * @example
+ * ```typescript
+ * const archetype = getOrCreateArchetype(world, [Position, Velocity]);
+ * moveEntityToArchetype(world, entity, archetype);
+ * ```
+ */
+export declare function moveEntityToArchetype(world: World, entityId: EntityId, toArchetype: Archetype): void;
+/**
+ * Registers archetype in entity records for all its component types.
+ *
+ * @param world - World instance
+ * @param archetype - Archetype to register
+ *
+ * @example
+ * ```typescript
+ * const archetype = createArchetype([Position, Velocity]);
+ * addEntityRecord(world, archetype);
+ * ```
+ */
+export declare function addEntityRecord(world: World, archetype: Archetype): void;
+/**
+ * Removes archetype from entity records for all its component types.
+ *
+ * @param world - World instance
+ * @param archetype - Archetype to unregister
+ *
+ * @example
+ * ```typescript
+ * removeEntityRecord(world, archetype);
+ * destroyArchetype(archetype);
+ * ```
+ */
+export declare function removeEntityRecord(world: World, archetype: Archetype): void;
+//# sourceMappingURL=entity.d.ts.map

package/dist/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,KAAK,EAAa,MAAM,EAAE,QAAQ,EAAY,MAAM,eAAe,CAAC;AAiB3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,SAAS,EAAE,SAAS,CAAC;IAErB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,OAAO,EAAE,SAAS,EAAE,CAAC;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AA4CF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAkDzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAOjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA0CpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAErE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,GAAG,IAAI,CAmBpG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAOxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAU3E"}

package/dist/entity.js

@@ -0,0 +1,243 @@
+import { addEntityToArchetype, removeEntityFromArchetypeByRow, transferEntityToArchetypeByRow } from "./archetype.js";
+import { addComponent, cascadeRemoveComponent } from "./component.js";
+import { COMPONENT_TYPE, ENTITY_TYPE, encodeEntity, extractId, extractMeta, extractType, ID_MASK_8, ID_MASK_20, isPair, RELATIONSHIP_TYPE, TAG_TYPE, } from "./encoding.js";
+import { fireObserverEvent } from "./observer.js";
+import { Exclusive, OnDeleteTarget } from "./registry.js";
+import { cleanupPairsTargetingEntity, getPairRelation } from "./relation.js";
+/**
+ * Allocates entity ID, preferring recycled IDs from freelist.
+ * Recycled IDs retain their generation for stale reference detection.
+ */
+function allocateEntityId(world) {
+    const rawId = world.entities.freeIds.pop();
+    if (rawId !== undefined) {
+        // Reuse recycled ID with its current generation
+        const generation = world.entities.generations.get(rawId);
+        return encodeEntity(rawId, generation);
+    }
+    const newRawId = world.entities.nextId++;
+    if (newRawId > ID_MASK_20) {
+        throw new RangeError(`Entity ID limit exceeded: cannot allocate ID ${newRawId} (max ${ID_MASK_20})`);
+    }
+    world.entities.generations.set(newRawId, 0);
+    return encodeEntity(newRawId, 0);
+}
+/**
+ * Registers entity in root archetype and creates its metadata.
+ * Schema is stored when entity is used as a component type.
+ */
+function registerEntity(world, entityId, schema) {
+    const rootArchetype = world.archetypes.root;
+    const row = addEntityToArchetype(rootArchetype, entityId);
+    const meta = {
+        archetype: rootArchetype,
+        row,
+        records: [],
+        schema,
+    };
+    world.entities.byId.set(entityId, meta);
+    return meta;
+}
+/**
+ * Ensures entity exists in world, auto-registering components/tags/relations if needed.
+ *
+ * @param world - World instance
+ * @param entityId - Entity or component ID
+ * @returns Entity metadata
+ * @throws {Error} If entity not registered (ENTITY_TYPE) or unknown type
+ *
+ * @example
+ * ```typescript
+ * const meta = ensureEntity(world, Position);
+ * console.log(meta.archetype);
+ * ```
+ */
+export function ensureEntity(world, entityId) {
+    const meta = world.entities.byId.get(entityId);
+    if (meta) {
+        return meta;
+    }
+    // Pairs inherit schema from their relation component
+    if (isPair(entityId)) {
+        const relation = getPairRelation(entityId);
+        const relationMeta = ensureEntity(world, relation);
+        return registerEntity(world, entityId, relationMeta.schema);
+    }
+    const type = extractType(entityId);
+    switch (type) {
+        case TAG_TYPE: {
+            return registerEntity(world, entityId);
+        }
+        case COMPONENT_TYPE: {
+            const componentMeta = world.components.byId.get(entityId);
+            return registerEntity(world, entityId, componentMeta?.schema);
+        }
+        case RELATIONSHIP_TYPE: {
+            const relationMeta = world.components.byId.get(entityId);
+            const meta = registerEntity(world, entityId, relationMeta?.schema);
+            // Materialize relation traits as queryable components
+            if (relationMeta?.exclusive) {
+                addComponent(world, entityId, Exclusive);
+            }
+            if (relationMeta?.onDeleteTarget === "delete") {
+                addComponent(world, entityId, OnDeleteTarget);
+            }
+            return meta;
+        }
+        case ENTITY_TYPE: {
+            throw new Error(`Entity ${entityId} not registered in world`);
+        }
+        default: {
+            throw new Error(`Invalid entity type: ${type}`);
+        }
+    }
+}
+/**
+ * Creates a new entity in the world.
+ *
+ * @param world - World instance
+ * @returns Encoded entity ID
+ * @throws {RangeError} If entity limit (1,048,576) exceeded
+ *
+ * @example
+ * ```typescript
+ * const entity = createEntity(world);
+ * addComponent(world, entity, Position, { x: 0, y: 0 });
+ * ```
+ */
+export function createEntity(world) {
+    const entityId = allocateEntityId(world);
+    registerEntity(world, entityId);
+    fireObserverEvent(world, "entityCreated", entityId);
+    return entityId;
+}
+/**
+ * Destroys an entity and recycles its ID for reuse.
+ *
+ * @param world - World instance
+ * @param entityId - Entity to destroy
+ *
+ * @example
+ * ```typescript
+ * destroyEntity(world, entity);
+ * isEntityAlive(world, entity); // false
+ * ```
+ */
+export function destroyEntity(world, entityId) {
+    // Idempotent - already destroyed entities are no-ops
+    if (!isEntityAlive(world, entityId)) {
+        return;
+    }
+    const meta = ensureEntity(world, entityId);
+    // Cycle protection - prevent infinite loops from cascade deletes
+    if (meta.destroying) {
+        return;
+    }
+    meta.destroying = true;
+    // Clean up pairs targeting this entity (handles cascade delete)
+    cleanupPairsTargetingEntity(world, entityId);
+    // Remove this entity from any entities that have it as a component
+    cascadeRemoveComponent(world, entityId);
+    const swappedEntityId = removeEntityFromArchetypeByRow(meta.archetype, meta.row);
+    // Swap-remove updates: entity swapped into our slot needs row update
+    if (swappedEntityId !== undefined) {
+        const swappedMeta = ensureEntity(world, swappedEntityId);
+        swappedMeta.row = meta.row;
+    }
+    fireObserverEvent(world, "entityDestroyed", entityId);
+    world.entities.byId.delete(entityId);
+    // Only entity IDs are recycled; component/tag/relation IDs are permanent
+    if (extractType(entityId) === ENTITY_TYPE) {
+        const rawId = extractId(entityId);
+        const oldGeneration = extractMeta(entityId);
+        // Increment generation so stale references become detectable
+        const newGeneration = (oldGeneration + 1) & ID_MASK_8;
+        world.entities.generations.set(rawId, newGeneration);
+        world.entities.freeIds.push(rawId);
+    }
+}
+/**
+ * Checks if an entity is currently alive in the world.
+ *
+ * @param world - World instance
+ * @param entity - Entity ID to check
+ * @returns True if entity exists and is alive
+ *
+ * @example
+ * ```typescript
+ * isEntityAlive(world, entity); // true
+ * destroyEntity(world, entity);
+ * isEntityAlive(world, entity); // false
+ * ```
+ */
+export function isEntityAlive(world, entity) {
+    return world.entities.byId.has(entity);
+}
+/**
+ * Moves entity to a different archetype, transferring component data.
+ *
+ * @param world - World instance
+ * @param entityId - Entity to move
+ * @param toArchetype - Target archetype
+ *
+ * @example
+ * ```typescript
+ * const archetype = getOrCreateArchetype(world, [Position, Velocity]);
+ * moveEntityToArchetype(world, entity, archetype);
+ * ```
+ */
+export function moveEntityToArchetype(world, entityId, toArchetype) {
+    const meta = ensureEntity(world, entityId);
+    const fromRow = meta.row;
+    const { toRow, swappedEntityId } = transferEntityToArchetypeByRow(meta.archetype, meta.row, toArchetype, world.execution.tick);
+    meta.archetype = toArchetype;
+    meta.row = toRow;
+    // Swap-remove updates: entity swapped into our old slot needs row update
+    if (swappedEntityId !== undefined) {
+        const swappedMeta = ensureEntity(world, swappedEntityId);
+        swappedMeta.row = fromRow;
+    }
+}
+/**
+ * Registers archetype in entity records for all its component types.
+ *
+ * @param world - World instance
+ * @param archetype - Archetype to register
+ *
+ * @example
+ * ```typescript
+ * const archetype = createArchetype([Position, Velocity]);
+ * addEntityRecord(world, archetype);
+ * ```
+ */
+export function addEntityRecord(world, archetype) {
+    // Each component type tracks which archetypes contain it for query matching
+    for (let i = 0; i < archetype.types.length; i++) {
+        const typeId = archetype.types[i];
+        const meta = ensureEntity(world, typeId);
+        meta.records.push(archetype);
+    }
+}
+/**
+ * Removes archetype from entity records for all its component types.
+ *
+ * @param world - World instance
+ * @param archetype - Archetype to unregister
+ *
+ * @example
+ * ```typescript
+ * removeEntityRecord(world, archetype);
+ * destroyArchetype(archetype);
+ * ```
+ */
+export function removeEntityRecord(world, archetype) {
+    for (let i = 0; i < archetype.types.length; i++) {
+        const typeId = archetype.types[i];
+        const meta = ensureEntity(world, typeId);
+        const idx = meta.records.indexOf(archetype);
+        if (idx !== -1) {
+            meta.records.splice(idx, 1);
+        }
+    }
+}
+//# sourceMappingURL=entity.js.map

package/dist/entity.js.map

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