@vworlds/vecs 1.0.15 → 1.0.16

package/dist/world.d.ts

@@ -1,389 +0,0 @@
-import { type ComponentClass, ComponentClassOrType, ComponentMeta, Hook } from "./component.js";
-import { Entity } from "./entity.js";
-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 } from "./phase.js";
-/**
- * The central ECS container. One world per game session.
- *
- * A `World` owns every entity, every registered component class, every
- * registered query / system, and the update pipeline. The typical lifecycle:
- *
- * 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} per phase or {@link progress} for
- *    every phase, once per frame.
- *
- * ```ts
- * const world = new World();
- *
- * class Position { x = 0; y = 0; }
- * class Velocity { vx = 0; vy = 0; }
- *
- * world.registerComponent(Position);
- * world.registerComponent(Velocity);
- *
- * world.system("Move")
- *   .requires(Position, Velocity)
- *   .each([Position, Velocity], (e, [pos, vel]) => {
- *     pos.x += vel.vx;
- *     e.modified(Position);
- *   });
- *
- * world.start();
- *
- * // game loop:
- * world.progress(now, delta);
- * ```
- *
- * ## Deferred mode
- *
- * The world can be in **deferred mode**, in which case entity mutations
- * (`add` / `attach` / `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 {
-    /** Hidden property key used to store this world's meta on component classes. */
-    readonly worldKey: string;
-    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>;
-    /**
-     * `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".
-     */
-    get deferred(): boolean;
-    /**
-     * Enter deferred mode. Mutations made until the matching {@link endDefer}
-     * are queued instead of executing inline.
-     *
-     * Nested `beginDefer` / `endDefer` pairs are allowed; only the outermost
-     * `endDefer` triggers a queue drain.
-     */
-    beginDefer(): void;
-    /**
-     * Leave deferred mode. When the depth returns to zero the world drains the
-     * command queue (firing hooks and routing enter / exit / update events).
-     */
-    endDefer(): void;
-    /**
-     * Run `fn` inside a deferred scope. Equivalent to
-     * `beginDefer(); try { fn(); } finally { endDefer(); }`.
-     *
-     * @param fn - Callback executed in deferred mode.
-     */
-    defer(fn: () => void): void;
-    /**
-     * Drain any commands queued at the top level (depth 0).
-     *
-     * 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.
-     */
-    flush(): void;
-    /**
-     * Pre-register a `componentName → typeId` mapping without binding a class.
-     *
-     * 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.
-     *
-     * @param componentName - String name used in network payloads.
-     * @param type - Numeric type id assigned by the server.
-     */
-    registerComponentType(componentName: string, type: number): void;
-    /**
-     * Register a component class with the world.
-     *
-     * Must be called before any entity uses the component. Components are plain
-     * classes constructed with no arguments. Registration is disabled once
-     * {@link start} (or {@link disableComponentRegistration}) is called.
-     *
-     * **Overloads:**
-     * - `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 - Component class to register.
-     * @returns The world-specific metadata record for the component class.
-     * @throws When the class has already been registered in this world or
-     *   registration is disabled.
-     */
-    registerComponent(ComponentClass: ComponentClass): ComponentMeta;
-    registerComponent(ComponentClass: ComponentClass, type: number): ComponentMeta;
-    registerComponent(ComponentClass: ComponentClass, componentName?: string): ComponentMeta;
-    registerComponent(ComponentClass: ComponentClass, type: number, componentName: string): ComponentMeta;
-    /**
-     * Look up the {@link ComponentMeta} for a registered component.
-     *
-     * @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 typeOrClass - Component class or numeric type id.
-     * @returns The numeric type id.
-     */
-    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((entity, c) => c.initialize(scene, entity))
-     *   .onRemove((entity, c) => c.destroy(scene, entity));
-     * ```
-     *
-     * @param C - Component class.
-     * @returns The hook bound to that component type.
-     */
-    hook<T extends ComponentClass>(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: ComponentClass[]): 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, 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))
-     *   .each([Position, Sprite], (e, [pos, sprite]) => sprite.draw(pos.x, pos.y));
-     * ```
-     *
-     * @param name - Unique display name for the system.
-     * @returns The new system.
-     */
-    system(name: string): System;
-    /**
-     * 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 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")
-     *   .requires(Enemy, Health)
-     *   .enter((e) => console.log("enemy spawned", e.eid));
-     *
-     * world.start();
-     * // enemies.entities is kept up-to-date automatically
-     * ```
-     *
-     * @param name - Unique display name for the query.
-     * @returns The new 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 on the world. Each call to {@link Filter.forEach} walks
-     * all current world entities and invokes the callback on the matches.
-     *
-     * 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.
-     * world.filter([Position, Velocity])
-     *   .forEach([Position, Velocity], (e, [pos, vel]) => { ... });
-     *
-     * // Manual override for an opaque query.
-     * world.filter(myTestFunc, [Position])
-     *   .forEach([Position], (e, [pos]) => pos.x);
-     * ```
-     *
-     * @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 ComponentClass[]>(q: QueryDSL, _guaranteed: readonly [...T]): Filter<T>;
-    /**
-     * Add a named phase to the update pipeline.
-     *
-     * 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");
-     * const update    = world.addPhase("update");
-     * const send      = world.addPhase("send");
-     * ```
-     *
-     * @param name - Unique phase name. Systems can reference it by this string.
-     * @returns The new phase.
-     */
-    addPhase(name: string): IPhase;
-    /**
-     * Prevent any further calls to {@link registerComponent}.
-     *
-     * Called automatically by {@link start}. Call directly if you want to lock
-     * registration before the rest of the systems are wired up.
-     */
-    disableComponentRegistration(): void;
-    /**
-     * Freeze component registration and prepare the world for running.
-     *
-     * 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}.
-     */
-    start(): void;
-    /**
-     * Open a new frame and evaluate every registered tick source once.
-     *
-     * Call this before one or more {@link runPhase} calls when manually driving
-     * phases. {@link progress} wraps this automatically for the full pipeline.
-     *
-     * @param delta - Milliseconds elapsed since the previous frame.
-     * @throws When a frame is already open.
-     */
-    beginFrame(delta: number): void;
-    /**
-     * Close the current frame.
-     *
-     * @throws When no frame is currently open.
-     */
-    endFrame(): void;
-    /**
-     * Execute every system in `phase` within the current frame.
-     *
-     * 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.
-     *
-     * `runPhase` is safe to call re-entrantly from a system body: it reuses the
-     * frame opened by {@link beginFrame} and does not advance `_frameCounter` or
-     * re-evaluate tick sources.
-     *
-     * @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.
-     * @throws When called outside an open frame.
-     */
-    runPhase(phase: IPhase, now: number, delta: number): void;
-    /**
-     * Run every phase in the pipeline in registration order.
-     *
-     * Equivalent to `beginFrame(delta)`, calling {@link runPhase} for each
-     * phase, then {@link endFrame}. All registered tick sources are evaluated
-     * once up front for the whole frame, and the frame is closed in a `finally`
-     * block if a system throws.
-     *
-     * @param now - Absolute timestamp in milliseconds (e.g. `Date.now()`).
-     * @param delta - Milliseconds elapsed since the previous tick.
-     */
-    progress(now: number, delta: number): void;
-}