@vworlds/vecs 1.0.3 → 1.0.4

package/README.md

@@ -14,18 +14,20 @@ yarn add @vworlds/vecs
 
 | Concept | What it is |
 |---|---|
-| **World** | Central container. Owns all entities, runs all systems. |
+| **World** | Central container. Owns all entities, runs all systems and queries. |
 | **Component** | A plain data class. Extend `Component` and attach instances to entities. |
 | **Entity** | An integer id with a set of components. Create via the world. |
-| **System** | Reactive logic. Declare which components you need; get called when things change. |
+| **Query** | A reactive, always-updated set of entities that match a predicate. |
+| **System** | A `Query` with per-tick runtime logic (phases, `update`, `each`, `run`). |
+| **Filter** | A non-reactive, one-shot scan: walks all world entities on each `forEach` call. |
 
 ### Lifecycle in brief
 
 ```
-registerComponent() × N  →  system() × N  →  start()  →  progress() every frame
+registerComponent() × N  →  system() / query() × N  →  start()  →  progress() every frame
 ```
 
-After `start()`, no new components or systems can be registered.
+After `start()`, component registration is disabled. Systems and queries can still be created — standalone queries backfill existing matched entities immediately.
 
 ---
 
@@ -112,17 +114,12 @@ world.start(); // freeze registration, sort systems into phases
 // ─── Create entities ───────────────────────────────────────────────────────
 
 const bullet = world.createEntity();
-const pos = bullet.add(Position);
-pos.x = 0;
-pos.y = 0;
+bullet.set(Position, { x: 0, y: 0 });
 
-const vel = bullet.add(Velocity);
-vel.vx = 5;
-vel.vy = 0;
+const vel = bullet.set(Velocity, { vx: 5, vy: 0 });
 vel.modified(); // first update: notify Move system
 
-const hp = bullet.add(Health);
-hp.hp = 3;
+const hp = bullet.set(Health, { hp: 3 });
 hp.modified();
 
 // ─── Game loop ─────────────────────────────────────────────────────────────
@@ -197,9 +194,54 @@ world.system("MySystem")
   .update(...)
   .exit(...);
 
-world.start(); // must be called once, after all systems are set up
+world.start(); // distributes systems to phases, freezes component registration
 ```
 
+#### Queries
+
+A standalone `Query` is a reactive entity set without a phase or per-tick callbacks. Use it when you need the matched set kept up-to-date automatically — for example to enumerate scene nodes or find the nearest enemy.
+
+```ts
+const enemies = world.query("Enemies")
+  .requires(Enemy, Health)
+  .enter((e) => console.log("enemy spawned", e.eid))
+  .exit((e)  => console.log("enemy died",    e.eid));
+
+world.start();
+// enemies.entities is kept up-to-date automatically
+
+// Can also be created after start(); existing matched entities are backfilled:
+const lateQuery = world.query("Walls").requires(Wall);
+// lateQuery.entities immediately contains all current Wall entities
+```
+
+#### Filters
+
+A `Filter` is a non-reactive, one-shot scan. It holds no tracked entity set — each `forEach` call walks all world entities at that moment. Use it for ad-hoc lookups that don't need to stay live.
+
+```ts
+// Entity only:
+world.filter([Position]).forEach((e) => console.log(e.eid));
+
+// With component injection:
+world.filter([Position, Velocity])
+  .forEach([Position, Velocity], (e, [pos, vel]) => {
+    pos.x += vel.vx;
+  });
+
+// Full DSL, with auto-deduced required components:
+world.filter({ AND: [{ HAS: Position }, { HAS: Velocity }] })
+  .forEach([Position, Velocity], (e, [pos, vel]) => {
+    pos.x += vel.vx; // pos and vel are non-null — deduced from AND of HAS
+  });
+
+// Manual type hint for queries the extractor can't see through:
+world.filter({ OR: [Position, Velocity] }, [Position])
+  .forEach([Position], (e, [pos]) => pos.x);
+```
+
+Unlike `Query`, a `Filter` requires no name, no `world.start()`, and no `destroy()` — create it anywhere and discard it freely.
+
 #### Phases
 
 ```ts
