archetype-ecs-lib 0.6.0 → 1.0.0

package/README.md

@@ -14,7 +14,8 @@ A tiny **archetype-based ECS** (Entity Component System) for TypeScript.
 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/)
+> :exclamation: The full documentation is at [https://piratejl.github.io/archetype-ecs-lib/](https://piratejl.github.io/archetype-ecs-lib/)  
+> Can view the [Changelog here](https://piratejl.github.io/archetype-ecs-lib/changelog/)
 
 ---
 
@@ -55,7 +56,7 @@ world.addSystem((w) => {
 world.update(1 / 60);
 ```
 
-> Note: `SystemFn` is typed as `(world: WorldApi, dt) => void`..
+> Note: `SystemFn` is typed as `(world: WorldApi, dt) => void`.
 
 ---
 

package/lib/ecs/Archetype.d.ts

@@ -4,6 +4,13 @@ export declare class Archetype {
     readonly sig: Signature;
     private readonly cols;
     readonly entities: Entity[];
+    /**
+     * Archetype graph edges: cache destination archetype for single-component add/remove transitions.
+     * Key: TypeId being added/removed. Value: destination Archetype after the transition.
+     * Populated lazily in World.add() / World.remove().
+     */
+    readonly addEdges: Map<number, Archetype>;
+    readonly removeEdges: Map<number, Archetype>;
     constructor(id: number, sig: Signature);
     /**
      * Adds a new row. The caller must push per-column values in the same order.

package/lib/ecs/Archetype.js

@@ -35,6 +35,13 @@ var Archetype = /** @class */ (function () {
         this.cols = new Map();
         // Entity handles stored per row
         this.entities = [];
+        /**
+         * Archetype graph edges: cache destination archetype for single-component add/remove transitions.
+         * Key: TypeId being added/removed. Value: destination Archetype after the transition.
+         * Populated lazily in World.add() / World.remove().
+         */
+        this.addEdges = new Map();
+        this.removeEdges = new Map();
         this.id = id;
         this.sig = sig;
         try {

package/lib/ecs/Commands.d.ts

@@ -10,21 +10,29 @@ export type Command = {
     e: Entity;
     ctor: ComponentCtor<any>;
     value: any;
+} | {
+    k: "addMany";
+    e: Entity;
+    items: ComponentCtorBundleItem[];
 } | {
     k: "remove";
     e: Entity;
     ctor: ComponentCtor<any>;
+} | {
+    k: "removeMany";
+    e: Entity;
+    ctors: ComponentCtor<any>[];
 };
 export declare class Commands implements CommandsApi {
     private q;
     spawn(init?: (e: Entity) => void): void;
-    spawnBundle(...items: ComponentCtorBundleItem[]): void;
+    spawnWith(...items: ComponentCtorBundleItem[]): void;
     despawn(e: Entity): void;
-    despawnBundle(entities: Entity[]): void;
+    despawnMany(entities: Entity[]): void;
     add<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;
-    addBundle(e: Entity, ...items: ComponentCtorBundleItem[]): void;
+    addMany(e: Entity, ...items: ComponentCtorBundleItem[]): void;
     remove<T>(e: Entity, ctor: ComponentCtor<T>): void;
-    removeBundle(e: Entity, ...ctors: ComponentCtor<any>[]): void;
+    removeMany(e: Entity, ...ctors: ComponentCtor<any>[]): void;
     hasPending(): boolean;
     drain(): Command[];
 }

package/lib/ecs/Commands.js

@@ -35,7 +35,7 @@ var Commands = /** @class */ (function () {
     Commands.prototype.spawn = function (init) {
         this.q.push({ k: "spawn", init: init });
     };
-    Commands.prototype.spawnBundle = function () {
+    Commands.prototype.spawnWith = function () {
         var _this = this;
         var items = [];
         for (var _i = 0; _i < arguments.length; _i++) {
@@ -62,7 +62,7 @@ var Commands = /** @class */ (function () {
     Commands.prototype.despawn = function (e) {
         this.q.push({ k: "despawn", e: e });
     };
-    Commands.prototype.despawnBundle = function (entities) {
+    Commands.prototype.despawnMany = 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()) {
@@ -81,48 +81,26 @@ var Commands = /** @class */ (function () {
     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;
+    Commands.prototype.addMany = function (e) {
         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; }
-        }
+        if (items.length === 0)
+            return;
+        this.q.push({ k: "addMany", e: e, items: items });
     };
     Commands.prototype.remove = function (e, ctor) {
         this.q.push({ k: "remove", e: e, ctor: ctor });
     };
-    Commands.prototype.removeBundle = function (e) {
-        var e_4, _a;
+    Commands.prototype.removeMany = function (e) {
         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; }
-        }
+        if (ctors.length === 0)
+            return;
+        this.q.push({ k: "removeMany", e: e, ctors: ctors });
     };
     Commands.prototype.hasPending = function () {
         return this.q.length > 0;

package/lib/ecs/Schedule.d.ts

@@ -124,7 +124,7 @@ export declare class Schedule {
      * - phases explicitly registered via `add()` keep insertion order when unconstrained
      * - remaining ties fall back to lexicographic order
      *
-     * @param world World instance to get phases from.
+     * @param phases Phase -> systems mapping from the World.
      * @returns A valid phase order that satisfies all constraints.
      * @throws If constraints contain a cycle.
      * @internal

package/lib/ecs/Schedule.js

@@ -177,67 +177,72 @@ var Schedule = /** @class */ (function () {
         if (worldInstance._getSystemCount() > 0) {
             worldInstance._warnAboutLifecycleConflict("Schedule.run");
         }
-        var phases = (_c = phaseOrder !== null && phaseOrder !== void 0 ? phaseOrder : this.phaseOrder) !== null && _c !== void 0 ? _c : this._computePhaseOrder(world);
+        var scheduleSystems = worldInstance._scheduleSystems;
+        var phases = (_c = phaseOrder !== null && phaseOrder !== void 0 ? phaseOrder : this.phaseOrder) !== null && _c !== void 0 ? _c : this._computePhaseOrder(scheduleSystems);
         if (!phases || phases.length === 0) {
             throw new Error('Schedule.run requires a phase order (pass it as an argument or call schedule.setOrder([...]))');
         }
         var frameStart = worldInstance._profBeginFrame(dt);
         try {
-            for (var phases_1 = __values(phases), phases_1_1 = phases_1.next(); !phases_1_1.done; phases_1_1 = phases_1.next()) {
-                var phase = phases_1_1.value;
-                var phaseStart = performance.now();
-                var list = world._scheduleSystems.get(phase);
-                // Run systems only if they exist for this phase
-                if (list) {
-                    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;
-                            var sysStart = performance.now();
-                            try {
-                                fn(world, dt);
-                            }
-                            catch (error) {
-                                var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
-                                var msg = error.message !== undefined && typeof error.message === 'string' ?
-                                    error.message : JSON.stringify(error);
-                                var e = new Error("[phase=".concat(phase, " system=").concat(sysName, "] ").concat(msg));
-                                e.cause = error;
-                                throw e;
+            try {
+                for (var phases_1 = __values(phases), phases_1_1 = phases_1.next(); !phases_1_1.done; phases_1_1 = phases_1.next()) {
+                    var phase = phases_1_1.value;
+                    var phaseStart = performance.now();
+                    var list = scheduleSystems.get(phase);
+                    // Run systems only if they exist for this phase
+                    if (list) {
+                        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;
+                                var sysStart = performance.now();
+                                try {
+                                    fn(world, dt);
+                                }
+                                catch (error) {
+                                    var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
+                                    var msg = error.message !== undefined && typeof error.message === 'string' ?
+                                        error.message : JSON.stringify(error);
+                                    var e = new Error("[phase=".concat(phase, " system=").concat(sysName, "] ").concat(msg));
+                                    e.cause = error;
+                                    throw e;
+                                }
+                                finally {
+                                    var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
+                                    worldInstance._profAddSystem("".concat(phase, ":").concat(sysName), performance.now() - sysStart);
+                                }
                             }
-                            finally {
-                                var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
-                                worldInstance._profAddSystem("".concat(phase, ":").concat(sysName), performance.now() - sysStart);
+                        }
+                        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; }
                         }
                     }
-                    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);
+                    if (this.boundaryMode !== "manual") {
+                        // apply deferred commands between phases
+                        if (world.cmd().hasPending()) {
+                            world.flush();
                         }
-                        finally { if (e_2) throw e_2.error; }
+                        // deliver events emitted in this phase to the next phase
+                        world.swapEvents();
                     }
+                    worldInstance._profAddPhase(phase, performance.now() - phaseStart);
                 }
-                if (this.boundaryMode !== "manual") {
-                    // apply deferred commands between phases
-                    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 }; }
+            finally {
+                try {
+                    if (phases_1_1 && !phases_1_1.done && (_a = phases_1.return)) _a.call(phases_1);
                 }
-                worldInstance._profAddPhase(phase, performance.now() - phaseStart);
+                finally { if (e_1) throw e_1.error; }
             }
         }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
         finally {
-            try {
-                if (phases_1_1 && !phases_1_1.done && (_a = phases_1.return)) _a.call(phases_1);
-            }
-            finally { if (e_1) throw e_1.error; }
+            worldInstance._profEndFrame(frameStart);
+            worldInstance.updateOverlay(worldInstance.stats(), worldInstance.statsHistory());
         }
-        worldInstance._profEndFrame(frameStart);
-        worldInstance.updateOverlay(worldInstance.stats(), worldInstance.statsHistory());
     };
     /**
      * Record a phase ordering constraint `before -> after`.
@@ -266,15 +271,14 @@ var Schedule = /** @class */ (function () {
      * - phases explicitly registered via `add()` keep insertion order when unconstrained
      * - remaining ties fall back to lexicographic order
      *
-     * @param world World instance to get phases from.
+     * @param phases Phase -> systems mapping from the World.
      * @returns A valid phase order that satisfies all constraints.
      * @throws If constraints contain a cycle.
      * @internal
      */
-    Schedule.prototype._computePhaseOrder = function (world) {
+    Schedule.prototype._computePhaseOrder = function (phases) {
         var e_3, _a, e_4, _b, e_5, _c, e_6, _d, e_7, _e, e_8, _f, e_9, _g, e_10, _h, e_11, _j;
         var _k, _l;
-        var phases = world._scheduleSystems;
         // Collect all known phases (defined or referenced by constraints)
         var all = new Set();
         try {

package/lib/ecs/Signature.d.ts

@@ -6,3 +6,7 @@ export declare function subtractSignature(sig: Signature, remove: TypeId): TypeI
  * True if `need` is a subset of `have`. Both must be sorted ascending.
  */
 export declare function signatureHasAll(have: Signature, need: Signature): boolean;
+/**
+ * True if `have` contains at least one element from `any`. Both must be sorted ascending.
+ */
+export declare function signatureHasAny(have: Signature, any: Signature): boolean;

package/lib/ecs/Signature.js

@@ -4,6 +4,7 @@ exports.signatureKey = signatureKey;
 exports.mergeSignature = mergeSignature;
 exports.subtractSignature = subtractSignature;
 exports.signatureHasAll = signatureHasAll;
+exports.signatureHasAny = signatureHasAny;
 function signatureKey(sig) {
     // canonical: sorted ascending, joined
     return sig.join(",");
@@ -48,3 +49,21 @@ function signatureHasAll(have, need) {
     }
     return j === need.length;
 }
+/**
+ * True if `have` contains at least one element from `any`. Both must be sorted ascending.
+ */
+function signatureHasAny(have, any) {
+    var i = 0;
+    var j = 0;
+    while (i < have.length && j < any.length) {
+        var a = have[i];
+        var b = any[j];
+        if (a === b)
+            return true;
+        if (a < b)
+            i++;
+        else
+            j++;
+    }
+    return false;
+}

package/lib/ecs/Types.d.ts

@@ -18,12 +18,47 @@ export type Signature = ReadonlyArray<TypeId>;
  */
 export type ComponentCtor<T> = (new (...args: any[]) => T) | ((...args: any[]) => T);
 export type ComponentCtorBundleItem<T = any> = readonly [ComponentCtor<T>, T];
+/**
+ * A reusable, named group of component/value pairs.
+ *
+ * @example
+ * ```ts
+ * const PhysicsBundle = bundle([Position, { x: 0, y: 0 }], [Velocity, { x: 0, y: 0 }]);
+ * world.spawnWith(...PhysicsBundle);
+ * world.cmd().spawnWith(...PhysicsBundle);
+ * ```
+ */
+export type Bundle = readonly ComponentCtorBundleItem[];
+/**
+ * Create a typed, reusable bundle (a list of component/value pairs).
+ * Bundles can be spread into `spawnWith`, `addMany`, or `cmd().spawnWith`.
+ */
+export declare function bundle(...items: ComponentCtorBundleItem[]): Bundle;
 /**
  * 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: WorldApi, dt: number) => void;
+/**
+ * Optional filter applied to any query.
+ *
+ * - `without`: exclude archetypes that have ANY of these component types.
+ * - `with`: require these component types to be present without returning their values.
+ *
+ * @example
+ * ```ts
+ * // Entities with Position but NOT Dead
+ * world.query(Position, { without: [Dead] })
+ *
+ * // Entities with Position AND Active marker, but NOT Frozen
+ * world.query(Position, { with: [Active], without: [Frozen] })
+ * ```
+ */
+export type QueryFilter = {
+    readonly without?: ReadonlyArray<ComponentCtor<any>>;
+    readonly with?: ReadonlyArray<ComponentCtor<any>>;
+};
 export type SnapshotCodec<T, D = unknown> = Readonly<{
     /**
      * Stable key written into the snapshot payload.
@@ -63,13 +98,13 @@ export type WorldSnapshot = Readonly<{
  */
 export interface CommandsApi {
     spawn(init?: (e: Entity) => void): void;
-    spawnBundle(...items: ComponentCtorBundleItem[]): void;
+    spawnWith(...items: ComponentCtorBundleItem[]): void;
     despawn(e: Entity): void;
-    despawnBundle(entities: Entity[]): void;
+    despawnMany(entities: Entity[]): void;
     add<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;
-    addBundle(e: Entity, ...items: ComponentCtorBundleItem[]): void;
+    addMany(e: Entity, ...items: ComponentCtorBundleItem[]): void;
     remove<T>(e: Entity, ctor: ComponentCtor<T>): void;
-    removeBundle(e: Entity, ...ctors: ComponentCtor<any>[]): void;
+    removeMany(e: Entity, ...ctors: ComponentCtor<any>[]): void;
     hasPending(): boolean;
 }
 export type QueryRow1<A> = {
@@ -186,14 +221,15 @@ export type WorldStatsHistory = Readonly<{
 export interface WorldApi {
     stats(): WorldStats;
     statsHistory(): WorldStatsHistory;
-    /** @internal Phase -> systems mapping for Schedule */
-    readonly _scheduleSystems: Map<string, SystemFn[]>;
-    /** @internal Returns the number of systems registered via addSystem() */
-    _getSystemCount(): number;
     /** Enables/disables profiling (system/phase timing). */
     setProfilingEnabled(enabled: boolean): void;
     /** Set how many frames of the profiling history to keep (default: 120). */
     setProfilingHistorySize(frames: number): void;
+    /**
+     * Destroy this world, releasing all archetypes, entities, resources, and event channels.
+     * Any further use of the world after calling this will throw.
+     */
+    destroy(): void;
     cmd(): CommandsApi;
     addSystem(fn: SystemFn): this;
     update(dt: number): void;
@@ -254,7 +290,7 @@ export interface WorldApi {
      */
     swapEvents(): void;
     spawn(): Entity;
-    spawnMany(...items: ComponentCtorBundleItem[]): Entity;
+    spawnWith(...items: ComponentCtorBundleItem[]): Entity;
     despawn(e: Entity): void;
     despawnMany(entities: Entity[]): void;
     isAlive(e: Entity): boolean;
@@ -265,25 +301,31 @@ export interface WorldApi {
     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>;
-    queryTables<A>(c1: ComponentCtor<A>): Iterable<QueryTable1<A>>;
-    queryTables<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>): Iterable<QueryTable2<A, B>>;
-    queryTables<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>): Iterable<QueryTable3<A, B, C>>;
-    queryTables<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>): Iterable<QueryTable4<A, B, C, D>>;
-    queryTables<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryTable5<A, B, C, D, E>>;
-    queryTables<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<QueryTable6<A, B, C, D, E, F>>;
-    queryTables(...ctors: ComponentCtor<any>[]): Iterable<any>;
+    query<A>(c1: ComponentCtor<A>, filter?: QueryFilter): Iterable<QueryRow1<A>>;
+    query<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, filter?: QueryFilter): Iterable<QueryRow2<A, B>>;
+    query<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, filter?: QueryFilter): Iterable<QueryRow3<A, B, C>>;
+    query<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, filter?: QueryFilter): 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>, filter?: QueryFilter): 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>, filter?: QueryFilter): Iterable<QueryRow6<A, B, C, D, E, F>>;
+    query(...args: any[]): Iterable<any>;
+    queryTables<A>(c1: ComponentCtor<A>, filter?: QueryFilter): Iterable<QueryTable1<A>>;
+    queryTables<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, filter?: QueryFilter): Iterable<QueryTable2<A, B>>;
+    queryTables<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, filter?: QueryFilter): Iterable<QueryTable3<A, B, C>>;
+    queryTables<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, filter?: QueryFilter): Iterable<QueryTable4<A, B, C, D>>;
+    queryTables<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, filter?: QueryFilter): Iterable<QueryTable5<A, B, C, D, E>>;
+    queryTables<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, filter?: QueryFilter): Iterable<QueryTable6<A, B, C, D, E, F>>;
+    queryTables(...args: any[]): Iterable<any>;
     queryEach<A>(c1: ComponentCtor<A>, fn: (e: Entity, c1: A) => void): void;
+    queryEach<A>(c1: ComponentCtor<A>, filter: QueryFilter, fn: (e: Entity, c1: A) => void): void;
     queryEach<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, fn: (e: Entity, c1: A, c2: B) => void): void;
+    queryEach<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B) => void): void;
     queryEach<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, fn: (e: Entity, c1: A, c2: B, c3: C) => void): void;
+    queryEach<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C) => void): void;
     queryEach<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D) => void): void;
+    queryEach<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D) => void): void;
     queryEach<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E) => void): void;
+    queryEach<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E) => void): void;
     queryEach<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E, c6: F) => void): void;
+    queryEach<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E, c6: F) => void): void;
     queryEach(...args: any[]): void;
 }

package/lib/ecs/Types.js

@@ -1,2 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundle = bundle;
+/**
+ * Create a typed, reusable bundle (a list of component/value pairs).
+ * Bundles can be spread into `spawnWith`, `addMany`, or `cmd().spawnWith`.
+ */
+function bundle() {
+    var items = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        items[_i] = arguments[_i];
+    }
+    return items;
+}

package/lib/ecs/World.d.ts

@@ -1,6 +1,6 @@
 import { Commands } from "./Commands";
 import { EventChannel } from "./Events";
-import type { ComponentCtor, ComponentCtorBundleItem, Entity, QueryRow1, QueryRow2, QueryRow3, QueryRow4, QueryRow5, QueryRow6, QueryTable1, QueryTable2, QueryTable3, QueryTable4, QueryTable5, QueryTable6, SnapshotCodec, SystemFn, WorldApi, WorldSnapshot, WorldStats, WorldStatsHistory } from "./Types";
+import type { ComponentCtor, ComponentCtorBundleItem, Entity, QueryFilter, QueryRow1, QueryRow2, QueryRow3, QueryRow4, QueryRow5, QueryRow6, QueryTable1, QueryTable2, QueryTable3, QueryTable4, QueryTable5, QueryTable6, SnapshotCodec, SystemFn, WorldApi, WorldSnapshot, WorldStats, WorldStatsHistory } from "./Types";
 import { StatsOverlay, type StatsOverlayOptions } from "./stats/StatsOverlay";
 export declare class World extends StatsOverlay implements WorldApi {
     private readonly entities;
@@ -12,8 +12,15 @@ export declare class World extends StatsOverlay implements WorldApi {
     private readonly resources;
     private readonly eventChannels;
     private readonly snapshotStore;
+    /**
+     * Query result cache: maps a sorted query signature key → matching archetypes.
+     * `checked` tracks how many archetypes were scanned when the entry was last updated.
+     * Because archetypes are append-only, new ones are scanned incrementally on next use.
+     */
+    private readonly _queryCache;
     /** @internal Phase -> systems mapping for Schedule */
     readonly _scheduleSystems: Map<string, SystemFn[]>;
+    private _destroyed;
     constructor(options?: {
         statsOverlayOptions: StatsOverlayOptions;
     });
@@ -50,6 +57,7 @@ export declare class World extends StatsOverlay implements WorldApi {
      */
     update(dt: number): void;
     flush(): void;
+    destroy(): void;
     registerComponentSnapshot<T, D = unknown>(key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): this;
     unregisterComponentSnapshot<T>(key: ComponentCtor<T>): boolean;
     registerResourceSnapshot<T, D = unknown>(key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): this;
@@ -69,7 +77,7 @@ export declare class World extends StatsOverlay implements WorldApi {
     /** @internal Called by Schedule at phase boundaries */
     swapEvents(): void;
     spawn(): Entity;
-    spawnMany(...items: ComponentCtorBundleItem[]): Entity;
+    spawnWith(...items: ComponentCtorBundleItem[]): Entity;
     isAlive(e: Entity): boolean;
     despawn(e: Entity): void;
     despawnMany(entities: Entity[]): void;
@@ -84,34 +92,49 @@ export declare class World extends StatsOverlay implements WorldApi {
      * Query all entities having all required component types.
      * Iterates archetypes (tables) and yields SoA columns for cache-friendly loops.
      */
-    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<A>(c1: ComponentCtor<A>, filter?: QueryFilter): Iterable<QueryRow1<A>>;
+    query<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, filter?: QueryFilter): Iterable<QueryRow2<A, B>>;
+    query<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, filter?: QueryFilter): Iterable<QueryRow3<A, B, C>>;
+    query<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, filter?: QueryFilter): 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>, filter?: QueryFilter): 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>, filter?: QueryFilter): Iterable<QueryRow6<A, B, C, D, E, F>>;
     /**
      * Table query: yields one item per matching archetype (SoA columns + entity array).
      * This avoids allocating one object per entity row.
      */
-    queryTables<A>(c1: ComponentCtor<A>): Iterable<QueryTable1<A>>;
-    queryTables<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>): Iterable<QueryTable2<A, B>>;
-    queryTables<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>): Iterable<QueryTable3<A, B, C>>;
-    queryTables<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>): Iterable<QueryTable4<A, B, C, D>>;
-    queryTables<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryTable5<A, B, C, D, E>>;
-    queryTables<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<QueryTable6<A, B, C, D, E, F>>;
+    queryTables<A>(c1: ComponentCtor<A>, filter?: QueryFilter): Iterable<QueryTable1<A>>;
+    queryTables<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, filter?: QueryFilter): Iterable<QueryTable2<A, B>>;
+    queryTables<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, filter?: QueryFilter): Iterable<QueryTable3<A, B, C>>;
+    queryTables<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, filter?: QueryFilter): Iterable<QueryTable4<A, B, C, D>>;
+    queryTables<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, filter?: QueryFilter): Iterable<QueryTable5<A, B, C, D, E>>;
+    queryTables<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, filter?: QueryFilter): Iterable<QueryTable6<A, B, C, D, E, F>>;
     /**
      * Callback query: calls `fn` for each matching entity row (no yield object allocations).
      */
     queryEach<A>(c1: ComponentCtor<A>, fn: (e: Entity, c1: A) => void): void;
+    queryEach<A>(c1: ComponentCtor<A>, filter: QueryFilter, fn: (e: Entity, c1: A) => void): void;
     queryEach<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, fn: (e: Entity, c1: A, c2: B) => void): void;
+    queryEach<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B) => void): void;
     queryEach<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, fn: (e: Entity, c1: A, c2: B, c3: C) => void): void;
+    queryEach<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C) => void): void;
     queryEach<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D) => void): void;
+    queryEach<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D) => void): void;
     queryEach<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E) => void): void;
+    queryEach<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E) => void): void;
     queryEach<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E, c6: F) => void): void;
+    queryEach<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, filter: QueryFilter, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E, c6: F) => void): void;
     private _snapshotRuntime;
     private _resetArchetypes;
+    private static _isQueryFilter;
+    private static _splitArgs;
+    /**
+     * Returns the list of archetypes matching `needSorted` (a sorted, deduped TypeId array).
+     * Results are cached per query signature. Because archetypes are append-only, stale entries
+     * are extended incrementally — only newly-added archetypes are re-scanned.
+     */
+    private _matchingArchetypes;
     private static _buildQueryTypeIds;
+    private _ensureNotDestroyed;
     private _ensureNotIterating;
     private _getOrCreateArchetype;
     private _removeFromArchetype;