archetype-ecs-lib 0.4.2 → 0.6.0

package/README.md

@@ -1,4 +1,4 @@
-![Coverage](https://raw.githubusercontent.com/PirateJL/archetype-ecs-lib/refs/heads/gh-pages/coverage.svg)
+![Coverage](https://raw.githubusercontent.com/PirateJL/archetype-ecs-lib/refs/heads/gh-pages/assets/coverage.svg)
 
 # Archetype ECS Lib
 
@@ -7,66 +7,23 @@ 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.
+- **Resources (singletons)** store **global world state** (Input, Time, Config, Asset caches…) keyed by type, without using entities.
+- **Events** transient messages (Hit happened, Click happened, Play sound).
 - A minimal **Schedule** runs systems by phases and flushes commands between phases.
 
 Exports are defined in `index.ts`:
 - `Types`, `TypeRegistry`, `Commands`, `World`, `Schedule`
 
+> :exclamation: The full documentation is at [https://piratejl.github.io/archetype-ecs-lib/](https://piratejl.github.io/archetype-ecs-lib/)
+
 ---
 
 ## Install
 
 ```bash
 npm i 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
@@ -85,7 +42,7 @@ 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) => {
+world.addSystem((w) => {
   for (const { e, c1: pos, c2: vel } of w.query(Position, Velocity)) {
     pos.x += vel.x * dt;
     pos.y += vel.y * dt;
@@ -98,107 +55,7 @@ world.addSystem((w: any, dt: number) => {
 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; ... }>`
+> Note: `SystemFn` is typed as `(world: WorldApi, dt) => void`..
 
 ---
 
@@ -212,26 +69,4 @@ This is handy when you want deterministic ordering and command application point
 
 ## 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.
-```
+This code is distributed under the terms and conditions of the [MIT license](https://github.com/PirateJL/archetype-ecs-lib/blob/master/LICENSE).

package/lib/ecs/Archetype.d.ts

@@ -1,4 +1,4 @@
-import { Column, Entity, Signature, TypeId } from "./Types";
+import type { Column, Entity, Signature, TypeId } from "./Types";
 export declare class Archetype {
     readonly id: number;
     readonly sig: Signature;

package/lib/ecs/Archetype.js

@@ -74,7 +74,7 @@ var Archetype = /** @class */ (function () {
             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];
+                    var _e = __read(_d.value, 2), col = _e[1];
                     col[row] = col[last];
                     col.pop();
                 }

package/lib/ecs/Commands.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentCtor, Entity } from "./Types";
+import type { CommandsApi, ComponentCtor, ComponentCtorBundleItem, Entity } from "./Types";
 export type Command = {
     k: "spawn";
     init?: (e: Entity) => void;
@@ -15,11 +15,16 @@ export type Command = {
     e: Entity;
     ctor: ComponentCtor<any>;
 };
-export declare class Commands {
+export declare class Commands implements CommandsApi {
     private q;
     spawn(init?: (e: Entity) => void): void;
+    spawnBundle(...items: ComponentCtorBundleItem[]): void;
     despawn(e: Entity): void;
+    despawnBundle(entities: Entity[]): void;
     add<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;
+    addBundle(e: Entity, ...items: ComponentCtorBundleItem[]): void;
     remove<T>(e: Entity, ctor: ComponentCtor<T>): void;
+    removeBundle(e: Entity, ...ctors: ComponentCtor<any>[]): void;
+    hasPending(): boolean;
     drain(): Command[];
 }

package/lib/ecs/Commands.js

@@ -1,4 +1,31 @@
 "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.Commands = void 0;
 var Commands = /** @class */ (function () {
@@ -8,15 +35,98 @@ var Commands = /** @class */ (function () {
     Commands.prototype.spawn = function (init) {
         this.q.push({ k: "spawn", init: init });
     };
+    Commands.prototype.spawnBundle = function () {
+        var _this = this;
+        var items = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            items[_i] = arguments[_i];
+        }
+        this.spawn(function (e) {
+            var e_1, _a;
+            try {
+                // Applied during the same flush thanks to World.flush draining until empty.
+                for (var items_1 = __values(items), items_1_1 = items_1.next(); !items_1_1.done; items_1_1 = items_1.next()) {
+                    var _b = __read(items_1_1.value, 2), ctor = _b[0], value = _b[1];
+                    _this.add(e, ctor, value);
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (items_1_1 && !items_1_1.done && (_a = items_1.return)) _a.call(items_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        });
+    };
     Commands.prototype.despawn = function (e) {
         this.q.push({ k: "despawn", e: e });
     };
+    Commands.prototype.despawnBundle = function (entities) {
+        var e_2, _a;
+        try {
+            for (var entities_1 = __values(entities), entities_1_1 = entities_1.next(); !entities_1_1.done; entities_1_1 = entities_1.next()) {
+                var e = entities_1_1.value;
+                this.despawn(e);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (entities_1_1 && !entities_1_1.done && (_a = entities_1.return)) _a.call(entities_1);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+    };
     Commands.prototype.add = function (e, ctor, value) {
         this.q.push({ k: "add", e: e, ctor: ctor, value: value });
     };
+    Commands.prototype.addBundle = function (e) {
+        var e_3, _a;
+        var items = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            items[_i - 1] = arguments[_i];
+        }
+        try {
+            for (var items_2 = __values(items), items_2_1 = items_2.next(); !items_2_1.done; items_2_1 = items_2.next()) {
+                var _b = __read(items_2_1.value, 2), ctor = _b[0], value = _b[1];
+                this.add(e, ctor, value);
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (items_2_1 && !items_2_1.done && (_a = items_2.return)) _a.call(items_2);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+    };
     Commands.prototype.remove = function (e, ctor) {
         this.q.push({ k: "remove", e: e, ctor: ctor });
     };
+    Commands.prototype.removeBundle = function (e) {
+        var e_4, _a;
+        var ctors = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            ctors[_i - 1] = arguments[_i];
+        }
+        try {
+            for (var ctors_1 = __values(ctors), ctors_1_1 = ctors_1.next(); !ctors_1_1.done; ctors_1_1 = ctors_1.next()) {
+                var ctor = ctors_1_1.value;
+                this.remove(e, ctor);
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (ctors_1_1 && !ctors_1_1.done && (_a = ctors_1.return)) _a.call(ctors_1);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+    };
+    Commands.prototype.hasPending = function () {
+        return this.q.length > 0;
+    };
     Commands.prototype.drain = function () {
         var out = this.q;
         this.q = [];

package/lib/ecs/EntityManager.d.ts

@@ -1,4 +1,4 @@
-import { Entity, EntityMeta } from "./Types";
+import type { Entity, EntityMeta, WorldSnapshotAllocator } from "./Types";
 export declare class EntityManager {
     private _nextId;
     private _free;
@@ -6,4 +6,6 @@ export declare class EntityManager {
     create(): Entity;
     isAlive(e: Entity): boolean;
     kill(e: Entity): void;
+    snapshotAllocator(): WorldSnapshotAllocator;
+    restoreAllocator(snapshot: WorldSnapshotAllocator): void;
 }

package/lib/ecs/EntityManager.js

@@ -1,4 +1,15 @@
 "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.EntityManager = void 0;
 var EntityManager = /** @class */ (function () {
@@ -33,6 +44,84 @@ var EntityManager = /** @class */ (function () {
         m.alive = false;
         this._free.push(e.id);
     };
+    EntityManager.prototype.snapshotAllocator = function () {
+        var generations = [];
+        for (var id = 1; id < this.meta.length; id++) {
+            var m = this.meta[id];
+            if (!m)
+                continue;
+            generations.push([id, m.gen]);
+        }
+        return {
+            nextId: this._nextId,
+            free: this._free.slice(),
+            generations: generations
+        };
+    };
+    EntityManager.prototype.restoreAllocator = function (snapshot) {
+        var e_1, _a, e_2, _b;
+        if (!Number.isInteger(snapshot.nextId) || snapshot.nextId < 1) {
+            throw new Error("Invalid snapshot allocator.nextId: ".concat(snapshot.nextId));
+        }
+        var seenGenerations = new Set();
+        this.meta.length = 0;
+        try {
+            for (var _c = __values(snapshot.generations), _d = _c.next(); !_d.done; _d = _c.next()) {
+                var entry = _d.value;
+                var id = entry[0];
+                var gen = entry[1];
+                if (!Number.isInteger(id) || id <= 0) {
+                    throw new Error("Invalid snapshot allocator generations id: ".concat(id));
+                }
+                if (!Number.isInteger(gen) || gen <= 0) {
+                    throw new Error("Invalid snapshot allocator generation for id ".concat(id, ": ").concat(gen));
+                }
+                if (id >= snapshot.nextId) {
+                    throw new Error("Invalid snapshot allocator generation id ".concat(id, ": must be < nextId (").concat(snapshot.nextId, ")"));
+                }
+                if (seenGenerations.has(id)) {
+                    throw new Error("Duplicate snapshot allocator generation entry for id ".concat(id));
+                }
+                seenGenerations.add(id);
+                this.meta[id] = { gen: gen, alive: false, arch: 0, row: 0 };
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        var seenFree = new Set();
+        try {
+            for (var _e = __values(snapshot.free), _f = _e.next(); !_f.done; _f = _e.next()) {
+                var id = _f.value;
+                if (!Number.isInteger(id) || id <= 0) {
+                    throw new Error("Invalid snapshot allocator free id: ".concat(id));
+                }
+                if (id >= snapshot.nextId) {
+                    throw new Error("Invalid snapshot allocator free id ".concat(id, ": must be < nextId (").concat(snapshot.nextId, ")"));
+                }
+                if (!seenGenerations.has(id)) {
+                    throw new Error("Invalid snapshot allocator free id ".concat(id, ": missing generation entry"));
+                }
+                if (seenFree.has(id)) {
+                    throw new Error("Duplicate snapshot allocator free id ".concat(id));
+                }
+                seenFree.add(id);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        this._nextId = snapshot.nextId;
+        this._free = snapshot.free.slice();
+    };
     return EntityManager;
 }());
 exports.EntityManager = EntityManager;

package/lib/ecs/Events.d.ts

@@ -0,0 +1,23 @@
+export declare class EventChannel<T> {
+    private _read;
+    private _write;
+    /** Emit an event into the current phase write buffer. */
+    emit(ev: T): void;
+    /**
+     * Drain readable events (emitted in the previous phase), then clears the read buffer.
+     * Zero allocations; fast for hot paths.
+     */
+    drain(fn: (ev: T) => void): void;
+    /**
+     * Read-only view of readable events (previous phase).
+     * Valid until the next schedule boundary (swapEvents).
+     * Do not store this reference long-term.
+     */
+    values(): readonly T[];
+    count(): number;
+    clear(): void;
+    /** Clears both buffers (rarely needed, but useful for resets). */
+    clearAll(): void;
+    /** @internal Called by World at phase boundaries. */
+    swapBuffers(): void;
+}

package/lib/ecs/Events.js

@@ -0,0 +1,76 @@
+"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.EventChannel = void 0;
+var EventChannel = /** @class */ (function () {
+    function EventChannel() {
+        this._read = [];
+        this._write = [];
+    }
+    /** Emit an event into the current phase write buffer. */
+    EventChannel.prototype.emit = function (ev) {
+        this._write.push(ev);
+    };
+    /**
+     * Drain readable events (emitted in the previous phase), then clears the read buffer.
+     * Zero allocations; fast for hot paths.
+     */
+    EventChannel.prototype.drain = function (fn) {
+        var e_1, _a;
+        var read = this._read;
+        try {
+            for (var read_1 = __values(read), read_1_1 = read_1.next(); !read_1_1.done; read_1_1 = read_1.next()) {
+                var r = read_1_1.value;
+                fn(r);
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (read_1_1 && !read_1_1.done && (_a = read_1.return)) _a.call(read_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        this.clear();
+    };
+    /**
+     * Read-only view of readable events (previous phase).
+     * Valid until the next schedule boundary (swapEvents).
+     * Do not store this reference long-term.
+     */
+    EventChannel.prototype.values = function () {
+        return this._read;
+    };
+    EventChannel.prototype.count = function () {
+        return this._read.length;
+    };
+    EventChannel.prototype.clear = function () {
+        this._read.length = 0;
+    };
+    /** Clears both buffers (rarely needed, but useful for resets). */
+    EventChannel.prototype.clearAll = function () {
+        this._read.length = 0;
+        this._write.length = 0;
+    };
+    /** @internal Called by World at phase boundaries. */
+    EventChannel.prototype.swapBuffers = function () {
+        if (this._write.length === 0 && this._read.length === 0)
+            return;
+        var tmp = this._read;
+        this._read = this._write;
+        this._write = tmp;
+        this._write.length = 0;
+    };
+    return EventChannel;
+}());
+exports.EventChannel = EventChannel;