archetype-ecs 1.3.1 → 1.3.2

package/README.md

@@ -13,7 +13,7 @@
 
 ---
 
-An Entity Component System for games and simulations in JavaScript. Entities with the same components are grouped into archetypes, and their fields are stored in TypedArrays — so iterating a million entities is a tight loop over contiguous memory, not a scatter of object lookups.
+An Entity Component System for games and simulations in TypeScript. Entities with the same components are grouped into archetypes, and their fields are stored in TypedArrays — so iterating a million entities is a tight loop over contiguous memory, not a scatter of object lookups.
 
 ```
 npm i archetype-ecs
@@ -55,6 +55,7 @@ em.forEach([Position, Velocity], (arch) => {
 <tr><td><strong>Low memory</strong></td><td>86 MB for 1M entities. Sparse-array ECS libraries use up to 2.4x more.</td></tr>
 <tr><td><strong>No allocations</strong></td><td><code>get</code>, <code>set</code>, and <code>forEach</code> don't allocate.</td></tr>
 <tr><td><strong>Typed</strong></td><td>TypeScript generics throughout. Field names autocomplete, wrong fields don't compile.</td></tr>
+<tr><td><strong>Systems</strong></td><td>Class-based systems with <code>@OnAdded</code> / <code>@OnRemoved</code> decorators. Functional API also available.</td></tr>
 </table>
 
 ---
@@ -83,7 +84,7 @@ const Enemy    = component('Enemy')
 
 ### Entities
 
-```js
+```ts
 const em = createEntityManager()
 
 // One at a time
@@ -109,7 +110,7 @@ em.destroyEntity(player)
 
 ### Read & write
 
-```js
+```ts
 // Access a single field (doesn't allocate)
 em.get(player, Position.x)         // 0
 em.get(player, Name.name)          // 'Hero'
@@ -120,7 +121,7 @@ em.getComponent(player, Position)  // { x: 0, y: 0 }
 em.getComponent(player, Name)      // { name: 'Hero', title: 'Sir' }
 ```
 
-### Systems — `forEach` vs `query`
+### Queries — `forEach` vs `query`
 
 Two ways to work with entities in bulk. Pick the right one for the job:
 
@@ -128,8 +129,8 @@ Two ways to work with entities in bulk. Pick the right one for the job:
 
 Iterates over matching archetypes. You get the backing TypedArrays directly.
 