@@ -275,6 +317,7 @@ const e = world.createEntity();
 | `eid` | Unique numeric entity id. |
 | `world` | The `World` that owns this entity. |
 | `add(Class)` | Attach a component; returns the typed instance. Idempotent. |
+| `set(Class, props)` | Like `add`, but also assigns the given partial properties onto the instance. Returns the typed instance. |
 | `get(Class)` | Return the component instance, or `undefined` if not present. |
 | `remove(Class)` | Detach a component (triggers `onRemove` hooks and `exit` callbacks). |
 | `destroy()` | Remove all components and unregister the entity. Recurses to children. |
@@ -436,7 +479,9 @@ Iterating `system.entities` after a phase run yields entities in the sorted orde
 
 #### `.track()`
 
-Enable entity tracking without an `each` callback — matched entities are exposed via `system.entities` as they enter and leave. `each` and `sort` imply `track` automatically; call this directly only when you need the set without a per-tick callback.
+Enable entity tracking without an `each` callback — matched entities are exposed via `system.entities` (or `query.entities`) as they enter and leave. `each` and `sort` imply `track` automatically; call this directly only when you need the tracked set without a per-tick callback.
+
+When called after `world.start()`, `track()` immediately backfills existing entities that satisfy the query predicate.
 
 #### `.run(callback)`
 
@@ -450,6 +495,82 @@ Called every tick when the system's phase runs, regardless of entity state. Use
 
 ---
 
