archetype-ecs-lib 0.4.2 → 0.5.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/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 } 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

@@ -58,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.
  */

package/lib/ecs/Types.d.ts

@@ -1,3 +1,4 @@
+import { EventChannel } from "./Events";
 export type EntityId = number;
 export type Entity = Readonly<{
     id: EntityId;
@@ -12,13 +13,140 @@ export type EntityMeta = {
 export type Column<T = unknown> = T[];
 export type Signature = ReadonlyArray<TypeId>;
 export type ComponentCtor<T> = new (...args: any[]) => T;
+export type ComponentCtorBundleItem<T = any> = readonly [ComponentCtor<T>, 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 {
+export type SystemFn = (world: WorldApi, dt: number) => void;
+/**
+ * Commands API exposed to systems.
+ * > Hides internal stuff like `drain()`
+ */
+export interface CommandsApi {
+    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;
+}
+export type QueryRow1<A> = {
+    e: Entity;
+    c1: A;
+};
+export type QueryRow2<A, B> = {
+    e: Entity;
+    c1: A;
+    c2: B;
+};
+export type QueryRow3<A, B, C> = {
+    e: Entity;
+    c1: A;
+    c2: B;
+    c3: C;
+};
+export type QueryRow4<A, B, C, D> = {
+    e: Entity;
+    c1: A;
+    c2: B;
+    c3: C;
+    c4: D;
+};
+export type QueryRow5<A, B, C, D, E> = {
+    e: Entity;
+    c1: A;
+    c2: B;
+    c3: C;
+    c4: D;
+    c5: E;
+};
+export type QueryRow6<A, B, C, D, E, F> = {
+    e: Entity;
+    c1: A;
+    c2: B;
+    c3: C;
+    c4: D;
+    c5: E;
+    c6: F;
+};
+/**
+ * Public World API visible from system functions.
+ * Structural typing keeps typings fast and avoids generic plumbing across the whole library.
+ */
+export interface WorldApi {
+    cmd(): CommandsApi;
     flush(): void;
+    /**
+     * Insert or replace a resource (singleton) stored on the World, keyed by ctor.
+     * This is NOT a structural change (safe during iteration).
+     */
+    setResource<T>(key: ComponentCtor<T>, value: T): void;
+    /**
+     * Returns the resource value if present, otherwise `undefined`.
+     * Use this for optional resources (debug tools, plugins, editor-only state, etc.).
+     *
+     * Note: if you explicitly stored `undefined` as a resource value, this also returns `undefined`.
+     * Use `hasResource()` to distinguish "missing" vs "present but undefined".
+     */
+    getResource<T>(key: ComponentCtor<T>): T | undefined;
+    /**
+     * Returns the resource value if present, otherwise throws.
+     * Use this for required resources (Time, Input, AssetCache, Config...) to keep systems clean.
+     *
+     * The check is based on `hasResource(key)` so "missing" is unambiguous even if the stored value is `undefined`.
+     */
+    requireResource<T>(key: ComponentCtor<T>): T;
+    hasResource<T>(key: ComponentCtor<T>): boolean;
+    removeResource<T>(key: ComponentCtor<T>): boolean;
+    /**
+     * Insert once, returning the existing value if already present.
+     * Great for bootstrapping defaults without double-initializing.
+     */
+    initResource<T>(key: ComponentCtor<T>, factory: () => T): T;
+    /** Emit an event into the current phase (write buffer). */
+    emit<T>(key: ComponentCtor<T>, ev: T): void;
+    /**
+     * Get the channel for an event type (created on first use).
+     * - readable events are from the previous phase
+     * - emitted events go to the current phase
+     */
+    events<T>(key: ComponentCtor<T>): EventChannel<T>;
+    /**
+     * Drain readable events for this type (previous phase), calling fn for each.
+     * If the channel doesn't exist yet, this is a no-op.
+     */
+    drainEvents<T>(key: ComponentCtor<T>, fn: (ev: T) => void): void;
+    /**
+     * Clears readable events for a type (or all types if omitted).
+     * Does not affect entity structure.
+     */
+    clearEvents<T>(key?: ComponentCtor<T>): void;
+    /**
+     * @internal Called by Schedule at phase boundaries to deliver events to the next phase.
+     */
+    swapEvents(): void;
+    spawn(): Entity;
+    spawnMany(...items: ComponentCtorBundleItem[]): void;
+    despawn(e: Entity): void;
+    despawnMany(entities: Entity[]): void;
+    isAlive(e: Entity): boolean;
+    add<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;
+    addMany(e: Entity, ...items: ComponentCtorBundleItem[]): void;
+    remove<T>(e: Entity, ctor: ComponentCtor<T>): void;
+    removeMany(e: Entity, ...ctors: ComponentCtor<any>[]): 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;
+    query<A>(c1: ComponentCtor<A>): Iterable<QueryRow1<A>>;
+    query<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>): Iterable<QueryRow2<A, B>>;
+    query<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>): Iterable<QueryRow3<A, B, C>>;
+    query<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>): Iterable<QueryRow4<A, B, C, D>>;
+    query<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryRow5<A, B, C, D, E>>;
+    query<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>): Iterable<QueryRow6<A, B, C, D, E, F>>;
+    query(...ctors: ComponentCtor<any>[]): Iterable<any>;
 }

