archetype-ecs-lib 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jean-Laurent Duzant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# Archetype ECS Lib
+
+A tiny **archetype-based ECS** (Entity Component System) for TypeScript.
+
+- **Archetypes (tables)** store entities in a **SoA** layout (one column per component type).
+- **Queries** iterate matching archetypes efficiently.
+- **Commands** let you **defer structural changes** (spawn/despawn/add/remove) safely.
+- A minimal **Schedule** runs systems by phases and flushes commands between phases.
+
+Exports are defined in `index.ts`:
+- `Types`, `TypeRegistry`, `Commands`, `World`, `Schedule`
+
+---
+
+## Install
+
+```bash
+npm i archetype-ecs-lib
+# or
+pnpm add archetype-ecs-lib
+# or
+yarn add archetype-ecs-lib
+````
+
+---
+
+## Core concepts
+
+### Entity
+
+An entity is a lightweight handle:
+
+```ts
+type Entity = { id: number; gen: number };
+```
+
+The `gen` (generation) prevents using stale entity handles after despawn/reuse.
+
+### Component
+
+A component is any class used as a type key:
+
+```ts
+class Position { constructor(public x = 0, public y = 0) {} }
+class Velocity { constructor(public x = 0, public y = 0) {} }
+```
+
+Internally, constructors are mapped to a stable numeric `TypeId` via `typeId()`.
+
+### World
+
+`World` owns entities, archetypes, commands, and systems.
+
+Structural operations:
+
+* `spawn()`, `despawn(e)`
+* `add(e, Ctor, value)`, `remove(e, Ctor)`
+* `has(e, Ctor)`, `get(e, Ctor)`, `set(e, Ctor, value)`
+* `query(...ctors)` to iterate entities with required components
+* `cmd()` to enqueue deferred commands
+* `flush()` applies queued commands
+* `update(dt)` runs registered systems and flushes at the end
+
+### Deferred structural changes (important)
+
+While iterating a query (or while systems are running), doing structural changes directly can throw:
+
+> “Cannot do structural change (…) while iterating. Use world.cmd() and flush …”
+
+Use `world.cmd()` inside systems / loops, and let `world.flush()` apply changes safely.
+
+---
+
+## Quick start
+
+```ts
+import { World, Schedule } from "archetype-ecs-lib";
+
+class Position { constructor(public x = 0, public y = 0) {} }
+class Velocity { constructor(public x = 0, public y = 0) {} }
+
+const world = new World();
+
+// Spawn immediately
+const e = world.spawn();
+world.add(e, Position, new Position(0, 0));
+world.add(e, Velocity, new Velocity(1, 0));
+
+// A simple system
+world.addSystem((w: any, dt: number) => {
+  for (const { e, c1: pos, c2: vel } of w.query(Position, Velocity)) {
+    pos.x += vel.x * dt;
+    pos.y += vel.y * dt;
+
+    // Defer structural changes safely
+    if (pos.x > 10) w.cmd().despawn(e);
+  }
+});
+
+world.update(1 / 60);
+```
+
+> Note: `SystemFn` is typed as `(world: WorldI, dt) => void` where `WorldI` only requires `flush()`.
+> In practice, you’ll typically use the concrete `World` API in systems (cast `world` or type your function accordingly).
+
+---
+
+## Query API
+
+```ts
+for (const row of world.query(Position, Velocity)) {
+  // row.e  -> Entity
+  // row.c1 -> Position
+  // row.c2 -> Velocity
+}
+```
+
+`query(...ctors)` yields objects shaped like:
+
+* `e`: the entity
+* `c1`, `c2`, `c3`, …: component values **in the same order** as the ctor arguments
+
+So if you call `query(A, B, C)` you’ll get `{ e, c1: A, c2: B, c3: C }`.
+
+---
+
+## Commands API (deferred ops)
+
+```ts
+const cmd = world.cmd();
+
+cmd.spawn((e) => {
+  cmd.add(e, Position, new Position(0, 0));
+});
+
+cmd.add(entity, Velocity, new Velocity(1, 0));
+cmd.remove(entity, Velocity);
+cmd.despawn(entity);
+
+// Apply them (World.update() also flushes automatically at end)
+world.flush();
+```
+
+Supported commands (`Commands.ts`):
+
+* `spawn(init?)`
+* `despawn(e)`
+* `add(e, ctor, value)`
+* `remove(e, ctor)`
+
+---
+
+## Schedule (phases)
+
+`Schedule` is a small phase runner:
+
+```ts
+import { World, Schedule } from "archetype-ecs-lib";
+
+const world = new World();
+const sched = new Schedule();
+
+sched
+  .add("input", (w: any) => { /* read input, enqueue commands */ })
+  .add("sim",   (w: any, dt) => { /* update movement */ })
+  .add("render",(w: any) => { /* build render data */ });
+
+const phases = ["input", "sim", "render"];
+
+// Runs each phase in order and calls world.flush() after each phase.
+sched.run(world, 1/60, phases);
+```
+
+This is handy when you want deterministic ordering and command application points.
+
+---
+
+## World API summary
+
+### Entity lifecycle
+
+* `spawn(): Entity`
+* `despawn(e: Entity): void`
+* `isAlive(e: Entity): boolean`
+
+### Components
+
+* `has(e, Ctor): boolean`
+* `get(e, Ctor): T | undefined`
+* `set(e, Ctor, value): void` *(requires the component to exist; otherwise throws)*
+* `add(e, Ctor, value): void` *(structural: may move entity between archetypes)*
+* `remove(e, Ctor): void` *(structural: may move entity between archetypes)*
+
+### Systems / frame
+
+* `addSystem(fn): this`
+* `update(dt): void` *(runs systems in order, then flushes)*
+* `cmd(): Commands`
+* `flush(): void`
+
+### Queries
+
+* `query(...ctors): Iterable<{ e: Entity; c1?: any; c2?: any; ... }>`
+
+---
+
+## Notes & limitations
+
+* This is intentionally minimal: **no parallelism**, no borrow-checking, no automatic conflict detection.
+* Query results use `c1/c2/...` fields for stability and speed; you can wrap this in helpers if you prefer tuple returns.
+* `TypeId` assignment is process-local and based on constructor identity (`WeakMap`).
+
+---
+
+## License
+
+```
+MIT License
+
+Copyright (c) 2025 Jean-Laurent Duzant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/lib/ecs/Archetype.d.ts

