@vworlds/vecs 1.0.10 → 1.0.12

package/dist/world.js

@@ -5,20 +5,27 @@ import { System } from "./system.js";
 import { Filter } from "./filter.js";
 import { ArrayMap } from "./util/array_map.js";
 import { Phase } from "./phase.js";
+import { ALWAYS_TICK_SOURCE } from "./timer.js";
+/**
+ * Numeric type ids below this value are reserved for components whose id was
+ * pre-registered via {@link World.registerComponentType} (typically server
+ * assigned). Auto-assigned ids start here.
+ */
 const LOCAL_COMPONENT_MIN = 256;
 /**
- * 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();
@@ -28,161 +35,201 @@ const LOCAL_COMPONENT_MIN = 256;
  *
  * 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 class World {
-    /** `true` when the world is in deferred mode — mutations are queued rather than applied immediately. */
-    get deferred() {
-        return this.deferredDepth > 0 || this.draining;
-    }
     constructor() {
-        this._entities = new Map(); // maps entity Id to Entity
-        this.componentNameTypeMap = new Map();
+        /** @internal Entity id → entity. Owns every live entity. */
+        this._entities = new Map();
+        /** @internal All registered queries, including systems (which extend `Query`). */
         this._queries = [];
-        this.Class2Meta = new Map();
-        this.Type2Meta = new ArrayMap();
-        this.localComponentCounter = LOCAL_COMPONENT_MIN;
-        this.componentRegistrationDisabled = false;
+        /** @internal Component class → meta record. */
+        this._Class2Meta = new Map();
+        /** @internal Component type id → meta record. */
+        this._Type2Meta = new ArrayMap();
+        /** @internal Pre-registered name → type id mappings (server-assigned ids). */
+        this._componentNameTypeMap = new Map();
+        /** @internal Counter used to auto-assign type ids for "local" components (≥ 256). */
+        this._localComponentCounter = LOCAL_COMPONENT_MIN;
+        /** @internal `true` once {@link start} (or {@link disableComponentRegistration}) has been called. */
+        this._componentRegistrationDisabled = false;
+        /** @internal Auto-incrementing entity id counter, seeded by {@link setEntityIdRange}. */
+        this._eidCounter = 0;
         /** @internal Single ordered command queue used in deferred mode. */
-        this.commandQueue = [];
-        /** @internal Nested `beginDefer` / `endDefer` count. */
-        this.deferredDepth = 0;
-        /** @internal True while `processCommandQueue` is iterating, to avoid re-entrant drains. */
-        this.draining = false;
-        /** @internal */
+        this._commandQueue = [];
+        /** @internal Nested {@link beginDefer} / {@link endDefer} count. */
+        this._deferredDepth = 0;
+        /** @internal `true` while {@link _processCommandQueue} is iterating, to avoid re-entrant drains. */
+        this._draining = false;
+        /** @internal Phase name → phase. Insertion-ordered, matches pipeline execution order. */
         this._pipeline = new Map();
-        this.eidCounter = 0;
-    }
-    /** @readonly */
-    get entities() {
-        return this._entities;
-    }
-    /** @readonly */
-    get queries() {
-        return this._queries;
+        /** @internal World-owned tick sources evaluated once per frame. */
+        this._tickSources = new Set();
+        /** @internal Monotonic frame id used to memoize tick-source evaluation. */
+        this._frameCounter = 0;
+        /** @internal True while the world is driving one logical frame. */
+        this._frameInProgress = false;
+        this._tickSources.add(ALWAYS_TICK_SOURCE);
     }
     /**
-     * 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.
+     * @internal Drain the top-level command queue: walk it in arrival order,
+     * executing each command. Callbacks may push more commands; they are picked
+     * up by index iteration in the same pass.
      */
