archetype-ecs 1.4.2 → 1.5.0

package/dist/{src/EntityManager.js → EntityManager.js}

@@ -1,4 +1,6 @@
 import { TYPED, componentSchemas, toSym } from './ComponentRegistry.js';
+import { WasmArena } from './WasmArena.js';
+import { instantiateKernelsSync, isWasmSimdAvailable } from './wasm-kernels.js';
 const INITIAL_CAPACITY = 64;
 // ── Array-based bitmask helpers ──────────────────────────
 function slotsNeeded(bitCount) {
@@ -57,84 +59,101 @@ function unpackSpec(spec) {
         return spec;
     return [spec, 0];
 }
-function createSoAStore(schema, capacity) {
-    const store = { [TYPED]: true, _schema: schema, _capacity: capacity, _arraySizes: {} };
+function createSoAStore(schema, capacity, arena) {
+    const fields = {};
+    const arraySizes = {};
     for (const [field, spec] of Object.entries(schema)) {
         const [Ctor, size] = unpackSpec(spec);
-        if (size > 0) {
-            store[field] = new Ctor(capacity * size);
-            store._arraySizes[field] = size;
+        const count = size > 0 ? capacity * size : capacity;
+        if (size > 0)
+            arraySizes[field] = size;
+        if (arena && Ctor !== Array) {
+            const NumCtor = Ctor;
+            const offset = arena.alloc(count * NumCtor.BYTES_PER_ELEMENT);
+            arena.createView(NumCtor, offset, count, fields, field);
         }
         else {
-            store[field] = new Ctor(capacity);
+            fields[field] = new Ctor(count);
         }
     }
-    return store;
+    return { [TYPED]: true, _schema: schema, _capacity: capacity, _arraySizes: arraySizes, _fields: fields };
 }
-function growSoAStore(store, newCapacity) {
+function growSoAStore(store, newCapacity, arena) {
     store._capacity = newCapacity;
     for (const [field, spec] of Object.entries(store._schema)) {
         const [Ctor, size] = unpackSpec(spec);
-        const old = store[field];
+        const old = store._fields[field];
         const allocSize = size > 0 ? newCapacity * size : newCapacity;
-        store[field] = new Ctor(allocSize);
-        if (Ctor === Array) {
-            for (let i = 0; i < old.length; i++)
-                store[field][i] = old[i];
+        if (arena && Ctor !== Array) {
+            const NumCtor = Ctor;
+            const offset = arena.alloc(allocSize * NumCtor.BYTES_PER_ELEMENT);
+            arena.updateView(store._fields, field, offset, NumCtor, allocSize);
+            store._fields[field].set(old);
         }
         else {
-            store[field].set(old);
+            const grown = new Ctor(allocSize);
+            if (Ctor === Array) {
+                for (let i = 0; i < old.length; i++)
+                    grown[i] = old[i];
+            }
+            else {
+                grown.set(old);
+            }
+            store._fields[field] = grown;
         }
     }
 }
 function soaWrite(store, idx, data) {
     if (!data) {
         for (const field in store._schema) {
+            const arr = store._fields[field];
             const size = store._arraySizes[field] || 0;
             if (size > 0) {
                 const base = idx * size;
                 for (let j = 0; j < size; j++)
-                    store[field][base + j] = 0;
+                    arr[base + j] = 0;
             }
             else {
-                store[field][idx] = 0;
+                arr[idx] = 0;
             }
         }
         return;
     }
     for (const field in store._schema) {
+        const arr = store._fields[field];
         const size = store._arraySizes[field] || 0;
         if (size > 0) {
             const base = idx * size;
             const src = data[field];
             if (src) {
                 for (let j = 0; j < size; j++) {
-                    store[field][base + j] = src[j] ?? 0;
+                    arr[base + j] = (src[j] ?? 0);
                 }
             }
         }
         else {
-            store[field][idx] = data[field];
+            arr[idx] = data[field];
         }
     }
 }
 function soaRead(store, idx) {
     const obj = {};
     for (const field in store._schema) {
+        const arr = store._fields[field];
         const size = store._arraySizes[field] || 0;
         if (size > 0) {
             const base = idx * size;
-            obj[field] = Array.from(store[field].subarray(base, base + size));
+            obj[field] = Array.from(arr.subarray(base, base + size));
         }
         else {
-            obj[field] = store[field][idx];
+            obj[field] = arr[idx];
         }
     }
     return obj;
 }
 function soaSwap(store, idxA, idxB) {
     for (const field in store._schema) {
-        const arr = store[field];
+        const arr = store._fields[field];
         const size = store._arraySizes[field] || 0;
         if (size > 0) {
             const baseA = idxA * size;
@@ -152,29 +171,51 @@ function soaSwap(store, idxA, idxB) {
         }
     }
 }
-function createSnapshotStore(schema, capacity) {
+function createSnapshotStore(schema, capacity, arena) {
     const snap = {};
     for (const [field, spec] of Object.entries(schema)) {
         const [Ctor, size] = unpackSpec(spec);
-        snap[field] = new Ctor(size > 0 ? capacity * size : capacity);
+        const count = size > 0 ? capacity * size : capacity;
+        if (arena && Ctor !== Array) {
+            const NumCtor = Ctor;
+            const offset = arena.alloc(count * NumCtor.BYTES_PER_ELEMENT);
+            arena.createView(NumCtor, offset, count, snap, field);
+        }
+        else {
+            snap[field] = new Ctor(count);
+        }
     }
     return snap;
 }
-function growSnapshotStore(snap, schema, newCapacity) {
+function growSnapshotStore(snap, schema, newCapacity, arena) {
     for (const [field, spec] of Object.entries(schema)) {
         const [Ctor, size] = unpackSpec(spec);
         const old = snap[field];
-        snap[field] = new Ctor(size > 0 ? newCapacity * size : newCapacity);
-        if (Ctor === Array) {
-            for (let i = 0; i < old.length; i++)
-                snap[field][i] = old[i];
+        const allocSize = size > 0 ? newCapacity * size : newCapacity;
+        if (arena && Ctor !== Array) {
+            const NumCtor = Ctor;
+            const offset = arena.alloc(allocSize * NumCtor.BYTES_PER_ELEMENT);
+            arena.updateView(snap, field, offset, NumCtor, allocSize);
+            snap[field].set(old);
         }
         else {
-            snap[field].set(old);
+            const grown = new Ctor(allocSize);
+            if (Ctor === Array) {
+                for (let i = 0; i < old.length; i++)
+                    grown[i] = old[i];
+            }
+            else {
+                grown.set(old);
+            }
+            snap[field] = grown;
         }
     }
 }
-export function createEntityManager() {
+// ── Entity Manager ───────────────────────────────────────
+export function createEntityManager(options) {
+    const useWasm = options?.wasm ?? isWasmSimdAvailable();
+    const arena = useWasm ? new WasmArena() : undefined;
+    const kernels = arena ? instantiateKernelsSync(arena.memory) : null;
     let nextId = 1;
     let nextArchId = 1;
     const allEntityIds = new Set();
@@ -183,7 +224,7 @@ export function createEntityManager() {
     let destroyedSet = null;
     const trackedArchetypes = [];
     let hooks = null;
-    // Deferred structural changes during forEach iteration
+    const removedData = new Map();
     let iterating = 0;
     const deferred = [];
     const componentBitIndex = new Map();
@@ -230,10 +271,10 @@ export function createEntityManager() {
             };
             for (const t of types) {
                 const schema = componentSchemas.get(t);
-                const store = schema ? createSoAStore(schema, INITIAL_CAPACITY) : null;
+                const store = schema ? createSoAStore(schema, INITIAL_CAPACITY, arena) : null;
                 arch.components.set(t, store);
                 if (tracked && store) {
-                    arch.snapshots.set(t, createSnapshotStore(schema, INITIAL_CAPACITY));
+                    arch.snapshots.set(t, createSnapshotStore(schema, INITIAL_CAPACITY, arena));
                 }
             }
             archetypes.set(key, arch);
@@ -250,11 +291,11 @@ export function createEntityManager() {
         arch.capacity = newCap;
         for (const [type, store] of arch.components) {
             if (store) {
-                growSoAStore(store, newCap);
+                growSoAStore(store, newCap, arena);
                 if (arch.snapshots) {
                     const snap = arch.snapshots.get(type);
                     if (snap)
-                        growSnapshotStore(snap, store._schema, newCap);
+                        growSnapshotStore(snap, store._schema, newCap, arena);
                 }
             }
         }
@@ -266,7 +307,7 @@ export function createEntityManager() {
         for (const t of arch.types) {
             const store = arch.components.get(t);
             if (store)
-                soaWrite(store, idx, componentMap[t]);
+                soaWrite(store, idx, componentMap.get(t));
         }
         arch.entityToIndex.set(entityId, idx);
         arch.count++;
@@ -313,7 +354,6 @@ export function createEntityManager() {
         queryCache.set(queryStr, { version: queryCacheVersion, archetypes: matching });
         return matching;
     }
-    // ── Internal structural change implementations ──────────
     function doDestroyEntity(id) {
         const arch = entityArchetype.get(id);
         if (arch) {
@@ -323,6 +363,22 @@ export function createEntityManager() {
                     if (pending)
                         pending.push(id);
                 }
+                if (hooks.removeCbs.size > 0) {
+                    const idx = arch.entityToIndex.get(id);
+                    let entitySnap;
+                    for (const type of arch.types) {
+                        if (hooks.removeCbs.has(type)) {
+                            const store = arch.components.get(type);
+                            if (store) {
+                                if (!entitySnap) {
+                                    entitySnap = new Map();
+                                    removedData.set(id, entitySnap);
+                                }
+                                entitySnap.set(type, soaRead(store, idx));
+                            }
+                        }
+                    }
+                }
             }
             if (destroyedSet && trackFilter && maskOverlaps(arch.key, trackFilter))
                 destroyedSet.add(id);
@@ -335,7 +391,7 @@ export function createEntityManager() {
         const arch = entityArchetype.get(entityId);
         if (!arch) {
             const newArch = getOrCreateArchetype([type]);
-            addToArchetype(newArch, entityId, { [type]: data });
+            addToArchetype(newArch, entityId, new Map([[type, data]]));
             if (hooks) {
                 const pending = hooks.pendingAdd.get(type);
                 if (pending)
@@ -354,9 +410,9 @@ export function createEntityManager() {
         const newTypes = [...arch.types, type];
         const newArch = getOrCreateArchetype(newTypes);
         const idx = arch.entityToIndex.get(entityId);
-        const map = { [type]: data };
+        const map = new Map([[type, data]]);
         for (const t of arch.types) {
-            map[t] = readComponentData(arch, t, idx);
+            map.set(t, readComponentData(arch, t, idx));
         }
         removeFromArchetype(arch, entityId);
         addToArchetype(newArch, entityId, map);
@@ -375,6 +431,15 @@ export function createEntityManager() {
             const pending = hooks.pendingRemove.get(type);
             if (pending)
                 pending.push(entityId);
+            if (hooks.removeCbs.has(type)) {
+                const store = arch.components.get(type);
+                if (store) {
+                    const idx = arch.entityToIndex.get(entityId);
+                    if (!removedData.has(entityId))
+                        removedData.set(entityId, new Map());
+                    removedData.get(entityId).set(type, soaRead(store, idx));
+                }
+            }
         }
         if (destroyedSet && trackFilter && maskOverlaps(arch.key, trackFilter))
             destroyedSet.add(entityId);
@@ -389,35 +454,31 @@ export function createEntityManager() {
         }
         const newArch = getOrCreateArchetype(newTypes);
         const idx = arch.entityToIndex.get(entityId);
-        const map = {};
+        const map = new Map();
         for (const t of newTypes) {
-            map[t] = readComponentData(arch, t, idx);
+            map.set(t, readComponentData(arch, t, idx));
         }
         removeFromArchetype(arch, entityId);
         addToArchetype(newArch, entityId, map);
     }
     function flushDeferred() {
-        // Process deferred ops in order. New ops may be added during flush
-        // (e.g. hooks triggering more structural changes), so use index loop.
-        while (deferred.length > 0) {
-            const ops = deferred.splice(0);
-            for (let i = 0; i < ops.length; i++) {
-                const op = ops[i];
-                switch (op.kind) {
-                    case 'add':
-                        doAddComponent(op.entityId, op.comp, op.data);
-                        break;
-                    case 'remove':
-                        doRemoveComponent(op.entityId, op.comp);
-                        break;
-                    case 'destroy':
-                        doDestroyEntity(op.entityId);
-                        break;
-                }
+        const ops = deferred.splice(0);
+        for (const op of ops) {
+            switch (op.kind) {
+                case 'add':
+                    doAddComponent(op.entityId, op.comp, op.data);
+                    break;
+                case 'remove':
+                    doRemoveComponent(op.entityId, op.comp);
+                    break;
+                case 'destroy':
+                    doDestroyEntity(op.entityId);
+                    break;
             }
         }
     }
     return {
+        wasmMemory: arena ? arena.memory : null,
         createEntity() {
             const id = nextId++;
             allEntityIds.add(id);
@@ -459,27 +520,39 @@ export function createEntityManager() {
         getComponent(entityId, comp) {
             const type = toSym(comp);
             const arch = entityArchetype.get(entityId);
-            if (!arch)
-                return undefined;
-            const idx = arch.entityToIndex.get(entityId);
-            if (idx === undefined)
-                return undefined;
-            return readComponentData(arch, type, idx);
+            if (arch) {
+                const idx = arch.entityToIndex.get(entityId);
+                if (idx !== undefined)
+                    return readComponentData(arch, type, idx);
+            }
+            // Fallback: check recently-removed data (accessible during @OnRemoved hooks)
+            const removed = removedData.get(entityId);
+            if (removed)
+                return removed.get(type);
+            return undefined;
         },
         get(entityId, fieldRef) {
             const arch = entityArchetype.get(entityId);
-            if (!arch)
-                return undefined;
-            const store = arch.components.get(fieldRef._sym);
-            if (!store)
-                return undefined;
-            const idx = arch.entityToIndex.get(entityId);
-            const size = store._arraySizes[fieldRef._field] || 0;
-            if (size > 0) {
-                const base = idx * size;
-                return store[fieldRef._field].subarray(base, base + size);
+            if (arch) {
+                const store = arch.components.get(fieldRef._sym);
+                if (store) {
+                    const idx = arch.entityToIndex.get(entityId);
+                    const size = store._arraySizes[fieldRef._field] || 0;
+                    if (size > 0) {
+                        const base = idx * size;
+                        return store._fields[fieldRef._field].subarray(base, base + size);
+                    }
+                    return store._fields[fieldRef._field][idx];
+                }
             }
-            return store[fieldRef._field][idx];
+            // Fallback: check recently-removed data (accessible during @OnRemoved hooks)
+            const removed = removedData.get(entityId);
+            if (removed) {
+                const compData = removed.get(fieldRef._sym);
+                if (compData)
+                    return compData[fieldRef._field];
+            }
+            return undefined;
         },
         set(entityId, fieldRef, value) {
             const arch = entityArchetype.get(entityId);
@@ -491,10 +564,10 @@ export function createEntityManager() {
             const idx = arch.entityToIndex.get(entityId);
             const size = store._arraySizes[fieldRef._field] || 0;
             if (size > 0) {
-                store[fieldRef._field].set(value, idx * size);
+                store._fields[fieldRef._field].set(value, idx * size);
             }
             else {
-                store[fieldRef._field][idx] = value;
+                store._fields[fieldRef._field][idx] = value;
             }
         },
         hasComponent(entityId, comp) {
@@ -521,11 +594,11 @@ export function createEntityManager() {
             const id = nextId++;
             allEntityIds.add(id);
             const types = [];
-            const map = {};
+            const map = new Map();
             for (let i = 0; i < args.length; i += 2) {
                 const sym = toSym(args[i]);
                 types.push(sym);
-                map[sym] = args[i + 1];
+                map.set(sym, args[i + 1]);
             }
             const arch = getOrCreateArchetype(types);
             addToArchetype(arch, id, map);
@@ -564,24 +637,49 @@ export function createEntityManager() {
                         snapshotEntityIds: arch.snapshotEntityIds,
                         snapshotCount: arch.snapshotCount,
                         field(ref) {
-                            const sym = ref._sym || ref;
-                            const store = arch.components.get(sym);
+                            const store = arch.components.get(ref._sym);
                             if (!store)
                                 return undefined;
-                            return store[ref._field];
+                            return store._fields[ref._field];
                         },
                         fieldStride(ref) {
-                            const sym = ref._sym || ref;
-                            const store = arch.components.get(sym);
+                            const store = arch.components.get(ref._sym);
                             if (!store)
                                 return 1;
                             return store._arraySizes[ref._field] || 1;
                         },
+                        fieldOffset(ref) {
+                            if (!arena)
+                                return -1;
+                            const store = arch.components.get(ref._sym);
+                            if (!store)
+                                return -1;
+                            const arr = store._fields[ref._field];
+                            if (!arr || arr instanceof Array)
+                                return -1;
+                            return arr.byteOffset;
+                        },
+                        fieldAdd(target, source) {
+                            const tStore = arch.components.get(target._sym);
+                            const sStore = arch.components.get(source._sym);
+                            if (!tStore || !sStore)
+                                return;
+                            const dst = tStore._fields[target._field];
+                            const src = sStore._fields[source._field];
+                            const stride = tStore._arraySizes[target._field] || 1;
+                            const n = arch.count * stride;
+                            if (kernels && dst instanceof Float32Array && src instanceof Float32Array) {
+                                kernels.add_f32(dst.byteOffset, src.byteOffset, n);
+                            }
+                            else {
+                                for (let i = 0; i < n; i++)
+                                    dst[i] = (dst[i] + src[i]);
+                            }
+                        },
                         snapshot(ref) {
                             if (!snaps)
                                 return undefined;
-                            const sym = ref._sym || ref;
-                            const snap = snaps.get(sym);
+                            const snap = snaps.get(ref._sym);
                             if (!snap)
                                 return undefined;
                             return snap[ref._field];
@@ -611,7 +709,7 @@ export function createEntityManager() {
                     arch.snapshotCount = 0;
                     for (const [t, store] of arch.components) {
                         if (store) {
-                            arch.snapshots.set(t, createSnapshotStore(store._schema, arch.capacity));
+                            arch.snapshots.set(t, createSnapshotStore(store._schema, arch.capacity, arena));
                         }
                     }
                     trackedArchetypes.push(arch);
@@ -640,11 +738,11 @@ export function createEntityManager() {
                     if (!snap)
                         continue;
                     for (const field in store._schema) {
-                        const src = store[field];
+                        const src = store._fields[field];
                         const dst = snap[field];
                         const size = store._arraySizes[field] || 0;
                         const len = size > 0 ? count * size : count;
-                        if (src.set) {
+                        if ('set' in src) {
                             dst.set(src.subarray(0, len));
                         }
                         else {
@@ -739,6 +837,9 @@ export function createEntityManager() {
                 pending.length = 0;
             }
         },
+        commitRemovals() {
+            removedData.clear();
+        },
         serialize(symbolToName, stripComponents = [], skipEntitiesWith = [], { serializers } = {}) {
             const stripSymbols = new Set(stripComponents.map(toSym));
             const skipSymbols = new Set(skipEntitiesWith.map(toSym));
@@ -809,7 +910,7 @@ export function createEntityManager() {
             const entityComponents = new Map();
             for (const id of data.entities) {
                 allEntityIds.add(id);
-                entityComponents.set(id, {});
+                entityComponents.set(id, new Map());
             }
             for (const [name, store] of Object.entries(data.components)) {
                 const entry = nameToSymbol[name];
@@ -823,16 +924,16 @@ export function createEntityManager() {
                     if (!obj)
                         continue;
                     if (customDeserializer) {
-                        obj[sym] = customDeserializer(compData);
+                        obj.set(sym, customDeserializer(compData));
                     }
                     else {
-                        obj[sym] = compData;
+                        obj.set(sym, compData);
                     }
                 }
             }
             const groupedByKey = new Map();
             for (const [entityId, compMap] of entityComponents) {
-                const types = Object.getOwnPropertySymbols(compMap);
+                const types = [...compMap.keys()];
                 if (types.length === 0)
                     continue;
                 const key = maskKey(computeMask(types));
@@ -842,7 +943,7 @@ export function createEntityManager() {
                 groupedByKey.get(key).push({ entityId, compMap });
             }
             for (const [, entries] of groupedByKey) {
-                const types = Object.getOwnPropertySymbols(entries[0].compMap);
+                const types = [...entries[0].compMap.keys()];
                 const arch = getOrCreateArchetype(types);
                 for (const { entityId, compMap } of entries) {
                     addToArchetype(arch, entityId, compMap);

package/dist/{src/System.d.ts → System.d.ts}

@@ -14,6 +14,8 @@ export declare class System {
     _registerHook(kind: 'add' | 'remove', types: ComponentDef[], handler: (id: EntityId) => void): void;
     forEach(types: ComponentDef[], callback: (view: ArchetypeView) => void, exclude?: ComponentDef[]): void;
     tick?(): void;
+    /** Process hooks and tick without clearing removed-data snapshots. */
+    _runCore(): void;
     run(): void;
     dispose(): void;
 }
@@ -26,6 +28,8 @@ export interface SystemContext {
 export type FunctionalSystemConstructor = (sys: SystemContext) => (() => void) | void;
 export interface FunctionalSystem {
     (): void;
+    /** @internal Process hooks and tick without clearing removed-data snapshots. */
+    _runCore(): void;
     dispose(): void;
 }
 export declare function createSystem(em: EntityManager, constructor: FunctionalSystemConstructor): FunctionalSystem;

package/dist/{src/System.js → System.js}

@@ -47,7 +47,8 @@ export class System {
     forEach(types, callback, exclude) {
         this.em.forEach(types, callback, exclude);
     }
-    run() {
+    /** Process hooks and tick without clearing removed-data snapshots. */
+    _runCore() {
         for (const hook of this._hooks) {
             for (const id of hook.buffer)
                 hook.handler(id);
@@ -56,6 +57,10 @@ export class System {
         if (this.tick)
             this.tick();
     }
+    run() {
+        this._runCore();
+        this.em.commitRemovals();
+    }
     dispose() {
         for (const unsub of this._unsubs)
             unsub();
@@ -101,7 +106,7 @@ export function createSystem(em, constructor) {
         },
     };
     const tick = constructor(sys);
-    function system() {
+    function runCore() {
         for (const hook of hooks) {
             for (const id of hook.buffer)
                 hook.callback(id);
@@ -110,6 +115,11 @@ export function createSystem(em, constructor) {
         if (tick)
             tick();
     }
+    function system() {
+        runCore();
+        em.commitRemovals();
+    }
+    system._runCore = runCore;
     system.dispose = function () {
         for (const hook of hooks) {
             for (const unsub of hook.unsubs)
@@ -119,17 +129,27 @@ export function createSystem(em, constructor) {
     };
     return system;
 }
+function isSystemClass(entry) {
+    let proto = entry.prototype;
+    while (proto) {
+        proto = Object.getPrototypeOf(proto);
+        if (proto === System.prototype)
+            return true;
+    }
+    return false;
+}
 export function createSystems(em, entries) {
     const systems = entries.map(Entry => {
-        if ('prototype' in Entry && Entry.prototype instanceof System) {
+        if (isSystemClass(Entry)) {
             return new Entry(em);
         }
         const sys = createSystem(em, Entry);
-        return { run: sys, dispose: sys.dispose };
+        return { _runCore: sys._runCore, dispose: sys.dispose };
     });
     function pipeline() {
         for (let i = 0; i < systems.length; i++)
-            systems[i].run();
+            systems[i]._runCore();
+        em.commitRemovals();
     }
     pipeline.dispose = function () {
         for (let i = 0; i < systems.length; i++)

package/dist/WasmArena.d.ts

@@ -0,0 +1,13 @@
+import type { SoAArrayValue } from './EntityManager.js';
+export type NumericTypedArrayConstructor = typeof Float32Array | typeof Float64Array | typeof Int8Array | typeof Int16Array | typeof Int32Array | typeof Uint8Array | typeof Uint16Array | typeof Uint32Array;
+export declare class WasmArena {
+    memory: WebAssembly.Memory;
+    private nextOffset;
+    private views;
+    constructor(initialPages?: number, maxPages?: number);
+    alloc(byteLength: number): number;
+    createView<T extends SoAArrayValue>(Ctor: NumericTypedArrayConstructor, offset: number, count: number, fields: Record<string, SoAArrayValue>, field: string): T;
+    private handleGrow;
+    /** Update a registered view to point to a new (larger) allocation. */
+    updateView(fields: Record<string, SoAArrayValue>, field: string, offset: number, Ctor: NumericTypedArrayConstructor, count: number): void;
+}