archetype-ecs 1.4.2 → 1.5.0

package/src/System.ts

@@ -66,7 +66,8 @@ export class System {
 
   tick?(): void;
 
-  run(): void {
+  /** Process hooks and tick without clearing removed-data snapshots. */
+  _runCore(): void {
     for (const hook of this._hooks) {
       for (const id of hook.buffer) hook.handler(id);
       hook.buffer.clear();
@@ -74,6 +75,11 @@ export class System {
     if (this.tick) this.tick();
   }
 
+  run(): void {
+    this._runCore();
+    this.em.commitRemovals();
+  }
+
   dispose(): void {
     for (const unsub of this._unsubs) unsub();
     this._unsubs.length = 0;
@@ -101,6 +107,8 @@ interface FunctionalHook {
 
 export interface FunctionalSystem {
   (): void;
+  /** @internal Process hooks and tick without clearing removed-data snapshots. */
+  _runCore(): void;
   dispose(): void;
 }
 
@@ -108,7 +116,7 @@ export function createSystem(em: EntityManager, constructor: FunctionalSystemCon
   const hooks: FunctionalHook[] = [];
 
   const sys: SystemContext = {
-    onAdded(...args: any[]) {
+    onAdded(...args: [...ComponentDef[], HookCallback]) {
       const callback = args[args.length - 1] as HookCallback;
       const types = args.slice(0, -1) as ComponentDef[];
       const buffer = new Set<EntityId>();
@@ -127,7 +135,7 @@ export function createSystem(em: EntityManager, constructor: FunctionalSystemCon
       hooks.push({ unsubs, buffer, callback });
     },
 
-    onRemoved(...args: any[]) {
+    onRemoved(...args: [...ComponentDef[], HookCallback]) {
       const callback = args[args.length - 1] as HookCallback;
       const types = args.slice(0, -1) as ComponentDef[];
       const buffer = new Set<EntityId>();
@@ -150,7 +158,7 @@ export function createSystem(em: EntityManager, constructor: FunctionalSystemCon
 
   const tick = constructor(sys);
 
-  function system() {
+  function runCore() {
     for (const hook of hooks) {
       for (const id of hook.buffer) hook.callback(id);
       hook.buffer.clear();
@@ -158,6 +166,13 @@ export function createSystem(em: EntityManager, constructor: FunctionalSystemCon
     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) unsub();
@@ -171,7 +186,7 @@ export function createSystem(em: EntityManager, constructor: FunctionalSystemCon
 // ── Activator ────────────────────────────────────────────
 
 interface Runnable {
-  run(): void;
+  _runCore(): void;
   dispose(): void;
 }
 
@@ -180,17 +195,27 @@ export interface Pipeline {
   dispose(): void;
 }
 
+function isSystemClass(entry: Function): entry is new (em: EntityManager) => System {
+  let proto = entry.prototype;
+  while (proto) {
+    proto = Object.getPrototypeOf(proto);
+    if (proto === System.prototype) return true;
+  }
+  return false;
+}
+
 export function createSystems(em: EntityManager, entries: (FunctionalSystemConstructor | (new (em: EntityManager) => System))[]): Pipeline {
   const systems: Runnable[] = entries.map(Entry => {
-    if ('prototype' in Entry && Entry.prototype instanceof System) {
-      return new (Entry as new (em: EntityManager) => System)(em);
+    if (isSystemClass(Entry)) {
+      return new Entry(em);
     }
     const sys = createSystem(em, Entry as FunctionalSystemConstructor);
-    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();
+    for (let i = 0; i < systems.length; i++) systems[i]._runCore();
+    em.commitRemovals();
   }
 
   pipeline.dispose = function () {

package/src/WasmArena.ts

@@ -0,0 +1,83 @@
+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;
+
+interface ViewRegistration {
+  fields: Record<string, SoAArrayValue>;
+  field: string;
+  offset: number;
+  Ctor: NumericTypedArrayConstructor;
+  count: number;
+}
+
+const ALIGN = 16; // 16-byte alignment for SIMD
+
+export class WasmArena {
+  memory: WebAssembly.Memory;
+  private nextOffset: number = 0;
+  private views: ViewRegistration[] = [];
+
+  constructor(initialPages = 2048, maxPages = 16384) {
+    this.memory = new WebAssembly.Memory({ initial: initialPages, maximum: maxPages });
+  }
+
+  alloc(byteLength: number): number {
+    // Align up to 16 bytes
+    const aligned = (this.nextOffset + ALIGN - 1) & ~(ALIGN - 1);
+    const end = aligned + byteLength;
+
+    if (end > this.memory.buffer.byteLength) {
+      const needed = Math.ceil((end - this.memory.buffer.byteLength) / 65536);
+      this.memory.grow(needed);
+      this.handleGrow();
+    }
+
+    this.nextOffset = end;
+    return aligned;
+  }
+
+  createView<T extends SoAArrayValue>(
+    Ctor: NumericTypedArrayConstructor,
+    offset: number,
+    count: number,
+    fields: Record<string, SoAArrayValue>,
+    field: string
+  ): T {
+    const view = new Ctor(this.memory.buffer, offset, count) as unknown as T;
+    this.views.push({ fields, field, offset, Ctor, count });
+    fields[field] = view;
+    return view;
+  }
+
+  private handleGrow(): void {
+    const buf = this.memory.buffer;
+    for (const reg of this.views) {
+      reg.fields[reg.field] = new reg.Ctor(buf, reg.offset, reg.count);
+    }
+  }
+
+  /** 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 {
+    // Find and update the existing registration
+    for (const reg of this.views) {
+      if (reg.fields === fields && reg.field === field) {
+        reg.offset = offset;
+        reg.Ctor = Ctor;
+        reg.count = count;
+        fields[field] = new Ctor(this.memory.buffer, offset, count);
+        return;
+      }
+    }
+    // Not found — register as new
+    this.createView(Ctor, offset, count, fields, field);
+  }
+}

package/src/index.ts

@@ -1,21 +1,26 @@
 export { createEntityManager } from './EntityManager.js';
-export type { EntityId, FieldRef, ArchetypeView, EntityManager, SerializedData } from './EntityManager.js';
+export type { EntityId, ArchetypeView, EntityManager, SerializedData } from './EntityManager.js';
 export { createSystem, createSystems, System, OnAdded, OnRemoved } from './System.js';
 export type { SystemContext, FunctionalSystemConstructor, FunctionalSystem, Pipeline } from './System.js';
 export { profiler } from './Profiler.js';
 export type { Profiler, ProfilerEntry } from './Profiler.js';
 export { TYPED, componentSchemas, parseTypeSpec } from './ComponentRegistry.js';
-export type { ComponentDef, TypeSpec } from './ComponentRegistry.js';
+export type { ComponentDef, FieldRef, TypeSpec } from './ComponentRegistry.js';
+export { WasmArena } from './WasmArena.js';
+export { instantiateKernels, isWasmSimdAvailable } from './wasm-kernels.js';
+export type { IterateKernels } from './wasm-kernels.js';
 
-import { parseTypeSpec, componentSchemas, type ComponentDef, type TypeSpec } from './ComponentRegistry.js';
-import type { FieldRef } from './EntityManager.js';
+import { parseTypeSpec, componentSchemas, type ComponentDef, type FieldRef, type TypeSpec } from './ComponentRegistry.js';
 
+// Tag component (no fields)
 export function component(name: string): ComponentDef;
-export function component<F extends readonly string[]>(name: string, type: string, fields: F): ComponentDef & { readonly [K in F[number]]: FieldRef };
-export function component<S extends Record<string, string>>(name: string, schema: S): ComponentDef & { readonly [K in keyof S]: FieldRef };
-export function component(name: string, typeOrSchema?: string | Record<string, string>, fields?: string[]): ComponentDef {
+// Uniform type with field list
+export function component<const F extends readonly string[]>(name: string, type: string, fields: F): ComponentDef<F[number]>;
+// Schema object with mixed types
+export function component<S extends Record<string, string>>(name: string, schema: S): ComponentDef<Extract<keyof S, string>>;
+export function component(name: string, typeOrSchema?: string | Record<string, string>, fields?: string[]): ComponentDef<string> {
   const sym = Symbol(name);
-  const comp: any = { _sym: sym, _name: name };
+  const comp: Record<string, unknown> = { _sym: sym, _name: name };
 
   let schema: Record<string, TypeSpec> | undefined;
 
@@ -24,13 +29,13 @@ export function component(name: string, typeOrSchema?: string | Record<string, s
     schema = {};
     for (const f of fields) {
       schema[f] = spec;
-      comp[f] = { _sym: sym, _field: f };
+      comp[f] = { _sym: sym, _field: f } satisfies FieldRef;
     }
   } else if (typeOrSchema && typeof typeOrSchema === 'object') {
     schema = {};
     for (const [field, type] of Object.entries(typeOrSchema)) {
       schema[field] = parseTypeSpec(type);
-      comp[field] = { _sym: sym, _field: field };
+      comp[field] = { _sym: sym, _field: field } satisfies FieldRef;
     }
   }
 
@@ -38,5 +43,5 @@ export function component(name: string, typeOrSchema?: string | Record<string, s
     componentSchemas.set(sym, schema);
   }
 
-  return comp;
+  return comp as ComponentDef<string>;
 }

package/src/iterate.wat

@@ -0,0 +1,135 @@
+(module
+  (memory (import "env" "memory") 1)
+
+  ;; Scalar loop: px[i] += vx[i]; py[i] += vy[i]
+  ;; params: byte offsets for px, py, vx, vy arrays + element count
+  (func (export "iterate_scalar")
+    (param $px i32) (param $py i32) (param $vx i32) (param $vy i32) (param $count i32)
+    (local $i i32)
+    (local $off i32)
+    (local.set $i (i32.const 0))
+    (block $break
+      (loop $loop
+        (br_if $break (i32.ge_u (local.get $i) (local.get $count)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        ;; px[i] += vx[i]
+        (f32.store
+          (i32.add (local.get $px) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $px) (local.get $off)))
+            (f32.load (i32.add (local.get $vx) (local.get $off)))
+          )
+        )
+        ;; py[i] += vy[i]
+        (f32.store
+          (i32.add (local.get $py) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $py) (local.get $off)))
+            (f32.load (i32.add (local.get $vy) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 1)))
+        (br $loop)
+      )
+    )
+  )
+
+  ;; SIMD loop: processes 4 floats at a time using v128 / f32x4
+  (func (export "iterate_simd")
+    (param $px i32) (param $py i32) (param $vx i32) (param $vy i32) (param $count i32)
+    (local $i i32)
+    (local $off i32)
+    (local $end4 i32)
+    ;; end4 = count & ~3 (round down to multiple of 4)
+    (local.set $end4 (i32.and (local.get $count) (i32.const -4)))
+    ;; SIMD loop: 4 elements per iteration
+    (local.set $i (i32.const 0))
+    (block $break
+      (loop $loop
+        (br_if $break (i32.ge_u (local.get $i) (local.get $end4)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        ;; px[i..i+4] += vx[i..i+4]
+        (v128.store
+          (i32.add (local.get $px) (local.get $off))
+          (f32x4.add
+            (v128.load (i32.add (local.get $px) (local.get $off)))
+            (v128.load (i32.add (local.get $vx) (local.get $off)))
+          )
+        )
+        ;; py[i..i+4] += vy[i..i+4]
+        (v128.store
+          (i32.add (local.get $py) (local.get $off))
+          (f32x4.add
+            (v128.load (i32.add (local.get $py) (local.get $off)))
+            (v128.load (i32.add (local.get $vy) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 4)))
+        (br $loop)
+      )
+    )
+    ;; Scalar remainder
+    (block $break2
+      (loop $loop2
+        (br_if $break2 (i32.ge_u (local.get $i) (local.get $count)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        (f32.store
+          (i32.add (local.get $px) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $px) (local.get $off)))
+            (f32.load (i32.add (local.get $vx) (local.get $off)))
+          )
+        )
+        (f32.store
+          (i32.add (local.get $py) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $py) (local.get $off)))
+            (f32.load (i32.add (local.get $vy) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 1)))
+        (br $loop2)
+      )
+    )
+  )
+
+  ;; Generic f32 add: dst[i] += src[i], SIMD 4-wide + scalar remainder
+  (func (export "add_f32")
+    (param $dst i32) (param $src i32) (param $count i32)
+    (local $i i32)
+    (local $off i32)
+    (local $end4 i32)
+    (local.set $end4 (i32.and (local.get $count) (i32.const -4)))
+    (local.set $i (i32.const 0))
+    (block $break
+      (loop $loop
+        (br_if $break (i32.ge_u (local.get $i) (local.get $end4)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        (v128.store
+          (i32.add (local.get $dst) (local.get $off))
+          (f32x4.add
+            (v128.load (i32.add (local.get $dst) (local.get $off)))
+            (v128.load (i32.add (local.get $src) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 4)))
+        (br $loop)
+      )
+    )
+    (block $break2
+      (loop $loop2
+        (br_if $break2 (i32.ge_u (local.get $i) (local.get $count)))
+        (local.set $off (i32.shl (local.get $i) (i32.const 2)))
+        (f32.store
+          (i32.add (local.get $dst) (local.get $off))
+          (f32.add
+            (f32.load (i32.add (local.get $dst) (local.get $off)))
+            (f32.load (i32.add (local.get $src) (local.get $off)))
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 1)))
+        (br $loop2)
+      )
+    )
+  )
+)

package/src/wasm-kernels.ts

@@ -0,0 +1,68 @@
+// Auto-generated from src/iterate.wat — do not edit by hand
+const ITERATE_WASM = new Uint8Array([
+  0,97,115,109,1,0,0,0,1,15,2,96,5,127,127,127,127,127,0,96,
+  3,127,127,127,0,2,15,1,3,101,110,118,6,109,101,109,111,114,121,2,
+  0,1,3,4,3,0,0,1,7,43,3,14,105,116,101,114,97,116,101,95,
+  115,99,97,108,97,114,0,0,12,105,116,101,114,97,116,101,95,115,105,109,
+  100,0,1,7,97,100,100,95,102,51,50,0,2,10,148,3,3,87,1,2,
+  127,65,0,33,5,2,64,3,64,32,5,32,4,79,13,1,32,5,65,2,
+  116,33,6,32,0,32,6,106,32,0,32,6,106,42,2,0,32,2,32,6,
+  106,42,2,0,146,56,2,0,32,1,32,6,106,32,1,32,6,106,42,2,
+  0,32,3,32,6,106,42,2,0,146,56,2,0,32,5,65,1,106,33,5,
+  12,0,11,11,11,183,1,1,3,127,32,4,65,124,113,33,7,65,0,33,
+  5,2,64,3,64,32,5,32,7,79,13,1,32,5,65,2,116,33,6,32,
+  0,32,6,106,32,0,32,6,106,253,0,4,0,32,2,32,6,106,253,0,
+  4,0,253,228,1,253,11,4,0,32,1,32,6,106,32,1,32,6,106,253,
+  0,4,0,32,3,32,6,106,253,0,4,0,253,228,1,253,11,4,0,32,
+  5,65,4,106,33,5,12,0,11,11,2,64,3,64,32,5,32,4,79,13,
+  1,32,5,65,2,116,33,6,32,0,32,6,106,32,0,32,6,106,42,2,
+  0,32,2,32,6,106,42,2,0,146,56,2,0,32,1,32,6,106,32,1,
+  32,6,106,42,2,0,32,3,32,6,106,42,2,0,146,56,2,0,32,5,
+  65,1,106,33,5,12,0,11,11,11,128,1,1,3,127,32,2,65,124,113,
+  33,5,65,0,33,3,2,64,3,64,32,3,32,5,79,13,1,32,3,65,
+  2,116,33,4,32,0,32,4,106,32,0,32,4,106,253,0,4,0,32,1,
+  32,4,106,253,0,4,0,253,228,1,253,11,4,0,32,3,65,4,106,33,
+  3,12,0,11,11,2,64,3,64,32,3,32,2,79,13,1,32,3,65,2,
+  116,33,4,32,0,32,4,106,32,0,32,4,106,42,2,0,32,1,32,4,
+  106,42,2,0,146,56,2,0,32,3,65,1,106,33,3,12,0,11,11,11
+]); // 500 bytes
+
+export interface IterateKernels {
+  iterate_scalar(px: number, py: number, vx: number, vy: number, count: number): void;
+  iterate_simd(px: number, py: number, vx: number, vy: number, count: number): void;
+  add_f32(dst: number, src: number, count: number): void;
+}
+
+// Cached compiled module (shared across all EntityManager instances)
+let cachedModule: WebAssembly.Module | null = null;
+
+function getCompiledModule(): WebAssembly.Module {
+  if (!cachedModule) {
+    cachedModule = new WebAssembly.Module(ITERATE_WASM);
+  }
+  return cachedModule;
+}
+
+/** Returns true if the runtime supports WebAssembly SIMD. Result is cached. */
+export function isWasmSimdAvailable(): boolean {
+  if (cachedModule !== null) return true;
+  try {
+    getCompiledModule();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function instantiateKernels(memory: WebAssembly.Memory): Promise<IterateKernels> {
+  const module = getCompiledModule();
+  const instance = await WebAssembly.instantiate(module, { env: { memory } });
+  return instance.exports as unknown as IterateKernels;
+}
+
+/** Synchronous instantiation — only for small modules (<4KB). Used internally. */
+export function instantiateKernelsSync(memory: WebAssembly.Memory): IterateKernels {
+  const module = getCompiledModule();
+  const instance = new WebAssembly.Instance(module, { env: { memory } });
+  return instance.exports as unknown as IterateKernels;
+}