archetype-ecs 1.0.0 → 1.2.0

package/.claude/settings.local.json

@@ -0,0 +1,32 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node /mnt/d/Projects/ECS/bench/vs-bitecs.js:*)",
+      "Bash(node:*)",
+      "Bash(npm test:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd getField/setField for zero-allocation field access with TS generics\n\ngetField and setField read/write individual component fields directly\nfrom TypedArrays without reconstructing an object. TypeScript generics\non component\\(\\) flow through to autocomplete field names and catch\ninvalid fields at compile time.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git push:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd compile-time type tests for TS generics validation\n\ntests/types.ts validates that component\\(\\) schema inference flows\nthrough getField, setField, addComponent, and forEach field\\(\\) with\n@ts-expect-error assertions for invalid field names. npm test now\nruns both runtime tests and tsc --noEmit.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /mnt/d/Projects/ECS status)",
+      "Bash(git -C /mnt/d/Projects/ECS diff)",
+      "Bash(git -C /mnt/d/Projects/ECS log --oneline -5)",
+      "Bash(git -C /mnt/d/Projects/ECS add bench/typed-vs-bitecs-1m.js src/ComponentRegistry.js src/EntityManager.js src/index.d.ts src/index.js tests/EntityManager.test.js tests/types.ts)",
+      "Bash(git -C /mnt/d/Projects/ECS commit -m \"$\\(cat <<''EOF''\nAdd field descriptor API: Position.x instead of string literals\n\nComponent objects now have field descriptors as properties, enabling\nem.get\\(id, Position.x\\) / em.set\\(id, Position.x, 5\\) for zero-alloc\nfield access and arch.field\\(Position.x\\) in forEach hot loops.\n\n- component\\(\\) supports short form: component\\(''Pos'', ''f32'', [''x'',''y'']\\)\n- toSym\\(\\) helper normalizes component objects to underlying symbols\n- Updated TS types: ComponentDef<T> with FieldRef descriptors\n- All tests and benchmarks updated to new API\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(wc:*)",
+      "Bash(git commit:*)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:www.webgamedev.com)",
+      "WebFetch(domain:3mcd.github.io)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(npm view:*)",
+      "Bash(npm pack:*)",
+      "Bash(curl:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run bench:*)",
+      "Bash(FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch:*)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,359 @@
+<p align="center">
+  <br>
+  <img src="https://em-content.zobj.net/source/apple/391/dna_1f9ec.png" width="80" />
+  <br><br>
+  <strong>archetype-ecs</strong>
+  <br>
+  <sub>Tiny, fast ECS with TypedArray storage. Zero dependencies.</sub>
+  <br><br>
+  <a href="https://www.npmjs.com/package/archetype-ecs"><img src="https://img.shields.io/npm/v/archetype-ecs.svg?style=flat-square&color=000" alt="npm" /></a>
+  <img src="https://img.shields.io/badge/gzip-~5kb-000?style=flat-square" alt="size" />
+  <a href="https://github.com/RvRooijen/archetype-ecs/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/archetype-ecs.svg?style=flat-square&color=000" alt="license" /></a>
+</p>
+
+---
+
+Entities grouped by component composition. Numeric fields in contiguous TypedArrays, strings in SoA arrays. Bitmask query matching. Zero-allocation hot paths.
+
+```
+npm i archetype-ecs
+```
+
+---
+
+### The full picture in 20 lines
+
+```ts
+import { createEntityManager, component } from 'archetype-ecs'
+
+const Position = component('Position', 'f32', ['x', 'y'])
+const Velocity = component('Velocity', 'f32', ['vx', 'vy'])
+
+const em = createEntityManager()
+
+for (let i = 0; i < 10_000; i++) {
+  em.createEntityWith(
+    Position, { x: Math.random() * 800, y: Math.random() * 600 },
+    Velocity, { vx: Math.random() - 0.5, vy: Math.random() - 0.5 },
+  )
+}
+
+em.forEach([Position, Velocity], (arch) => {
+  const px = arch.field(Position.x)  // Float32Array
+  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]
+  }
+})
+```
+
+Define components, spawn entities, iterate with raw TypedArrays — no allocations, no cache misses, full type safety.
+
+---
+
+### Why archetype-ecs?
+
+<table>
+<tr><td><strong>Fastest iteration</strong></td><td>SoA TypedArrays give the fastest iteration of any JS ECS we've tested. 1.7 ms/frame over 1M entities — see <a href="#benchmarks">benchmarks</a>.</td></tr>
+<tr><td><strong>Compact memory</strong></td><td>Packed archetypes store 1M entities in 86 MB. Up to 2.4x less than sparse-array alternatives.</td></tr>
+<tr><td><strong>Zero-alloc hot path</strong></td><td><code>em.get</code>, <code>em.set</code>, and <code>forEach</code> never allocate. Your GC stays quiet.</td></tr>
+<tr><td><strong>Type-safe</strong></td><td>Full TypeScript generics. Field names autocomplete. Wrong fields don't compile.</td></tr>
+<tr><td><strong>Zero dependencies</strong></td><td>~5kb gzipped. No build step. Ships as ES modules.</td></tr>
+</table>
+
+---
+
+### Components
+
+```ts
+import { createEntityManager, component } from 'archetype-ecs'
+
+// Numeric — backed by TypedArrays for cache-friendly iteration
+const Position = component('Position', 'f32', ['x', 'y'])
+const Velocity = component('Velocity', 'f32', ['vx', 'vy'])
+const Health   = component('Health', { hp: 'i32', maxHp: 'i32' })
+
+// Strings — backed by SoA arrays, same field access API
+const Name     = component('Name', 'string', ['name', 'title'])
+
+// Mixed — numeric and string fields in one component
+const Item     = component('Item', { name: 'string', weight: 'f32' })
+
+// Tag — no data, just a marker
+const Enemy    = component('Enemy')
+```
+
+> Field types: `f32` `f64` `i8` `i16` `i32` `u8` `u16` `u32` `string`
+
+### Entities
+
+```js
+const em = createEntityManager()
+
+// One at a time
+const player = em.createEntity()
+em.addComponent(player, Position, { x: 0, y: 0 })
+em.addComponent(player, Velocity, { vx: 0, vy: 0 })
+em.addComponent(player, Health, { hp: 100, maxHp: 100 })
+em.addComponent(player, Name, { name: 'Hero', title: 'Sir' })
+
+// Or all at once — no archetype migration overhead
+for (let i = 0; i < 10_000; i++) {
+  em.createEntityWith(
+    Position, { x: Math.random() * 800, y: Math.random() * 600 },
+    Velocity, { vx: Math.random() - 0.5, vy: Math.random() - 0.5 },
+    Enemy,    {},
+  )
+}
+
+em.hasComponent(player, Health)   // true
+em.removeComponent(player, Health)
+em.destroyEntity(player)
+```
+
+### Read & write
+
+```js
+// Zero allocation — access any field directly
+em.get(player, Position.x)         // 0
+em.get(player, Name.name)          // 'Hero'
+em.set(player, Velocity.vx, 5)
+
+// Or grab the whole component as an object (allocates)
+em.getComponent(player, Position)  // { x: 0, y: 0 }
+em.getComponent(player, Name)      // { name: 'Hero', title: 'Sir' }
+```
+
+### Systems — `forEach` vs `query`
+
+Two ways to work with entities in bulk. Pick the right one for the job:
+
+#### `forEach` — zero-alloc bulk processing
+
+Best for **systems that run every frame**. Gives you raw TypedArrays — no entity lookups, no object allocations, no cache misses.
+
+```js
+function movementSystem(dt) {
+  em.forEach([Position, Velocity], (arch) => {
+    const px = arch.field(Position.x)  // Float32Array
+    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] * dt
+      py[i] += vy[i] * dt
+    }
+  })
+}
+```
+
+#### `query` — when you need entity IDs
+
+Best for **event-driven logic** where you need to store, pass around, or target specific entity IDs.
+
+```js
+// Find the closest enemy to the player
+const enemies = em.query([Position, Enemy])
+let closest = -1, minDist = Infinity
+for (const id of enemies) {
+  const dx = em.get(id, Position.x) - playerX
+  const dy = em.get(id, Position.y) - playerY
+  const dist = dx * dx + dy * dy
+  if (dist < minDist) { minDist = dist; closest = id }
+}
+
+// Store the result as a component
+em.addComponent(player, Target, { entityId: closest })
+
+// Exclude enemies from friendly queries
+const friendly = em.query([Health], [Enemy])
+
+// Just need a count? No allocation needed
+const total = em.count([Position])
+```
+
+#### When to use which
+
+| | `forEach` | `query` |
+|---|---|---|
+| **Use for** | Movement, physics, rendering | Damage events, UI, spawning |
+| **Runs** | Every frame | On demand |
+| **Allocates** | Nothing | `number[]` of entity IDs |
+| **Access** | Raw TypedArrays by field | `get` / `set` by entity ID |
+
+### Serialize
+
+```js
+const symbolToName = new Map([
+  [Position._sym, 'Position'],
+  [Velocity._sym, 'Velocity'],
+  [Health._sym, 'Health'],
+])
+
+const snapshot = em.serialize(symbolToName)
+const json = JSON.stringify(snapshot)
+
+// Later...
+em.deserialize(JSON.parse(json), { Position, Velocity, Health })
+```
+
+Strip components, skip entities, or plug in custom serializers — see the API section below.
+
+---
+
+## TypeScript
+
+Every component carries its type. Field names autocomplete, wrong fields and shapes are compile errors.
+
+```ts
+// Schema is inferred — Position becomes ComponentDef<{ x: number; y: number }>
+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'])
+
+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.addComponent(id, Name, { name: 'Hero', title: 'Sir' })  // ok
+em.addComponent(id, Name, { foo: 'bar' })                   // type error
+```
+
+---
+
+## API reference
+
+### `component(name)`
+
+Tag component — no data, used as a marker for queries.
+
+### `component(name, type, fields)`
+
+Schema component with uniform field type.
+
+```js
+const Position = component('Position', 'f32', ['x', 'y'])
+const Name     = component('Name', 'string', ['name', 'title'])
+```
+
+### `component(name, schema)`
+
+Schema component with mixed field types.
+
+```js
+const Item = component('Item', { name: 'string', weight: 'f32', armor: 'u8' })
+```
+
+### `createEntityManager()`
+
+Returns an entity manager with the following methods:
+
+| Method | Description |
+|---|---|
+| `createEntity()` | Create an empty entity |
+| `createEntityWith(Comp, data, ...)` | Create entity with components — no migration cost |
+| `destroyEntity(id)` | Remove entity and all its components |
+| `addComponent(id, Comp, data)` | Add a component to an existing entity |
+| `removeComponent(id, Comp)` | Remove a component |
+| `hasComponent(id, Comp)` | Check if entity has a component |
+| `getComponent(id, Comp)` | Get component data as object *(allocates)* |
+| `get(id, Comp.field)` | Read a single field *(zero-alloc)* |
+| `set(id, Comp.field, value)` | Write a single field *(zero-alloc)* |
+| `query(include, exclude?)` | Get matching entity IDs |
+| `count(include, exclude?)` | Count matching entities |
+| `forEach(include, callback, exclude?)` | Iterate archetypes with raw TypedArray access |
+| `serialize(symbolToName, strip?, skip?, opts?)` | Serialize world to JSON-friendly object |
+| `deserialize(data, nameToSymbol, opts?)` | Restore world from serialized data |
+
+---
+
+## Benchmarks
+
+1M entities, Position += Velocity, 5 runs (median), Node.js:
+
+| | archetype-ecs | bitecs | wolf-ecs | harmony-ecs | miniplex |
+|---|---:|---:|---:|---:|---:|
+| **Iteration** (ms/frame) | **1.7** | 2.2 | 2.2 | 1.8 | 32.5 |
+| **Entity creation** (ms) | 401 | 366 | **106** | 248 | 265 |
+| **Memory** (MB) | 86 | 204 | 60 | **31** | 166 |
+
+Each library runs the same test — iterate 1M entities over 500 frames:
+
+```js
+// archetype-ecs
+em.forEach([Position, Velocity], (arch) => {
+  const px = arch.field(Position.x)   // Float32Array, dense
+  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]
+  }
+})
+```
+
+archetype-ecs has the fastest iteration — the metric that matters most for game loops. Harmony-ecs and wolf-ecs are close behind; miniplex pays for object-based storage with ~20x slower iteration.
+
+Run them yourself:
+
+```bash
+npm run bench
+```
+
+---
+
+## Feature comparison
+
+How archetype-ecs stacks up against other JS ECS libraries:
+
+### Unique to archetype-ecs
+
+| Feature | archetype-ecs | bitecs | wolf-ecs | harmony-ecs | miniplex |
+|---|:---:|:---:|:---:|:---:|:---:|
+| String SoA storage | ✓ | — | — | — | — |
+| Mixed string + numeric components | ✓ | — | — | — | — |
+| `forEach` with dense TypedArray field access | ✓ | — | — | — | — |
+| Field descriptors for both per-entity and bulk access | ✓ | — | — | — | — |
+| Built-in profiler | ✓ | — | — | — | — |
+
+### Full comparison
+
+| Feature | archetype-ecs | bitecs | wolf-ecs | harmony-ecs | miniplex |
+|---|:---:|:---:|:---:|:---:|:---:|
+| TypedArray iteration | ✓ | ✓ | ✓ | ✓ | — |
+| String support | ✓ | ✓ | — | — | ✓ |
+| Serialize / deserialize | ✓ | ✓✓ | — | — | — |
+| TypeScript type inference | ✓ | — | ✓ | ✓ | ✓✓ |
+| Batch entity creation | ✓ | — | — | ✓ | ✓ |
+| Zero-alloc per-entity access | ✓ | ✓ | ✓ | ✓ | — |
+| Relations / hierarchies | — | ✓ | — | — | — |
+| React integration | — | — | — | — | ✓ |
+
+✓✓ = notably stronger implementation in that library.
+
+archetype-ecs is the only library that combines fastest iteration, string SoA storage, serialization, type safety, and a built-in profiler.
+
+---
+
+## License
+
+MIT

