@vworlds/vecs 1.0.0

package/dist/system.d.ts

@@ -0,0 +1,361 @@
+import { ArrayMap } from "./util/array_map.js";
+import { Bitset } from "./util/bitset.js";
+import { Component, ComponentClassArray, ComponentClassOrType } from "./component.js";
+import type { Entity } from "./entity.js";
+import { Phase, type IPhase } from "./phase.js";
+import { type World } from "./world.js";
+type EntityCallback = (e: Entity) => void;
+type ComponentCallback = (c: Component) => void;
+type RunCallback = (now: number, delta: number) => void;
+/** A function that tests whether a given entity belongs to a system. */
+export type EntityTestFunc = (e: Entity) => boolean;
+type ComponentOrParent = typeof Component | {
+    parent: typeof Component;
+};
+type ComponentInstance<T> = T extends {
+    parent: typeof Component;
+} ? InstanceType<T["parent"]> : T extends typeof Component ? InstanceType<T> : never;
+/**
+ * A composable query expression used to declare which entities a
+ * {@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 SystemQuery = ComponentClassArray | ComponentClassOrType | EntityTestFunc | {
+    HAS: ComponentClassArray | ComponentClassOrType;
+} | {
+    HAS_ONLY: ComponentClassArray | ComponentClassOrType;
+} | {
+    AND: SystemQuery[];
+} | {
+    OR: SystemQuery[];
+} | {
+    NOT: SystemQuery;
+} | {
+    PARENT: SystemQuery;
+};
+/**
+ * A reactive processor that operates on a filtered subset of world entities.
+ *
+ * Systems are created and registered through {@link World.system}:
+ *
+ * ```ts
+ * world.system("Move")
+ *   .requires(Position, Velocity)       // track entities with both components
+ *   .phase("update")
+ *   .enter([Position], (e, [pos]) => { pos.x = 0; })
+ *   .update(Position, (pos) => { pos.x += pos.vx; })
+ *   .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}.
+ *
+ * ### 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.
+ *
+ * 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`.
+ */
+type MaybeRequired<C, R extends (typeof Component)[]> = C extends typeof Component ? C extends R[number] ? InstanceType<C> : InstanceType<C> | undefined : never;
+export declare class System<R extends (typeof Component)[] = []> {
+    /** Unique name for this system, used in logs and pipeline output. */
+    readonly name: string;
+    /** The world that owns this system. */
+    readonly world: World;
+    protected componentUpdateCallbacks: ArrayMap<ComponentCallback>;
+    protected eachCallback: EntityCallback | undefined;
+    protected _entities: Set<Entity> | undefined;
+    protected _enterCallback: EntityCallback[];
+    protected _exitCallback: EntityCallback[];
+    private _runCallback;
+    protected _belongs: EntityTestFunc;
+    private readonly updateQueue;
+    private hasQuery;
+    /** @internal */
+    _phase: string | Phase | undefined;
+    protected watchlistBitmask: Bitset;
+    constructor(
+    /** Unique name for this system, used in logs and pipeline output. */
+    name: string, 
+    /** The world that owns this system. */
+    world: World);
+    /** Returns the system name. */
+    toString(): string;
+    /**
+     * Read-only view of the entities currently tracked by this system.
+     *
+     * Empty unless {@link track} (or {@link each}, which implies it) was
+     * called during system configuration.
+     */
+    get entities(): ReadonlySet<Entity>;
+    /**
+     * 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.
+     *
+     * @param p - Phase name or `IPhase` reference.
+     * @returns `this` for chaining.
+     */
+    phase(p: string | IPhase): this;
+    /** @internal Delivers a component-modified notification to this system. */
+    notifyModified(c: Component): void;
+    /** Returns `true` if the entity satisfies this system's query. */
+    belongs(e: Entity): boolean;
+    /** @internal Fires `enter` callbacks for a newly matched entity. */
+    _enter(e: Entity): void;
+    /** @internal Fires `exit` callbacks when an entity leaves the system. */
+    _exit(e: Entity): void;
+    /** @internal Execute one tick: run `run`, fire `each`, then drain the update queue. */
+    _run(now: number, delta: number): void;
+    private getComponent;
+    private getInjected;
+    private mapInjectedClassToTypes;
+    /**
+     * Register a callback that fires when an entity **enters** this system
+     * (i.e. first satisfies the system's query) with injected components.
+     *
+     * @param inject - Ordered list of component classes (or `{ parent: C }`) to
+     *   resolve from the entering entity and pass to `callback`.
+     * @param callback - Receives the entity and the resolved component tuple.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * system.enter([Position, Sprite], (e, [pos, sprite]) => {
+     *   sprite.initialize(scene);
+     *   sprite.sprite.setPosition(pos.x, pos.y);
+     * });
+     * ```
+     */
+    enter<J extends ComponentOrParent[]>(inject: readonly [...J], callback: (e: Entity, injected: {
+        [K in keyof J]: ComponentInstance<J[K]>;
+    }) => void): this;
+    /**
+     * Register a callback that fires when an entity enters this system.
+     *
+     * @param callback - Receives only the entity (no injection).
+     * @returns `this` for chaining.
+     */
+    enter(callback: (e: Entity) => void): this;
+    /**
+     * Register a callback that fires when an entity **exits** this system
+     * (its components no longer satisfy the query, or it was destroyed) with
+     * injected components.
+     *
+     * Components that were just removed are still accessible via `get_deleted`
+     * semantics — the injected tuple includes them even though they are no
+     * longer in the entity's active component set.
+     *
+     * @param inject - Component classes to resolve and inject.
+     * @param callback - Receives the entity and the resolved component tuple.
+     * @returns `this` for chaining.
+     */
+    exit<J extends ComponentOrParent[]>(inject: readonly [...J], callback: (e: Entity, injected: {
+        [K in keyof J]: ComponentInstance<J[K]>;
+    }) => void): this;
+    /**
+     * Register a callback that fires when an entity exits this system.
+     *
+     * @param callback - Receives only the entity.
+     * @returns `this` for chaining.
+     */
+    exit(callback: (e: Entity) => void): this;
+    /**
+     * Register a per-tick callback that runs every time this system's phase
+     * executes, regardless of entity membership.
+     *
+     * Use this for logic that is not driven by component updates — 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.
+     */
+    run(callback: RunCallback): this;
+    /**
+     * Register a callback that fires when a component of type `ComponentClass`
+     * is modified on any entity in this system.
+     *
+     * The system will automatically begin tracking entities that have this
+     * component type (equivalent to adding it to a `requires` / `HAS` query)
+     * unless a custom {@link query} was already set.
+     *
+     * @param ComponentClass - The component class to watch.
+     * @param callback - Receives the modified component instance.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * world.system("RenderPosition")
+     *   .update(Position, (pos) => {
+     *     sprite.setPosition(pos.x, pos.y);
+     *   });
+     * ```
+     */
+    update<C extends typeof Component>(ComponentClass: C, callback: (c: InstanceType<C>) => void): this;
+    /**
+     * Register a callback that fires when `ComponentClass` is modified, with
+     * additional components injected from the same entity.
+     *
+     * @param ComponentClass - The component class to watch.
+     * @param inject - Additional component classes to resolve from the entity.
+     * @param callback - Receives the modified component and the injected tuple.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * world.system("SyncSprite")
+     *   .update(Position, [Sprite], (pos, [sprite]) => {
+     *     sprite.sprite.setPosition(pos.x, pos.y);
+     *   });
+     * ```
+     */
+    update<C extends typeof Component, J extends (typeof Component)[]>(ComponentClass: C, inject: readonly [...J], callback: (c: InstanceType<C>, injected: {
+        [K in keyof J]: MaybeRequired<J[K], R>;
+    }) => void): this;
+    /**
+     * Register a callback that fires **every tick** for every entity currently
+     * tracked by this system, 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.
+     *
+     * `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.
+     *
+     * @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.
+     *
+     * @example
+     * ```ts
+     * world.system("Move")
+     *   .requires(Position, Velocity)
+     *   .each([Position, Velocity], (e, [pos, vel]) => {
+     *     pos.x += vel.vx;
+     *     pos.y += vel.vy;
+     *   });
+     * ```
+     */
+    each<J extends (typeof Component)[]>(components: readonly [...J], callback: (e: Entity, resolved: {
+        [K in keyof J]: MaybeRequired<J[K], R>;
+    }) => void): this;
+    /**
+     * Enable entity tracking: matched entities are inserted into
+     * {@link entities} as they enter the system and removed as they exit.
+     *
+     * Idempotent. Intended to be called during system configuration before
+     * `world.start()`; entities already matched when `track` is called late
+     * will not be backfilled.
+     *
+     * {@link each} implies `track` — call this directly only when you want
+     * the tracked set without an `each` callback.
+     *
+     * @returns `this` for chaining.
+     */
+    track(): this;
+    /**
+     * Enable sorted entity tracking: matched entities are stored in insertion
+     * order determined by `compare`, which receives a tuple of resolved
+     * component instances for each pair of entities being ordered.
+     *
+     * Implies {@link track}.
+     *
+     * @param components - Component classes to resolve and pass to `compare`.
+     * @param compare - Returns a negative number, zero, or positive number when
+     *   `a` should sort before, equal to, or after `b`.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * world.system("Render")
+     *   .requires(Position, Sprite)
+     *   .sort([Position], ([posA], [posB]) => posA.z - posB.z);
+     * ```
+     */
+    sort<J extends (typeof Component)[]>(components: readonly [...J], compare: (a: {
+        [K in keyof J]: MaybeRequired<J[K], R>;
+    }, b: {
+        [K in keyof J]: MaybeRequired<J[K], R>;
+    }) => number): this;
+    private queryBuilder;
+    /**
+     * Set the entity membership predicate using the {@link SystemQuery} DSL.
+     *
+     * Replaces any implicit query derived from `update` watchlists and any
+     * previous `requires` call. After calling `query`, auto-expanding of
+     * `update` watchlists 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.
+     *
+     * @param q - A {@link SystemQuery} expression.
+     * @param _guaranteed - Component classes guaranteed present on every matched
+     *   entity (type hint only — not validated at runtime).
+     * @returns `this` 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
+     *   });
+     * ```
+     */
+    query<T extends (typeof Component)[] = []>(q: SystemQuery, _guaranteed?: readonly [...T]): System<T>;
+    /**
+     * Shorthand for `query([...components])` — the system tracks entities that
+     * have **all** of the listed component types.
+     *
+     * 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.
+     *
+     * @param components - One or more component classes.
+     * @returns `this` for chaining.
+     */
+    requires<T extends (typeof Component)[]>(...components: [...T]): System<T>;
+}
+export {};