archetype-ecs 1.2.0 → 1.3.1

package/README.md

@@ -4,7 +4,7 @@
   <br><br>
   <strong>archetype-ecs</strong>
   <br>
-  <sub>Tiny, fast ECS with TypedArray storage. Zero dependencies.</sub>
+  <sub>ECS with TypedArray storage. No 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" />
@@ -13,16 +13,12 @@
 
 ---
 
-Entities grouped by component composition. Numeric fields in contiguous TypedArrays, strings in SoA arrays. Bitmask query matching. Zero-allocation hot paths.
+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.
 
 ```
 npm i archetype-ecs
 ```
 
----
-
-### The full picture in 20 lines
-
 ```ts
 import { createEntityManager, component } from 'archetype-ecs'
 
@@ -50,18 +46,15 @@ em.forEach([Position, Velocity], (arch) => {
 })
 ```
 
-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>
+<tr><td><strong>Fast iteration</strong></td><td>1.7 ms/frame over 1M entities. Faster than bitecs, wolf-ecs, harmony-ecs — see <a href="#benchmarks">benchmarks</a>.</td></tr>
+<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>
 </table>
 
 ---
@@ -71,12 +64,12 @@ Define components, spawn entities, iterate with raw TypedArrays — no allocatio
 ```ts
 import { createEntityManager, component } from 'archetype-ecs'
 
-// Numeric — backed by TypedArrays for cache-friendly iteration
+// Numeric — stored as TypedArrays
 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
+// Strings — stored as arrays, same API
 const Name     = component('Name', 'string', ['name', 'title'])
 
 // Mixed — numeric and string fields in one component
@@ -100,7 +93,7 @@ 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
+// Or all at once
 for (let i = 0; i < 10_000; i++) {
   em.createEntityWith(
     Position, { x: Math.random() * 800, y: Math.random() * 600 },
@@ -117,7 +110,7 @@ em.destroyEntity(player)
 ### Read & write
 
 ```js
-// Zero allocation — access any field directly
+// Access a single field (doesn't allocate)
 em.get(player, Position.x)         // 0
 em.get(player, Name.name)          // 'Hero'
 em.set(player, Velocity.vx, 5)
@@ -131,9 +124,9 @@ em.getComponent(player, Name)      // { name: 'Hero', title: 'Sir' }
 
 Two ways to work with entities in bulk. Pick the right one for the job:
 
-#### `forEach` — zero-alloc bulk processing
+#### `forEach` — bulk processing
 
-Best for **systems that run every frame**. Gives you raw TypedArrays — no entity lookups, no object allocations, no cache misses.
+Iterates over matching archetypes. You get the backing TypedArrays directly.
 
 ```js
 function movementSystem(dt) {
@@ -152,7 +145,7 @@ function movementSystem(dt) {
 
 #### `query` — when you need entity IDs
 
-Best for **event-driven logic** where you need to store, pass around, or target specific entity IDs.
+Returns entity IDs for when you need to target specific entities.
 
 ```js
 // Find the closest enemy to the player
@@ -182,7 +175,7 @@ const total = em.count([Position])
 | **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 |
+| **Access** | TypedArrays by field | `get` / `set` by entity ID |
 
 ### Serialize
 
@@ -200,13 +193,13 @@ const json = JSON.stringify(snapshot)
 em.deserialize(JSON.parse(json), { Position, Velocity, Health })
 ```
 
-Strip components, skip entities, or plug in custom serializers — see the API section below.
+Supports stripping components, skipping entities, and custom serializers.
 
 ---
 
 ## TypeScript
 
-Every component carries its type. Field names autocomplete, wrong fields and shapes are compile errors.
+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 }>
@@ -269,17 +262,17 @@ 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 |
+| `createEntityWith(Comp, data, ...)` | Create entity with components in one call |
 | `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)* |
+| `get(id, Comp.field)` | Read a single field |
+| `set(id, Comp.field, value)` | Write a single field |
 | `query(include, exclude?)` | Get matching entity IDs |
 | `count(include, exclude?)` | Count matching entities |
-| `forEach(include, callback, exclude?)` | Iterate archetypes with raw TypedArray access |
+| `forEach(include, callback, exclude?)` | Iterate archetypes with TypedArray access |
 | `serialize(symbolToName, strip?, skip?, opts?)` | Serialize world to JSON-friendly object |
 | `deserialize(data, nameToSymbol, opts?)` | Restore world from serialized data |
 
@@ -289,7 +282,7 @@ Returns an entity manager with the following methods:
 
 1M entities, Position += Velocity, 5 runs (median), Node.js:
 
