@vworlds/vecs 1.0.10 → 1.0.12

package/dist/system.d.ts

@@ -2,14 +2,15 @@ import { Component } from "./component.js";
 import { Query } from "./query.js";
 import { type QueryDSL, type MaybeRequired } from "./dsl.js";
 import type { Entity } from "./entity.js";
-import { Phase, type IPhase } from "./phase.js";
+import { type IPhase } from "./phase.js";
 import { type World } from "./world.js";
+import { type ITickSource } from "./timer.js";
 export type { QueryDSL as SystemQuery, EntityTestFunc } from "./dsl.js";
 type RunCallback = (now: number, delta: number) => void;
 /**
- * A reactive processor that operates on a filtered subset of world entities.
+ * A reactive processor running over a filtered subset of world entities.
  *
- * Systems are created and registered through {@link World.system}:
+ * Systems are created and configured through {@link World.system}:
  *
  * ```ts
  * world.system("Move")
@@ -20,9 +21,9 @@ type RunCallback = (now: number, delta: number) => void;
  *   .exit((e) => { console.log("entity left", e.eid); });
  * ```
  *
- * All builder methods return `this` for chaining. Call {@link World.start}
- * once all systems are registered; after that, drive the loop with
- * {@link World.runPhase}.
+ * Every builder method returns `this` for chaining. After registering systems
+ * call {@link World.start} once, then drive the loop with
+ * {@link World.runPhase} or {@link World.progress}.
  *
  * Internally each system holds a single ordered **inbox** of routed events
  * (`enter`, `exit`, `update`). The world appends to it during command-queue
@@ -31,83 +32,135 @@ type RunCallback = (now: number, delta: number) => void;
  *
  * ### Component injection and type inference
  *
- * `enter`, `exit`, `update`, `each`, and `sort` all accept an array of
- * component classes that are resolved from the entity and passed as a typed
- * tuple to the callback. Use `{ parent: SomeComponent }` to resolve from the
- * entity's parent instead of the entity itself.
+ * `enter`, `exit`, `update`, `each`, and `sort` accept an array of component
+ * classes resolved from the entity and passed as a typed tuple to the
+ * callback. Use `{ parent: SomeComponent }` to resolve from the entity's
+ * parent instead of the entity itself.
  *
- * Components declared via {@link requires} (or the second argument of
- * {@link query}) are tracked as a type parameter `R` on the system. In
- * `sort`, `each`, and `update` inject callbacks, those components appear as
- * non-nullable; any component not in `R` remains `Type | undefined`.
+ * Components declared via {@link requires} (or the `_guaranteed` argument of
+ * {@link query}) are tracked as the type parameter `R`. Inside `sort`,
+ * `each`, and `update` injection callbacks they are non-nullable; any other
+ * component remains `Type | undefined`.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity.
  */