package/bench/allocations-1m.js

@@ -0,0 +1,161 @@
+// Allocation benchmark: creating 1M entities with Position + Velocity
+// Compares: archetype-ecs (typed) vs bitECS vs archetype-ecs (untyped/legacy)
+
+import {
+  createWorld, addEntity, addComponent, removeEntity, query
+} from 'bitecs';
+import { createEntityManager, component } from '../src/index.js';
+
+const COUNT = 1_000_000;
+const RUNS = 5;
+
+function median(arr) {
+  const s = [...arr].sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)];
+}
+
+function memMB() {
+  if (globalThis.gc) globalThis.gc();
+  return process.memoryUsage().heapUsed / 1024 / 1024;
+}
+
+// --- archetype-ecs: typed (SoA) ---
+function benchOursTyped() {
+  const Position = component('AllocPos', { x: 'f32', y: 'f32' });
+  const Velocity = component('AllocVel', { vx: 'f32', vy: 'f32' });
+  const em = createEntityManager();
+
+  const memBefore = memMB();
+  const t0 = performance.now();
+
+  for (let i = 0; i < COUNT; i++) {
+    const id = em.createEntity();
+    em.addComponent(id, Position, { x: i, y: i });
+    em.addComponent(id, Velocity, { vx: 1, vy: 1 });
+  }
+
+  const createTime = performance.now() - t0;
+  const memAfter = memMB();
+
+  // Destroy all
+  const t1 = performance.now();
+  const ids = em.query([Position]);
+  for (const id of ids) em.destroyEntity(id);
+  const destroyTime = performance.now() - t1;
+
+  return { createTime, destroyTime, memDelta: memAfter - memBefore };
+}
+
+// --- archetype-ecs: typed (SoA) with createEntityWith (no migration) ---
+function benchOursTypedBatch() {
+  const Position = component('AllocPosBatch', { x: 'f32', y: 'f32' });
+  const Velocity = component('AllocVelBatch', { vx: 'f32', vy: 'f32' });
+  const em = createEntityManager();
+
+  const memBefore = memMB();
+  const t0 = performance.now();
+
+  for (let i = 0; i < COUNT; i++) {
+    em.createEntityWith(Position, { x: i, y: i }, Velocity, { vx: 1, vy: 1 });
+  }
+
+  const createTime = performance.now() - t0;
+  const memAfter = memMB();
+
+  const t1 = performance.now();
+  const ids = em.query([Position]);
+  for (const id of ids) em.destroyEntity(id);
+  const destroyTime = performance.now() - t1;
+
+  return { createTime, destroyTime, memDelta: memAfter - memBefore };
+}
+
+// --- archetype-ecs: untyped (legacy object arrays) ---
+function benchOursUntyped() {
+  const Position = Symbol('AllocPosUn');
+  const Velocity = Symbol('AllocVelUn');
+  const em = createEntityManager();
+
+  const memBefore = memMB();
+  const t0 = performance.now();
+
+  for (let i = 0; i < COUNT; i++) {
+    const id = em.createEntity();
+    em.addComponent(id, Position, { x: i, y: i });
+    em.addComponent(id, Velocity, { vx: 1, vy: 1 });
+  }
+
+  const createTime = performance.now() - t0;
+  const memAfter = memMB();
+
+  const t1 = performance.now();
+  const ids = em.query([Position]);
+  for (const id of ids) em.destroyEntity(id);
+  const destroyTime = performance.now() - t1;
+
+  return { createTime, destroyTime, memDelta: memAfter - memBefore };
+}
+
+// --- bitECS ---
+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) };
+
+  const memBefore = memMB();
+  const t0 = performance.now();
+
+  for (let i = 0; i < COUNT; 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;
+  }
+
+  const createTime = performance.now() - t0;
+  const memAfter = memMB();
+
+  const t1 = performance.now();
+  const entities = query(world, [Position, Velocity]);
+  for (const eid of entities) removeEntity(world, eid);
+  const destroyTime = performance.now() - t1;
+
+  return { createTime, destroyTime, memDelta: memAfter - memBefore };
+}
+
+// --- Run ---
+console.log(`\n=== Allocation benchmark: ${(COUNT / 1e6).toFixed(0)}M entities (Position + Velocity) ===`);
+console.log(`    ${RUNS} runs, median taken\n`);
+
+const results = { typed: [], typedBatch: [], untyped: [], bitecs: [] };
+
+for (let r = 0; r < RUNS; r++) {
+  results.typed.push(benchOursTyped());
+  results.typedBatch.push(benchOursTypedBatch());
+  results.untyped.push(benchOursUntyped());
+  results.bitecs.push(benchBitECS());
+}
+
+function report(label, runs) {
+  const create = median(runs.map(r => r.createTime));
+  const destroy = median(runs.map(r => r.destroyTime));
+  const mem = median(runs.map(r => r.memDelta));
+  console.log(`  ${label}`);
+  console.log(`    create:  ${create.toFixed(1)} ms`);
+  console.log(`    destroy: ${destroy.toFixed(1)} ms`);
+  console.log(`    heap:    +${mem.toFixed(1)} MB`);
+  return { create, destroy, mem };
+}
+
+const t = report('typed + addComponent (2 migraties)', results.typed);
+const tb = report('typed + createEntityWith (0 migraties)', results.typedBatch);
+const u = report('untyped + addComponent', results.untyped);
+const b = report('bitECS', results.bitecs);
+
+console.log(`\n  createEntityWith vs addComponent: ${(t.create / tb.create).toFixed(1)}x sneller`);
+console.log(`  createEntityWith vs bitECS:       ${(tb.create / b.create).toFixed(1)}x (${tb.create < b.create ? 'sneller' : 'trager'})`);
+console.log(`  memory: typed ${t.mem.toFixed(0)} MB, batch ${tb.mem.toFixed(0)} MB, bitECS ${b.mem.toFixed(0)} MB`);
+console.log();