archetype-ecs 1.0.0 → 1.2.0

package/bench/multi-ecs-bench.js

@@ -0,0 +1,393 @@
+// Multi-ECS Benchmark: archetype-ecs vs bitECS vs wolf-ecs vs harmony-ecs vs miniplex
+// 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';
+
+const COUNT = 1_000_000;
+const FRAMES = 500;
+const RUNS = 5;
+
+// ── Utilities ────────────────────────────────────────────────────────────────
+
+const median = (arr) => {
+  const s = [...arr].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length & 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+};
+
+const memMB = () => {
+  if (globalThis.gc) globalThis.gc();
+  return process.memoryUsage().heapUsed / 1024 / 1024;
+};
+
+const pad = (s, n) => String(s).padStart(n);
+const padEnd = (s, n) => String(s).padEnd(n);
+
+// ── Safe import ──────────────────────────────────────────────────────────────
+
+async function tryImport(specifier) {
+  try {
+    return await import(specifier);
+  } catch {
+    return null;
+  }
+}
+
+// ── Library adapters ─────────────────────────────────────────────────────────
+
+function adapterArchetypeECS() {
+  return {
+    name: 'archetype-ecs',
+    setup() {
+      const Position = component('BPos', { x: 'f32', y: 'f32' });
+      const Velocity = component('BVel', { vx: 'f32', vy: 'f32' });
+      const em = createEntityManager();
+      return { em, Position, Velocity };
+    },
+    createEntities(ctx, count) {
+      const { em, Position, Velocity } = ctx;
+      for (let i = 0; i < count; i++) {
+        em.createEntityWith(
+          Position, { x: i * 0.1, y: i * 0.1 },
+          Velocity, { vx: 1, vy: 1 },
+        );
+      }
+    },
+    iterateFrame(ctx) {
+      const { em, Position, Velocity } = ctx;
+      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];
+        }
+      });
+    },
+  };
+}
+
+async function adapterBitECS() {
+  const mod = await tryImport('bitecs');
+  if (!mod) return null;
+  const { createWorld, addEntity, addComponent, query } = mod;
+  return {
+    name: 'bitecs',
+    setup() {
+      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),
+      };
+      return { world, Position, Velocity };
+    },
+    createEntities(ctx, count) {
+      const { world, Position, Velocity } = ctx;
+      for (let i = 0; i < count; i++) {
+        const eid = addEntity(world);
+        addComponent(world, eid, Position);
+        addComponent(world, eid, Velocity);
+        Position.x[eid] = i * 0.1;
+        Position.y[eid] = i * 0.1;
+        Velocity.vx[eid] = 1;
+        Velocity.vy[eid] = 1;
+      }
+    },
+    iterateFrame(ctx) {
+      const { world, Position, Velocity } = ctx;
+      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];
+      }
+    },
+  };
+}
+
+async function adapterWolfECS() {
+  const mod = await tryImport('wolf-ecs');
+  if (!mod) return null;
+  const { ECS, types } = mod;
+  return {
+    name: 'wolf-ecs',
+    setup() {
+      const ecs = new ECS(COUNT + 10);
+      const Position = ecs.defineComponent({ x: types.f32, y: types.f32 });
+      const Velocity = ecs.defineComponent({ x: types.f32, y: types.f32 });
+      const q = ecs.createQuery(Position, Velocity);
+      return { ecs, Position, Velocity, q };
+    },
+    createEntities(ctx, count) {
+      const { ecs, Position, Velocity } = ctx;
+      for (let i = 0; i < count; i++) {
+        const e = ecs.createEntity();
+        ecs.addComponent(e, Position);
+        ecs.addComponent(e, Velocity);
+        Position.x[e] = i * 0.1;
+        Position.y[e] = i * 0.1;
+        Velocity.x[e] = 1;
+        Velocity.y[e] = 1;
+      }
+    },
+    iterateFrame(ctx) {
+      const { Position, Velocity, q } = ctx;
+      for (let i = 0; i < q.a.length; i++) {
+        const arch = q.a[i].e;
+        for (let j = 0; j < arch.length; j++) {
+          const id = arch[j];
+          Position.x[id] += Velocity.x[id];
+          Position.y[id] += Velocity.y[id];
+        }
+      }
+    },
+  };
+}
+
+async function adapterHarmonyECS() {
+  const mod = await tryImport('harmony-ecs');
+  if (!mod) return null;
+  const { World, Schema, Entity, Query, Format } = mod;
+  return {
+    name: 'harmony-ecs',
+    setup() {
+      const world = World.make(COUNT + 10);
+      const Position = Schema.makeBinary(world, { x: Format.float32, y: Format.float32 });
+      const Velocity = Schema.makeBinary(world, { x: Format.float32, y: Format.float32 });
+      const layout = [Position, Velocity];
+      const q = Query.make(world, layout);
+      return { world, Position, Velocity, layout, q };
+    },
+    createEntities(ctx, count) {
+      const { world, layout } = ctx;
+      for (let i = 0; i < count; i++) {
+        Entity.make(world, layout);
+      }
+    },
+    iterateFrame(ctx) {
+      const { q } = ctx;
+      for (const [entities, [p, v]] of q) {
+        for (let i = 0; i < entities.length; i++) {
+          p.x[i] += v.x[i];
+          p.y[i] += v.y[i];
+        }
+      }
+    },
+  };
+}
+
+async function adapterMiniplex() {
+  let mod = await tryImport('miniplex');
+  if (!mod) return null;
+  const World = mod.World || mod.default?.World;
+  if (!World) return null;
+  return {
+    name: 'miniplex',
+    setup() {
+      const world = new World();
+      const q = world.with('position', 'velocity');
+      return { world, q };
+    },
+    createEntities(ctx, count) {
+      const { world } = ctx;
+      for (let i = 0; i < count; i++) {
+        world.add({
+          position: { x: i * 0.1, y: i * 0.1 },
+          velocity: { x: 1, y: 1 },
+        });
+      }
+    },
+    iterateFrame(ctx) {
+      const { q } = ctx;
+      for (const { position, velocity } of q) {
+        position.x += velocity.x;
+        position.y += velocity.y;
+      }
+    },
+  };
+}
+
+// ── Benchmark runner ─────────────────────────────────────────────────────────
+
+function benchIteration(adapter) {
+  const ctx = adapter.setup();
+  adapter.createEntities(ctx, COUNT);
+  // Warmup
+  for (let f = 0; f < 5; f++) adapter.iterateFrame(ctx);
+
+  const t0 = performance.now();
+  for (let f = 0; f < FRAMES; f++) {
+    adapter.iterateFrame(ctx);
+  }
+  return (performance.now() - t0) / FRAMES;
+}
+
+function benchCreation(adapter) {
+  const ctx = adapter.setup();
+  const t0 = performance.now();
+  adapter.createEntities(ctx, COUNT);
+  return performance.now() - t0;
+}
+
+function benchMemory(adapter) {
+  try {
+    const before = memMB();
+    const ctx = adapter.setup();
+    adapter.createEntities(ctx, COUNT);
+    const after = memMB();
+    return after - before;
+  } catch {
+    return null;
+  }
+}
+
+function runMultiple(fn, adapter, runs) {
+  const results = [];
+  for (let r = 0; r < runs; r++) {
+    try {
+      results.push(fn(adapter));
+    } catch {
+      // Some libraries (e.g. harmony-ecs) have global state that breaks on re-creation
+      break;
+    }
+  }
+  return results.length > 0 ? median(results) : null;
+}
+
+// ── Output formatting ────────────────────────────────────────────────────────
+
+function printTable(title, unit, results, baselineName, { moreLabel = 'slower', lessLabel = 'faster' } = {}) {
+  console.log(`\n--- ${title} ---\n`);
+
+  const baseline = results.find(r => r.name === baselineName)?.value;
+  const nameWidth = 20;
+  const valueWidth = 12;
+
+  console.log(`  ${padEnd('Library', nameWidth)} ${pad(unit, valueWidth)}     vs ${baselineName}`);
+  console.log(`  ${'─'.repeat(nameWidth + valueWidth + 25)}`);
+
+  for (const { name, value } of results) {
+    const valueStr = pad(value.toFixed(1), valueWidth);
+    let comparison;
+    if (name === baselineName) {
+      comparison = 'baseline';
+    } else if (baseline != null && baseline > 0) {
+      const ratio = value / baseline;
+      if (ratio > 1.05) {
+        comparison = `${ratio.toFixed(1)}x ${moreLabel}`;
+      } else if (ratio < 0.95) {
+        comparison = `${(1 / ratio).toFixed(1)}x ${lessLabel}`;
+      } else {
+        comparison = '~same';
+      }
+    } else {
+      comparison = '';
+    }
+    console.log(`  ${padEnd(name, nameWidth)} ${valueStr}     ${comparison}`);
+  }
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  if (!globalThis.gc) {
+    console.log('⚠  Run with --expose-gc for accurate memory measurements');
+    console.log('   node --expose-gc bench/multi-ecs-bench.js\n');
+  }
+
+  console.log(`=== Multi-ECS Benchmark: ${(COUNT / 1e6).toFixed(0)}M entities ===`);
+  console.log(`    ${RUNS} runs, median | node --expose-gc bench/multi-ecs-bench.js\n`);
+
+  // Resolve adapters
+  const adapterFactories = [
+    adapterArchetypeECS,
+    adapterBitECS,
+    adapterWolfECS,
+    adapterHarmonyECS,
+    adapterMiniplex,
+  ];
+
+  const adapters = [];
+  for (const factory of adapterFactories) {
+    try {
+      const adapter = await (typeof factory === 'function' && factory.constructor.name === 'AsyncFunction'
+        ? factory()
+        : factory());
+      if (adapter) {
+        adapters.push(adapter);
+      } else {
+        const name = factory.name.replace('adapter', '').replace(/([A-Z])/g, ' $1').trim();
+        console.log(`  [skip] ${name} — not installed`);
+      }
+    } catch (e) {
+      const name = factory.name.replace('adapter', '').replace(/([A-Z])/g, ' $1').trim();
+      console.log(`  [skip] ${name} — ${e.message}`);
+    }
+  }
+
+  if (adapters.length === 0) {
+    console.log('\nNo libraries available. Install dependencies and try again.');
+    process.exit(1);
+  }
+
+  console.log(`\n  Running benchmarks for: ${adapters.map(a => a.name).join(', ')}\n`);
+
+  // ── Iteration benchmark ──────────────────────────────────────────────────
+  const iterResults = [];
+  for (const adapter of adapters) {
+    process.stdout.write(`  Benchmarking iteration: ${adapter.name}...`);
+    const ms = runMultiple(benchIteration, adapter, RUNS);
+    if (ms != null) {
+      iterResults.push({ name: adapter.name, value: ms });
+      process.stdout.write(` ${ms.toFixed(2)} ms/frame\n`);
+    } else {
+      process.stdout.write(` failed\n`);
+    }
+  }
+  iterResults.sort((a, b) => a.value - b.value);
+  printTable(`Iteration (${FRAMES} frames, ${(COUNT / 1e6).toFixed(0)}M entities) — ms/frame`, 'ms/frame', iterResults, 'archetype-ecs');
+
+  // ── Creation benchmark ───────────────────────────────────────────────────
+  const createResults = [];
+  for (const adapter of adapters) {
+    process.stdout.write(`  Benchmarking creation: ${adapter.name}...`);
+    const ms = runMultiple(benchCreation, adapter, RUNS);
+    if (ms != null) {
+      createResults.push({ name: adapter.name, value: ms });
+      process.stdout.write(` ${ms.toFixed(1)} ms\n`);
+    } else {
+      process.stdout.write(` failed\n`);
+    }
+  }
+  createResults.sort((a, b) => a.value - b.value);
+  printTable(`Entity creation (${(COUNT / 1e6).toFixed(0)}M with Position + Velocity) — ms total`, 'ms', createResults, 'archetype-ecs');
+
+  // ── Memory benchmark ─────────────────────────────────────────────────────
+  const memResults = [];
+  for (const adapter of adapters) {
+    process.stdout.write(`  Benchmarking memory: ${adapter.name}...`);
+    const mb = benchMemory(adapter);
+    if (mb != null) {
+      memResults.push({ name: adapter.name, value: mb });
+      process.stdout.write(` ${mb.toFixed(1)} MB\n`);
+    } else {
+      process.stdout.write(` failed\n`);
+    }
+  }
+  memResults.sort((a, b) => a.value - b.value);
+  printTable(`Memory (heap delta, ${(COUNT / 1e6).toFixed(0)}M entities) — MB`, 'MB', memResults, 'archetype-ecs', { moreLabel: 'more', lessLabel: 'less' });
+
+  console.log();
+}
+
+main().catch(e => {
+  console.error(e);
+  process.exit(1);
+});