-export declare class System<R extends (typeof Component)[] = []> extends Query<R> {
-    protected eachCallback: ((e: Entity) => void) | undefined;
-    private _runCallback;
-    private readonly inbox;
-    /** @internal */
-    _phase: string | Phase | undefined;
+export declare class System<R extends (typeof Component)[] = []> extends Query<R> implements ITickSource {
     constructor(name: string, world: World);
+    /** True when this system's cadence source fired during the current frame. */
+    get didTick(): boolean;
+    /** Milliseconds accumulated into this system's most recent fire. */
+    get lastFireDelta(): number;
+    /**
+     * Run this system at a fixed interval, expressed in seconds.
+     *
+     * This is seconds, unlike `World.beginFrame`, `World.progress`, and
+     * `runPhase`, which receive millisecond deltas. Calling `interval` replaces
+     * the current cadence source with an {@link IntervalTickSource}. When this
+     * system has a cadence source, the `delta` passed to {@link run} is the
+     * accumulated milliseconds since the previous fire, not the per-frame delta.
+     *
+     * @param seconds - Positive interval duration in seconds.
+     * @returns This system, for chaining.
+     * @throws When `seconds` is less than or equal to zero.
+     *
+     * @example
+     * ```ts
+     * world.system("AI")
+     *   .interval(0.5)
+     *   .run((now, delta) => tickAI(delta));
+     * ```
+     */
+    interval(seconds: number): this;
+    /**
+     * Run this system every `n` ticks from the world or an upstream source.
+     *
+     * Without a `source`, this composes with the current cadence source. For an
+     * unconfigured system, that means every `n` frames. With a `source`, it
+     * replaces the current cadence with a {@link RateTickSource} over that source.
+     * The `delta` passed to {@link run} is the accumulated milliseconds since
+     * this system last fired.
+     *
+     * @param n - Positive integer tick divisor.
+     * @param source - Optional upstream source to divide.
+     * @returns This system, for chaining.
+     * @throws When `n` is not a positive integer.
+     *
+     * @example
+     * ```ts
+     * world.system("SendSnapshots")
+     *   .rate(2)
+     *   .run(flushNetwork);
+     * ```
+     */
+    rate(n: number): this;
+    rate(n: number, source: ITickSource): this;
+    /**
+     * Run this system only when another timer or system ticks.
+     *
+     * Calling `tickSource` mirrors `source` directly; no wrapper source is
+     * created. Use `.tickSource(source).rate(n)` or `.rate(n, source)` when this
+     * system should divide an upstream source. The `delta` passed to {@link run}
+     * is the accumulated milliseconds since this system last fired.
+     *
+     * @param source - Tick source or system source to mirror.
+     * @returns This system, for chaining.
+     *
+     * @example
+     * ```ts
+     * const second = new IntervalTickSource(1);
+     * world.system("Logger").tickSource(second).run(logStats);
+     * ```
+     */
+    tickSource(source: ITickSource): this;
+    private _setTickSource;
     /**
      * Assign this system to a pipeline phase.
      *
-     * The phase can be specified by name (the world will resolve it at
-     * {@link World.start | start} time) or by an {@link IPhase} reference
-     * returned from {@link World.addPhase}. Systems without an explicit phase
-     * are placed in the built-in `"update"` phase.
+     * Pass either a phase name (resolved at {@link World.start}) or an
+     * {@link IPhase} reference returned from {@link World.addPhase}. Systems
+     * with no explicit phase fall into the built-in `"update"` phase.
      *
      * @param p - Phase name or `IPhase` reference.
-     * @returns `this` for chaining.
+     * @returns This system, for chaining.
+     * @throws When the phase reference is not a `Phase`, or belongs to a
+     *   different world.
      */
     phase(p: string | IPhase): this;
-    /** @internal Routing entry: register membership and enqueue an enter event. */
-    _enter(e: Entity): void;
-    /** @internal Routing entry: deregister membership and enqueue an exit event. */
-    _exit(e: Entity): void;
-    /** @internal Routing entry: enqueue an update event if the watchlist matches. */
-    notifyModified(c: Component): void;
     /**
-     * @internal Execute one tick: drain the inbox in arrival order, then run
-     * `runCallback` and `eachCallback`. The whole body runs in a deferred
-     * scope; any mutations made by callbacks land in the world queue and are
-     * processed by the world after `_run` returns.
-     */
-    _run(now: number, delta: number): void;
-    /**
-     * Register a per-tick callback that runs every time this system's phase
-     * executes, regardless of entity membership.
+     * Register a per-tick callback fired every time this system's phase runs,
+     * regardless of entity membership.
      *
-     * Use this for logic that is not driven by component updates — polling,
+     * Use it for logic that is not driven by component changes — polling,
      * network flushing, global timers, etc.
      *
      * @param callback - Receives `now` (absolute timestamp in ms) and `delta`
-     *   (ms since the last tick).
-     * @returns `this` for chaining.
+     *   (ms since the previous tick). If the system has an active interval,
+     *   rate, or tick source, `delta` is the accumulated milliseconds since this
+     *   system last fired.
+     * @returns This system, for chaining.
      */
     run(callback: RunCallback): this;
     /**
-     * Register a callback that fires **every tick** for every entity currently
-     * tracked by this system, with the listed components resolved from each
-     * entity.
+     * Register a callback fired **every tick** for **every tracked entity**,
+     * unconditionally, with the listed components resolved from each entity.
      *
      * Unlike {@link update} (which only fires when `component.modified()` is
-     * called), `each` fires unconditionally on every tick the system runs,
-     * once per tracked entity. Components declared via {@link requires} are
-     * guaranteed non-null in the resolved tuple; any other component class
-     * may be `undefined` if the entity lacks it.
+     * called), `each` fires every tick the system runs, once per tracked entity.
+     * Components declared via {@link requires} are non-nullable in the resolved
+     * tuple; any other component class may be `undefined` if the entity lacks it.
      *
      * `each` does **not** modify the system's query — define membership with
      * {@link requires} or {@link query} as usual. It does, however, implicitly
      * enable {@link track}, so matched entities are exposed via {@link entities}.
      *
-     * Only a single `each` callback may be registered per system; calling
-     * `each` a second time throws.
+     * Only one `each` callback may be registered per system; calling `each` a
+     * second time throws.
      *
      * @param components - Component classes to resolve from each entity.
      * @param callback - Receives the entity and a tuple of resolved component
-     *   instances (`undefined` for components not covered by {@link requires}).
-     * @returns `this` for chaining.
-     * @throws If `each` has already been registered on this system.
+     *   instances (`undefined` for any not covered by {@link requires}).
+     * @returns This system, for chaining.
+     * @throws When `each` has already been registered on this system.
      *
      * @example
      * ```ts
@@ -123,50 +176,81 @@ export declare class System<R extends (typeof Component)[] = []> extends Query<R
         [K in keyof J]: MaybeRequired<J[K], R>;
     }) => void): this;
     /**
-     * Not supported on `System`. Throws unconditionally.
-     *
-     * Systems are owned by the world for the duration of the session. If you
-     * need a temporary reactive set, use a standalone {@link Query} instead.
-     */
-    destroy(): never;
-    /**
-     * Set the entity membership predicate using the {@link QueryDSL} DSL.
+     * Set the entity-membership predicate using a {@link QueryDSL} expression.
      *
      * Replaces any implicit query derived from `update` watchlists and any
-     * previous `requires` call. After calling `query`, auto-expanding of
-     * `update` watchlists is disabled.
+     * previous `requires` call. After calling `query`, watchlist auto-expansion
+     * via `update` is disabled.
      *
-     * The optional `guaranteed` tuple is a pure type-level hint: it tells
-     * `sort`, `each`, and `update` callbacks which components are guaranteed
-     * to be present on every matched entity, eliminating `| undefined` from
-     * those positions. It has no effect at runtime.
+     * The optional `_guaranteed` tuple is a pure type-level hint — see
+     * {@link Query.query} for details.
      *
-     * @param q - A {@link QueryDSL} expression.
+     * @param q - Query expression.
      * @param _guaranteed - Component classes guaranteed present on every matched
      *   entity (type hint only — not validated at runtime).
-     * @returns `this` for chaining.
+     * @returns This system, retyped with the guaranteed tuple as its `R`.
+     */
+    query<T extends (typeof Component)[] = []>(q: QueryDSL, _guaranteed?: readonly [...T]): System<T>;
+    /**
+     * Shorthand for `query([...components])` — tracks entities that have **all**
+     * of the listed component types.
+     *
+     * Equivalent to `query({ HAS: components })`. The listed components are also
+     * recorded in the type parameter `R`, so {@link sort}, {@link each}, and
+     * {@link update} callbacks treat them as non-nullable.
+     *
+     * @param components - Component classes to require.
+     * @returns This system, retyped with the required tuple as its `R`.
+     */
+    requires<T extends (typeof Component)[]>(...components: [...T]): System<T>;
+    /**
+     * Disable this system.
+     *
+     * While disabled the system is effectively invisible: the inbox is cleared
+     * immediately, any new `enter`, `exit`, or `update` events are silently
+     * dropped, and {@link _run} returns without executing any callbacks. Entity
+     * membership in the underlying query is still maintained so the tracked set
+     * remains consistent and the system resumes correctly when
+     * {@link enable} is called.
+     *
+     * Disabling is independent from tick-source cadence: `disable` suppresses
+     * callbacks, but a disabled system used as a tick source still drives
+     * downstream consumers. Use `stop()` on an external `IntervalTickSource` or
+     * `RateTickSource` reference to halt that clock itself.
+     *
+     * Calling `disable` on an already-disabled system is a no-op.
+     *
+     * @returns This system, for chaining.
      *
      * @example
      * ```ts
-     * world.system("Move")
-     *   .query({ AND: [{ HAS: Position }, { HAS: Velocity }] }, [Position, Velocity])
-     *   .each([Position, Velocity], (e, [pos, vel]) => {
-     *     pos.x += vel.vx;  // no ! needed
-     *   });
+     * const sys = world.system("AI").requires(Enemy).run(runAI);
+     * // Pause AI processing during a cutscene:
+     * sys.disable();
+     * // Resume:
+     * sys.enable();
      * ```
      */
-    query<T extends (typeof Component)[] = []>(q: QueryDSL, _guaranteed?: readonly [...T]): System<T>;
+    disable(): this;
     /**
-     * Shorthand for `query([...components])` — the system tracks entities that
-     * have **all** of the listed component types.
+     * Enable this system after a previous {@link disable} call.
+     *
+     * Once re-enabled the system resumes its normal tick behaviour: enter, exit,
+     * and update events are queued, and {@link _run} processes the inbox and fires
+     * all registered callbacks. Events that occurred while the system was disabled
+     * are not replayed.
      *
-     * Equivalent to `query({ HAS: components })`. Unlike `query`, passing
-     * component classes here also informs the types of {@link sort} and
-     * {@link each} callbacks: listed components will be non-nullable in those
-     * tuples.
+     * Calling `enable` on an already-enabled system is a no-op.
      *
-     * @param components - One or more component classes.
-     * @returns `this` for chaining.
+     * @returns This system, for chaining.
      */
-    requires<T extends (typeof Component)[]>(...components: [...T]): System<T>;
+    enable(): this;
+    /**
+     * Not supported on `System`. Throws unconditionally.
+     *
+     * Systems are owned by the world for the duration of the session; if you
+     * need a temporary reactive set use a standalone {@link Query} via
+     * {@link World.query}.
+     */
+    destroy(): never;
 }