-| | archetype-ecs | bitecs | wolf-ecs | harmony-ecs | miniplex |
+| | archetype-ecs | [bitecs](https://github.com/NateTheGreatt/bitECS) | [wolf-ecs](https://github.com/EnderShadow8/wolf-ecs) | [harmony-ecs](https://github.com/3mcd/harmony-ecs) | [miniplex](https://github.com/hmans/miniplex) |
 |---|---:|---:|---:|---:|---:|
 | **Iteration** (ms/frame) | **1.7** | 2.2 | 2.2 | 1.8 | 32.5 |
 | **Entity creation** (ms) | 401 | 366 | **106** | 248 | 265 |
@@ -311,7 +304,7 @@ em.forEach([Position, Velocity], (arch) => {
 })
 ```
 
-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.
+archetype-ecs is fastest at iteration. Harmony-ecs and wolf-ecs are close; miniplex is ~20x slower due to object-based storage.
 
 Run them yourself:
 
@@ -323,7 +316,7 @@ npm run bench
 
 ## Feature comparison
 
-How archetype-ecs stacks up against other JS ECS libraries:
+Compared against other JS ECS libraries:
 
 ### Unique to archetype-ecs
 
@@ -350,7 +343,7 @@ How archetype-ecs stacks up against other JS ECS libraries:
 
 ✓✓ = 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.
+archetype-ecs is the only one that combines fast iteration, string storage, serialization, and type safety.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archetype-ecs",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Lightweight archetype-based Entity Component System",
   "type": "module",
   "main": "src/index.js",

package/src/EntityManager.js

@@ -46,10 +46,39 @@ function soaSwap(store, idxA, idxB) {
   }
 }
 
+function createSnapshotStore(schema, capacity) {
+  const snap = {};
+  for (const [field, Ctor] of Object.entries(schema)) {
+    snap[field] = new Ctor(capacity);
+  }
+  return snap;
+}
+
+function growSnapshotStore(snap, schema, newCapacity) {
+  for (const [field, Ctor] of Object.entries(schema)) {
+    const old = snap[field];
+    snap[field] = new Ctor(newCapacity);
+    if (Ctor === Array) {
+      for (let i = 0; i < old.length; i++) snap[field][i] = old[i];
+    } else {
+      snap[field].set(old);
+    }
+  }
+}
+
 export function createEntityManager() {
   let nextId = 1;
   const allEntityIds = new Set();
 
+  // Change tracking (opt-in via enableTracking)
+  let trackFilter = 0;   // bitmask — only track archetypes matching this
+  let createdSet = null;  // Set<EntityId>
+  let destroyedSet = null; // Set<EntityId>
+
+  // Double-buffered snapshots: tracked archetypes get back-buffer arrays
+  // Game systems write to front (normal SoA arrays), flushSnapshots copies front→back
+  const trackedArchetypes = [];  // archetypes that match trackFilter
+
   // Component bit registry (symbol → bit index 0..31)
   const componentBitIndex = new Map();
   let nextBitIndex = 0;
@@ -84,20 +113,29 @@ export function createEntityManager() {
     const key = computeMask(types);
     let arch = archetypes.get(key);
     if (!arch) {
+      const tracked = trackFilter !== 0 && (key & trackFilter) !== 0;
       arch = {
         key,
         types: new Set(types),
         entityIds: [],
         components: new Map(),
+        snapshots: tracked ? new Map() : null,
+        snapshotEntityIds: tracked ? [] : null,
+        snapshotCount: 0,
         entityToIndex: new Map(),
         count: 0,
         capacity: INITIAL_CAPACITY
       };
       for (const t of types) {
         const schema = componentSchemas.get(t);
-        arch.components.set(t, schema ? createSoAStore(schema, INITIAL_CAPACITY) : null);
+        const store = schema ? createSoAStore(schema, INITIAL_CAPACITY) : null;
+        arch.components.set(t, store);
+        if (tracked && store) {
+          arch.snapshots.set(t, createSnapshotStore(schema, INITIAL_CAPACITY));
+        }
       }
       archetypes.set(key, arch);
+      if (tracked) trackedArchetypes.push(arch);
       queryCacheVersion++;
     }
     return arch;
@@ -108,7 +146,13 @@ export function createEntityManager() {
     const newCap = arch.capacity * 2;
     arch.capacity = newCap;
     for (const [type, store] of arch.components) {
-      if (store) growSoAStore(store, newCap);
+      if (store) {
+        growSoAStore(store, newCap);
+        if (arch.snapshots) {
+          const snap = arch.snapshots.get(type);
+          if (snap) growSnapshotStore(snap, store._schema, newCap);
+        }
+      }
     }
   }
 
@@ -182,6 +226,7 @@ export function createEntityManager() {
     destroyEntity(id) {
       const arch = entityArchetype.get(id);
       if (arch) {
+        if (destroyedSet && (arch.key & trackFilter)) destroyedSet.add(id);
         removeFromArchetype(arch, id);
       }
       allEntityIds.delete(id);
@@ -224,6 +269,9 @@ export function createEntityManager() {
       const arch = entityArchetype.get(entityId);
       if (!arch || !arch.types.has(type)) return;
 
+      // If entity is leaving a tracked archetype, treat as destroyed
+      if (destroyedSet && (arch.key & trackFilter)) destroyedSet.add(entityId);
+
       if (arch.types.size === 1) {
         removeFromArchetype(arch, entityId);
         return;
@@ -309,6 +357,7 @@ export function createEntityManager() {
       const arch = getOrCreateArchetype(types);
       addToArchetype(arch, id, map);
 
+      if (createdSet && (arch.key & trackFilter)) createdSet.add(id);
       return id;
     },
 
@@ -326,20 +375,87 @@ export function createEntityManager() {
       for (let a = 0; a < matching.length; a++) {
         const arch = matching[a];
         if (arch.count === 0) continue;
+        const snaps = arch.snapshots;
         const view = {
+          id: arch.key,
           entityIds: arch.entityIds,
           count: arch.count,
+          snapshotEntityIds: arch.snapshotEntityIds,
+          snapshotCount: arch.snapshotCount,
           field(ref) {
             const sym = ref._sym || ref;
             const store = arch.components.get(sym);
             if (!store) return undefined;
             return store[ref._field];
+          },
+          snapshot(ref) {
+            if (!snaps) return undefined;
+            const sym = ref._sym || ref;
+            const snap = snaps.get(sym);
+            if (!snap) return undefined;
+            return snap[ref._field];
           }
         };
         callback(view);
       }
     },
 
+    enableTracking(filterComponent) {
+      trackFilter = 1 << getBit(filterComponent);
+      createdSet = new Set();
+      destroyedSet = new Set();
+      // Retroactively add snapshots to existing matching archetypes
+      for (const arch of archetypes.values()) {
+        if ((arch.key & trackFilter) !== 0 && !arch.snapshots) {
+          arch.snapshots = new Map();
+          arch.snapshotEntityIds = [];
+          arch.snapshotCount = 0;
+          for (const [t, store] of arch.components) {
+            if (store) {
+              arch.snapshots.set(t, createSnapshotStore(store._schema, arch.capacity));
+            }
+          }
+          trackedArchetypes.push(arch);
+        }
+      }
+    },
+
+    flushChanges() {
+      const result = { created: createdSet, destroyed: destroyedSet };
+      createdSet = new Set();
+      destroyedSet = new Set();
+      return result;
+    },
+
+    flushSnapshots() {
+      for (let a = 0; a < trackedArchetypes.length; a++) {
+        const arch = trackedArchetypes[a];
+        const count = arch.count;
+        // Copy entityIds
+        const eids = arch.entityIds;
+        const snapEids = arch.snapshotEntityIds;
+        for (let i = 0; i < count; i++) snapEids[i] = eids[i];
+        arch.snapshotCount = count;
+        // Copy all field arrays via .set() (one memcpy per field)
+        for (const [type, store] of arch.components) {
+          if (!store) continue;
+          const snap = arch.snapshots.get(type);
+          if (!snap) continue;
+          for (const field in store._schema) {
+            const src = store[field];
+            const dst = snap[field];
+            if (src.set) {
+              // TypedArray — use .set() for memcpy, only copy active region
+              dst.set(src.subarray(0, count));
+            } else {
+              // Regular Array (string fields)
+              for (let i = 0; i < count; i++) dst[i] = src[i];
+            }
+          }
+        }
+      }
+    },
+
     serialize(symbolToName, stripComponents = [], skipEntitiesWith = [], { serializers } = {}) {
       const stripSymbols = new Set(stripComponents.map(toSym));
       const skipSymbols = new Set(skipEntitiesWith.map(toSym));

package/src/index.d.ts

@@ -41,9 +41,13 @@ type TypedArray = Float32Array | Float64Array | Int8Array | Int16Array | Int32Ar
 
 // === ArchetypeView (forEach callback) ===
 export interface ArchetypeView {
+  readonly id: number;
   readonly entityIds: EntityId[];
   readonly count: number;
+  readonly snapshotEntityIds: EntityId[] | null;
+  readonly snapshotCount: number;
   field(ref: FieldRef<any>): TypedArray | unknown[] | undefined;
+  snapshot(ref: FieldRef<any>): TypedArray | unknown[] | undefined;
 }
 
 // === Serialize/Deserialize ===
@@ -76,6 +80,9 @@ export interface EntityManager {
   createEntityWith(...args: unknown[]): EntityId;
   count(include: ComponentDef[], exclude?: ComponentDef[]): number;
   forEach(include: ComponentDef[], callback: (view: ArchetypeView) => void, exclude?: ComponentDef[]): void;
+  enableTracking(filterComponent: ComponentDef): void;
+  flushChanges(): { created: Set<EntityId>; destroyed: Set<EntityId> };
+  flushSnapshots(): void;
   serialize(
     symbolToName: Map<symbol, string>,
     stripComponents?: ComponentDef[],

package/.claude/settings.local.json

@@ -1,32 +0,0 @@
-{
-  "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:*)"
-    ]
-  }
-}