-    getOrCreateEntity(eid, onCreateCallback) {
-        let e = this._entities.get(eid);
-        if (!e) {
-            e = new Entity(this, eid);
-            this._entities.set(eid, e);
-            if (onCreateCallback) {
-                onCreateCallback(e);
-            }
+    _processCommandQueue() {
+        if (this._draining) {
+            return;
         }
-        return e;
-    }
-    entity(id) {
-        if (id === undefined) {
-            const eid = this.eidCounter++;
-            const e = new Entity(this, eid);
-            if (this.deferred) {
-                this._enqueue({ kind: 0 /* CommandKind.CreateEntity */, entity: e });
-            }
-            else {
-                this._entities.set(eid, e);
+        if (this._commandQueue.length === 0) {
+            return;
+        }
+        this._draining = true;
+        try {
+            for (let i = 0; i < this._commandQueue.length; i++) {
+                this._executeCommand(this._commandQueue[i]);
             }
-            return e;
+            this._commandQueue.length = 0;
+        }
+        finally {
+            this._draining = false;
         }
-        return this._entities.get(id);
     }
     /**
-     * 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.
+     * @internal Run one command's side effects: data-layer mutation, hook
+     * firing, and routing to every registered query / system.
      */
-    setEntityIdRange(min) {
-        if (this.componentRegistrationDisabled) {
-            throw "setEntityIdRange must be called before component registration is disabled";
+    _executeCommand(cmd) {
+        switch (cmd.kind) {
+            case 0 /* CommandKind.CreateEntity */:
+                this._entities.set(cmd.entity.eid, cmd.entity);
+                return;
+            case 1 /* CommandKind.Set */:
+                cmd.entity._set(cmd.type, cmd.props);
+                return;
+            case 2 /* CommandKind.Modified */:
+                cmd.entity._modified(cmd.type);
+                return;
+            case 3 /* CommandKind.Remove */:
+                cmd.entity._remove(cmd.type);
+                return;
+            case 4 /* CommandKind.Destroy */:
+                cmd.entity._destroy();
+                return;
+            case 5 /* CommandKind.SetParent */:
+                cmd.entity._setParent(cmd.parent);
+                return;
         }
-        this.eidCounter = min;
     }
     /**
-     * Retrieve the {@link ComponentMeta} record for a registered component.
-     *
-     * @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.
+     * @internal Distribute every registered system into its phase's `systems`
+     * list. Called by {@link start}; idempotent so it can be re-run if the
+     * pipeline is rebuilt.
      */
-    getComponentMeta(typeOrClass) {
-        let meta;
-        if (typeof typeOrClass === "function") {
-            meta = this.Class2Meta.get(typeOrClass);
-        }
-        else {
-            meta = this.Type2Meta.get(typeOrClass);
-        }
-        if (!meta) {
-            throw `unregistered component meta for component type or class '${typeOrClass}'`;
+    _reindexSystems() {
+        let _defaultPhase = this._pipeline.get("update");
+        if (!_defaultPhase) {
+            _defaultPhase = new Phase("update", this);
+            this._pipeline.set(_defaultPhase.name, _defaultPhase);
         }
-        return meta;
+        const defaultPhase = _defaultPhase;
+        this._queries.forEach((q) => {
+            if (!(q instanceof System)) {
+                return;
+            }
+            let phase = q._phase;
+            if (typeof phase === "string") {
+                phase = this._pipeline.get(phase);
+            }
+            phase = phase || defaultPhase;
+            phase.systems.push(q);
+        });
+        this._pipeline.forEach((phase) => {
+            console.log("Phase %s : %s", phase.name, phase.systems.map((s) => s.name).join(" -> "));
+        });
+    }
+    /** @internal Append a command to the deferred-mode queue. */
+    _enqueue(cmd) {
+        this._commandQueue.push(cmd);
+    }
+    /** @internal Register a freshly created {@link Query} (called from its constructor). */
+    _addQuery(q) {
+        this._queries.push(q);
+    }
+    /** @internal Register a tick source with this world. */
+    _registerTickSource(t) {
+        this._tickSources.add(t);
     }
     /**
-     * Resolve a component class or type id to its numeric type id.
-     *
-     * @param typeOrClass - A component class constructor or a numeric type id.
-     * @returns The numeric type id.
+     * @internal Unregister a query and purge its membership from every entity.
+     * Called by {@link Query.destroy}.
      */
-    getComponentType(typeOrClass) {
-        if (typeof typeOrClass === "function") {
-            return this.getComponentMeta(typeOrClass).type;
+    _removeQuery(q) {
+        const idx = this._queries.indexOf(q);
+        if (idx !== -1) {
+            this._queries.splice(idx, 1);
         }
-        return typeOrClass;
+        this._entities.forEach((e) => e._purgeQuery(q));
+    }
+    /** @internal Remove an entity from the world's entity map (called by `Entity._destroy`). */
+    _unregisterEntity(entity) {
+        this._entities.delete(entity.eid);
+    }
+    /** Read-only view of the live entities, keyed by entity id. */
+    get entities() {
+        return this._entities;
+    }
+    /** Read-only view of every registered query (includes systems). */
+    get queries() {
+        return this._queries;
+    }
+    /**
+     * `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() {
+        return this._deferredDepth > 0 || this._draining;
     }
     /**
      * Enter deferred mode. Mutations made until the matching {@link endDefer}
      * are queued instead of executing inline.
      *
-     * Nested begin/end pairs are allowed; only the outermost `endDefer`
-     * triggers a drain.
-     *
+     * Nested `beginDefer` / `endDefer` pairs are allowed; only the outermost
+     * `endDefer` triggers a queue drain.
      */
     beginDefer() {
-        this.deferredDepth++;
+        this._deferredDepth++;
     }
     /**
-     * Leave deferred mode. When the depth returns to zero, the world processes
-     * the command queue (firing hooks and routing enter / exit / update events).
-     *
+     * Leave deferred mode. When the depth returns to zero the world drains the
+     * command queue (firing hooks and routing enter / exit / update events).
      */
     endDefer() {
-        this.deferredDepth--;
+        this._deferredDepth--;
         this.flush();
     }
     /**
+     * Run `fn` inside a deferred scope. Equivalent to
+     * `beginDefer(); try { fn(); } finally { endDefer(); }`.
      *
-     * @param fn callback to invoke in deferred mode.
+     * @param fn - Callback executed in deferred mode.
      */
     defer(fn) {
         this.beginDefer();
@@ -194,80 +241,36 @@ export class World {
         }
     }
     /**
-     * Drain any pending commands queued at the top level (depth 0).
+     * Drain any commands queued at the top level (depth 0).
      *
-     * Useful between phases or after batch-loading network snapshots, to make
-     * accumulated mutations visible (fire hooks, route enter/exit/update) before
-     * the next read or system run.
+     * 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() {
-        if (this.deferredDepth === 0) {
-            this.processCommandQueue();
+        if (this._deferredDepth === 0) {
+            this._processCommandQueue();
         }
     }
-    /** @internal Append a command to the queue. */
-    _enqueue(cmd) {
-        this.commandQueue.push(cmd);
-    }
     /**
-     * @internal Walk the command queue in insertion order, executing each
-     * command. Callbacks may push more commands, which are processed in the
-     * same pass via index iteration.
-     */
-    processCommandQueue() {
-        if (this.draining) {
-            return;
-        }
-        if (this.commandQueue.length === 0) {
-            return;
-        }
-        this.draining = true;
-        try {
-            for (let i = 0; i < this.commandQueue.length; i++) {
-                this.executeCommand(this.commandQueue[i]);
-            }
-            this.commandQueue.length = 0;
-        }
-        finally {
-            this.draining = false;
-        }
-    }
-    /**
-     * @internal Run a single command's side effects: data-layer mutation, hook
-     * firing, and routing to all registered queries / systems.
+     * 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.
      */
-    executeCommand(cmd) {
-        switch (cmd.kind) {
-            case 0 /* CommandKind.CreateEntity */:
-                this._entities.set(cmd.entity.eid, cmd.entity);
-                return;
-            case 1 /* CommandKind.Set */:
-                cmd.entity._set(cmd.type, cmd.props);
-                return;
-            case 2 /* CommandKind.Modified */:
-                cmd.entity._modified(cmd.type);
-                return;
-            case 3 /* CommandKind.Remove */:
-                cmd.entity._remove(cmd.type);
-                return;
-            case 4 /* CommandKind.Destroy */:
-                cmd.entity._destroy();
-                return;
-            case 5 /* CommandKind.SetParent */:
-                cmd.entity._setParent(cmd.parent);
-                return;
-        }
-    }
-    /** @internal Remove an entity from the world's entity map. Called by Entity._destroy. */
-    _unregisterEntity(entity) {
-        this._entities.delete(entity.eid);
+    registerComponentType(componentName, type) {
+        this._componentNameTypeMap.set(componentName, type);
     }
     registerComponent(ComponentClass, typeOrComponentName, componentName) {
-        if (this.componentRegistrationDisabled) {
+        if (this._componentRegistrationDisabled) {
             throw "World component registartion is disabled";
         }
         let type = undefined;
-        // Determine if the second argument is type or componentName based on its type
         if (typeof typeOrComponentName === "number") {
             type = typeOrComponentName;
         }
@@ -277,78 +280,202 @@ export class World {
         componentName = componentName || ComponentClass.name;
         let local = false;
         if (type === undefined) {
-            // attempt to get type id from name->type map
-            type = this.componentNameTypeMap.get(componentName);
+            type = this._componentNameTypeMap.get(componentName);
             if (type === undefined) {
-                type = this.localComponentCounter++;
+                type = this._localComponentCounter++;
                 local = true;
             }
         }
-        let meta = this.Class2Meta.get(ComponentClass);
+        let meta = this._Class2Meta.get(ComponentClass);
         if (meta) {
             if (local) {
-                this.localComponentCounter--;
+                this._localComponentCounter--;
             }
             throw `Trying to register ${componentName} with type=${type} which is already registered to ${meta.componentName}`;
         }
         this.registerComponentType(componentName, type);
         meta = new ComponentMeta(ComponentClass, type, componentName);
-        this.Class2Meta.set(ComponentClass, meta);
-        this.Type2Meta.set(type, meta);
+        this._Class2Meta.set(ComponentClass, meta);
+        this._Type2Meta.set(type, meta);
         console.log("Registered component %s with type=%d as %s component", componentName, type, local ? "local" : "networked");
     }
     /**
-     * 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) {
+        let meta;
+        if (typeof typeOrClass === "function") {
+            meta = this._Class2Meta.get(typeOrClass);
+        }
+        else {
+            meta = this._Type2Meta.get(typeOrClass);
+        }
+        if (!meta) {
+            throw `unregistered component meta for component type or class '${typeOrClass}'`;
+        }
+        return meta;
+    }
+    /**
+     * 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, type) {
-        this.componentNameTypeMap.set(componentName, type);
+    getComponentType(typeOrClass) {
+        if (typeof typeOrClass === "function") {
+            return this.getComponentMeta(typeOrClass).type;
+        }
+        return typeOrClass;
     }
-    /** @internal Called by the {@link Query} constructor to register itself. */
-    _addQuery(q) {
-        this._queries.push(q);
+    /**
+     * 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(C) {
+        return this.getComponentMeta(C);
     }
-    /** @internal Called by {@link Query.destroy} to unregister a query and remove it from all entities. */
-    _removeQuery(q) {
-        const idx = this._queries.indexOf(q);
-        if (idx !== -1) {
-            this._queries.splice(idx, 1);
+    /**
+     * 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) {
+        const types = components.map((C) => this.getComponentType(C));
+        for (let i = 0; i < components.length; i++) {
+            this.getComponentMeta(components[i]).exclusive = types.filter((_, j) => j !== i);
         }
-        this._entities.forEach((e) => e._purgeQuery(q));
     }
     /**
-     * Create a new {@link System}, register it, and return it for configuration.
+     * 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) {
+        if (this._componentRegistrationDisabled) {
+            throw "setEntityIdRange must be called before component registration is disabled";
+        }
+        this._eidCounter = min;
+    }
+    /**
+     * 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, onCreateCallback) {
+        let e = this._entities.get(eid);
+        if (!e) {
+            e = new Entity(this, eid);
+            this._entities.set(eid, e);
+            if (onCreateCallback) {
+                onCreateCallback(e);
+            }
+        }
+        return e;
+    }
+    entity(id) {
+        if (id === undefined) {
+            const eid = this._eidCounter++;
+            const e = new Entity(this, eid);
+            if (this.deferred) {
+                this._enqueue({ kind: 0 /* CommandKind.CreateEntity */, entity: e });
+            }
+            else {
+                this._entities.set(eid, e);
+            }
+            return e;
+        }
+        return this._entities.get(id);
+    }
+    /**
+     * 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() {
+        this._entities.forEach((e) => {
+            e.destroy();
+        });
+        this.flush();
+    }
+    /**
+     * 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) {
         return new System(name, this);
     }
     /**
-     * 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")
@@ -359,8 +486,8 @@ export 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) {
         return new Query(name, this);
@@ -368,157 +495,125 @@ export class World {
     filter(q, _guaranteed) {
         return new Filter(this, q);
     }
+    /**
+     * 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) {
+        const phase = new Phase(name, this);
+        this._pipeline.set(name, phase);
+        return phase;
+    }
     /**
      * 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.
+     * Called automatically by {@link start}. Call directly if you want to lock
+     * registration before the rest of the systems are wired up.
      */
     disableComponentRegistration() {
-        this.componentRegistrationDisabled = true;
+        this._componentRegistrationDisabled = true;
     }
     /**
      * 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.
+     * 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 this once before the first {@link runPhase} call.
+     * Call once before the first {@link runPhase} / {@link progress}.
      */
     start() {
-        this.componentRegistrationDisabled = true;
-        this.reindexSystems();
-    }
-    reindexSystems() {
-        let _defaultPhase = this._pipeline.get("update");
-        if (!_defaultPhase) {
-            _defaultPhase = new Phase("update", this);
-            this._pipeline.set(_defaultPhase.name, _defaultPhase);
-        }
-        const defaultPhase = _defaultPhase;
-        this._queries.forEach((q) => {
-            if (!(q instanceof System)) {
-                return;
-            }
-            let phase = q._phase;
-            if (typeof phase === "string") {
-                phase = this._pipeline.get(phase);
-            }
-            phase = phase || defaultPhase;
-            phase.systems.push(q);
-        });
-        this._pipeline.forEach((phase) => {
-            console.log("Phase %s : %s", phase.name, phase.systems.map((s) => s.name).join(" -> "));
-        });
+        this._componentRegistrationDisabled = true;
+        this._reindexSystems();
     }
     /**
-     * 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 hook is backed by the
-     * component's {@link ComponentMeta} and the same object is returned on every
-     * call.
+     * Open a new frame and evaluate every registered tick source once.
      *
-     * ```ts
-     * world.hook(Sprite)
-     *   .onAdd(c  => c.initialize(scene))
-     *   .onRemove(c => c.destroy());
-     * ```
+     * Call this before one or more {@link runPhase} calls when manually driving
+     * phases. {@link progress} wraps this automatically for the full pipeline.
      *
-     * @param C - The component class.
-     * @returns The `Hook` for that component type.
+     * @param delta - Milliseconds elapsed since the previous frame.
+     * @throws When a frame is already open.
      */
-    hook(C) {
-        return this.getComponentMeta(C);
+    beginFrame(delta) {
+        if (this._frameInProgress) {
+            throw "endFrame() not called before beginFrame()";
+        }
+        this._frameInProgress = true;
+        this._frameCounter++;
+        this.flush();
+        this._tickSources.forEach((t) => t._evalTick(delta, this._frameCounter));
     }
     /**
-     * Add a named phase to the update pipeline and return it.
+     * Close the current frame.
      *
-     * Phases are executed in insertion order when you call {@link runPhase} for
-     * each one. Systems are assigned to 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 {@link IPhase}.
+     * @throws When no frame is currently open.
      */
-    addPhase(name) {
-        const phase = new Phase(name, this);
-        this._pipeline.set(name, phase);
-        return phase;
+    endFrame() {
+        if (!this._frameInProgress) {
+            throw "beginFrame() not called before endFrame()";
+        }
+        this._frameInProgress = false;
     }
     /**
-     * Execute all systems in the given phase for one tick.
+     * Execute every system in `phase` within the current frame.
      *
-     * Pending top-level mutations are drained at the start of the phase so the
-     * first system observes a consistent world. Each system's body runs in a
-     * deferred scope; mutations made by callbacks are appended to the world
-     * queue and processed by the world after the system returns, before the
-     * next system runs.
+     * 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 phase - The {@link IPhase} to run (returned by {@link addPhase}).
+     * `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, now, delta) {
+        if (!this._frameInProgress) {
+            throw "runPhase() called outside a frame — call beginFrame() first";
+        }
         this.flush();
         phase.systems.forEach((s) => {
             s._run(now, delta);
-            // System._run wraps in begin/end which drains on return; nothing more
-            // to do here.
         });
     }
     /**
-     * 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.
+     * 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, delta) {
-        this.flush();
-        this._pipeline.forEach((phase) => {
-            this.runPhase(phase, now, delta);
-        });
-    }
-    /**
-     * 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
-     *
-     * ```ts
-     * world.setExclusiveComponents(Walking, Running, Idle);
-     * // entity.add(Running) throws if entity already has Walking or Idle
-     * ```
-     *
-     * @param components - Two or more component classes that cannot coexist.
-     * @throws If any class has not been registered.
-     */
-    setExclusiveComponents(...components) {
-        const types = components.map((C) => this.getComponentType(C));
-        for (let i = 0; i < components.length; i++) {
-            this.getComponentMeta(components[i]).exclusive = types.filter((_, j) => j !== i);
+        this.beginFrame(delta);
+        try {
+            this._pipeline.forEach((phase) => {
+                this.runPhase(phase, now, delta);
+            });
+        }
+        finally {
+            this.endFrame();
         }
-    }
-    /**
-     * 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() {
-        this._entities.forEach((e) => {
-            e.destroy();
-        });
-        this.flush();
     }
 }
 //# sourceMappingURL=world.js.map