archetype-ecs 1.1.0 → 1.2.0

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

@@ -0,0 +1,86 @@
+// Focused benchmark: archetype+TypedArrays vs bitECS at 1M entities
+
+import {
+  createWorld, addEntity, addComponent, query
+} from 'bitecs';
+import { createEntityManager, component } from '../src/index.js';
+
+const COUNT = 1_000_000;
+const FRAMES = 500;
+
+// archetype-ecs: component() with schema + forEach() hot path
+function benchArchetypeTyped() {
+  const Position = component('BenchPos', { x: 'f32', y: 'f32' });
+  const Velocity = component('BenchVel', { vx: 'f32', vy: 'f32' });
+  const em = createEntityManager();
+
+  for (let i = 0; i < COUNT; 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++) {
+    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;
+}
+
+// bitECS: sparse TypedArrays, query returns entity ID list
+function benchBitECS() {
+  const world = createWorld();
+  const Position = {
+    x: new Float32Array(COUNT + 10),
+    y: new Float32Array(COUNT + 10)
+  };
+  const Velocity = {
+    vx: new Float32Array(COUNT + 10),
+    vy: new Float32Array(COUNT + 10)
+  };
+
+  for (let i = 0; i < COUNT; i++) {
+    const eid = addEntity(world);
+    addComponent(world, eid, Position);
+    addComponent(world, eid, Velocity);
+    Position.x[eid] = Math.random() * 100;
+    Position.y[eid] = Math.random() * 100;
+    Velocity.vx[eid] = Math.random() * 10;
+    Velocity.vy[eid] = Math.random() * 10;
+  }
+
+  const t0 = performance.now();
+  for (let f = 0; f < FRAMES; f++) {
+    const entities = query(world, [Position, Velocity]);
+    for (let i = 0; i < entities.length; i++) {
+      const eid = entities[i];
+      Position.x[eid] += Velocity.vx[eid];
+      Position.y[eid] += Velocity.vy[eid];
+    }
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+// Warmup
+benchArchetypeTyped();
+
+console.log(`\n=== 1M entities, ${FRAMES} frames: Position += Velocity ===\n`);
+
+const archTyped = benchArchetypeTyped();
+console.log(`  arch+typed:  ${archTyped.toFixed(3)} ms/frame`);
+
+const bit = benchBitECS();
+console.log(`  bitECS:      ${bit.toFixed(3)} ms/frame`);
+
+const ratio = bit / archTyped;
+console.log(`\n  → arch+typed is ${ratio.toFixed(1)}x sneller`);
+console.log();

package/bench/typed-vs-untyped.js

@@ -0,0 +1,166 @@
+// Benchmark: typed (SoA TypedArrays) vs untyped (object arrays) components
+
+import { createEntityManager, component } from '../src/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']);
+  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 });
+  }
+  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) => {
+      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 (performance.now() - t0) / FRAMES;
+}
+
+// --- Untyped: iteration with forEach (object access) ---
+function benchUntypedIterate(em, Pos, Vel) {
+  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++) {
+      const pos = em.getComponent(ids[i], Pos);
+      const vel = em.getComponent(ids[i], Vel);
+      pos.x += vel.vx;
+      pos.y += vel.vy;
+    }
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+// --- String SoA: creation + access ---
+function benchStringSoA() {
+  const Name = component('SSoA', { name: 'string', tag: 'string' });
+  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;
+
+  // forEach field access
+  const t1 = performance.now();
+  let count = 0;
+  for (let f = 0; f < 50; f++) {
+    em.forEach([Name], (arch) => {
+      const names = arch.field(Name.name);
+      for (let i = 0; i < arch.count; i++) {
+        if (names[i].length > 5) count++;
+      }
+    });
+  }
+  const forEachTime = (performance.now() - t1) / 50;
+
+  // get() field access
+  const ids = em.query([Name]);
+  const t2 = performance.now();
+  let count2 = 0;
+  for (let f = 0; f < 50; f++) {
+    for (let i = 0; i < ids.length; i++) {
+      if (em.get(ids[i], Name.name).length > 5) count2++;
+    }
+  }
+  const getTime = (performance.now() - t2) / 50;
+
+  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();
+
+// Creation
+const typed = benchTypedCreate();
+const untyped = benchUntypedCreate();
+
+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`);
+
+// Iteration
+const typedIter = benchTypedIterate(typed.em, typed.Pos, typed.Vel);
+const untypedIter = benchUntypedIterate(untyped.em, untyped.Pos, untyped.Vel);
+
+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`);
+
+// 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`);
+console.log();

