archetype-ecs-lib 0.4.1 → 0.5.0

package/README.md

@@ -1,3 +1,5 @@
+![Coverage](https://raw.githubusercontent.com/PirateJL/archetype-ecs-lib/refs/heads/gh-pages/assets/coverage.svg)
+
 # Archetype ECS Lib
 
 A tiny **archetype-based ECS** (Entity Component System) for TypeScript.
@@ -5,70 +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
-# 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
@@ -87,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;
@@ -100,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`..
 
 ---
 
@@ -214,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/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 {
-    private readonly q;
+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,18 +35,101 @@ 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.slice();
-        this.q.length = 0;
+        var out = this.q;
+        this.q = [];
         return out;
     };
     return Commands;

package/lib/ecs/EntityManager.d.ts

@@ -1,4 +1,4 @@
-import { Entity, EntityMeta } from "./Types";
+import type { Entity, EntityMeta } from "./Types";
 export declare class EntityManager {
     private _nextId;
     private _free;

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;

package/lib/ecs/Schedule.d.ts

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

package/lib/ecs/Schedule.js

@@ -38,7 +38,16 @@ var Schedule = /** @class */ (function () {
                 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);
+                        try {
+                            fn(world, dt);
+                        }
+                        catch (error) {
+                            var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
+                            var msg = error.message !== undefined && typeof 'string' ? error.message : JSON.stringify(error);
+                            var e = new Error("[phase=".concat(phase, " system=").concat(sysName, "] ").concat(msg));
+                            e.cause = error;
+                            throw e;
+                        }
                     }
                 }
                 catch (e_2_1) { e_2 = { error: e_2_1 }; }
@@ -49,7 +58,11 @@ var Schedule = /** @class */ (function () {
                     finally { if (e_2) throw e_2.error; }
                 }
                 // apply deferred commands between phases
-                world.flush();
+                if (world.cmd().hasPending()) {
+                    world.flush();
+                }
+                // deliver events emitted in this phase to the next phase
+                world.swapEvents();
             }
         }
         catch (e_1_1) { e_1 = { error: e_1_1 }; }

package/lib/ecs/Signature.d.ts

@@ -1,4 +1,4 @@
-import { Signature, TypeId } from "./Types";
+import type { 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[];

package/lib/ecs/TypeRegistry.d.ts

@@ -1,4 +1,4 @@
-import { TypeId, ComponentCtor } from "./Types";
+import type { TypeId, ComponentCtor } from "./Types";
 /**
  * Returns a stable numeric TypeId for a component constructor.
  */