-```js
-function movementSystem(dt) {
+```ts
+function movementSystem(dt: number) {
   em.forEach([Position, Velocity], (arch) => {
     const px = arch.field(Position.x)  // Float32Array
     const py = arch.field(Position.y)
@@ -147,7 +148,7 @@ function movementSystem(dt) {
 
 Returns entity IDs for when you need to target specific entities.
 
-```js
+```ts
 // Find the closest enemy to the player
 const enemies = em.query([Position, Enemy])
 let closest = -1, minDist = Infinity
@@ -177,9 +178,67 @@ const total = em.count([Position])
 | **Allocates** | Nothing | `number[]` of entity IDs |
 | **Access** | TypedArrays by field | `get` / `set` by entity ID |
 
+### Systems
+
+Class-based systems with decorators for component lifecycle hooks:
+
+```ts
+import { System, OnAdded, OnRemoved, createSystems, type EntityId } from 'archetype-ecs'
+
+class MovementSystem extends System {
+  tick() {
+    this.forEach([Position, Velocity], (arch) => {
+      const px = arch.field(Position.x)
+      const py = arch.field(Position.y)
+      const vx = arch.field(Velocity.vx)
+      const vy = arch.field(Velocity.vy)
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i]
+        py[i] += vy[i]
+      }
+    })
+  }
+}
+
+class DeathSystem extends System {
+  @OnAdded(Health)
+  onSpawn(id: EntityId) {
+    console.log(`Entity ${id} spawned with ${this.em.get(id, Health.hp)} HP`)
+  }
+
+  @OnRemoved(Health)
+  onDeath(id: EntityId) {
+    this.em.addComponent(id, Dead)
+  }
+}
+
+const em = createEntityManager()
+const pipeline = createSystems(em, [MovementSystem, DeathSystem])
+
+// Game loop
+em.flushHooks()
+pipeline()
+```
+
+`@OnAdded(Health, Position)` fires when an entity has **all** specified components. `@OnRemoved(Health)` fires when any specified component is removed. Hooks are buffered and deduplicated — they fire during `pipeline()` (or `sys.run()`), after `flushHooks()` collects the pending changes.
+
+A functional API is also available:
+
+```ts
+import { createSystem } from 'archetype-ecs'
+
+const deathSystem = createSystem(em, (sys) => {
+  sys.onAdded(Health, (id) => console.log(`${id} spawned`))
+  sys.onRemoved(Health, (id) => console.log(`${id} died`))
+})
+
+em.flushHooks()
+deathSystem()
+```
+
 ### Serialize
 
-```js
+```ts
 const symbolToName = new Map([
   [Position._sym, 'Position'],
   [Velocity._sym, 'Velocity'],
@@ -202,32 +261,16 @@ Supports stripping components, skipping entities, and custom serializers.
 Component types are inferred from their definition. Field names autocomplete, wrong fields are compile errors.
 
 ```ts
-// Schema is inferred — Position becomes ComponentDef<{ x: number; y: number }>
+// Schema is inferred — Position becomes ComponentDef<'x' | 'y'>
 const Position = component('Position', 'f32', ['x', 'y'])
 
-Position.x                // autocompletes to .x and .y
-Position.z                // Property 'z' does not exist
-
-em.get(id, Position.x)    // number | undefined
-em.set(id, Position.z, 5) // Property 'z' does not exist
-
-em.addComponent(id, Position, { x: 1, y: 2 })  // ok
-em.addComponent(id, Position, { x: 1 })         // Property 'y' is missing
-
-em.getComponent(id, Position)  // { x: number; y: number } | undefined
-```
-
-String fields are fully typed too:
-
-```ts
-const Name = component('Name', 'string', ['name', 'title'])
+Position.x                // FieldRef — autocompletes to .x and .y
+Position.z                // compile error: Property 'z' does not exist
 
-em.get(id, Name.name)    // string | undefined
-em.set(id, Name.name, 'Hero')    // ok
-em.set(id, Name.name, 42)        // number not assignable to string
+em.get(id, Position.x)    // zero-alloc field access
+em.set(id, Position.x, 5) // zero-alloc field write
 
-em.addComponent(id, Name, { name: 'Hero', title: 'Sir' })  // ok
-em.addComponent(id, Name, { foo: 'bar' })                   // type error
+arch.field(Position.x)    // Float32Array — direct TypedArray access
 ```
 
 ---
@@ -242,7 +285,7 @@ Tag component — no data, used as a marker for queries.
 
 Schema component with uniform field type.
 
-```js
+```ts
 const Position = component('Position', 'f32', ['x', 'y'])
 const Name     = component('Name', 'string', ['name', 'title'])
 ```
@@ -251,7 +294,7 @@ const Name     = component('Name', 'string', ['name', 'title'])
 
 Schema component with mixed field types.
 
-```js
+```ts
 const Item = component('Item', { name: 'string', weight: 'f32', armor: 'u8' })
 ```
 
@@ -273,9 +316,33 @@ Returns an entity manager with the following methods:
 | `query(include, exclude?)` | Get matching entity IDs |
 | `count(include, exclude?)` | Count matching entities |
 | `forEach(include, callback, exclude?)` | Iterate archetypes with TypedArray access |
+| `onAdd(Comp, callback)` | Register callback for component additions *(deferred)* |
+| `onRemove(Comp, callback)` | Register callback for component removals *(deferred)* |
+| `flushHooks()` | Collect pending add/remove events for registered hooks |
 | `serialize(symbolToName, strip?, skip?, opts?)` | Serialize world to JSON-friendly object |
 | `deserialize(data, nameToSymbol, opts?)` | Restore world from serialized data |
 
+### `System`
+
+Base class for decorator-based systems.
+
+| | Description |
+|---|---|
+| `@OnAdded(...Comps)` | Decorator — method fires when entity gains **all** specified components |
+| `@OnRemoved(...Comps)` | Decorator — method fires when **any** specified component is removed |
+| `tick()` | Override — called every `run()` after hook callbacks |
+| `forEach(types, callback, exclude?)` | Shorthand for `this.em.forEach(...)` |
+| `run()` | Fire buffered hook callbacks, then `tick()` |
+| `dispose()` | Unsubscribe all hooks |
+
+### `createSystem(em, constructor)`
+
+Functional alternative to class-based systems. The constructor receives a context with `onAdded`, `onRemoved`, and `forEach`, and optionally returns a tick function.
+
+### `createSystems(em, entries)`
+
+Creates a pipeline from an array of class-based (`System` subclasses) and/or functional system constructors. Returns a callable that runs all systems in order, with a `dispose()` method.
+
 ---
 
 ## Benchmarks
@@ -290,7 +357,7 @@ Returns an entity manager with the following methods:
 
 Each library runs the same test — iterate 1M entities over 500 frames:
 
-```js
+```ts
 // archetype-ecs
 em.forEach([Position, Velocity], (arch) => {
   const px = arch.field(Position.x)   // Float32Array, dense
@@ -326,6 +393,7 @@ Compared against other JS ECS libraries:
 | Mixed string + numeric components | ✓ | — | — | — | — |
 | `forEach` with dense TypedArray field access | ✓ | — | — | — | — |
 | Field descriptors for both per-entity and bulk access | ✓ | — | — | — | — |
+| TC39 decorator system (`@OnAdded` / `@OnRemoved`) | ✓ | — | — | — | — |
 | Built-in profiler | ✓ | — | — | — | — |
 
 ### Full comparison
@@ -338,12 +406,14 @@ Compared against other JS ECS libraries:
 | TypeScript type inference | ✓ | — | ✓ | ✓ | ✓✓ |
 | Batch entity creation | ✓ | — | — | ✓ | ✓ |
 | Zero-alloc per-entity access | ✓ | ✓ | ✓ | ✓ | — |
+| System framework (class + functional) | ✓ | — | — | — | — |
+| Component lifecycle hooks | ✓ | — | — | — | ✓ |
 | Relations / hierarchies | — | ✓ | — | — | — |
 | React integration | — | — | — | — | ✓ |
 
 ✓✓ = notably stronger implementation in that library.
 
-archetype-ecs is the only one that combines fast iteration, string storage, serialization, and type safety.
+archetype-ecs is the only one that combines fast iteration, string storage, serialization, decorator-based systems, and type safety.
 
 ---
 

package/bench/allocations-1m.js

@@ -4,7 +4,7 @@
 import {
   createWorld, addEntity, addComponent, removeEntity, query
 } from 'bitecs';
-import { createEntityManager, component } from '../src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const RUNS = 5;

package/bench/multi-ecs-bench.js

@@ -2,7 +2,7 @@
 // Tests: iteration (Position += Velocity), entity creation, memory usage
 // Run with: node --expose-gc bench/multi-ecs-bench.js
 
-import { createEntityManager, component } from '../src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const FRAMES = 500;

package/bench/typed-vs-bitecs-1m.js

@@ -3,7 +3,7 @@
 import {
   createWorld, addEntity, addComponent, query
 } from 'bitecs';
-import { createEntityManager, component } from '../src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const FRAMES = 500;

package/bench/typed-vs-untyped.js

@@ -1,38 +1,34 @@
-// Benchmark: typed (SoA TypedArrays) vs untyped (object arrays) components
+// Benchmark: forEach+field (bulk TypedArray) vs query+get/set (per-entity) vs query+getComponent (allocating)
 
-import { createEntityManager, component } from '../src/index.js';
+import { createEntityManager, component } from '../dist/index.js';
 
 const COUNT = 1_000_000;
 const FRAMES = 200;
 
-// --- Typed: creation ---
-function benchTypedCreate() {
-  const Pos = component('TP', 'f32', ['x', 'y']);
-  const Vel = component('TV', 'f32', ['vx', 'vy']);
+// --- forEach + field() — bulk dense TypedArray access ---
+function benchForEachField() {
+  const Pos = component('FP', 'f32', ['x', 'y']);
+  const Vel = component('FV', 'f32', ['vx', 'vy']);
   const em = createEntityManager();
 
-  const t0 = performance.now();
   for (let i = 0; i < COUNT; i++) {
     em.createEntityWith(Pos, { x: i, y: i }, Vel, { vx: 1, vy: 1 });
   }
-  return { em, Pos, Vel, time: performance.now() - t0 };
-}
-
-// --- Untyped: creation ---
-function benchUntypedCreate() {
-  const Pos = component('UP');
-  const Vel = component('UV');
-  const em = createEntityManager();
 
-  const t0 = performance.now();
-  for (let i = 0; i < COUNT; i++) {
-    em.createEntityWith(Pos, { x: i, y: i }, Vel, { vx: 1, vy: 1 });
+  // Warmup
+  for (let f = 0; f < 5; f++) {
+    em.forEach([Pos, Vel], (arch) => {
+      const px = arch.field(Pos.x);
+      const py = arch.field(Pos.y);
+      const vx = arch.field(Vel.vx);
+      const vy = arch.field(Vel.vy);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i];
+        py[i] += vy[i];
+      }
+    });
   }
-  return { em, Pos, Vel, time: performance.now() - t0 };
-}
 
-// --- Typed: iteration with forEach + field() ---
-function benchTypedIterate(em, Pos, Vel) {
   const t0 = performance.now();
   for (let f = 0; f < FRAMES; f++) {
     em.forEach([Pos, Vel], (arch) => {
@@ -49,19 +45,61 @@ function benchTypedIterate(em, Pos, Vel) {
   return (performance.now() - t0) / FRAMES;
 }
 
-// --- Untyped: iteration with forEach (object access) ---
-function benchUntypedIterate(em, Pos, Vel) {
+// --- query + get/set — per-entity field access (zero-alloc per field) ---
+function benchQueryGetSet() {
+  const Pos = component('GP', 'f32', ['x', 'y']);
+  const Vel = component('GV', 'f32', ['vx', 'vy']);
+  const em = createEntityManager();
+
+  for (let i = 0; i < COUNT; i++) {
+    em.createEntityWith(Pos, { x: i, y: i }, Vel, { vx: 1, vy: 1 });
+  }
+
+  const ids = em.query([Pos, Vel]);
+
+  // Warmup
+  for (let f = 0; f < 5; f++) {
+    for (let i = 0; i < ids.length; i++) {
+      em.set(ids[i], Pos.x, em.get(ids[i], Pos.x) + em.get(ids[i], Vel.vx));
+      em.set(ids[i], Pos.y, em.get(ids[i], Pos.y) + em.get(ids[i], Vel.vy));
+    }
+  }
+
   const t0 = performance.now();
   for (let f = 0; f < FRAMES; f++) {
-    const ids = em.query([Pos, Vel]);
+    for (let i = 0; i < ids.length; i++) {
+      em.set(ids[i], Pos.x, em.get(ids[i], Pos.x) + em.get(ids[i], Vel.vx));
+      em.set(ids[i], Pos.y, em.get(ids[i], Pos.y) + em.get(ids[i], Vel.vy));
+    }
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+// --- query + getComponent — per-entity object allocation ---
+function benchQueryGetComponent() {
+  const Pos = component('CP', 'f32', ['x', 'y']);
+  const Vel = component('CV', 'f32', ['vx', 'vy']);
+  const em = createEntityManager();
+
+  for (let i = 0; i < COUNT; i++) {
+    em.createEntityWith(Pos, { x: i, y: i }, Vel, { vx: 1, vy: 1 });
+  }
+
+  const ids = em.query([Pos, Vel]);
+
+  // Only 20 frames for this one — it's very slow at 1M
+  const frames = 20;
+
+  const t0 = performance.now();
+  for (let f = 0; f < frames; f++) {
     for (let i = 0; i < ids.length; i++) {
       const pos = em.getComponent(ids[i], Pos);
       const vel = em.getComponent(ids[i], Vel);
-      pos.x += vel.vx;
-      pos.y += vel.vy;
+      em.set(ids[i], Pos.x, pos.x + vel.vx);
+      em.set(ids[i], Pos.y, pos.y + vel.vy);
     }
   }
-  return (performance.now() - t0) / FRAMES;
+  return (performance.now() - t0) / frames;
 }
 
 // --- String SoA: creation + access ---
@@ -102,65 +140,27 @@ function benchStringSoA() {
   return { createTime, forEachTime, getTime, count, count2 };
 }
 
-// --- String untyped: creation + access ---
-function benchStringUntyped() {
-  const Name = component('SUn');
-  const em = createEntityManager();
-
-  const t0 = performance.now();
-  for (let i = 0; i < COUNT; i++) {
-    em.createEntityWith(Name, { name: `entity_${i}`, tag: 'npc' });
-  }
-  const createTime = performance.now() - t0;
-
-  // getComponent access
-  const ids = em.query([Name]);
-  const t1 = performance.now();
-  let count = 0;
-  for (let f = 0; f < 50; f++) {
-    for (let i = 0; i < ids.length; i++) {
-      const n = em.getComponent(ids[i], Name);
-      if (n.name.length > 5) count++;
-    }
-  }
-  const accessTime = (performance.now() - t1) / 50;
-
-  return { createTime, accessTime, count };
-}
-
 // --- Run ---
-console.log(`\n=== Typed vs Untyped: ${(COUNT / 1e6).toFixed(0)}M entities ===\n`);
-
-// Warmup
-benchTypedCreate();
-benchUntypedCreate();
+console.log(`\n=== Access patterns: ${(COUNT / 1e6).toFixed(0)}M entities ===\n`);
 
-// Creation
-const typed = benchTypedCreate();
-const untyped = benchUntypedCreate();
+console.log(`Iteration (${FRAMES} frames, Position += Velocity):`);
+const forEachField = benchForEachField();
+console.log(`  forEach + field():            ${forEachField.toFixed(2)} ms/frame`);
 
-console.log(`Creation (${(COUNT / 1e6).toFixed(0)}M entities, createEntityWith):`);
-console.log(`  typed:    ${typed.time.toFixed(0)} ms`);
-console.log(`  untyped:  ${untyped.time.toFixed(0)} ms`);
-console.log(`  ratio:    ${(untyped.time / typed.time).toFixed(2)}x`);
+const queryGetSet = benchQueryGetSet();
+console.log(`  query + get/set:              ${queryGetSet.toFixed(2)} ms/frame`);
 
-// Iteration
-const typedIter = benchTypedIterate(typed.em, typed.Pos, typed.Vel);
-const untypedIter = benchUntypedIterate(untyped.em, untyped.Pos, untyped.Vel);
+const queryGetComp = benchQueryGetComponent();
+console.log(`  query + getComponent:         ${queryGetComp.toFixed(2)} ms/frame`);
 
-console.log(`\nIteration (${FRAMES} frames, Position += Velocity):`);
-console.log(`  typed (forEach+field):        ${typedIter.toFixed(2)} ms/frame`);
-console.log(`  untyped (query+getComponent): ${untypedIter.toFixed(2)} ms/frame`);
-console.log(`  ratio:    ${(untypedIter / typedIter).toFixed(1)}x slower`);
+console.log(`\n  forEach vs get/set:           ${(queryGetSet / forEachField).toFixed(1)}x faster`);
+console.log(`  forEach vs getComponent:      ${(queryGetComp / forEachField).toFixed(1)}x faster`);
 
 // String components
 console.log(`\nString component (${(COUNT / 1e6).toFixed(0)}M entities, { name, tag }):`);
-const strSoA = benchStringSoA();
-const strUn = benchStringUntyped();
-console.log(`  SoA create:                   ${strSoA.createTime.toFixed(0)} ms`);
-console.log(`  untyped create:               ${strUn.createTime.toFixed(0)} ms`);
-console.log(`  SoA forEach(field):           ${strSoA.forEachTime.toFixed(1)} ms/frame`);
-console.log(`  SoA get():                    ${strSoA.getTime.toFixed(1)} ms/frame`);
-console.log(`  untyped getComponent():       ${strUn.accessTime.toFixed(1)} ms/frame`);
-console.log(`  forEach vs getComponent:      ${(strUn.accessTime / strSoA.forEachTime).toFixed(1)}x faster`);
+const str = benchStringSoA();
+console.log(`  create:                       ${str.createTime.toFixed(0)} ms`);
+console.log(`  forEach(field):               ${str.forEachTime.toFixed(1)} ms/frame`);
+console.log(`  get() per entity:             ${str.getTime.toFixed(1)} ms/frame`);
+console.log(`  forEach vs get:               ${(str.getTime / str.forEachTime).toFixed(1)}x faster`);
 console.log();

package/bench/vs-bitecs.js

@@ -1,7 +1,7 @@
-// Benchmark: archetype-ecs (current) vs archetype+TypedArrays (hypothetical) vs bitECS
+// Benchmark: archetype-ecs vs bitECS
 // Tests: system loop, entity creation, component add/remove churn
 
-import { createEntityManager } from '../src/EntityManager.js';
+import { createEntityManager, component } from '../dist/index.js';
 import {
   createWorld, addEntity,
   addComponent, removeComponent,
@@ -19,52 +19,29 @@ const pad = (s, n) => String(s).padStart(n);
 // =========================================================================
 
 function benchArchetypeLoop(entityCount) {
+  const Position = component('APos', 'f32', ['x', 'y']);
+  const Velocity = component('AVel', 'f32', ['vx', 'vy']);
   const em = createEntityManager();
-  const Position = Symbol('Position');
-  const Velocity = Symbol('Velocity');
 
   for (let i = 0; i < entityCount; i++) {
-    const id = em.createEntity();
-    em.addComponent(id, Position, { x: Math.random() * 100, y: Math.random() * 100 });
-    em.addComponent(id, Velocity, { vx: Math.random() * 10, vy: Math.random() * 10 });
-  }
-
-  const t0 = performance.now();
-  for (let f = 0; f < FRAMES; f++) {
-    const entities = em.query([Position, Velocity]);
-    for (let i = 0; i < entities.length; i++) {
-      const pos = em.getComponent(entities[i], Position);
-      const vel = em.getComponent(entities[i], Velocity);
-      pos.x += vel.vx;
-      pos.y += vel.vy;
-    }
-  }
-  return (performance.now() - t0) / FRAMES;
-}
-
-// Simulates archetype-ecs with TypedArray backing:
-// Dense arrays per archetype, but Float32Arrays instead of object arrays
-function benchArchetypeTypedLoop(entityCount) {
-  // One archetype with all entities (they all have Position+Velocity)
-  const count = entityCount;
-  const px = new Float32Array(count);
-  const py = new Float32Array(count);
-  const vx = new Float32Array(count);
-  const vy = new Float32Array(count);
-  for (let i = 0; i < count; i++) {
-    px[i] = Math.random() * 100;
-    py[i] = Math.random() * 100;
-    vx[i] = Math.random() * 10;
-    vy[i] = Math.random() * 10;
+    em.createEntityWith(
+      Position, { x: Math.random() * 100, y: Math.random() * 100 },
+      Velocity, { vx: Math.random() * 10, vy: Math.random() * 10 },
+    );
   }
 
   const t0 = performance.now();
   for (let f = 0; f < FRAMES; f++) {
-    // Dense iteration — no entity ID lookup, no getComponent, no sparse gaps
-    for (let i = 0; i < count; i++) {
-      px[i] += vx[i];
-      py[i] += vy[i];
-    }
+    em.forEach([Position, Velocity], (arch) => {
+      const px = arch.field(Position.x);
+      const py = arch.field(Position.y);
+      const vx = arch.field(Velocity.vx);
+      const vy = arch.field(Velocity.vy);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i];
+        py[i] += vy[i];
+      }
+    });
   }
   return (performance.now() - t0) / FRAMES;
 }
@@ -107,15 +84,16 @@ function benchBitECSLoop(entityCount) {
 // =========================================================================
 
 function benchArchetypeCreate(entityCount) {
+  const Position = component('CPos', 'f32', ['x', 'y']);
+  const Velocity = component('CVel', 'f32', ['vx', 'vy']);
   const em = createEntityManager();
-  const Position = Symbol('Position');
-  const Velocity = Symbol('Velocity');
 
   const t0 = performance.now();
   for (let i = 0; i < entityCount; i++) {
-    const id = em.createEntity();
-    em.addComponent(id, Position, { x: i, y: i });
-    em.addComponent(id, Velocity, { vx: 1, vy: 1 });
+    em.createEntityWith(
+      Position, { x: i, y: i },
+      Velocity, { vx: 1, vy: 1 },
+    );
   }
   return performance.now() - t0;
 }
@@ -149,9 +127,9 @@ function benchBitECSCreate(entityCount) {
 // =========================================================================
 
 function benchArchetypeChurn(entityCount) {
+  const Position = component('ChPos', 'f32', ['x', 'y']);
+  const Health = component('ChHp', 'f32', ['hp']);
   const em = createEntityManager();
-  const Position = Symbol('Position');
-  const Health = Symbol('Health');
 
   const ids = [];
   for (let i = 0; i < entityCount; i++) {
@@ -208,25 +186,22 @@ function benchBitECSChurn(entityCount) {
 
 // Warmup
 benchArchetypeLoop(100);
-benchArchetypeTypedLoop(100);
 benchBitECSLoop(100);
 
 console.log(`\n=== System loop: Position += Velocity (${FRAMES} frames, per-frame time) ===\n`);
-console.log('Entities    | arch (now)    | arch+typed   | bitECS       | arch+typed vs bitECS');
-console.log('------------|---------------|--------------|--------------|---------------------');
+console.log('Entities    | archetype-ecs | bitECS       | Δ');
+console.log('------------|---------------|--------------|---------------------');
 
 for (const count of ENTITY_COUNTS) {
   const arch = benchArchetypeLoop(count);
-  const archTyped = benchArchetypeTypedLoop(count);
   const bit = benchBitECSLoop(count);
-  const vsNow = arch / archTyped;
-  const vsBit = bit / archTyped;
+  const ratio = bit / arch;
+  const label = ratio > 1.1 ? `arch ${ratio.toFixed(1)}x sneller` : ratio < 0.9 ? `bitECS ${(1/ratio).toFixed(1)}x sneller` : '~gelijk';
   console.log(
     `${pad(count.toLocaleString(), 11)} | ` +
     `${pad(arch.toFixed(3), 10)} ms | ` +
-    `${pad(archTyped.toFixed(3), 9)} ms | ` +
     `${pad(bit.toFixed(3), 9)} ms | ` +
-    `${vsBit > 1.1 ? `arch+typed ${vsBit.toFixed(1)}x sneller` : vsBit < 0.9 ? `bitECS ${(1/vsBit).toFixed(1)}x sneller` : '~gelijk'}`
+    `${label}`
   );
 }
 

package/dist/ComponentRegistry.d.ts

@@ -0,0 +1,18 @@
+export declare const TYPED: unique symbol;
+type TypedArrayConstructor = typeof Float32Array | typeof Float64Array | typeof Int8Array | typeof Int16Array | typeof Int32Array | typeof Uint8Array | typeof Uint16Array | typeof Uint32Array | typeof Array;
+export declare const TYPE_MAP: Record<string, TypedArrayConstructor>;
+export type TypeSpec = TypedArrayConstructor | [TypedArrayConstructor, number];
+export declare function parseTypeSpec(typeStr: string): TypeSpec;
+export declare const componentSchemas: Map<symbol, Record<string, TypeSpec>>;
+export interface FieldRef {
+    readonly _sym: symbol;
+    readonly _field: string;
+}
+export type ComponentDef<F extends string = never> = {
+    readonly _sym: symbol;
+    readonly _name: string;
+} & {
+    readonly [K in F]: FieldRef;
+};
+export declare function toSym(type: ComponentDef | symbol): symbol;
+export {};