package/bench/vs-bitecs.js

@@ -0,0 +1,267 @@
+// Benchmark: archetype-ecs (current) vs archetype+TypedArrays (hypothetical) vs bitECS
+// Tests: system loop, entity creation, component add/remove churn
+
+import { createEntityManager } from '../src/EntityManager.js';
+import {
+  createWorld, addEntity,
+  addComponent, removeComponent,
+  query
+} from 'bitecs';
+
+const ENTITY_COUNTS = [100, 1_000, 10_000, 100_000];
+const FRAMES = 500;
+const MAX_ENTITIES = 110_000;
+
+const pad = (s, n) => String(s).padStart(n);
+
+// =========================================================================
+//  System loop: Position += Velocity
+// =========================================================================
+
+function benchArchetypeLoop(entityCount) {
+  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;
+  }
+
+  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];
+    }
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+function benchBitECSLoop(entityCount) {
+  const world = createWorld();
+  const Position = {
+    x: new Float32Array(MAX_ENTITIES),
+    y: new Float32Array(MAX_ENTITIES)
+  };
+  const Velocity = {
+    vx: new Float32Array(MAX_ENTITIES),
+    vy: new Float32Array(MAX_ENTITIES)
+  };
+
+  for (let i = 0; i < entityCount; i++) {
+    const eid = addEntity(world);
+    addComponent(world, eid, Position);
+    addComponent(world, eid, Velocity);
+    Position.x[eid] = Math.random() * 100;
+    Position.y[eid] = Math.random() * 100;
+    Velocity.vx[eid] = Math.random() * 10;
+    Velocity.vy[eid] = Math.random() * 10;
+  }
+
+  const t0 = performance.now();
+  for (let f = 0; f < FRAMES; f++) {
+    const entities = query(world, [Position, Velocity]);
+    for (let i = 0; i < entities.length; i++) {
+      const eid = entities[i];
+      Position.x[eid] += Velocity.vx[eid];
+      Position.y[eid] += Velocity.vy[eid];
+    }
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+// =========================================================================
+//  Entity creation with 2 components
+// =========================================================================
+
+function benchArchetypeCreate(entityCount) {
+  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 });
+  }
+  return performance.now() - t0;
+}
+
+function benchBitECSCreate(entityCount) {
+  const world = createWorld();
+  const Position = {
+    x: new Float32Array(entityCount + 10),
+    y: new Float32Array(entityCount + 10)
+  };
+  const Velocity = {
+    vx: new Float32Array(entityCount + 10),
+    vy: new Float32Array(entityCount + 10)
+  };
+
+  const t0 = performance.now();
+  for (let i = 0; i < entityCount; i++) {
+    const eid = addEntity(world);
+    addComponent(world, eid, Position);
+    addComponent(world, eid, Velocity);
+    Position.x[eid] = i;
+    Position.y[eid] = i;
+    Velocity.vx[eid] = 1;
+    Velocity.vy[eid] = 1;
+  }
+  return performance.now() - t0;
+}
+
+// =========================================================================
+//  Component add/remove churn
+// =========================================================================
+
+function benchArchetypeChurn(entityCount) {
+  const em = createEntityManager();
+  const Position = Symbol('Position');
+  const Health = Symbol('Health');
+
+  const ids = [];
+  for (let i = 0; i < entityCount; i++) {
+    const id = em.createEntity();
+    em.addComponent(id, Position, { x: 0, y: 0 });
+    ids.push(id);
+  }
+
+  const ops = Math.min(entityCount, 10_000);
+  const t0 = performance.now();
+  for (let i = 0; i < ops; i++) {
+    em.addComponent(ids[i], Health, { hp: 100 });
+  }
+  for (let i = 0; i < ops; i++) {
+    em.removeComponent(ids[i], Health);
+  }
+  return { ms: performance.now() - t0, ops: ops * 2 };
+}
+
+function benchBitECSChurn(entityCount) {
+  const world = createWorld();
+  const Position = {
+    x: new Float32Array(entityCount + 10),
+    y: new Float32Array(entityCount + 10)
+  };
+  const Health = {
+    hp: new Float32Array(entityCount + 10)
+  };
+
+  const eids = [];
+  for (let i = 0; i < entityCount; i++) {
+    const eid = addEntity(world);
+    addComponent(world, eid, Position);
+    Position.x[eid] = 0;
+    Position.y[eid] = 0;
+    eids.push(eid);
+  }
+
+  const ops = Math.min(entityCount, 10_000);
+  const t0 = performance.now();
+  for (let i = 0; i < ops; i++) {
+    addComponent(world, eids[i], Health);
+    Health.hp[eids[i]] = 100;
+  }
+  for (let i = 0; i < ops; i++) {
+    removeComponent(world, eids[i], Health);
+  }
+  return { ms: performance.now() - t0, ops: ops * 2 };
+}
+
+// =========================================================================
+//  RUN
+// =========================================================================
+
+// 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('------------|---------------|--------------|--------------|---------------------');
+
+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;
+  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'}`
+  );
+}
+
+console.log(`\n=== Entity creation (with 2 components) ===\n`);
+console.log('Entities    | archetype-ecs | bitECS       | Δ');
+console.log('------------|---------------|--------------|-------');
+
+for (const count of ENTITY_COUNTS) {
+  const arch = benchArchetypeCreate(count);
+  const bit = benchBitECSCreate(count);
+  const ratio = arch / bit;
+  const winner = ratio > 1.1 ? `bitECS ${ratio.toFixed(1)}x` : ratio < 0.9 ? `arch ${(1/ratio).toFixed(1)}x` : '~gelijk';
+  console.log(
+    `${pad(count.toLocaleString(), 11)} | ` +
+    `${pad(arch.toFixed(1), 10)} ms | ` +
+    `${pad(bit.toFixed(1), 9)} ms | ` +
+    `${winner}`
+  );
+}
+
+console.log(`\n=== Component add/remove churn (10k ops) ===\n`);
+console.log('Entities    | archetype-ecs | bitECS       | Δ');
+console.log('------------|---------------|--------------|-------');
+
+for (const count of [1_000, 10_000, 100_000]) {
+  const arch = benchArchetypeChurn(count);
+  const bit = benchBitECSChurn(count);
+  const ratio = arch.ms / bit.ms;
+  const winner = ratio > 1.1 ? `bitECS ${ratio.toFixed(1)}x` : ratio < 0.9 ? `arch ${(1/ratio).toFixed(1)}x` : '~gelijk';
+  console.log(
+    `${pad(count.toLocaleString(), 11)} | ` +
+    `${pad(arch.ms.toFixed(1), 10)} ms | ` +
+    `${pad(bit.ms.toFixed(1), 9)} ms | ` +
+    `${winner}`
+  );
+}
+
+console.log();