package/bench/typed-array-vs-objects.js

@@ -0,0 +1,268 @@
+// Benchmark: TypedArray SoA vs plain object arrays
+// Tests performance + allocation / GC pressure
+// Run with: node --expose-gc bench/typed-array-vs-objects.js
+
+const hasGC = typeof globalThis.gc === 'function';
+if (!hasGC) {
+  console.log('WARNING: Run with --expose-gc for accurate allocation measurements\n');
+}
+
+const ENTITY_COUNTS = [100, 1_000, 10_000, 100_000, 1_000_000];
+const ITERATIONS = 1_000;
+
+function getHeapUsed() {
+  if (hasGC) globalThis.gc();
+  return process.memoryUsage().heapUsed;
+}
+
+// =========================================================================
+//  PERFORMANCE BENCHMARKS
+// =========================================================================
+
+function getIters() {
+  return ITERATIONS;
+}
+
+function benchObjectArrays(entityCount) {
+  const iters = getIters(entityCount);
+  const positions = [];
+  const velocities = [];
+  for (let i = 0; i < entityCount; i++) {
+    positions.push({ x: Math.random() * 100, y: Math.random() * 100 });
+    velocities.push({ vx: Math.random() * 10, vy: Math.random() * 10 });
+  }
+
+  const t0 = performance.now();
+  for (let iter = 0; iter < iters; iter++) {
+    for (let i = 0; i < entityCount; i++) {
+      positions[i].x += velocities[i].vx;
+      positions[i].y += velocities[i].vy;
+    }
+  }
+  return { ms: performance.now() - t0, iters };
+}
+
+function benchTypedArraysSoA(entityCount) {
+  const iters = getIters(entityCount);
+  const px = new Float32Array(entityCount);
+  const py = new Float32Array(entityCount);
+  const vx = new Float32Array(entityCount);
+  const vy = new Float32Array(entityCount);
+  for (let i = 0; i < entityCount; 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 iter = 0; iter < iters; iter++) {
+    for (let i = 0; i < entityCount; i++) {
+      px[i] += vx[i];
+      py[i] += vy[i];
+    }
+  }
+  return { ms: performance.now() - t0, iters };
+}
+
+// =========================================================================
+//  ALLOCATION: Storage footprint
+// =========================================================================
+
+function benchStorageAlloc(entityCount) {
+  // Objects
+  const heapBefore1 = getHeapUsed();
+  const positions = [];
+  const velocities = [];
+  for (let i = 0; i < entityCount; i++) {
+    positions.push({ x: Math.random() * 100, y: Math.random() * 100 });
+    velocities.push({ vx: Math.random() * 10, vy: Math.random() * 10 });
+  }
+  const objectBytes = getHeapUsed() - heapBefore1;
+
+  // Clear
+  positions.length = 0;
+  velocities.length = 0;
+
+  // TypedArrays
+  const heapBefore2 = getHeapUsed();
+  const px = new Float32Array(entityCount);
+  const py = new Float32Array(entityCount);
+  const vx = new Float32Array(entityCount);
+  const vy = new Float32Array(entityCount);
+  for (let i = 0; i < entityCount; i++) {
+    px[i] = Math.random() * 100;
+    py[i] = Math.random() * 100;
+    vx[i] = Math.random() * 10;
+    vy[i] = Math.random() * 10;
+  }
+  const typedBytes = getHeapUsed() - heapBefore2;
+
+  return { objectBytes, typedBytes };
+}
+
+// =========================================================================
+//  ALLOCATION: getComponent reconstruction GC pressure
+// =========================================================================
+
+function benchGetComponentGC(entityCount) {
+  const px = new Float32Array(entityCount);
+  const py = new Float32Array(entityCount);
+  for (let i = 0; i < entityCount; i++) {
+    px[i] = Math.random() * 100;
+    py[i] = Math.random() * 100;
+  }
+
+  const positions = [];
+  for (let i = 0; i < entityCount; i++) {
+    positions.push({ x: px[i], y: py[i] });
+  }
+
+  const calls = 100_000;
+
+  // Object array — return existing ref, no allocation
+  if (hasGC) globalThis.gc();
+  const heapBefore1 = process.memoryUsage().heapUsed;
+  const t0 = performance.now();
+  let sink = 0;
+  for (let i = 0; i < calls; i++) {
+    const pos = positions[i % entityCount];
+    sink += pos.x + pos.y;
+  }
+  const objTime = performance.now() - t0;
+  const objHeapAfter = process.memoryUsage().heapUsed;
+
+  // TypedArray — reconstruct object each call
+  if (hasGC) globalThis.gc();
+  const heapBefore2 = process.memoryUsage().heapUsed;
+  const t1 = performance.now();
+  for (let i = 0; i < calls; i++) {
+    const idx = i % entityCount;
+    const pos = { x: px[idx], y: py[idx] };
+    sink += pos.x + pos.y;
+  }
+  const typedTime = performance.now() - t1;
+  const typedHeapAfter = process.memoryUsage().heapUsed;
+
+  return {
+    calls,
+    objTime,
+    objHeapDelta: objHeapAfter - heapBefore1,
+    typedTime,
+    typedHeapDelta: typedHeapAfter - heapBefore2,
+    sink
+  };
+}
+
+// =========================================================================
+//  ALLOCATION: addComponent — object creation vs TypedArray write
+// =========================================================================
+
+function benchAddComponentAlloc(entityCount) {
+  const calls = 100_000;
+
+  // Objects: creating new objects (simulates current addComponent)
+  const objectStore = new Array(entityCount);
+  if (hasGC) globalThis.gc();
+  const heapBefore1 = process.memoryUsage().heapUsed;
+  const t0 = performance.now();
+  for (let i = 0; i < calls; i++) {
+    const idx = i % entityCount;
+    objectStore[idx] = { x: i, y: i * 2 };
+  }
+  const objTime = performance.now() - t0;
+  const objHeapAfter = process.memoryUsage().heapUsed;
+
+  // TypedArrays: write to existing arrays (zero allocation)
+  const px = new Float32Array(entityCount);
+  const py = new Float32Array(entityCount);
+  if (hasGC) globalThis.gc();
+  const heapBefore2 = process.memoryUsage().heapUsed;
+  const t1 = performance.now();
+  for (let i = 0; i < calls; i++) {
+    const idx = i % entityCount;
+    px[idx] = i;
+    py[idx] = i * 2;
+  }
+  const typedTime = performance.now() - t1;
+  const typedHeapAfter = process.memoryUsage().heapUsed;
+
+  return {
+    calls,
+    objTime,
+    objHeapDelta: objHeapAfter - heapBefore1,
+    typedTime,
+    typedHeapDelta: typedHeapAfter - heapBefore2,
+  };
+}
+
+// =========================================================================
+//  RUN
+// =========================================================================
+
+// Warmup
+benchObjectArrays(1000);
+benchTypedArraysSoA(1000);
+
+const fmt = (bytes) => {
+  if (Math.abs(bytes) < 1024) return `${bytes} B`;
+  if (Math.abs(bytes) < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};
+const pad = (s, n) => String(s).padStart(n);
+
+// --- Performance ---
+console.log(`\n=== System loop: Position += Velocity ===\n`);
+console.log('Entities    | Frames | Objects      | TypedArr SoA | Speedup');
+console.log('------------|--------|--------------|--------------|--------');
+
+for (const count of ENTITY_COUNTS) {
+  const obj = benchObjectArrays(count);
+  const soa = benchTypedArraysSoA(count);
+  const perFrameObj = obj.ms / obj.iters;
+  const perFrameSoa = soa.ms / soa.iters;
+  console.log(
+    `${pad(count.toLocaleString(), 11)} | ` +
+    `${pad(obj.iters, 6)} | ` +
+    `${pad(perFrameObj.toFixed(3), 9)} ms | ` +
+    `${pad(perFrameSoa.toFixed(3), 9)} ms | ` +
+    `${pad((perFrameObj / perFrameSoa).toFixed(1), 5)}x`
+  );
+}
+
+// --- Storage footprint ---
+console.log(`\n=== Storage footprint (2 components × 2 fields each) ===\n`);
+console.log('Entities  | Objects      | TypedArrays  | Savings');
+console.log('----------|--------------|--------------|--------');
+
+for (const count of ENTITY_COUNTS) {
+  const { objectBytes, typedBytes } = benchStorageAlloc(count);
+  console.log(
+    `${pad(count.toLocaleString(), 9)} | ` +
+    `${pad(fmt(objectBytes), 12)} | ` +
+    `${pad(fmt(typedBytes), 12)} | ` +
+    `${pad(((1 - typedBytes / objectBytes) * 100).toFixed(0), 4)}%`
+  );
+}
+
+// --- getComponent GC pressure ---
+console.log(`\n=== getComponent ×100k: existing object vs reconstruct from TypedArray ===\n`);
+
+for (const count of [1_000, 10_000, 1_000_000]) {
+  const r = benchGetComponentGC(count);
+  console.log(`${count.toLocaleString()} entities, ${r.calls.toLocaleString()} getComponent calls:`);
+  console.log(`  Object (return ref):  ${pad(r.objTime.toFixed(1), 6)} ms | heap Δ ${fmt(r.objHeapDelta)}`);
+  console.log(`  TypedArr (construct): ${pad(r.typedTime.toFixed(1), 6)} ms | heap Δ ${fmt(r.typedHeapDelta)}`);
+  console.log();
+}
+
+// --- addComponent allocation ---
+console.log(`=== addComponent ×100k: object creation vs TypedArray write ===\n`);
+
+for (const count of [1_000, 10_000, 1_000_000]) {
+  const r = benchAddComponentAlloc(count);
+  console.log(`${count.toLocaleString()} entities, ${r.calls.toLocaleString()} addComponent calls:`);
+  console.log(`  Object (new {}):      ${pad(r.objTime.toFixed(1), 6)} ms | heap Δ ${fmt(r.objHeapDelta)}`);
+  console.log(`  TypedArr (write):     ${pad(r.typedTime.toFixed(1), 6)} ms | heap Δ ${fmt(r.typedHeapDelta)}`);
+  console.log();
+}