+### Query
+
+A standalone query is created via `world.query(name)` and configured through the same fluent builder API as `System` (`requires`, `query`, `enter`, `exit`, `sort`, `track`, `forEach`, `entities`). It has no phase and no per-tick callbacks.
+
+```ts
+const projectiles = world.query("Projectiles")
+  .requires(Position, Velocity)
+  .sort([Position], ([a], [b]) => a.z - b.z)
+  .enter([Position], (e, [pos]) => { pos.x = spawnX; });
+
+world.start();
+
+// Anywhere in game code:
+projectiles.forEach((e) => { /* ... */ });
+console.log(projectiles.entities.size, "active projectiles");
+```
+
+| Method | Description |
+|---|---|
+| `.requires(...components)` | Set the membership predicate and start tracking. |
+| `.query(expr)` | Set the membership predicate using the {@link SystemQuery} DSL. |
+| `.enter(callback)` / `.enter(inject, callback)` | Fires when an entity joins the query. |
+| `.exit(callback)` / `.exit(inject, callback)` | Fires when an entity leaves the query. |
+| `.sort(components, compare)` | Store matched entities in sorted order. |
+| `.track()` | Enable tracking (implied by `sort`; backfills when called after `start`). |
+| `.belongs(e)` | Returns `true` if the entity satisfies the predicate. |
+| `.forEach(callback)` | Iterate all currently tracked entities (entity only). |
+| `.forEach(components, callback)` | Iterate with component injection — same signature as `Filter.forEach`. |
+| `.entities` | `ReadonlySet<Entity>` of all currently tracked entities. |
+| `.destroy()` | Remove the query from the world and all entities. See below. |
+
+#### `.destroy()`
+
+Permanently removes a standalone query from the world. All entity references are silently purged (no exit callbacks fire), the tracked entity set is cleared, and the query's `world` reference is set to `undefined`. After this call, any use of the query object is **undefined behavior**.
+
+```ts
+const q = world.query("Temporary").requires(Position);
+// ... use q.entities ...
+q.destroy(); // unregisters from world and all entities
+```
+
+`System` does **not** support `destroy()` — calling it throws. Systems are owned by the world for the lifetime of the session. Use a standalone `Query` when you need a temporary reactive set.
+
+Both `System` and `Query` share the same query DSL, enter/exit callbacks, sort, and `entities` set — `System` extends `Query` and layers phase execution on top.
+
+---
+
+### Filter
+
+A `Filter` is created via `world.filter(dsl)` and provides a non-reactive `forEach`. It accepts the same [`QueryDSL`](#-requirescomponents-and-queryq) expressions as systems and queries.
+
+```ts
+const f = world.filter([Position, Velocity]);
+```
+
+| Method | Description |
+|---|---|
+| `.forEach(callback)` | Walk all world entities; invoke callback for each matching one. |
+| `.forEach(components, callback)` | Same, with component injection and non-null types for required components. |
+
+**Type inference** works the same way as for `requires()` on systems/queries: component classes extractable from the DSL (`HAS`, `HAS_ONLY`, plain arrays, and `AND` of those) are non-nullable in the callback tuple. Pass a `_guaranteed` second argument to `world.filter()` as a manual override when inference can't reach:
+
+```ts
+// Auto-deduced — both non-null:
+world.filter([Position, Velocity])
+  .forEach([Position, Velocity], (e, [pos, vel]) => { ... });
+
+// Manual hint for OR / NOT / PARENT / custom function:
+world.filter({ OR: [Position, Velocity] }, [Position])
+  .forEach([Position], (e, [pos]) => pos.x);
+```
+
+A `Filter` holds no tracked set, makes no registration calls, and needs no `destroy()`.
+
+---
+
 ## Build & Test
 
 ```

package/dist/dsl.d.ts

@@ -0,0 +1,71 @@
+import { Component, ComponentClassArray, ComponentClassOrType } from "./component.js";
+import type { Entity } from "./entity.js";
+import type { World } from "./world.js";
+/** A function that tests whether a given entity belongs to a query. */
+export type EntityTestFunc = (e: Entity) => boolean;
+/**
+ * A composable query expression used to declare which entities a
+ * {@link Query} or {@link System} should track.
+ *
+ * Queries can be nested arbitrarily:
+ *
+ * ```ts
+ * // Entities that have Position AND (Sprite OR Container):
+ * world.system("render").query({
+ *   AND: [Position, { OR: [Sprite, Container] }]
+ * });
+ *
+ * // Entities that have a parent with Player AND Container:
+ * world.system("attach").query({
+ *   PARENT: { AND: [Player, Container] }
+ * });
+ * ```
+ *
+ * Short forms:
+ * - A single class or type id is equivalent to `{ HAS: [C] }`.
+ * - An array `[A, B]` is equivalent to `{ HAS: [A, B] }`.
+ * - Pass an {@link EntityTestFunc} directly for fully custom membership logic.
+ */
+export type QueryDSL = ComponentClassArray | ComponentClassOrType | EntityTestFunc | {
+    HAS: ComponentClassArray | ComponentClassOrType;
+} | {
+    HAS_ONLY: ComponentClassArray | ComponentClassOrType;
+} | {
+    AND: readonly QueryDSL[];
+} | {
+    OR: readonly QueryDSL[];
+} | {
+    NOT: QueryDSL;
+} | {
+    PARENT: QueryDSL;
+};
+export declare function HAS(world: World, ...components: ComponentClassArray): EntityTestFunc;
+/**
+ * Resolves component nullability based on what was declared in `requires` (or
+ * the `_guaranteed` hint). Components in `R` are non-nullable; others are
+ * `InstanceType<C> | undefined`.
+ */
+export type MaybeRequired<C, R extends (typeof Component)[]> = C extends typeof Component ? C extends R[number] ? InstanceType<C> : InstanceType<C> | undefined : never;
+/**
+ * Statically extracts the component classes that are **guaranteed present** on
+ * every entity matched by a {@link QueryDSL} expression.
+ *
+ * Rules:
+ * - Plain class `C` → `[C]`
+ * - Plain array `[A, B]` → `[A, B]`
+ * - `{HAS: ...}` / `{HAS_ONLY: ...}` → recurse into the payload
+ * - `{AND: [q1, q2, ...]}` → concatenation of each branch's extraction
+ * - `{OR: ...}` / `{NOT: ...}` / `{PARENT: ...}` → `[]` (no guarantee)
+ * - `EntityTestFunc` / numeric type id → `[]` (opaque)
+ */
+export type ExtractRequired<Q> = Q extends typeof Component ? [Q] : Q extends readonly (typeof Component)[] ? Q : Q extends {
+    HAS: infer H;
+} ? ExtractRequired<H> : Q extends {
+    HAS_ONLY: infer H;
+} ? ExtractRequired<H> : Q extends {
+    AND: infer A extends readonly QueryDSL[];
+} ? ExtractAndChain<A> : [];
+type ExtractAndChain<A extends readonly QueryDSL[]> = A extends readonly [infer First, ...infer Rest extends readonly QueryDSL[]] ? [...ExtractRequired<First>, ...ExtractAndChain<Rest>] : [];
+/** Convert a {@link QueryDSL} expression into a runtime entity-test predicate. */
+export declare function buildEntityTest(world: World, q: QueryDSL): EntityTestFunc;
+export {};

package/dist/dsl.js

@@ -0,0 +1,58 @@
+import { Component, calculateComponentBitmask, } from "./component.js";
+export function HAS(world, ...components) {
+    const testBitmask = calculateComponentBitmask(components, world);
+    return (e) => e.componentBitmask.hasBitset(testBitmask);
+}
+function HAS_ONLY(world, ...components) {
+    const testBitmask = calculateComponentBitmask(components, world);
+    return (e) => e.componentBitmask.equal(testBitmask);
+}
+function NOT(func) {
+    return (e) => !func(e);
+}
+function AND(...funcs) {
+    return (e) => funcs.every((f) => f(e));
+}
+function OR(...funcs) {
+    return (e) => funcs.some((f) => f(e));
+}
+function PARENT(func) {
+    return (e) => (e.parent && func(e.parent)) || false;
+}
+/** Convert a {@link QueryDSL} expression into a runtime entity-test predicate. */
+export function buildEntityTest(world, q) {
+    if (typeof q === "number" ||
+        (typeof q === "function" && q.prototype instanceof Component)) {
+        return HAS(world, q);
+    }
+    else if (typeof q === "function") {
+        return q;
+    }
+    if (q instanceof Array) {
+        return HAS(world, ...q);
+    }
+    if ("HAS" in q) {
+        return buildEntityTest(world, q.HAS);
+    }
+    if ("HAS_ONLY" in q) {
+        const v = q.HAS_ONLY;
+        if (v instanceof Array) {
+            return HAS_ONLY(world, ...v);
+        }
+        return HAS_ONLY(world, v);
+    }
+    if ("AND" in q) {
+        return AND(...q.AND.map((sq) => buildEntityTest(world, sq)));
+    }
+    if ("OR" in q) {
+        return OR(...q.OR.map((sq) => buildEntityTest(world, sq)));
+    }
+    if ("NOT" in q) {
+        return NOT(buildEntityTest(world, q.NOT));
+    }
+    if ("PARENT" in q) {
+        return PARENT(buildEntityTest(world, q.PARENT));
+    }
+    throw "Unrecognized query term";
+}
+//# sourceMappingURL=dsl.js.map

package/dist/dsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../src/dsl.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAGT,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAyCxB,MAAM,UAAU,GAAG,CAAC,KAAY,EAAE,GAAG,UAA+B;IAClE,MAAM,WAAW,GAAG,yBAAyB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjE,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAY,EAAE,GAAG,UAA+B;IAChE,MAAM,WAAW,GAAG,yBAAyB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjE,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,GAAG,CAAC,IAAoB;IAC/B,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,GAAG,CAAC,GAAG,KAAuB;IACrC,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,EAAE,CAAC,GAAG,KAAuB;IACpC,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,MAAM,CAAC,IAAoB;IAClC,OAAO,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC;AAC9D,CAAC;AA4CD,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,KAAY,EAAE,CAAW;IACvD,IACE,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,OAAO,CAAC,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,YAAY,SAAS,CAAC,EAC7D;QACA,OAAO,GAAG,CAAC,KAAK,EAAE,CAAqB,CAAC,CAAC;KAC1C;SAAM,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE;QAClC,OAAO,CAAmB,CAAC;KAC5B;IAED,IAAI,CAAC,YAAY,KAAK,EAAE;QACtB,OAAO,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;KACzB;IAED,IAAI,KAAK,IAAI,CAAC,EAAE;QACd,OAAO,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;KACtC;IAED,IAAI,UAAU,IAAI,CAAC,EAAE;QACnB,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QACrB,IAAI,CAAC,YAAY,KAAK,EAAE;YACtB,OAAO,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;SAC9B;QACD,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;KAC3B;IAED,IAAI,KAAK,IAAI,CAAC,EAAE;QACd,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;KAC9D;IAED,IAAI,IAAI,IAAI,CAAC,EAAE;QACb,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;KAC5D;IAED,IAAI,KAAK,IAAI,CAAC,EAAE;QACd,OAAO,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;KAC3C;IAED,IAAI,QAAQ,IAAI,CAAC,EAAE;QACjB,OAAO,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;KACjD;IAED,MAAM,yBAAyB,CAAC;AAClC,CAAC"}

package/dist/entity.d.ts

@@ -1,6 +1,6 @@
 import { Component } from "./component.js";
 import type { World } from "./world.js";
-import { type System } from "./system.js";
+import { type Query } from "./query.js";
 import { Events } from "./util/events.js";
 import { Bitset } from "./util/bitset.js";
 type EntityEvents = Events<{
@@ -33,12 +33,12 @@ export declare class Entity {
     private deletedComponents;
     /**
      * Bitmask representing the set of component types currently attached to this
-     * entity. Used by the world to efficiently match entities against system
-     * queries.
+     * entity. Used by the world to efficiently match entities against query
+     * predicates.
      */
     readonly componentBitmask: Bitset;
-    private readonly systems;
-    private readonly newSystems;
+    private readonly queries;
+    private readonly newQueries;
     /**
      * A free-form property bag that modules can use to associate arbitrary data
      * with an entity without registering a component.
@@ -86,6 +86,22 @@ export declare class Entity {
      * @param markAsModified - Whether to queue an update notification.
      */
     add(type: number, markAsModified?: boolean): Component;
+    /**
+     * Add a component of type `Class` (if not already present) and assign the
+     * provided properties onto the instance, then return it.
+     *
+     * @param Class - The component class to instantiate.
+     * @param props - Optional properties to assign onto the component instance.
+     * @returns The new (or existing) component instance with the given properties applied.
+     */
+    set<C extends typeof Component>(Class: C, props: Partial<InstanceType<C>>): InstanceType<C>;
+    /**
+     * Add a component by its numeric type id and assign the provided properties.
+     *
+     * @param type - Numeric component type id.
+     * @param props - Optional properties to assign onto the component instance.
+     */
+    set(type: number, props: Partial<Component>): Component;
     /**
      * Remove the component of the given class from this entity.
      *
@@ -102,7 +118,7 @@ export declare class Entity {
      * @param type - Numeric component type id.
      */
     remove(type: number): void;
-    /** @internal Called by systems to deliver update notifications. */
+    /** @internal Called by queries to deliver update notifications. */
     _notifyModified(component: Component): void;
     /**
      * Retrieve the component of type `Class`, or `undefined` if not present.
@@ -124,13 +140,15 @@ export declare class Entity {
      */
     get events(): EntityEvents;
     /** @internal */
-    _hasSystem(s: System): boolean;
+    _hasQuery(q: Query): boolean;
+    /** @internal Removes a query from this entity's tracking sets without firing any callbacks. */
+    _purgeQuery(q: Query): void;
     /** @internal */
-    _addSystem(s: System): void;
+    _addQuery(q: Query): void;
     /** @internal */
-    _removeSystem(s: System): void;
+    _removeQuery(q: Query): void;
     /** @internal */
-    _updateSystems(): void;
+    _updateQueries(): void;
     /** `true` when the entity has no components attached. */
     get empty(): boolean;
     private _destroy;

package/dist/entity.js

@@ -31,12 +31,12 @@ export class Entity {
         this.deletedComponents = new ArrayMap(); //maps deleted component types to Components
         /**
          * Bitmask representing the set of component types currently attached to this
-         * entity. Used by the world to efficiently match entities against system
-         * queries.
+         * entity. Used by the world to efficiently match entities against query
+         * predicates.
          */
         this.componentBitmask = new Bitset();
-        this.systems = new Set();
-        this.newSystems = [];
+        this.queries = new Set();
+        this.newQueries = [];
         /**
          * A free-form property bag that modules can use to associate arbitrary data
          * with an entity without registering a component.
@@ -71,6 +71,10 @@ export class Entity {
             this.world._queueUpdatedComponent(c);
         return c;
     }
+    set(typeOrClass, props) {
+        const c = this.add(typeOrClass);
+        return Object.assign(c, props);
+    }
     remove(typeOrClass) {
         const type = this.world.getComponentType(typeOrClass);
         const c = this.components.get(type);
@@ -81,10 +85,10 @@ export class Entity {
             this.world._notifyComponentRemoved(this, c);
         }
     }
-    /** @internal Called by systems to deliver update notifications. */
+    /** @internal Called by queries to deliver update notifications. */
     _notifyModified(component) {
-        this.systems.forEach((s) => {
-            s.notifyModified(component);
+        this.queries.forEach((q) => {
+            q.notifyModified(component);
         });
     }
     /**
@@ -119,28 +123,35 @@ export class Entity {
         return this._events;
     }
     /** @internal */
-    _hasSystem(s) {
-        return this.systems.has(s);
+    _hasQuery(q) {
+        return this.queries.has(q);
+    }
+    /** @internal Removes a query from this entity's tracking sets without firing any callbacks. */
+    _purgeQuery(q) {
+        this.queries.delete(q);
+        const idx = this.newQueries.indexOf(q);
+        if (idx !== -1)
+            this.newQueries.splice(idx, 1);
     }
     /** @internal */
-    _addSystem(s) {
-        if (!this.systems.has(s)) {
-            this.newSystems.push(s);
-            s._enter(this);
+    _addQuery(q) {
+        if (!this.queries.has(q)) {
+            this.newQueries.push(q);
+            q._enter(this);
         }
     }
     /** @internal */
-    _removeSystem(s) {
-        if (this.systems.delete(s)) {
-            s._exit(this);
+    _removeQuery(q) {
+        if (this.queries.delete(q)) {
+            q._exit(this);
         }
     }
     /** @internal */
-    _updateSystems() {
-        this.newSystems.forEach((s) => {
-            this.systems.add(s);
+    _updateQueries() {
+        this.newQueries.forEach((q) => {
+            this.queries.add(q);
         });
-        this.newSystems.length = 0;
+        this.newQueries.length = 0;
     }
     /** `true` when the entity has no components attached. */
     get empty() {
@@ -150,10 +161,10 @@ export class Entity {
         if (this.destroyed)
             return;
         this.destroyed = true;
-        this.systems.forEach((s) => {
-            s._exit(this);
+        this.queries.forEach((q) => {
+            q._exit(this);
         });
-        this.systems.clear();
+        this.queries.clear();
         if (this._events) {
             this._events.emit("destroy");
             this._events.removeAllListeners("destroy");

package/dist/entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"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"}

package/dist/filter.d.ts

@@ -0,0 +1,59 @@
+import { Component } from "./component.js";
+import type { Entity } from "./entity.js";
+import type { World } from "./world.js";
+import { type MaybeRequired, type QueryDSL } from "./dsl.js";
+/**
+ * A non-reactive, one-shot entity filter.
+ *
+ * Unlike {@link Query}, a `Filter` holds no tracked entity set and registers
+ * nothing with the world. Every {@link forEach} call walks all world entities
+ * and invokes the callback for those that match the predicate captured at
+ * construction time.
+ *
+ * Create via {@link World.filter}:
+ *
+ * ```ts
+ * const f = world.filter([Position, Velocity]);
+ *
+ * // Entity only:
+ * f.forEach((e) => console.log(e.eid));
+ *
+ * // With component injection:
+ * f.forEach([Position, Velocity], (e, [pos, vel]) => {
+ *   pos.x += vel.vx;
+ * });
+ * ```
+ *
+ * ### Type parameter `R`
+ * Tracks which component classes are guaranteed present on every matched
+ * entity — inferred automatically from the DSL by {@link World.filter}, or
+ * supplied manually via the optional `_guaranteed` argument. Components in `R`
+ * appear as non-nullable in `forEach` callback tuples.
+ */
+export declare class Filter<R extends (typeof Component)[] = []> {
+    private readonly world;
+    private readonly belongs;
+    constructor(world: World, dsl: QueryDSL);
+    /**
+     * Iterate all world entities and call `callback` for each one that matches
+     * the DSL this filter was created with.
+     *
+     * @param callback - Receives only the entity.
+     */
+    forEach(callback: (e: Entity) => void): void;
+    /**
+     * Iterate all world entities and call `callback` for each one that matches
+     * the DSL, with component injection.
+     *
+     * Components declared via {@link World.filter}'s DSL (or `_guaranteed`) are
+     * non-nullable in the resolved tuple; any other requested component may be
+     * `undefined` if the entity lacks it.
+     *
+     * @param components - Component classes to resolve from each matching entity.
+     * @param callback - Receives the entity and a tuple of resolved component
+     *   instances.
+     */
+    forEach<J extends (typeof Component)[]>(components: readonly [...J], callback: (e: Entity, resolved: {
+        [K in keyof J]: MaybeRequired<J[K], R>;
+    }) => void): void;
+}

package/dist/filter.js

@@ -0,0 +1,53 @@
+import { buildEntityTest, } from "./dsl.js";
+/**
+ * A non-reactive, one-shot entity filter.
+ *
+ * Unlike {@link Query}, a `Filter` holds no tracked entity set and registers
+ * nothing with the world. Every {@link forEach} call walks all world entities
+ * and invokes the callback for those that match the predicate captured at
+ * construction time.
+ *
+ * Create via {@link World.filter}:
+ *
+ * ```ts
+ * const f = world.filter([Position, Velocity]);
+ *
+ * // Entity only:
+ * f.forEach((e) => console.log(e.eid));
+ *
+ * // With component injection:
+ * f.forEach([Position, Velocity], (e, [pos, vel]) => {
+ *   pos.x += vel.vx;
+ * });
+ * ```
+ *
+ * ### Type parameter `R`
+ * Tracks which component classes are guaranteed present on every matched
+ * entity — inferred automatically from the DSL by {@link World.filter}, or
+ * supplied manually via the optional `_guaranteed` argument. Components in `R`
+ * appear as non-nullable in `forEach` callback tuples.
+ */
+export class Filter {
+    constructor(world, dsl) {
+        this.world = world;
+        this.belongs = buildEntityTest(world, dsl);
+    }
+    forEach(componentsOrCallback, callback) {
+        if (typeof componentsOrCallback === "function") {
+            this.world._forEachEntity((e) => {
+                if (this.belongs(e))
+                    componentsOrCallback(e);
+            });
+        }
+        else {
+            const types = componentsOrCallback.map((C) => this.world.getComponentType(C));
+            this.world._forEachEntity((e) => {
+                if (!this.belongs(e))
+                    return;
+                const resolved = types.map((t) => e.get(t));
+                callback(e, resolved);
+            });
+        }
+    }
+}
+//# sourceMappingURL=filter.js.map

package/dist/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,eAAe,GAIhB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,MAAM;IAGjB,YACmB,KAAY,EAC7B,GAAa;QADI,UAAK,GAAL,KAAK,CAAO;QAG7B,IAAI,CAAC,OAAO,GAAG,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IA8BM,OAAO,CACZ,oBAEyB,EACzB,QAGS;QAET,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE;YAC9C,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;oBAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC;SACJ;aAAM;YACL,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3C,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAC/B,CAAC;YACF,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC9B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;oBAAE,OAAO;gBAC7B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC5C,QAAS,CAAC,CAAC,EAAE,QAAe,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;SACJ;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { type System } from "./system.js";
+export { Query } from "./query.js";
 export { World } from "./world.js";
+export { Filter } from "./filter.js";
 export { Component, type ComponentMeta } from "./component.js";
 export { type Entity } from "./entity.js";
 export { type IPhase } from "./phase.js";