iris-ecs 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,8 @@
 # iris-ecs
 
-High-performance, TypeScript-idiomatic Entity Component System.
+Entity Component System implementation for TypeScript.
+
+> **Early stage implementation.** APIs are unstable and breaking changes can happen between versions.
 
 ## What is ECS?
 
@@ -41,8 +43,7 @@ import {
   setComponentValue,
   fetchEntities,
   addSystem,
-  buildSchedule,
-  executeSchedule,
+  runOnce,
   Type,
 } from "iris-ecs";
 
@@ -72,10 +73,9 @@ function movementSystem(world) {
   }
 }
 
-// Register and run systems
+// Register and run
 addSystem(world, movementSystem);
-buildSchedule(world);
-executeSchedule(world);
+await runOnce(world);
 
 // Position is now { x: 1, y: 0 }
 ```
@@ -416,8 +416,8 @@ A **System** is a function that operates on the world. Systems query entities, r
 ```typescript
 import {
   addSystem,
-  buildSchedule,
-  executeSchedule,
+  run,
+  stop,
   fetchEntities,
   getComponentValue,
   setComponentValue,
@@ -436,15 +436,13 @@ function movementSystem(world) {
 }
 
 addSystem(world, movementSystem);
-buildSchedule(world);
+run(world);
 
-// Game loop
-while (running) {
-  executeSchedule(world);
-}
+// ... later
+await stop(world);
 ```
 
-Systems are registered with `addSystem()`, ordered by `buildSchedule()`, and run with `executeSchedule()`. The system function's name becomes its identifier.
+Systems are registered with `addSystem()` and executed automatically when the world runs. The system function's name becomes its identifier.
 
 #### Ordering Constraints
 
@@ -458,8 +456,6 @@ function renderSystem(world) { /* draw frame */ }
 addSystem(world, inputSystem);
 addSystem(world, physicsSystem, { after: "inputSystem" });
 addSystem(world, renderSystem, { after: "physicsSystem" });
-
-buildSchedule(world);
 // Executes: inputSystem -> physicsSystem -> renderSystem
 ```
 
@@ -469,27 +465,70 @@ Without constraints, systems run in registration order. Use arrays for multiple
 
 #### Schedules
 
-Systems are grouped into **schedules**. The default schedule is `"runtime"`, but you can create others for initialization, cleanup, or custom phases:
+Systems are grouped into **schedules** -- named execution phases. The default pipeline runs these schedules every frame:
+
+```
+First -> PreUpdate -> Update -> PostUpdate -> Last
+```
+
+`Update` is the default schedule. Assign systems to other phases based on when they should run:
 
 ```typescript
-addSystem(world, loadAssetsSystem, { schedule: "startup" });
-addSystem(world, saveGameSystem, { schedule: "shutdown" });
-addSystem(world, physicsSystem); // defaults to "runtime"
+import { addSystem, First, PreUpdate, PostUpdate, Last, run, stop } from "iris-ecs";
 
-buildSchedule(world, "startup");
-buildSchedule(world, "runtime");
-buildSchedule(world, "shutdown");
+addSystem(world, inputSystem, { schedule: First });
+addSystem(world, physicsSystem, { schedule: PreUpdate });
+addSystem(world, movementSystem); // defaults to Update
+addSystem(world, collisionSystem, { schedule: PostUpdate });
+addSystem(world, renderSystem, { schedule: Last });
 
-executeSchedule(world, "startup"); // Run once at start
-while (running) {
-  executeSchedule(world);          // "runtime" is default
-}
-executeSchedule(world, "shutdown"); // Run once at end
+run(world);
+
+// ... later
+await stop(world);
+```
+
+Two additional schedules run outside the main loop:
+
+- **Startup** runs once before the first frame (asset loading, initialization)
+- **Shutdown** runs once when `stop()` is called (cleanup, save state)
+
+```typescript
+import { Startup, Shutdown } from "iris-ecs";
+
+addSystem(world, loadAssetsSystem, { schedule: Startup });
+addSystem(world, saveGameSystem, { schedule: Shutdown });
+```
+
+#### Custom Schedules
+
+Create custom pipeline phases with `defineSchedule()` and insert them relative to existing ones:
+
+```typescript
+import { defineSchedule, insertScheduleAfter, PreUpdate } from "iris-ecs";
+
+const Physics = defineSchedule("Physics");
+insertScheduleAfter(world, Physics, PreUpdate);
+addSystem(world, gravitySystem, { schedule: Physics });
+
+// Pipeline is now: First -> PreUpdate -> Physics -> Update -> PostUpdate -> Last
+```
+
+#### Running the World
+
+`run(world)` starts a `requestAnimationFrame` loop. Each frame runs all pipeline schedules then flushes events. `stop(world)` stops the loop and runs Shutdown. Calling `stop()` then `run()` again re-triggers Startup and Shutdown for each cycle.
+
+For manual frame stepping (tests, server-side), use `runOnce()`:
+
+```typescript
+import { runOnce } from "iris-ecs";
+
+await runOnce(world); // one frame
 ```
 
 #### Async Systems
 
-For systems that need to `await` (loading assets, network calls), use `executeScheduleAsync()`:
+Systems can be async. Both `run()` and `runOnce()` handle sync and async systems transparently:
 
 ```typescript
 async function loadAssetsSystem(world) {
@@ -497,14 +536,9 @@ async function loadAssetsSystem(world) {
   // ...
 }
 
-addSystem(world, loadAssetsSystem, { schedule: "startup" });
-buildSchedule(world, "startup");
-
-await executeScheduleAsync(world, "startup");
+addSystem(world, loadAssetsSystem, { schedule: Startup });
 ```
 
-⚠️ `executeSchedule()` throws if any system returns a Promise. Use `executeScheduleAsync()` for schedules with async systems.
-
 ### Actions
 
 **Actions** bundle reusable operations with a world captured in closure. Define actions once, then call them without repeatedly passing the world.
@@ -614,7 +648,7 @@ if (isPaused) {
 
 #### Event Lifetime
 
-Events persist for a short window (2 ticks) to ensure all systems can read them regardless of execution order, then expire automatically. Calling `fetchEvents()` marks events as read for that system -- a second call in the same system sees nothing new.
+Events use double-buffered storage. Buffers rotate automatically at the end of each frame -- events survive one frame (so systems that run next frame can still read them), then are discarded. Calling `fetchEvents()` marks events as read for that system -- a second call in the same system sees nothing new.
 
 ⚠️ **Events are not entities.** Unlike components and tags, events exist outside the entity-component model. You cannot query for events or attach them to entities.
 

package/dist/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAMtF,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAChE,IAAI,CAAC;AAER,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EACjD,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC7C,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACzB,IAAI,CAAC;AAwER;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAsD7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAI7F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,EACzE,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC7C,SAAS,EAAE,CAAC,GACX,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAc/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,EACzE,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC7C,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACvB,IAAI,CAqBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CASlG;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAiBhF"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAMtF,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAChE,IAAI,CAAC;AAER,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EACjD,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC7C,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACzB,IAAI,CAAC;AAyER;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAsD7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAI7F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,EACzE,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC7C,SAAS,EAAE,CAAC,GACX,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAc/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC,EACzE,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC7C,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACvB,IAAI,CAqBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CASlG;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAiBhF"}

package/dist/component.js

@@ -21,8 +21,9 @@ import { getPairRelation, getPairTarget, getRelationTargets } from "./relation.j
  * addComponent(world, child, pair(ChildOf, parent));
  */
 export function addComponent(world, entityId, componentId, data) {
+    const entityMeta = ensureEntity(world, entityId);
     // Idempotent: already has component
-    if (hasComponent(world, entityId, componentId)) {
+    if (entityMeta.archetype.typesSet.has(componentId)) {
         return;
     }
     // Exclusive enforcement: remove old target before adding new
@@ -36,7 +37,6 @@ export function addComponent(world, entityId, componentId, data) {
             }
         }
     }
-    const entityMeta = ensureEntity(world, entityId);
     const componentMeta = ensureEntity(world, componentId);
     const schema = componentMeta.schema;
     // Find target archetype
@@ -48,7 +48,7 @@ export function addComponent(world, entityId, componentId, data) {
         toArchetype = archetypeTraverseAdd(world, toArchetype, encodePair(Wildcard, target));
         toArchetype = archetypeTraverseAdd(world, toArchetype, encodePair(relation, Wildcard));
     }
-    moveEntityToArchetype(world, entityId, toArchetype);
+    moveEntityToArchetype(world, entityMeta, toArchetype);
     if (data) {
         for (const fieldName in data) {
             const value = data[fieldName];
@@ -112,7 +112,7 @@ export function removeComponent(world, entityId, componentId) {
     }
     // Fire before move so observers can access component data
     fireObserverEvent(world, "componentRemoved", componentId, entityId);
-    moveEntityToArchetype(world, entityId, toArchetype);
+    moveEntityToArchetype(world, meta, toArchetype);
 }
 /**
  * Check if entity has component.
@@ -221,7 +221,7 @@ export function emitComponentChanged(world, entityId, componentId) {
  * @param componentId - Component to remove from all entities
  */
 export function cascadeRemoveComponent(world, componentId) {
-    const meta = ensureEntity(world, componentId);
+    const meta = world.entities.byId.get(componentId);
     // Copy records - will be modified during iteration as entities move
     const archetypes = [...meta.records];
     for (const archetype of archetypes) {

package/dist/component.js.map

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

package/dist/entity.d.ts

@@ -35,7 +35,8 @@ export type EntityMeta = {
  * @param world - World instance
  * @param entityId - Entity or component ID
  * @returns Entity metadata
- * @throws {Error} If entity not registered (ENTITY_TYPE) or unknown type
+ * @throws {NotFound} If entity not registered (ENTITY_TYPE)
+ * @throws {InvalidState} If unknown entity type
  *
  * @example
  * ```typescript
@@ -49,7 +50,7 @@ export declare function ensureEntity(world: World, entityId: EntityId): EntityMe
  *
  * @param world - World instance
  * @returns Encoded entity ID
- * @throws {RangeError} If entity limit (1,048,576) exceeded
+ * @throws {LimitExceeded} If entity limit (1,048,576) exceeded
  *
  * @example
  * ```typescript
@@ -90,16 +91,16 @@ 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 meta - Entity metadata
  * @param toArchetype - Target archetype
  *
  * @example
  * ```typescript
  * const archetype = getOrCreateArchetype(world, [Position, Velocity]);
- * moveEntityToArchetype(world, entity, archetype);
+ * moveEntityToArchetype(world, meta, archetype);
  * ```
  */
-export declare function moveEntityToArchetype(world: World, entityId: EntityId, toArchetype: Archetype): void;
+export declare function moveEntityToArchetype(world: World, meta: EntityMeta, toArchetype: Archetype): void;
 /**
  * Registers archetype in entity records for all its component types.
  *

package/dist/entity.d.ts.map

@@ -1 +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"}
+{"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;AAkB3E,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;AA0CF;;;;;;;;;;;;;;GAcG;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,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,GAAG,IAAI,CAkBlG;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

@@ -1,6 +1,7 @@
 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 { assert, InvalidState, LimitExceeded, NotFound } from "./error.js";
 import { fireObserverEvent } from "./observer.js";
 import { Exclusive, OnDeleteTarget } from "./registry.js";
 import { cleanupPairsTargetingEntity, getPairRelation } from "./relation.js";
@@ -16,9 +17,7 @@ function allocateEntityId(world) {
         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})`);
-    }
+    assert(newRawId <= ID_MASK_20, LimitExceeded, { resource: "Entity", max: ID_MASK_20, id: newRawId });
     world.entities.generations.set(newRawId, 0);
     return encodeEntity(newRawId, 0);
 }
@@ -44,7 +43,8 @@ function registerEntity(world, entityId, schema) {
  * @param world - World instance
  * @param entityId - Entity or component ID
  * @returns Entity metadata
- * @throws {Error} If entity not registered (ENTITY_TYPE) or unknown type
+ * @throws {NotFound} If entity not registered (ENTITY_TYPE)
+ * @throws {InvalidState} If unknown entity type
  *
  * @example
  * ```typescript
@@ -85,10 +85,10 @@ export function ensureEntity(world, entityId) {
             return meta;
         }
         case ENTITY_TYPE: {
-            throw new Error(`Entity ${entityId} not registered in world`);
+            throw new NotFound({ resource: "Entity", id: entityId, context: "world" });
         }
         default: {
-            throw new Error(`Invalid entity type: ${type}`);
+            throw new InvalidState({ message: `Invalid entity type: ${type}` });
         }
     }
 }
@@ -97,7 +97,7 @@ export function ensureEntity(world, entityId) {
  *
  * @param world - World instance
  * @returns Encoded entity ID
- * @throws {RangeError} If entity limit (1,048,576) exceeded
+ * @throws {LimitExceeded} If entity limit (1,048,576) exceeded
  *
  * @example
  * ```typescript
@@ -128,7 +128,7 @@ export function destroyEntity(world, entityId) {
     if (!isEntityAlive(world, entityId)) {
         return;
     }
-    const meta = ensureEntity(world, entityId);
+    const meta = world.entities.byId.get(entityId);
     // Cycle protection - prevent infinite loops from cascade deletes
     if (meta.destroying) {
         return;
@@ -141,7 +141,7 @@ export function destroyEntity(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);
+        const swappedMeta = world.entities.byId.get(swappedEntityId);
         swappedMeta.row = meta.row;
     }
     fireObserverEvent(world, "entityDestroyed", entityId);
@@ -177,24 +177,23 @@ export function isEntityAlive(world, entity) {
  * Moves entity to a different archetype, transferring component data.
  *
  * @param world - World instance
- * @param entityId - Entity to move
+ * @param meta - Entity metadata
  * @param toArchetype - Target archetype
  *
  * @example
  * ```typescript
  * const archetype = getOrCreateArchetype(world, [Position, Velocity]);
- * moveEntityToArchetype(world, entity, archetype);
+ * moveEntityToArchetype(world, meta, archetype);
  * ```
  */
-export function moveEntityToArchetype(world, entityId, toArchetype) {
-    const meta = ensureEntity(world, entityId);
+export function moveEntityToArchetype(world, meta, toArchetype) {
     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);
+        const swappedMeta = world.entities.byId.get(swappedEntityId);
         swappedMeta.row = fromRow;
     }
 }
@@ -233,7 +232,7 @@ export function addEntityRecord(world, 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 meta = world.entities.byId.get(typeId);
         const idx = meta.records.indexOf(archetype);
         if (idx !== -1) {
             meta.records.splice(idx, 1);

package/dist/entity.js.map

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

package/dist/error.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Base error class for all Iris ECS errors.
+ *
+ * Provides structured error categories with typed parameters for
+ * programmatic error handling via `instanceof` checks.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   createEntity(world);
+ * } catch (error) {
+ *   if (error instanceof LimitExceeded) {
+ *     console.log(error.resource, error.max);
+ *   }
+ * }
+ * ```
+ */
+export declare class IrisError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an ID space is exhausted.
+ *
+ * @example
+ * ```typescript
+ * // Thrown when entity limit (1,048,576) is exceeded
+ * const entity = createEntity(world);
+ * ```
+ */
+export declare class LimitExceeded extends IrisError {
+    readonly resource: string;
+    readonly max: number;
+    readonly id?: number;
+    constructor(params: {
+        resource: string;
+        max: number;
+        id?: number;
+    });
+}
+/**
+ * Thrown when a referenced item does not exist.
+ *
+ * @example
+ * ```typescript
+ * // Thrown when accessing a destroyed entity
+ * ensureEntity(world, destroyedEntity);
+ * ```
+ */
+export declare class NotFound extends IrisError {
+    readonly resource: string;
+    readonly id: string | number;
+    readonly context?: string;
+    constructor(params: {
+        resource: string;
+        id: string | number;
+        context?: string;
+    });
+}
+/**
+ * Thrown when attempting to register a duplicate item.
+ *
+ * @example
+ * ```typescript
+ * // Thrown when registering a system with the same name twice
+ * addSystem(world, mySystem);
+ * addSystem(world, mySystem); // throws Duplicate
+ * ```
+ */
+export declare class Duplicate extends IrisError {
+    readonly resource: string;
+    readonly id: string | number;
+    constructor(params: {
+        resource: string;
+        id: string | number;
+    });
+}
+/**
+ * Thrown when a function argument fails validation.
+ *
+ * @example
+ * ```typescript
+ * // Thrown when registering an anonymous system without a name
+ * addSystem(world, () => {});
+ * ```
+ */
+export declare class InvalidArgument extends IrisError {
+    readonly expected: string;
+    readonly actual?: string;
+    constructor(params: {
+        expected: string;
+        actual?: string;
+    });
+}
+/**
+ * Thrown when the system reaches an invalid or unexpected state.
+ *
+ * @example
+ * ```typescript
+ * // Thrown on circular system dependencies
+ * addSystem(world, a, { before: "b" });
+ * addSystem(world, b, { before: "a" });
+ * await runOnce(world);
+ * ```
+ */
+export declare class InvalidState extends IrisError {
+    constructor(params: {
+        message: string;
+    });
+}
+/**
+ * Assert a condition, throwing a typed error if false.
+ *
+ * Error is only constructed when the condition fails (lazy construction).
+ * TypeScript `asserts condition` narrows the type at call sites.
+ *
+ * @param condition - Value to check for truthiness
+ * @param ErrorClass - Error class to instantiate on failure
+ * @param params - Constructor parameters for the error class
+ *
+ * @example
+ * ```typescript
+ * assert(rawId <= ID_MASK_20, LimitExceeded, { resource: "Entity", max: ID_MASK_20, id: rawId });
+ * // rawId is narrowed to truthy after this point
+ * ```
+ */
+export declare function assert<P>(condition: unknown, ErrorClass: new (params: P) => IrisError, params: P): asserts condition;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAMD;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;gBAET,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE;CAOnE;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAS,SAAQ,SAAS;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEd,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;CAOhF;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAU,SAAQ,SAAS;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;gBAEjB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE;CAK9D;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAM1D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE;CAGxC;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,MAAM,EAAE,CAAC,KAAK,SAAS,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,SAAS,CAIpH"}