@vworlds/vecs 1.0.10 → 1.0.12

package/dist/filter.d.ts

@@ -5,49 +5,57 @@ 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.
+ * Unlike {@link Query} a `Filter` keeps no tracked entity set and registers
+ * nothing on the world. Each call to {@link forEach} walks all current world
+ * entities and invokes the callback on those that match the predicate captured
+ * at construction time.
  *
- * Create via {@link World.filter}:
+ * Create one through {@link World.filter}:
  *
  * ```ts
  * const f = world.filter([Position, Velocity]);
  *
- * // Entity only:
+ * // Iterate matching entities:
  * f.forEach((e) => console.log(e.eid));
  *
- * // With component injection:
+ * // ...or 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.
+ * `forEach` runs the callback inside a {@link World.defer | deferred scope}, so
+ * mutations made by the callback are batched and become visible after iteration
+ * finishes. Nesting a `forEach` inside an already-deferred block (a system, a
+ * `Query.forEach`, an outer `defer`) inherits the outer scope and does not
+ * drain on exit.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity.
+ *   Inferred from the DSL by {@link World.filter} when possible, or supplied
+ *   manually via the `_guaranteed` argument. Components in `R` are 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);
+    /** World this filter reads entities from. */
+    readonly world: World;
+    private readonly _belongs;
+    constructor(
+    /** World this filter reads entities from. */
+    world: World, dsl: QueryDSL);
     /**
-     * Iterate all world entities and call `callback` for each one that matches
-     * the DSL this filter was created with.
+     * Walk all current world entities and call `callback` for each one that
+     * satisfies the filter's DSL.
      *
-     * @param callback - Receives only the entity.
+     * @param callback - Receives only the matching entity.
      */
     forEach(callback: (e: Entity) => void): void;
     /**
-     * Iterate all world entities and call `callback` for each one that matches
-     * the DSL, with component injection.
+     * Walk all current world entities, call `callback` for each one that
+     * satisfies the filter's DSL, and inject the requested component instances.
      *
-     * 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.
+     * Components covered by the filter's DSL or `_guaranteed` hint are
+     * non-nullable in the resolved tuple; any other component class may be
+     * `undefined` if the entity does not have it.
      *
      * @param components - Component classes to resolve from each matching entity.
      * @param callback - Receives the entity and a tuple of resolved component

package/dist/filter.js

@@ -1,42 +1,49 @@
-import { buildEntityTest } from "./dsl.js";
+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.
+ * Unlike {@link Query} a `Filter` keeps no tracked entity set and registers
+ * nothing on the world. Each call to {@link forEach} walks all current world
+ * entities and invokes the callback on those that match the predicate captured
+ * at construction time.
  *
- * Create via {@link World.filter}:
+ * Create one through {@link World.filter}:
  *
  * ```ts
  * const f = world.filter([Position, Velocity]);
  *
- * // Entity only:
+ * // Iterate matching entities:
  * f.forEach((e) => console.log(e.eid));
  *