package/lib/ecs/World.d.ts

@@ -1,12 +1,15 @@
 import { Commands } from "./Commands";
-import { ComponentCtor, Entity, SystemFn, WorldI } from "./Types";
-export declare class World implements WorldI {
+import { EventChannel } from "./Events";
+import type { ComponentCtor, ComponentCtorBundleItem, Entity, QueryRow1, QueryRow2, QueryRow3, QueryRow4, QueryRow5, QueryRow6, SystemFn, WorldApi } from "./Types";
+export declare class World implements WorldApi {
     private readonly entities;
     private readonly archetypes;
     private readonly archByKey;
     private readonly systems;
     private readonly commands;
     private _iterateDepth;
+    private readonly resources;
+    private readonly eventChannels;
     constructor();
     /** Queue structural changes to apply safely after systems run. */
     cmd(): Commands;
@@ -18,19 +21,40 @@ export declare class World implements WorldI {
      */
     update(dt: number): void;
     flush(): void;
+    setResource<T>(key: ComponentCtor<T>, value: T): void;
+    getResource<T>(key: ComponentCtor<T>): T | undefined;
+    requireResource<T>(key: ComponentCtor<T>): T;
+    hasResource<T>(key: ComponentCtor<T>): boolean;
+    removeResource<T>(key: ComponentCtor<T>): boolean;
+    initResource<T>(key: ComponentCtor<T>, factory: () => T): T;
+    emit<T>(key: ComponentCtor<T>, ev: T): void;
+    events<T>(key: ComponentCtor<T>): EventChannel<T>;
+    drainEvents<T>(key: ComponentCtor<T>, fn: (ev: T) => void): void;
+    clearEvents<T>(key?: ComponentCtor<T>): void;
+    /** @internal Called by Schedule at phase boundaries */
+    swapEvents(): void;
     spawn(): Entity;
+    spawnMany(...items: ComponentCtorBundleItem[]): Entity;
     isAlive(e: Entity): boolean;
     despawn(e: Entity): void;
+    despawnMany(entities: 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;
+    addMany(e: Entity, ...items: ComponentCtorBundleItem[]): void;
     remove<T>(e: Entity, ctor: ComponentCtor<T>): void;
+    removeMany(e: Entity, ...ctors: ComponentCtor<any>[]): 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>;
+    query<A>(c1: ComponentCtor<A>): Iterable<QueryRow1<A>>;
+    query<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>): Iterable<QueryRow2<A, B>>;
+    query<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>): Iterable<QueryRow3<A, B, C>>;
+    query<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>): Iterable<QueryRow4<A, B, C, D>>;
+    query<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryRow5<A, B, C, D, E>>;
+    query<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>): Iterable<QueryRow6<A, B, C, D, E, F>>;
     private _ensureNotIterating;
     private _getOrCreateArchetype;
     private _removeFromArchetype;
@@ -46,4 +70,5 @@ export declare class World implements WorldI {
      * Throws an error if the entity is not alive
      */
     private _assertAlive;
+    private _events;
 }

package/lib/ecs/World.js