package/package.json

@@ -1,16 +1,34 @@
 {
   "name": "archetype-ecs",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Lightweight archetype-based Entity Component System",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
+  "types": "src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
   "scripts": {
-    "test": "node --test tests/"
+    "test": "node --test tests/ && npx tsc --noEmit",
+    "bench": "node --expose-gc bench/multi-ecs-bench.js"
   },
-  "keywords": ["ecs", "entity", "component", "system", "archetype", "gamedev"],
-  "license": "MIT"
+  "keywords": [
+    "ecs",
+    "entity",
+    "component",
+    "system",
+    "archetype",
+    "gamedev"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "bitecs": "^0.4.0",
+    "harmony-ecs": "^0.0.12",
+    "miniplex": "^2.0.0",
+    "wolf-ecs": "^2.0.0"
+  }
 }

package/src/ComponentRegistry.js

@@ -0,0 +1,21 @@
+export const TYPED = Symbol('typed');
+
+export const TYPE_MAP = {
+  'f32': Float32Array,
+  'f64': Float64Array,
+  'i8': Int8Array,
+  'i16': Int16Array,
+  'i32': Int32Array,
+  'u8': Uint8Array,
+  'u16': Uint16Array,
+  'u32': Uint32Array,
+  'string': Array,
+};
+
+/** @type {Map<symbol, Record<string, typeof Float32Array>>} */
+export const componentSchemas = new Map();
+
+/** Extract the underlying symbol from a component object or pass through a plain symbol */
+export function toSym(type) {
+  return type._sym || type;
+}