- * // With component injection:
+ * // ...or 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.
+ * `forEach` runs the callback inside a {@link World.defer | deferred scope}, so
+ * mutations made by the callback are batched and become visible after iteration
+ * finishes. Nesting a `forEach` inside an already-deferred block (a system, a
+ * `Query.forEach`, an outer `defer`) inherits the outer scope and does not
+ * drain on exit.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity.
+ *   Inferred from the DSL by {@link World.filter} when possible, or supplied
+ *   manually via the `_guaranteed` argument. Components in `R` are non-nullable
+ *   in `forEach` callback tuples.
  */
 export class Filter {
-    constructor(world, dsl) {
+    constructor(
+    /** World this filter reads entities from. */
+    world, dsl) {
         this.world = world;
-        this.belongs = buildEntityTest(world, dsl);
+        this._belongs = _buildEntityTest(world, dsl);
     }
     forEach(componentsOrCallback, callback) {
         this.world.defer(() => {
             if (typeof componentsOrCallback === "function") {
                 this.world.entities.forEach((e) => {
-                    if (this.belongs(e)) {
+                    if (this._belongs(e)) {
                         componentsOrCallback(e);
                     }
                 });
@@ -44,7 +51,7 @@ export class Filter {
             else {
                 const types = componentsOrCallback.map((C) => this.world.getComponentType(C));
                 this.world.entities.forEach((e) => {
-                    if (!this.belongs(e)) {
+                    if (!this._belongs(e)) {
                         return;
                     }
                     const resolved = types.map((t) => e.get(t));

package/dist/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAA0D,MAAM,UAAU,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;;;;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;IA2BM,OAAO,CACZ,oBAA6D,EAC7D,QAAoF;QAEpF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE;gBAC9C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;wBACnB,oBAAoB,CAAC,CAAC,CAAC,CAAC;qBACzB;gBACH,CAAC,CAAC,CAAC;aACJ;iBAAM;gBACL,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC9E,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;wBACpB,OAAO;qBACR;oBACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC5C,QAAS,CAAC,CAAC,EAAE,QAAe,CAAC,CAAC;gBAChC,CAAC,CAAC,CAAC;aACJ;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAA0D,MAAM,UAAU,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,MAAM;IAGjB;IACE,6CAA6C;IAC7B,KAAY,EAC5B,GAAa;QADG,UAAK,GAAL,KAAK,CAAO;QAG5B,IAAI,CAAC,QAAQ,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;IA2BM,OAAO,CACZ,oBAA6D,EAC7D,QAAoF;QAEpF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE;gBAC9C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;wBACpB,oBAAoB,CAAC,CAAC,CAAC,CAAC;qBACzB;gBACH,CAAC,CAAC,CAAC;aACJ;iBAAM;gBACL,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC9E,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;wBACrB,OAAO;qBACR;oBACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC5C,QAAS,CAAC,CAAC,EAAE,QAAe,CAAC,CAAC;gBAChC,CAAC,CAAC,CAAC;aACJ;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export { type System } from "./system.js";
+export { type System, type SystemQuery } 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";
+export { IntervalTickSource, RateTickSource, type ITickSource } from "./timer.js";
 export { Bitset } from "./util/bitset.js";

package/dist/index.js

@@ -2,5 +2,6 @@ export { Query } from "./query.js";
 export { World } from "./world.js";
 export { Filter } from "./filter.js";
 export { Component } from "./component.js";
+export { IntervalTickSource, RateTickSource } from "./timer.js";
 export { Bitset } from "./util/bitset.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAsB,MAAM,gBAAgB,CAAC;AAG/D,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAsB,MAAM,gBAAgB,CAAC;AAG/D,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -12,6 +12,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/ tests/",
+    "typecheck": "tsc --noEmit",
+    "format:check": "prettier --check \"**/*.{ts,md}\"",
     "prepare": "husky"
   },
   "devDependencies": {

package/dist/phase.d.ts

@@ -1,32 +1,9 @@
-import { type System } from "./system.js";
 import { type World } from "./world.js";
 /**
- * A named, ordered bucket of {@link System | systems} within the world's
- * update pipeline.
+ * Public interface for a pipeline phase, returned by {@link World.addPhase}.
  *
- * Created internally by {@link World.addPhase}. The systems in a phase run in
- * the order they were registered. Between each system run the world flushes
- * pending archetype changes, so `enter` / `exit` callbacks are always
- * delivered before the next system executes.
- *
- * @internal The concrete class is not part of the public API. Use
- * {@link IPhase} to refer to phases in user code.
- */
-export declare class Phase {
-    /** Name used to look up the phase in the pipeline. */
-    readonly name: string;
-    world: World;
-    /** Systems that belong to this phase, in execution order. */
-    systems: System[];
-    constructor(
-    /** Name used to look up the phase in the pipeline. */
-    name: string, world: World);
-}
-/**
- * Public interface for a pipeline phase returned by {@link World.addPhase}.
- *
- * Pass an `IPhase` to {@link System.phase} to assign a system to that phase,
- * or to {@link World.runPhase} to execute it:
+ * Pass an `IPhase` to {@link System.phase} to assign a system to the phase, or
+ * to {@link World.runPhase} to execute the phase:
  *
  * ```ts
  * const preUpdate = world.addPhase("preupdate");
@@ -35,13 +12,18 @@ export declare class Phase {
  * world.system("NetworkUpdate").phase(preUpdate).run(tick);
  *
  * // each frame:
- * world.runPhase(preUpdate, now, delta);
- * world.runPhase(send,      now, delta);
+ * world.beginFrame(now, delta);
+ * try {
+ *   world.runPhase(preUpdate, now, delta);
+ *   world.runPhase(send,      now, delta);
+ * } finally {
+ *   world.endFrame();
+ * }
  * ```
  */
 export interface IPhase {
-    /** The name this phase was registered under. */
+    /** Name this phase was registered under. */
     get name(): string;
-    /** The world that owns this phase. */
+    /** World that owns this phase. */
     get world(): World;
 }

package/dist/phase.js

@@ -1,22 +1,23 @@
 /**
- * A named, ordered bucket of {@link System | systems} within the world's
- * update pipeline.
+ * Concrete implementation of {@link IPhase}: a named, ordered bucket of
+ * {@link System | systems} within a world's update pipeline.
  *
- * Created internally by {@link World.addPhase}. The systems in a phase run in
- * the order they were registered. Between each system run the world flushes
- * pending archetype changes, so `enter` / `exit` callbacks are always
- * delivered before the next system executes.
+ * Created by {@link World.addPhase}. Systems run in the order they were added
+ * to the phase. Between systems the world drains pending commands so each
+ * system observes a consistent view of the world.
  *
- * @internal The concrete class is not part of the public API. Use
- * {@link IPhase} to refer to phases in user code.
+ * @internal The class itself is not part of the public API; user code should
+ * refer to phases via {@link IPhase}.
  */
 export class Phase {
     constructor(
     /** Name used to look up the phase in the pipeline. */
-    name, world) {
+    name, 
+    /** World that owns this phase. */
+    world) {
         this.name = name;
         this.world = world;
-        /** Systems that belong to this phase, in execution order. */
+        /** Systems registered in this phase, in execution order. */
         this.systems = [];
     }
 }

package/dist/phase.js.map

@@ -1 +1 @@
-{"version":3,"file":"phase.js","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,KAAK;IAIhB;IACE,sDAAsD;IACtC,IAAY,EACrB,KAAY;QADH,SAAI,GAAJ,IAAI,CAAQ;QACrB,UAAK,GAAL,KAAK,CAAO;QANrB,6DAA6D;QACtD,YAAO,GAAa,EAAE,CAAC;IAM3B,CAAC;CACL"}
+{"version":3,"file":"phase.js","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,KAAK;IAIhB;IACE,sDAAsD;IACtC,IAAY;IAC5B,kCAAkC;IAClB,KAAY;QAFZ,SAAI,GAAJ,IAAI,CAAQ;QAEZ,UAAK,GAAL,KAAK,CAAO;QAP9B,4DAA4D;QACrD,YAAO,GAAa,EAAE,CAAC;IAO3B,CAAC;CACL"}