@@ -0,0 +1,19 @@
+import { Column, Entity, Signature, TypeId } from "./Types";
+export declare class Archetype {
+    readonly id: number;
+    readonly sig: Signature;
+    private readonly cols;
+    readonly entities: Entity[];
+    constructor(id: number, sig: Signature);
+    /**
+     * Adds a new row. The caller must push per-column values in the same order.
+     * Returns row index.
+     */
+    addRow(e: Entity): number;
+    /**
+     * Swap-remove a row (O(1)). Returns the entity that moved into `row`, or null if none.
+     */
+    removeRow(row: number): Entity | null;
+    has(t: TypeId): boolean;
+    column<T>(t: TypeId): Column<T>;
+}

package/lib/ecs/Archetype.js

@@ -0,0 +1,119 @@
+"use strict";
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Archetype = void 0;
+var Archetype = /** @class */ (function () {
+    function Archetype(id, sig) {
+        var e_1, _a;
+        // One column per component type id (SoA layout)
+        this.cols = new Map();
+        // Entity handles stored per row
+        this.entities = [];
+        this.id = id;
+        this.sig = sig;
+        try {
+            for (var sig_1 = __values(sig), sig_1_1 = sig_1.next(); !sig_1_1.done; sig_1_1 = sig_1.next()) {
+                var t = sig_1_1.value;
+                this.cols.set(t, []);
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (sig_1_1 && !sig_1_1.done && (_a = sig_1.return)) _a.call(sig_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    }
+    /**
+     * Adds a new row. The caller must push per-column values in the same order.
+     * Returns row index.
+     */
+    Archetype.prototype.addRow = function (e) {
+        var row = this.entities.length;
+        this.entities.push(e);
+        return row;
+    };
+    /**
+     * Swap-remove a row (O(1)). Returns the entity that moved into `row`, or null if none.
+     */
+    Archetype.prototype.removeRow = function (row) {
+        var e_2, _a, e_3, _b;
+        var last = this.entities.length - 1;
+        if (row < 0 || row > last)
+            throw new Error("removeRow out of range: ".concat(row));
+        if (row !== last) {
+            var moved = this.entities[last];
+            this.entities[row] = moved;
+            this.entities.pop();
+            try {
+                for (var _c = __values(this.cols), _d = _c.next(); !_d.done; _d = _c.next()) {
+                    var _e = __read(_d.value, 2), _ = _e[0], col = _e[1];
+                    col[row] = col[last];
+                    col.pop();
+                }
+            }
+            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            finally {
+                try {
+                    if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+                }
+                finally { if (e_2) throw e_2.error; }
+            }
+            return moved;
+        }
+        // removing last
+        this.entities.pop();
+        try {
+            for (var _f = __values(this.cols), _g = _f.next(); !_g.done; _g = _f.next()) {
+                var _h = __read(_g.value, 2), col = _h[1];
+                col.pop();
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+        return null;
+    };
+    Archetype.prototype.has = function (t) {
+        return this.cols.has(t);
+    };
+    Archetype.prototype.column = function (t) {
+        var c = this.cols.get(t);
+        if (!c)
+            throw new Error("Archetype ".concat(this.id, " missing column for type ").concat(t));
+        return c;
+    };
+    return Archetype;
+}());
+exports.Archetype = Archetype;

package/lib/ecs/Commands.d.ts

@@ -0,0 +1,25 @@
+import type { ComponentCtor, Entity } from "./Types";
+export type Command = {
+    k: "spawn";
+    init?: (e: Entity) => void;
+} | {
+    k: "despawn";
+    e: Entity;
+} | {
+    k: "add";
+    e: Entity;
+    ctor: ComponentCtor<any>;
+    value: any;
+} | {
+    k: "remove";
+    e: Entity;
+    ctor: ComponentCtor<any>;
+};
+export declare class Commands {
+    private readonly q;
+    spawn(init?: (e: Entity) => void): void;
+    despawn(e: Entity): void;
+    add<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;
+    remove<T>(e: Entity, ctor: ComponentCtor<T>): void;
+    drain(): Command[];
+}

package/lib/ecs/Commands.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Commands = void 0;
+var Commands = /** @class */ (function () {
+    function Commands() {
+        this.q = [];
+    }
+    Commands.prototype.spawn = function (init) {
+        this.q.push({ k: "spawn", init: init });
+    };
+    Commands.prototype.despawn = function (e) {
+        this.q.push({ k: "despawn", e: e });
+    };
+    Commands.prototype.add = function (e, ctor, value) {
+        this.q.push({ k: "add", e: e, ctor: ctor, value: value });
+    };
+    Commands.prototype.remove = function (e, ctor) {
+        this.q.push({ k: "remove", e: e, ctor: ctor });
+    };
+    Commands.prototype.drain = function () {
+        var out = this.q.slice();
+        this.q.length = 0;
+        return out;
+    };
+    return Commands;
+}());
+exports.Commands = Commands;

package/lib/ecs/EntityManager.d.ts

@@ -0,0 +1,9 @@
+import { Entity, EntityMeta } from "./Types";
+export declare class EntityManager {
+    private _nextId;
+    private _free;
+    readonly meta: EntityMeta[];
+    create(): Entity;
+    isAlive(e: Entity): boolean;
+    kill(e: Entity): void;
+}

package/lib/ecs/EntityManager.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityManager = void 0;
+var EntityManager = /** @class */ (function () {
+    function EntityManager() {
+        this._nextId = 1;
+        this._free = [];
+        this.meta = []; // indexed by EntityId; meta[0] unused
+    }
+    EntityManager.prototype.create = function () {
+        var id;
+        if (this._free.length > 0) {
+            id = this._free.pop();
+            var m = this.meta[id];
+            m.alive = true;
+            m.gen += 1; // bump generation on reuse
+            m.arch = 0;
+            m.row = 0;
+            return { id: id, gen: m.gen };
+        }
+        id = this._nextId++;
+        this.meta[id] = { gen: 1, alive: true, arch: 0, row: 0 };
+        return { id: id, gen: 1 };
+    };
+    EntityManager.prototype.isAlive = function (e) {
+        var m = this.meta[e.id];
+        return !!m && m.alive && m.gen === e.gen;
+    };
+    EntityManager.prototype.kill = function (e) {
+        var m = this.meta[e.id];
+        if (!m || !m.alive || m.gen !== e.gen)
+            return;
+        m.alive = false;
+        this._free.push(e.id);
+    };
+    return EntityManager;
+}());
+exports.EntityManager = EntityManager;

package/lib/ecs/Schedule.d.ts

@@ -0,0 +1,10 @@
+import type { SystemFn, WorldI } from "./Types";
+/**
+ * Minimal scheduler that supports phases, without borrow-checking.
+ * (Add conflict detection later if you want parallelism.)
+ */
+export declare class Schedule {
+    private readonly phases;
+    add(phase: string, fn: SystemFn): this;
+    run(world: WorldI, dt: number, phaseOrder: string[]): void;
+}

package/lib/ecs/Schedule.js

@@ -0,0 +1,65 @@
+"use strict";
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Schedule = void 0;
+/**
+ * Minimal scheduler that supports phases, without borrow-checking.
+ * (Add conflict detection later if you want parallelism.)
+ */
+var Schedule = /** @class */ (function () {
+    function Schedule() {
+        this.phases = new Map();
+    }
+    Schedule.prototype.add = function (phase, fn) {
+        var _a;
+        var list = (_a = this.phases.get(phase)) !== null && _a !== void 0 ? _a : [];
+        list.push(fn);
+        this.phases.set(phase, list);
+        return this;
+    };
+    Schedule.prototype.run = function (world, dt, phaseOrder) {
+        var e_1, _a, e_2, _b;
+        try {
+            for (var phaseOrder_1 = __values(phaseOrder), phaseOrder_1_1 = phaseOrder_1.next(); !phaseOrder_1_1.done; phaseOrder_1_1 = phaseOrder_1.next()) {
+                var phase = phaseOrder_1_1.value;
+                var list = this.phases.get(phase);
+                if (!list)
+                    continue;
+                try {
+                    for (var list_1 = (e_2 = void 0, __values(list)), list_1_1 = list_1.next(); !list_1_1.done; list_1_1 = list_1.next()) {
+                        var fn = list_1_1.value;
+                        fn(world, dt);
+                    }
+                }
+                catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                finally {
+                    try {
+                        if (list_1_1 && !list_1_1.done && (_b = list_1.return)) _b.call(list_1);
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                }
+                // apply deferred commands between phases
+                world.flush();
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (phaseOrder_1_1 && !phaseOrder_1_1.done && (_a = phaseOrder_1.return)) _a.call(phaseOrder_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    };
+    return Schedule;
+}());
+exports.Schedule = Schedule;

package/lib/ecs/Signature.d.ts

@@ -0,0 +1,8 @@
+import { Signature, TypeId } from "./Types";
+export declare function signatureKey(sig: Signature): string;
+export declare function mergeSignature(sig: Signature, add: TypeId): TypeId[];
+export declare function subtractSignature(sig: Signature, remove: TypeId): TypeId[];
+/**
+ * True if `need` is a subset of `have`. Both must be sorted ascending.
+ */
+export declare function signatureHasAll(have: Signature, need: Signature): boolean;

package/lib/ecs/Signature.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signatureKey = signatureKey;
+exports.mergeSignature = mergeSignature;
+exports.subtractSignature = subtractSignature;
+exports.signatureHasAll = signatureHasAll;
+function signatureKey(sig) {
+    // canonical: sorted ascending, joined
+    return sig.join(",");
+}
+function mergeSignature(sig, add) {
+    var out = sig.slice();
+    // insert in sorted order (sig is sorted)
+    var i = 0;
+    while (i < out.length && out[i] < add)
+        i++;
+    if (out[i] === add)
+        return out;
+    out.splice(i, 0, add);
+    return out;
+}
+function subtractSignature(sig, remove) {
+    var out = sig.slice();
+    var idx = out.indexOf(remove);
+    if (idx >= 0)
+        out.splice(idx, 1);
+    return out;
+}
+/**
+ * True if `need` is a subset of `have`. Both must be sorted ascending.
+ */
+function signatureHasAll(have, need) {
+    var i = 0;
+    var j = 0;
+    while (i < have.length && j < need.length) {
+        var a = have[i];
+        var b = need[j];
+        if (a === b) {
+            i++;
+            j++;
+            continue;
+        }
+        if (a < b) {
+            i++;
+            continue;
+        }
+        return false; // a > b -> missing b
+    }
+    return j === need.length;
+}

package/lib/ecs/TypeRegistry.d.ts

@@ -0,0 +1,5 @@
+import { TypeId, ComponentCtor } from "./Types";
+/**
+ * Returns a stable numeric TypeId for a component constructor.
+ */
+export declare function typeId<T>(ctor: ComponentCtor<T>): TypeId;

package/lib/ecs/TypeRegistry.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeId = typeId;
+var ctorToId = new WeakMap();
+var nextId = 1;
+/**
+ * Returns a stable numeric TypeId for a component constructor.
+ */
+function typeId(ctor) {
+    var existing = ctorToId.get(ctor);
+    if (existing != null)
+        return existing;
+    var id = nextId++;
+    ctorToId.set(ctor, id);
+    return id;
+}

package/lib/ecs/Types.d.ts

@@ -0,0 +1,24 @@
+export type EntityId = number;
+export type Entity = Readonly<{
+    id: EntityId;
+    gen: number;
+}>;
+export type EntityMeta = {
+    gen: number;
+    alive: boolean;
+    arch: number;
+    row: number;
+};
+export type Column<T = unknown> = T[];
+export type Signature = ReadonlyArray<TypeId>;
+export type ComponentCtor<T> = new (...args: any[]) => T;
+/**
+ * Internal numeric id for a component "type".
+ * (We keep it numeric so signatures can be sorted quickly.)
+ */
+export type TypeId = number;
+export type SystemFn = (world: WorldI, dt: number) => void;
+/** Forward declaration to avoid circular import types-only pain. */
+export interface WorldI {
+    flush(): void;
+}

package/lib/ecs/Types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/ecs/World.d.ts

@@ -0,0 +1,43 @@
+import { Commands } from "./Commands";
+import { ComponentCtor, Entity, SystemFn, WorldI } from "./Types";
+export declare class World implements WorldI {
+    private readonly entities;
+    private readonly archetypes;
+    private readonly archByKey;
+    private readonly systems;
+    private readonly commands;
+    private _isIterating;
+    constructor();
+    /** Queue structural changes to apply safely after systems run. */
+    cmd(): Commands;
+    addSystem(fn: SystemFn): this;
+    /**
+     * Run a frame:
+     * - run systems in order
+     * - flush queued commands (structural changes)
+     */
+    update(dt: number): void;
+    flush(): void;
+    spawn(): Entity;
+    isAlive(e: Entity): boolean;
+    despawn(e: Entity): void;
+    has<T>(e: Entity, ctor: ComponentCtor<T>): boolean;
+    get<T>(e: Entity, ctor: ComponentCtor<T>): T | undefined;
+    set<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;
+    add<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;
+    remove<T>(e: Entity, ctor: ComponentCtor<T>): void;
+    /**
+     * Query all entities having all required component types.
+     * Iterates archetypes (tables) and yields SoA columns for cache-friendly loops.
+     */
+    query(...ctors: ComponentCtor<any>[]): Iterable<any>;
+    private _ensureNotIterating;
+    private _getOrCreateArchetype;
+    private _removeFromArchetype;
+    /**
+     * Move entity from src archetype row to dst archetype, copying columns via `pick`.
+     * Then swap-remove from src.
+     */
+    private _moveEntity;
+    private _apply;
+}

package/lib/ecs/World.js

@@ -0,0 +1,365 @@
+"use strict";
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.World = void 0;
+var Archetype_1 = require("./Archetype");
+var Commands_1 = require("./Commands");
+var EntityManager_1 = require("./EntityManager");
+var Signature_1 = require("./Signature");
+var TypeRegistry_1 = require("./TypeRegistry");
+var World = /** @class */ (function () {
+    function World() {
+        this.entities = new EntityManager_1.EntityManager();
+        this.archetypes = [];
+        this.archByKey = new Map();
+        this.systems = [];
+        this.commands = new Commands_1.Commands();
+        this._isIterating = false;
+        // Archetype 0: empty signature
+        var archetype0 = new Archetype_1.Archetype(0, []);
+        this.archetypes[0] = archetype0;
+        this.archByKey.set("", archetype0);
+    }
+    /** Queue structural changes to apply safely after systems run. */
+    World.prototype.cmd = function () { return this.commands; };
+    World.prototype.addSystem = function (fn) {
+        this.systems.push(fn);
+        return this;
+    };
+    /**
+     * Run a frame:
+     * - run systems in order
+     * - flush queued commands (structural changes)
+     */
+    World.prototype.update = function (dt) {
+        var e_1, _a;
+        this._isIterating = true;
+        try {
+            try {
+                for (var _b = __values(this.systems), _c = _b.next(); !_c.done; _c = _b.next()) {
+                    var s = _c.value;
+                    s(this, dt);
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        finally {
+            this._isIterating = false;
+            this.flush();
+        }
+    };
+    World.prototype.flush = function () {
+        var e_2, _a;
+        var ops = this.commands.drain();
+        try {
+            for (var ops_1 = __values(ops), ops_1_1 = ops_1.next(); !ops_1_1.done; ops_1_1 = ops_1.next()) {
+                var op = ops_1_1.value;
+                this._apply(op);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (ops_1_1 && !ops_1_1.done && (_a = ops_1.return)) _a.call(ops_1);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+    };
+    //#region ---------- Entity lifecycle ----------
+    World.prototype.spawn = function () {
+        var entity = this.entities.create();
+        // place in archetype 0
+        var archetype0 = this.archetypes[0];
+        var row = archetype0.addRow(entity);
+        var entityMeta = this.entities.meta[entity.id];
+        entityMeta.arch = 0;
+        entityMeta.row = row;
+        return entity;
+    };
+    World.prototype.isAlive = function (e) {
+        return this.entities.isAlive(e);
+    };
+    World.prototype.despawn = function (e) {
+        if (!this.entities.isAlive(e))
+            return;
+        this._ensureNotIterating("despawn");
+        this._removeFromArchetype(e);
+        this.entities.kill(e);
+    };
+    //#endregion
+    //#region ---------- Components ----------
+    World.prototype.has = function (e, ctor) {
+        var meta = this.entities.meta[e.id];
+        if (!meta || !meta.alive || meta.gen !== e.gen)
+            return false;
+        var tid = (0, TypeRegistry_1.typeId)(ctor);
+        return this.archetypes[meta.arch].has(tid);
+    };
+    World.prototype.get = function (e, ctor) {
+        var meta = this.entities.meta[e.id];
+        if (!meta || !meta.alive || meta.gen !== e.gen)
+            return undefined;
+        var tid = (0, TypeRegistry_1.typeId)(ctor);
+        var a = this.archetypes[meta.arch];
+        if (!a.has(tid))
+            return undefined;
+        return a.column(tid)[meta.row];
+    };
+    World.prototype.set = function (e, ctor, value) {
+        var meta = this.entities.meta[e.id];
+        if (!meta || !meta.alive || meta.gen !== e.gen)
+            return;
+        var tid = (0, TypeRegistry_1.typeId)(ctor);
+        var a = this.archetypes[meta.arch];
+        if (!a.has(tid))
+            throw new Error("set() requires component to exist; use add()");
+        a.column(tid)[meta.row] = value;
+    };
+    World.prototype.add = function (e, ctor, value) {
+        if (!this.entities.isAlive(e))
+            return;
+        this._ensureNotIterating("add");
+        var tid = (0, TypeRegistry_1.typeId)(ctor);
+        var srcMeta = this.entities.meta[e.id];
+        var src = this.archetypes[srcMeta.arch];
+        if (src.has(tid)) {
+            // overwrite in-place
+            src.column(tid)[srcMeta.row] = value;
+            return;
+        }
+        var dstSig = (0, Signature_1.mergeSignature)(src.sig, tid);
+        var dst = this._getOrCreateArchetype(dstSig);
+        this._moveEntity(e, src, srcMeta.row, dst, function (t) {
+            if (t === tid)
+                return value;
+            return src.column(t)[srcMeta.row];
+        });
+    };
+    World.prototype.remove = function (e, ctor) {
+        if (!this.entities.isAlive(e))
+            return;
+        this._ensureNotIterating("remove");
+        var tid = (0, TypeRegistry_1.typeId)(ctor);
+        var srcMeta = this.entities.meta[e.id];
+        var src = this.archetypes[srcMeta.arch];
+        if (!src.has(tid))
+            return;
+        var dstSig = (0, Signature_1.subtractSignature)(src.sig, tid);
+        var dst = this._getOrCreateArchetype(dstSig);
+        this._moveEntity(e, src, srcMeta.row, dst, function (t) {
+            // copy all but removed, but dstSig guarantees t != tid
+            return src.column(t)[srcMeta.row];
+        });
+    };
+    //#endregion
+    //region ---------- Queries ----------
+    /**
+     * Query all entities having all required component types.
+     * Iterates archetypes (tables) and yields SoA columns for cache-friendly loops.
+     */
+    World.prototype.query = function () {
+        var ctors = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            ctors[_i] = arguments[_i];
+        }
+        var requested = ctors.map(TypeRegistry_1.typeId); // preserve caller order
+        var needSorted = Array.from(new Set(requested)).sort(function (a, b) { return a - b; }); // for signatureHasAll
+        function gen(world) {
+            var _loop_1, _a, _b, a, e_3_1;
+            var e_3, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        world._isIterating = true;
+                        _d.label = 1;
+                    case 1:
+                        _d.trys.push([1, , 10, 11]);
+                        _loop_1 = function (a) {
+                            var cols, row, e, out, i;
+                            return __generator(this, function (_e) {
+                                switch (_e.label) {
+                                    case 0:
+                                        if (!a)
+                                            return [2 /*return*/, "continue"];
+                                        // if (!signatureHasAll(a.sig, need)) continue;
+                                        if (!(0, Signature_1.signatureHasAll)(a.sig, needSorted))
+                                            return [2 /*return*/, "continue"];
+                                        cols = requested.map(function (t) { return a.column(t); });
+                                        row = 0;
+                                        _e.label = 1;
+                                    case 1:
+                                        if (!(row < a.entities.length)) return [3 /*break*/, 4];
+                                        e = a.entities[row];
+                                        out = { e: e };
+                                        for (i = 0; i < cols.length; i++)
+                                            out["c".concat(i + 1)] = cols[i][row];
+                                        return [4 /*yield*/, out];
+                                    case 2:
+                                        _e.sent();
+                                        _e.label = 3;
+                                    case 3:
+                                        row++;
+                                        return [3 /*break*/, 1];
+                                    case 4: return [2 /*return*/];
+                                }
+                            });
+                        };
+                        _d.label = 2;
+                    case 2:
+                        _d.trys.push([2, 7, 8, 9]);
+                        _a = __values(world.archetypes), _b = _a.next();
+                        _d.label = 3;
+                    case 3:
+                        if (!!_b.done) return [3 /*break*/, 6];
+                        a = _b.value;
+                        return [5 /*yield**/, _loop_1(a)];
+                    case 4:
+                        _d.sent();
+                        _d.label = 5;
+                    case 5:
+                        _b = _a.next();
+                        return [3 /*break*/, 3];
+                    case 6: return [3 /*break*/, 9];
+                    case 7:
+                        e_3_1 = _d.sent();
+                        e_3 = { error: e_3_1 };
+                        return [3 /*break*/, 9];
+                    case 8:
+                        try {
+                            if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
+                        }
+                        finally { if (e_3) throw e_3.error; }
+                        return [7 /*endfinally*/];
+                    case 9: return [3 /*break*/, 11];
+                    case 10:
+                        world._isIterating = false;
+                        return [7 /*endfinally*/];
+                    case 11: return [2 /*return*/];
+                }
+            });
+        }
+        return gen(this);
+    };
+    //#endregion
+    //#region ---------- Internals ----------
+    World.prototype._ensureNotIterating = function (op) {
+        if (this._isIterating) {
+            throw new Error("Cannot do structural change (".concat(op, ") while iterating. Use world.cmd() and flush at end of frame."));
+        }
+    };
+    World.prototype._getOrCreateArchetype = function (sig) {
+        var key = (0, Signature_1.signatureKey)(sig);
+        var existing = this.archByKey.get(key);
+        if (existing)
+            return existing;
+        var id = this.archetypes.length;
+        var a = new Archetype_1.Archetype(id, sig.slice().sort(function (x, y) { return x - y; }));
+        this.archetypes[id] = a;
+        this.archByKey.set(key, a);
+        return a;
+    };
+    World.prototype._removeFromArchetype = function (e) {
+        var m = this.entities.meta[e.id];
+        var a = this.archetypes[m.arch];
+        var moved = a.removeRow(m.row);
+        if (moved) {
+            // update moved entity meta to new row
+            var mm = this.entities.meta[moved.id];
+            mm.row = m.row;
+        }
+    };
+    /**
+     * Move entity from src archetype row to dst archetype, copying columns via `pick`.
+     * Then swap-remove from src.
+     */
+    World.prototype._moveEntity = function (e, src, srcRow, dst, pick) {
+        var e_4, _a;
+        // add row in dst
+        var dstRow = dst.addRow(e);
+        try {
+            for (var _b = __values(dst.sig), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var t = _c.value;
+                dst.column(t).push(pick(t));
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+        // update meta to dst before removing from src (in case src==dst should never happen here)
+        var m = this.entities.meta[e.id];
+        m.arch = dst.id;
+        m.row = dstRow;
+        // remove from src (swap-remove)
+        var moved = src.removeRow(srcRow);
+        if (moved) {
+            var mm = this.entities.meta[moved.id];
+            mm.arch = src.id;
+            mm.row = srcRow;
+        }
+    };
+    World.prototype._apply = function (op) {
+        var _a;
+        switch (op.k) {
+            case "spawn": {
+                var e = this.spawn();
+                (_a = op.init) === null || _a === void 0 ? void 0 : _a.call(op, e);
+                return;
+            }
+            case "despawn":
+                return this.despawn(op.e);
+            case "add":
+                return this.add(op.e, op.ctor, op.value);
+            case "remove":
+                return this.remove(op.e, op.ctor);
+        }
+    };
+    return World;
+}());
+exports.World = World;

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./ecs/Types";
+export * from "./ecs/TypeRegistry";
+export * from "./ecs/Commands";
+export * from "./ecs/World";
+export * from "./ecs/Schedule";

package/lib/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ecs/Types"), exports);
+__exportStar(require("./ecs/TypeRegistry"), exports);
+__exportStar(require("./ecs/Commands"), exports);
+__exportStar(require("./ecs/World"), exports);
+__exportStar(require("./ecs/Schedule"), exports);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "archetype-ecs-lib",
+  "version": "0.4.1",
+  "description": "An Archetype Entity Component System (AECS)",
+  "main": "./lib/index.js",
+  "scripts": {
+    "test": "jest --coverage",
+    "build": "tsc",
+    "lint": "tslint -c tslint.json src/**/*.ts",
+    "reload-packages": "rm -Rf node_modules && npm cache clean --force && npm ci"
+  },
+  "keywords": [
+    "archetype",
+    "ecs",
+    "lib"
+  ],
+  "author": {
+    "name": "PirateJL"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "tslint": "^6.1.3",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "./bin/*",
+    "./lib/*"
+  ],
+  "typings": "./lib/index.d.ts",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6"
+  }
+}