@@ -37,11 +37,28 @@ var __values = (this && this.__values) || function(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.World = void 0;
 var Archetype_1 = require("./Archetype");
 var Commands_1 = require("./Commands");
 var EntityManager_1 = require("./EntityManager");
+var Events_1 = require("./Events");
 var Signature_1 = require("./Signature");
 var TypeRegistry_1 = require("./TypeRegistry");
 var World = /** @class */ (function () {
@@ -52,6 +69,8 @@ var World = /** @class */ (function () {
         this.systems = [];
         this.commands = new Commands_1.Commands();
         this._iterateDepth = 0;
+        this.resources = new Map();
+        this.eventChannels = new Map();
         // Archetype 0: empty signature
         var archetype0 = new Archetype_1.Archetype(0, []);
         this.archetypes[0] = archetype0;
@@ -96,21 +115,113 @@ var World = /** @class */ (function () {
     World.prototype.flush = function () {
         var e_2, _a;
         this._ensureNotIterating("flush");
-        var ops = this.commands.drain();
+        // Apply commands until queue is empty. This allows spawn(init) to enqueue add/remove
+        // operations that will be applied during the same flush.
+        while (true) {
+            var ops = this.commands.drain();
+            if (ops.length === 0)
+                break;
+            try {
+                for (var ops_1 = (e_2 = void 0, __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 ---------- Resources (singletons) ----------
+    World.prototype.setResource = function (key, value) {
+        this.resources.set(key, value);
+    };
+    World.prototype.getResource = function (key) {
+        if (!this.resources.has(key))
+            return undefined;
+        return this.resources.get(key);
+    };
+    World.prototype.requireResource = function (key) {
+        if (!this.resources.has(key)) {
+            var name = this._formatCtor(key);
+            throw new Error("Missing resource ".concat(name, ". ") +
+                "Insert it via world.setResource(".concat(name, ", value) or world.initResource(").concat(name, ", () => value)."));
+        }
+        return this.resources.get(key);
+    };
+    World.prototype.hasResource = function (key) {
+        return this.resources.has(key);
+    };
+    World.prototype.removeResource = function (key) {
+        return this.resources.delete(key);
+    };
+    World.prototype.initResource = function (key, factory) {
+        if (this.resources.has(key))
+            return this.resources.get(key);
+        var value = factory();
+        this.resources.set(key, value);
+        return value;
+    };
+    //#endregion
+    //#region ---------- Events (phase-scoped) ----------
+    World.prototype.emit = function (key, ev) {
+        this._events(key).emit(ev);
+    };
+    World.prototype.events = function (key) {
+        return this._events(key);
+    };
+    World.prototype.drainEvents = function (key, fn) {
+        var ch = this.eventChannels.get(key);
+        if (!ch)
+            return;
+        ch.drain(fn);
+    };
+    World.prototype.clearEvents = function (key) {
+        var e_3, _a;
+        if (key) {
+            var ch = this.eventChannels.get(key);
+            if (!ch)
+                return;
+            ch.clear();
+            return;
+        }
+        try {
+            // clear all readable buffers
+            for (var _b = __values(this.eventChannels.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var ch = _c.value;
+                ch.clear();
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+    };
+    /** @internal Called by Schedule at phase boundaries */
+    World.prototype.swapEvents = function () {
+        var e_4, _a;
         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);
+            for (var _b = __values(this.eventChannels.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var ch = _c.value;
+                ch.swapBuffers();
             }
         }
-        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
         finally {
             try {
-                if (ops_1_1 && !ops_1_1.done && (_a = ops_1.return)) _a.call(ops_1);
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_2) throw e_2.error; }
+            finally { if (e_4) throw e_4.error; }
         }
     };
+    //#endregion
     //#region ---------- Entity lifecycle ----------
     World.prototype.spawn = function () {
         var entity = this.entities.create();
@@ -122,6 +233,28 @@ var World = /** @class */ (function () {
         entityMeta.row = row;
         return entity;
     };
+    World.prototype.spawnMany = function () {
+        var e_5, _a;
+        var items = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            items[_i] = arguments[_i];
+        }
+        var e = this.spawn();
+        try {
+            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_5_1) { e_5 = { error: e_5_1 }; }
+        finally {
+            try {
+                if (items_1_1 && !items_1_1.done && (_a = items_1.return)) _a.call(items_1);
+            }
+            finally { if (e_5) throw e_5.error; }
+        }
+        return e;
+    };
     World.prototype.isAlive = function (e) {
         return this.entities.isAlive(e);
     };
@@ -131,6 +264,22 @@ var World = /** @class */ (function () {
         this._removeFromArchetype(e);
         this.entities.kill(e);
     };
+    World.prototype.despawnMany = function (entities) {
+        var e_6, _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_6_1) { e_6 = { error: e_6_1 }; }
+        finally {
+            try {
+                if (entities_1_1 && !entities_1_1.done && (_a = entities_1.return)) _a.call(entities_1);
+            }
+            finally { if (e_6) throw e_6.error; }
+        }
+    };
     //#endregion
     //#region ---------- Components ----------
     World.prototype.has = function (e, ctor) {
@@ -177,6 +326,26 @@ var World = /** @class */ (function () {
             return src.column(t)[srcMeta.row];
         });
     };
+    World.prototype.addMany = function (e) {
+        var e_7, _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_7_1) { e_7 = { error: e_7_1 }; }
+        finally {
+            try {
+                if (items_2_1 && !items_2_1.done && (_a = items_2.return)) _a.call(items_2);
+            }
+            finally { if (e_7) throw e_7.error; }
+        }
+    };
     World.prototype.remove = function (e, ctor) {
         this._assertAlive(e, "remove(".concat(this._formatCtor(ctor), ")"));
         this._ensureNotIterating("remove");
@@ -192,12 +361,26 @@ var World = /** @class */ (function () {
             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.removeMany = function (e) {
+        var e_8, _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_8_1) { e_8 = { error: e_8_1 }; }
+        finally {
+            try {
+                if (ctors_1_1 && !ctors_1_1.done && (_a = ctors_1.return)) _a.call(ctors_1);
+            }
+            finally { if (e_8) throw e_8.error; }
+        }
+    };
     World.prototype.query = function () {
         var ctors = [];
         for (var _i = 0; _i < arguments.length; _i++) {
@@ -218,8 +401,8 @@ var World = /** @class */ (function () {
         }
         needSorted.length = w;
         function gen(world) {
-            var _a, _b, a, cols, i, row, e, out, i, e_3_1;
-            var e_3, _c;
+            var _a, _b, a, cols, i, row, e, out, i, e_9_1;
+            var e_9, _c;
             return __generator(this, function (_d) {
                 switch (_d.label) {
                     case 0:
@@ -262,14 +445,14 @@ var World = /** @class */ (function () {
                         return [3 /*break*/, 3];
                     case 8: return [3 /*break*/, 11];
                     case 9:
-                        e_3_1 = _d.sent();
-                        e_3 = { error: e_3_1 };
+                        e_9_1 = _d.sent();
+                        e_9 = { error: e_9_1 };
                         return [3 /*break*/, 11];
                     case 10:
                         try {
                             if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
                         }
-                        finally { if (e_3) throw e_3.error; }
+                        finally { if (e_9) throw e_9.error; }
                         return [7 /*endfinally*/];
                     case 11: return [3 /*break*/, 13];
                     case 12:
@@ -314,7 +497,7 @@ var World = /** @class */ (function () {
      * Then swap-remove from src.
      */
     World.prototype._moveEntity = function (e, src, srcRow, dst, pick) {
-        var e_4, _a;
+        var e_10, _a;
         // add row in dst
         var dstRow = dst.addRow(e);
         try {
@@ -323,12 +506,12 @@ var World = /** @class */ (function () {
                 dst.column(t).push(pick(t));
             }
         }
-        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        catch (e_10_1) { e_10 = { error: e_10_1 }; }
         finally {
             try {
                 if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_4) throw e_4.error; }
+            finally { if (e_10) throw e_10.error; }
         }
         // update meta to dst before removing from src (in case src==dst should never happen here)
         var m = this.entities.meta[e.id];
@@ -376,6 +559,14 @@ var World = /** @class */ (function () {
         }
         return meta;
     };
+    World.prototype._events = function (key) {
+        var ch = this.eventChannels.get(key);
+        if (!ch) {
+            ch = new Events_1.EventChannel();
+            this.eventChannels.set(key, ch);
+        }
+        return ch;
+    };
     return World;
 }());
 exports.World = World;

package/lib/index.d.ts

@@ -3,3 +3,4 @@ export * from "./ecs/TypeRegistry";
 export * from "./ecs/Commands";
 export * from "./ecs/World";
 export * from "./ecs/Schedule";
+export * from "./ecs/Events";

package/lib/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./ecs/TypeRegistry"), exports);
 __exportStar(require("./ecs/Commands"), exports);
 __exportStar(require("./ecs/World"), exports);
 __exportStar(require("./ecs/Schedule"), exports);
+__exportStar(require("./ecs/Events"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archetype-ecs-lib",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "An Archetype Entity Component System (AECS)",
   "main": "./lib/index.js",
   "scripts": {
@@ -13,6 +13,7 @@
     "type": "git",
     "url": "git+https://github.com/PirateJL/archetype-ecs-lib.git"
   },
+  "homepage": "https://piratejl.github.io/archetype-ecs-lib",
   "keywords": [
     "game",
     "gamedev",