@vworlds/vecs 1.0.9 → 1.0.11

package/dist/world.d.ts

@@ -4,20 +4,21 @@ import { Query } from "./query.js";
 import { System } from "./system.js";
 import { Filter } from "./filter.js";
 import { type QueryDSL, type ExtractRequired } from "./dsl.js";
-import { IPhase, Phase } from "./phase.js";
+import { IPhase } from "./phase.js";
 /**
- * The central ECS container.
+ * The central ECS container. One world per game session.
  *
- * A `World` owns all entities, components, systems, queries, and the update
- * pipeline. Typical lifecycle:
+ * A `World` owns every entity, every registered component class, every
+ * registered query / system, and the update pipeline. The typical lifecycle:
  *
- * 1. **Register components** — call {@link registerComponent} (and optionally
- *    {@link registerComponentType}) for every component class.
- * 2. **Register systems and queries** — call {@link system} and {@link query}
- *    to create and configure them.
+ * 1. **Register components** — {@link registerComponent} (and optionally
+ *    {@link registerComponentType}) for every component class you plan to use.
+ * 2. **Build the pipeline** — {@link addPhase} for every named phase, then
+ *    {@link system} / {@link query} for each processor.
  * 3. **Start** — call {@link start} to freeze component registration and
  *    distribute systems into their phases.
- * 4. **Run loop** — call {@link runPhase} once per frame for each phase.
+ * 4. **Run loop** — call {@link runPhase} per phase or {@link progress} for
+ *    every phase, once per frame.
  *
  * ```ts
  * const world = new World();
@@ -27,126 +28,95 @@ import { IPhase, Phase } from "./phase.js";
  *
  * world.system("Move")
  *   .requires(Position, Velocity)
- *   .update(Position, (pos) => { pos.x += vel.x; });
+ *   .each([Position, Velocity], (e, [pos, vel]) => {
+ *     pos.x += vel.vx;
+ *   });
  *
  * world.start();
  *
  * // game loop:
- * world.runPhase(updatePhase, Date.now(), 16);
+ * world.progress(now, delta);
  * ```
+ *
+ * ## Deferred mode
+ *
+ * The world can be in **deferred mode**, in which case entity mutations
+ * (`add` / `set` / `remove` / `destroy` / `setParent` / `modified`) are
+ * queued instead of applied inline. Systems run inside an automatically
+ * deferred scope; user code can wrap arbitrary blocks with
+ * {@link beginDefer} / {@link endDefer} or {@link defer}. {@link flush}
+ * drains the queue at top level.
  */
 export declare class World {
-    private entities;
-    private componentNameTypeMap;
-    private archChangeQueue;
-    private destroyedEntities;
-    private allQueries;
-    private Class2Meta;
-    private Type2Meta;
-    private updatedComponents;
-    private localComponentCounter;
-    private componentRegistrationDisabled;
-    /** @internal */
-    _pipeline: Map<string, Phase>;
-    private eidCounter;
     constructor();
+    /** Read-only view of the live entities, keyed by entity id. */
+    get entities(): Omit<Map<number, Entity>, "set" | "delete" | "clear">;
+    /** Read-only view of every registered query (includes systems). */
+    get queries(): ReadonlyArray<Query>;
     /**
-     * Return the entity with id `eid`, creating it if it does not yet exist.
-     *
-     * Used by networking code to materialise server-assigned entities:
-     *
-     * ```ts
-     * const e = world.getOrCreateEntity(snapshot.eid, (e) => {
-     *   networkEntities.add(e);
-     * });
-     * e.add(snapshot.type, false);
-     * ```
-     *
-     * @param eid - The entity id to look up or create.
-     * @param onCreateCallback - Optional callback invoked only when a **new**
-     *   entity is created, before it is returned. Use this to initialise
-     *   bookkeeping (e.g. tracking it in a local set).
-     * @returns The existing or newly created entity.
-     */
-    getOrCreateEntity(eid: number, onCreateCallback?: (e: Entity) => void): Entity;
-    /**
-     * Create a new entity with an auto-assigned id and register it in the world.
-     *
-     * The id counter starts at 0 (or at the value set by
-     * {@link setEntityIdRange}) and increments by one for each call.
+     * `true` while the world is in deferred mode — entity mutations are queued
+     * rather than applied inline. Equivalent to "the queue depth is non-zero or
+     * the world is currently draining".
      */
-    entity(): Entity;
+    get deferred(): boolean;
     /**
-     * Look up an entity by id.
+     * Enter deferred mode. Mutations made until the matching {@link endDefer}
+     * are queued instead of executing inline.
      *
-     * @param id - Numeric entity id.
-     * @returns The entity, or `undefined` if no entity with that id exists.
+     * Nested `beginDefer` / `endDefer` pairs are allowed; only the outermost
+     * `endDefer` triggers a queue drain.
      */
-    entity(id: number): Entity | undefined;
+    beginDefer(): void;
     /**
-     * Set the starting value for the auto-incrementing entity id counter.
-     *
-     * Must be called **before** {@link start} (or
-     * {@link disableComponentRegistration}). Useful when the world runs alongside
-     * a server that owns a different id range — for example, locally-created
-     * client entities can start at a high offset to avoid collisions with
-     * server-assigned ids.
-     *
-     * @param min - The first id that will be assigned by {@link entity}.
-     * @throws If called after registration has been disabled.
+     * Leave deferred mode. When the depth returns to zero the world drains the
+     * command queue (firing hooks and routing enter / exit / update events).
      */
-    setEntityIdRange(min: number): void;
+    endDefer(): void;
     /**
-     * Retrieve the {@link ComponentMeta} record for a registered component.
+     * Run `fn` inside a deferred scope. Equivalent to
+     * `beginDefer(); try { fn(); } finally { endDefer(); }`.
      *
-     * @param typeOrClass - A component class constructor or a numeric type id.
-     * @returns The corresponding `ComponentMeta`.
-     * @throws If no component with that class or type id has been registered.
+     * @param fn - Callback executed in deferred mode.
      */
-    getComponentMeta(typeOrClass: ComponentClassOrType): ComponentMeta;
+    defer(fn: () => void): void;
     /**
-     * Resolve a component class or type id to its numeric type id.
+     * Drain any commands queued at the top level (depth 0).
      *
-     * @param typeOrClass - A component class constructor or a numeric type id.
-     * @returns The numeric type id.
+     * Call between phases or after batch-loading network snapshots to surface
+     * accumulated mutations (firing hooks and routing enter / exit / update)
+     * before the next read or system run.
      */
-    getComponentType(typeOrClass: ComponentClassOrType): number;
+    flush(): void;
     /**
-     * Mark an entity's archetype as changed, queuing it for re-evaluation
-     * against all system queries at the end of the current system run.
+     * Pre-register a `componentName → typeId` mapping without binding a class.
      *
-     * Also recursively marks all children as changed so that `{ PARENT: ... }`
-     * queries are re-evaluated.
+     * Useful when network messages refer to components by type id and the
+     * corresponding class may be registered later. Call this **before**
+     * {@link registerComponent} so the class picks up the server-assigned id
+     * rather than a locally generated one.
      *
-     * @internal Called automatically by {@link Entity.add} and
-     * {@link Entity.remove}.
+     * @param componentName - String name used in network payloads.
+     * @param type - Numeric type id assigned by the server.
      */
-    archetypeChanged(e: Entity): void;
-    /** @internal */
-    _notifyComponentAdded(e: Entity, c: Component): void;
-    /** @internal */
-    _notifyComponentRemoved(e: Entity, c: Component): void;
-    /** @internal */
-    _notifyEntityDestroyed(e: Entity): void;
-    private updateArchetypes;
-    /** @internal Queues a component for onSet / update delivery. */
-    _queueUpdatedComponent(c: Component): void;
+    registerComponentType(componentName: string, type: number): void;
     /**
      * Register a component class with the world.
      *
-     * Must be called before any entity can use the component. Registration is
-     * disabled once {@link start} is called.
+     * Must be called before any entity uses the component. Registration is
+     * disabled once {@link start} (or {@link disableComponentRegistration}) is
+     * called.
      *
      * **Overloads:**
-     * - `registerComponent(Class)` — type id auto-assigned from the name map, or
-     *   from a local counter (≥ 256) if the name is not yet mapped.
+     * - `registerComponent(Class)` — type id auto-assigned from the
+     *   {@link registerComponentType} map, falling back to a local counter
+     *   (≥ 256) if the name is not yet mapped.
      * - `registerComponent(Class, type)` — explicit numeric type id.
      * - `registerComponent(Class, componentName)` — auto-assigned id, custom
      *   display name (useful when the class name differs from the network name).
      * - `registerComponent(Class, type, componentName)` — explicit id + name.
      *
-     * @param ComponentClass - The component class to register.
-     * @throws If the class has already been registered, or if registration is
+     * @param ComponentClass - Component class to register.
+     * @throws When the class has already been registered or registration is
      *   disabled.
      */
     registerComponent(ComponentClass: typeof Component): void;
@@ -154,47 +124,138 @@ export declare class World {
     registerComponent(ComponentClass: typeof Component, componentName?: string): void;
     registerComponent(ComponentClass: typeof Component, type: number, componentName: string): void;
     /**
-     * Pre-register a component name → type id mapping without associating a
-     * class.
+     * Look up the {@link ComponentMeta} for a registered component.
      *
-     * Useful when network messages refer to components by type id and the
-     * corresponding class may be registered later. Call this before
-     * {@link registerComponent} to ensure the class picks up the server-assigned
-     * id rather than a locally generated one.
+     * @param typeOrClass - Component class or numeric type id.
+     * @returns The corresponding meta record.
+     * @throws When no component with that class or type id has been registered.
+     */
+    getComponentMeta(typeOrClass: ComponentClassOrType): ComponentMeta;
+    /**
+     * Resolve a component class or type id to its numeric type id.
      *
-     * @param componentName - The string name used in network payloads.
-     * @param type - The numeric type id assigned by the server.
+     * @param typeOrClass - Component class or numeric type id.
+     * @returns The numeric type id.
      */
-    registerComponentType(componentName: string, type: number): void;
-    /** @internal Called by the {@link Query} constructor to register itself. */
-    _addQuery(q: Query): void;
-    /** @internal Called by {@link Query.destroy} to unregister a query and remove it from all entities. */
-    _removeQuery(q: Query): void;
-    /** @internal Iterate over all entities currently in the world. */
-    _forEachEntity(callback: (e: Entity) => void): void;
+    getComponentType(typeOrClass: ComponentClassOrType): number;
+    /**
+     * Return the {@link Hook} for a component class.
+     *
+     * Hooks let you react to component lifecycle events (add / remove / set)
+     * without building a full {@link System}. The same hook is returned on every
+     * call — handlers stack on the underlying meta record.
+     *
+     * ```ts
+     * world.hook(Sprite)
+     *   .onAdd(c => c.initialize(scene))
+     *   .onRemove(c => c.destroy());
+     * ```
+     *
+     * @param C - Component class.
+     * @returns The hook bound to that component type.
+     */
+    hook<T extends typeof Component>(C: T): Hook<InstanceType<T>>;
+    /**
+     * Declare a group of mutually exclusive components.
+     *
+     * Adding any component in the group to an entity that already has another
+     * member of the group automatically removes the previous member. Members
+     * not in the group are unaffected.
+     *
+     * ```ts
+     * world.setExclusiveComponents(Walking, Running, Idle);
+     * entity.add(Walking);
+     * entity.add(Running);            // Walking is removed automatically
+     * ```
+     *
+     * Each call defines one independent group. A component may belong to at
+     * most one group at a time; calling {@link setExclusiveComponents} with the
+     * same class again overwrites its group. Safe to call before or after
+     * {@link start}.
+     *
+     * @param components - Two or more component classes that cannot coexist.
+     * @throws When any class has not been registered.
+     */
+    setExclusiveComponents(...components: (typeof Component)[]): void;
+    /**
+     * Set the starting value of the auto-incrementing entity id counter.
+     *
+     * Must be called **before** {@link start} (or
+     * {@link disableComponentRegistration}). Useful when the world runs
+     * alongside a server that owns a different id range — locally created
+     * client entities can start at a high offset to avoid collisions with
+     * server-assigned ids.
+     *
+     * @param min - First id assigned by {@link entity}.
+     * @throws When called after registration has been disabled.
+     */
+    setEntityIdRange(min: number): void;
+    /**
+     * Return the entity with id `eid`, creating it if it does not yet exist.
+     *
+     * Used by networking code to materialise server-assigned entities:
+     *
+     * ```ts
+     * const e = world.getOrCreateEntity(snapshot.eid, (e) => {
+     *   networkEntities.add(e);
+     * });
+     * e.add(snapshot.type);
+     * ```
+     *
+     * @param eid - Entity id to look up or create.
+     * @param onCreateCallback - Optional callback invoked only when a new
+     *   entity is created, before it is returned. Use it to initialise
+     *   bookkeeping (e.g. tracking it in a local set).
+     * @returns The existing or newly created entity.
+     */
+    getOrCreateEntity(eid: number, onCreateCallback?: (e: Entity) => void): Entity;
+    /**
+     * Create a new entity with an auto-assigned id.
+     *
+     * The id counter starts at `0` (or at the value set by
+     * {@link setEntityIdRange}) and increments by one for each call. In
+     * deferred mode the new entity is queued onto the command queue and is not
+     * visible in {@link entities} until the queue drains.
+     */
+    entity(): Entity;
+    /**
+     * Look up an existing entity by id.
+     *
+     * @param id - Numeric entity id.
+     * @returns The entity, or `undefined` when no entity with that id exists.
+     */
+    entity(id: number): Entity | undefined;
+    /**
+     * Destroy every entity currently tracked by the world.
+     *
+     * Triggers all `onRemove` hooks and `exit` callbacks. Useful when
+     * transitioning between game sessions or resetting to a clean state.
+     */
+    clearAllEntities(): void;
     /**
-     * Create a new {@link System}, register it, and return it for configuration.
+     * Create, register, and return a new {@link System}, ready for fluent
+     * configuration.
      *
      * ```ts
      * world.system("Render")
      *   .phase("update")
      *   .requires(Position, Sprite)
      *   .enter([Sprite], (e, [sprite]) => sprite.initialize(scene))
-     *   .update(Position, (pos) => { ... });
+     *   .each([Position, Sprite], (e, [pos, sprite]) => sprite.draw(pos.x, pos.y));
      * ```
      *
-     * @param name - A unique display name for the system.
-     * @returns The new `System` instance.
+     * @param name - Unique display name for the system.
+     * @returns The new system.
      */
-    system(name: string): System<[]>;
+    system(name: string): System;
     /**
-     * Create a standalone {@link Query}, register it, and return it for
+     * Create, register, and return a standalone {@link Query}, ready for fluent
      * configuration.
      *
      * Unlike a {@link System}, a standalone query has no phase and no per-tick
-     * callbacks — it is a reactive, always-updated entity set that can be read
-     * at any time after {@link start}. Standalone queries can also be created
-     * after {@link start}; existing matched entities are backfilled immediately.
+     * callbacks — it is a reactive entity set that can be read at any time. It
+     * can also be created **after** {@link start}; existing matched entities
+     * are backfilled immediately.
      *
      * ```ts
      * const enemies = world.query("Enemies")
@@ -205,81 +266,44 @@ export declare class World {
      * // enemies.entities is kept up-to-date automatically
      * ```
      *
-     * @param name - A unique display name for the query.
-     * @returns The new `Query` instance.
+     * @param name - Unique display name for the query.
+     * @returns The new query.
      */
-    query(name: string): Query<[]>;
+    query(name: string): Query;
     /**
      * Create a non-reactive {@link Filter} that matches entities satisfying `q`.
      *
      * Unlike {@link query}, the returned filter holds no tracked entity set and
-     * registers nothing with the world. Each call to {@link Filter.forEach} walks
-     * all current world entities and invokes the callback for matching ones.
+     * registers nothing on the world. Each call to {@link Filter.forEach} walks
+     * all current world entities and invokes the callback on the matches.
      *
-     * Component classes guaranteed present on every matched entity are inferred
-     * automatically from the DSL where possible (plain arrays, `HAS`, `HAS_ONLY`,
-     * and `AND` of those forms). For cases the type extractor cannot see through
-     * (`OR`, `NOT`, `PARENT`, custom `EntityTestFunc`), pass a `_guaranteed`
+     * The component classes guaranteed present on every matched entity are
+     * inferred from the DSL where possible (plain arrays, `HAS`, `HAS_ONLY`,
+     * and `AND` of those forms). For shapes the inferer cannot see through
+     * (`OR`, `NOT`, `PARENT`, custom `EntityTestFunc`) supply a `_guaranteed`
      * tuple as a type-level override:
      *
      * ```ts
-     * // Auto-deduced — pos and vel are non-nullable
+     * // Auto-deduced: pos and vel are non-nullable.
      * world.filter([Position, Velocity])
      *   .forEach([Position, Velocity], (e, [pos, vel]) => { ... });
      *
-     * // Manual override for an opaque query
+     * // Manual override for an opaque query.
      * world.filter(myTestFunc, [Position])
      *   .forEach([Position], (e, [pos]) => pos.x);
      * ```
      *
-     * @param q - A {@link QueryDSL} expression.
+     * @param q - Query expression.
      * @param _guaranteed - Optional type hint declaring which components are
      *   guaranteed present (not validated at runtime).
      */
     filter<Q extends QueryDSL>(q: Q): Filter<ExtractRequired<Q>>;
     filter<T extends (typeof Component)[]>(q: QueryDSL, _guaranteed: readonly [...T]): Filter<T>;
     /**
-     * Prevent any further calls to {@link registerComponent}.
-     *
-     * Called automatically by {@link start}. Can be called early if you want to
-     * lock component registration before systems are fully configured.
-     */
-    disableComponentRegistration(): void;
-    /**
-     * Freeze component registration and prepare the world for running.
-     *
-     * Distributes all systems registered so far into their pipeline phases
-     * (defaulting to `"update"`) and logs the phase → system order to the
-     * console. Systems and queries can still be created after this call —
-     * standalone queries will immediately backfill existing matched entities.
-     *
-     * Call this once before the first {@link runPhase} call.
-     */
-    start(): void;
-    private reindexSystems;
-    /**
-     * Return the {@link Hook} for a component class.
+     * Add a named phase to the update pipeline.
      *
-     * Hooks let you react to component lifecycle events (add / remove / set)
-     * without building a full {@link System}. The hook is backed by the
-     * component's {@link ComponentMeta} and the same object is returned on every
-     * call.
-     *
-     * ```ts
-     * world.hook(Sprite)
-     *   .onAdd(c  => c.initialize(scene))
-     *   .onRemove(c => c.destroy());
-     * ```
-     *
-     * @param C - The component class.
-     * @returns The `Hook` for that component type.
-     */
-    hook<T extends typeof Component>(C: T): Hook<InstanceType<T>>;
-    /**
-     * Add a named phase to the update pipeline and return it.
-     *
-     * Phases are executed in insertion order when you call {@link runPhase} for
-     * each one. Systems are assigned to a phase via {@link System.phase}.
+     * Phases are executed in insertion order when {@link runPhase} or
+     * {@link progress} is called. Systems join a phase via {@link System.phase}.
      *
      * ```ts
      * const preUpdate = world.addPhase("preupdate");
@@ -288,50 +312,47 @@ export declare class World {
      * ```
      *
      * @param name - Unique phase name. Systems can reference it by this string.
-     * @returns The new {@link IPhase}.
+     * @returns The new phase.
      */
     addPhase(name: string): IPhase;
     /**
-     * Execute all systems in the given phase for one tick.
-     *
-     * After each system runs, pending archetype changes (entity add/remove
-     * component events) are flushed so that `enter` / `exit` callbacks are
-     * delivered before the next system in the same phase executes.
+     * Prevent any further calls to {@link registerComponent}.
      *
-     * @param phase - The {@link IPhase} to run (returned by {@link addPhase}).
-     * @param now - Absolute timestamp in milliseconds (e.g. `Date.now()`).
-     * @param delta - Milliseconds elapsed since the previous tick.
+     * Called automatically by {@link start}. Call directly if you want to lock
+     * registration before the rest of the systems are wired up.
      */
-    runPhase(phase: IPhase, now: number, delta: number): void;
+    disableComponentRegistration(): void;
     /**
-     * Run every phase in the pipeline in insertion order (the order phases were
-     * registered via {@link addPhase}). Equivalent to calling
-     * {@link runPhase} for each phase manually.
+     * Freeze component registration and prepare the world for running.
      *
-     * @param now - Absolute timestamp in milliseconds (e.g. `Date.now()`).
-     * @param delta - Milliseconds elapsed since the previous tick.
+     * Distributes every system registered so far into its phase (defaulting to
+     * `"update"`) and logs the phase → system order to the console. Systems
+     * and queries can still be created after this call — standalone queries
+     * backfill existing matched entities immediately.
+     *
+     * Call once before the first {@link runPhase} / {@link progress}.
      */
-    progress(now: number, delta: number): void;
+    start(): void;
     /**
-     * Declare a group of mutually exclusive components.
-     *
-     * After this call, adding any component in the group to an entity that
-     * already has another component from the same group will remove the other component
+     * Execute every system in `phase` for one tick.
      *
-     * ```ts
-     * world.setExclusiveComponents(Walking, Running, Idle);
-     * // entity.add(Running) throws if entity already has Walking or Idle
-     * ```
+     * Pending top-level mutations are drained before the first system runs so
+     * each system observes a consistent world. Each system body executes in a
+     * deferred scope; mutations made by callbacks land in the world queue and
+     * are processed before the next system runs.
      *
-     * @param components - Two or more component classes that cannot coexist.
-     * @throws If any class has not been registered.
+     * @param phase - Phase reference returned from {@link addPhase}.
+     * @param now - Absolute timestamp in milliseconds (e.g. `Date.now()`).
+     * @param delta - Milliseconds elapsed since the previous tick.
      */
-    setExclusiveComponents(...components: (typeof Component)[]): void;
+    runPhase(phase: IPhase, now: number, delta: number): void;
     /**
-     * Destroy every entity currently tracked by the world.
+     * Run every phase in the pipeline in registration order.
      *
-     * Triggers all `onRemove` hooks and `exit` callbacks. Useful when
-     * transitioning between game sessions or resetting to a clean state.
+     * Equivalent to calling {@link runPhase} for each phase manually.
+     *
+     * @param now - Absolute timestamp in milliseconds (e.g. `Date.now()`).
+     * @param delta - Milliseconds elapsed since the previous tick.
      */
-    clearAllEntities(): void;
+    progress(now: number, delta: number): void;
 }