@vworlds/vecs 1.0.15 → 1.0.16

package/dist/world/world.components.js

@@ -0,0 +1,93 @@
+import { Component } from "../component.js";
+import { Entities } from "./world.entities.js";
+const RESERVED_EID = 0;
+export class Components extends Entities {
+    constructor() {
+        super(...arguments);
+        /** @internal `true` once {@link start} or {@link disableComponentRegistration} has been called. */
+        this._componentRegistrationDisabled = false;
+    }
+    component(ComponentClassOrName, eid) {
+        if (typeof ComponentClassOrName === "string") {
+            const entity = this.entity(ComponentClassOrName);
+            if (!(entity instanceof Component)) {
+                throw new Error(`Entity named '${ComponentClassOrName}' is not a component entity`);
+            }
+            return entity;
+        }
+        return this._component(Component, ComponentClassOrName, eid);
+    }
+    /** Prevent any further calls to {@link component}. */
+    disableComponentRegistration() {
+        this._componentRegistrationDisabled = true;
+    }
+    /**
+     * Read the singleton data stored on the component entity for `Class`.
+     *
+     * This is a convenience shorthand for `world.component(Class).get(Class)`.
+     * Use it when you store world-global state as a component on the component
+     * entity itself (the Singleton pattern).
+     *
+     * @param Class - Registered component class.
+     * @returns The component instance stored on the component entity, or
+     *   `undefined` when none has been set.
+     */
+    get(Class) {
+        return this.component(Class).get(Class);
+    }
+    /**
+     * Attach or update the singleton data stored on the component entity for `Class`.
+     *
+     * Shorthand for `world.component(Class).set(Class, props)`. Stores `props`
+     * on the component entity itself so the data can be retrieved globally via
+     * {@link get}.
+     *
+     * @param Class - Registered component class.
+     * @param props - Properties to merge onto the component instance.
+     * @returns The `Component` entity, for chaining.
+     */
+    set(Class, props) {
+        return this.component(Class).set(Class, props);
+    }
+    /** Declare a group of mutually exclusive components. */
+    setExclusiveComponents(...components) {
+        const metas = components.map((C) => this.entity(C).ownMeta);
+        for (let i = 0; i < metas.length; i++) {
+            metas[i]._exclusive = metas.filter((_, j) => j !== i);
+        }
+    }
+    /** @internal Register a component-like entity in the requested id pool. */
+    _component(Constructor, ComponentClass, eid, pool = this._componentPool) {
+        if (eid === RESERVED_EID) {
+            throw new Error(`Component eid ${eid} is reserved`);
+        }
+        const existingComponent = this._classRegistry.get(ComponentClass);
+        if (existingComponent) {
+            if (eid === undefined || eid === existingComponent.eid) {
+                return existingComponent;
+            }
+            throw new Error(`Component class ${ComponentClass.name} is already registered with eid ${existingComponent.eid}`);
+        }
+        if (this._componentRegistrationDisabled) {
+            throw new Error("World component registration is disabled");
+        }
+        if (eid === undefined) {
+            eid = pool.alloc();
+        }
+        else {
+            if (this._entities.has(eid)) {
+                throw new Error(`Entity id ${eid} is already taken`);
+            }
+            this._reserveEid(eid);
+        }
+        const component = new Constructor(this, eid, ComponentClass);
+        this._entities.set(eid, component);
+        this._classRegistry.set(ComponentClass, component);
+        // Component-definition entities are first-class entities: notify so any
+        // live world-rooted query/term picks them up reactively (reflection),
+        // exactly like an ordinary `world.entity()`.
+        this._notifyEntityCreated(component);
+        return component;
+    }
+}
+//# sourceMappingURL=world.components.js.map

package/dist/world/world.components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.components.js","sourceRoot":"","sources":["../../src/world/world.components.ts"],"names":[],"mappings":"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"}

package/dist/world/world.d.ts

@@ -0,0 +1,29 @@
+import { Pipeline } from "./world.pipeline.js";
+import { type WorldOptions } from "./world.base.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** — call {@link component} 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.
+ *
+ * ## Deferred mode
+ *
+ * The world can be in **deferred mode**, in which case entity mutations
+ * (`add` / `attach` / `set` / `remove` / `destroy` / `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 extends Pipeline {
+    constructor(options?: WorldOptions);
+}

package/dist/world/world.deferred.d.ts

@@ -0,0 +1,13 @@
+import { Queries } from "./world.queries.js";
+export declare class Deferred extends Queries {
+    /** `true` while the world is in deferred mode. */
+    get deferred(): boolean;
+    /** Enter deferred mode. */
+    beginDefer(): void;
+    /** Run `fn` inside a deferred scope. */
+    defer(fn: () => void): void;
+    /** Leave deferred mode and drain at the outermost scope. */
+    endDefer(): void;
+    /** Build pending queries and drain queued commands at the top level. */
+    flush(): void;
+}

package/dist/world/world.deferred.js

@@ -0,0 +1,93 @@
+import { Queries } from "./world.queries.js";
+export class Deferred extends Queries {
+    constructor() {
+        super(...arguments);
+        /** @internal Single ordered command queue used in deferred mode. */
+        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;
+    }
+    /** `true` while the world is in deferred mode. */
+    get deferred() {
+        return this._deferredDepth > 0 || this._draining;
+    }
+    /** @internal Append a command to the deferred-mode queue. */
+    _enqueue(cmd) {
+        cmd.source = this._currentSource;
+        this._commandQueue.push(cmd);
+    }
+    /** Enter deferred mode. */
+    beginDefer() {
+        this._deferredDepth++;
+    }
+    /** Run `fn` inside a deferred scope. */
+    defer(fn) {
+        this.beginDefer();
+        try {
+            fn();
+        }
+        finally {
+            this.endDefer();
+        }
+    }
+    /** Leave deferred mode and drain at the outermost scope. */
+    endDefer() {
+        this._deferredDepth--;
+        this.flush();
+    }
+    /** Build pending queries and drain queued commands at the top level. */
+    flush() {
+        if (this._deferredDepth === 0) {
+            this._buildPendingQueries();
+            this._processCommandQueue();
+        }
+    }
+    /** @internal Run one command's side effects. */
+    _executeCommand(cmd) {
+        this._routingSource = cmd.source;
+        switch (cmd.kind) {
+            case 0 /* CommandKind.CreateEntity */:
+                this._entities.set(cmd.entity.eid, cmd.entity);
+                this._notifyEntityCreated(cmd.entity);
+                return;
+            case 1 /* CommandKind.Set */:
+                cmd.entity._set(cmd.meta, cmd.props);
+                return;
+            case 2 /* CommandKind.Modified */:
+                cmd.entity._modified(cmd.meta);
+                return;
+            case 3 /* CommandKind.Remove */:
+                cmd.entity._remove(cmd.meta);
+                return;
+            case 4 /* CommandKind.Destroy */:
+                cmd.entity._destroy();
+                return;
+            case 5 /* CommandKind.Attach */:
+                cmd.entity._attach(cmd.meta, cmd.component);
+                return;
+        }
+    }
+    /** @internal Drain the top-level command queue in arrival order. */
+    _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._routingSource = undefined;
+            this._draining = false;
+        }
+    }
+}
+//# sourceMappingURL=world.deferred.js.map

package/dist/world/world.deferred.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.deferred.js","sourceRoot":"","sources":["../../src/world/world.deferred.ts"],"names":[],"mappings":"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"}

package/dist/world/world.entities.d.ts

@@ -0,0 +1,18 @@
+import { type ComponentRef } from "../component.js";
+import { Entity } from "../entity/index.js";
+import { Deferred } from "./world.deferred.js";
+import type { World } from "./world.js";
+export declare class Entities extends Deferred {
+    /** Return the entity with id `eid`, creating it if it does not yet exist. */
+    getOrCreateEntity(this: World, eid: number, onCreateCallback?: (e: Entity) => void): Entity;
+    /** Look up an entity by component ref or identity name. */
+    getEntity(this: World, ref: ComponentRef | string): Entity | undefined;
+    /** Create a new entity with an auto-assigned id. */
+    entity(this: World): Entity;
+    /** Look up an existing entity by identity name, creating it if absent. */
+    entity(this: World, ref: string): Entity;
+    /** Look up an existing entity by component ref. */
+    entity(this: World, ref: ComponentRef): Entity;
+    /** Destroy every entity currently tracked by the world. */
+    clearAllEntities(): void;
+}

package/dist/world/world.entities.js

@@ -0,0 +1,97 @@
+import { Entity, Identity } from "../entity/index.js";
+import { Deferred } from "./world.deferred.js";
+const RESERVED_EID = 0;
+export class Entities extends Deferred {
+    /** Return the entity with id `eid`, creating it if it does not yet exist. */
+    getOrCreateEntity(eid, onCreateCallback) {
+        if (eid === RESERVED_EID) {
+            throw new Error(`Entity eid ${eid} is reserved`);
+        }
+        let e = this._entities.get(eid);
+        if (!e) {
+            this._reserveEid(eid);
+            e = new Entity(this, eid);
+            this._entities.set(eid, e);
+            this._notifyEntityCreated(e);
+            if (onCreateCallback) {
+                onCreateCallback(e);
+            }
+        }
+        return e;
+    }
+    /** Look up an entity by component ref or identity name. */
+    getEntity(ref) {
+        if (typeof ref === "string") {
+            return this._identityNameIndex.get(ref);
+        }
+        if (typeof ref === "function") {
+            return this._classRegistry.get(ref);
+        }
+        if (typeof ref === "number") {
+            if (ref === RESERVED_EID) {
+                throw new Error(`Entity eid ${ref} is reserved`);
+            }
+            return this._entities.get(ref);
+        }
+        return ref.world === this && this._entities.get(ref.eid) === ref ? ref : undefined;
+    }
+    entity(ref) {
+        if (ref === undefined) {
+            return this._entity(Entity);
+        }
+        if (typeof ref === "string") {
+            let entity = this._identityNameIndex.get(ref);
+            if (entity) {
+                return entity;
+            }
+            entity = this._entity(Entity);
+            entity.set(Identity, { name: ref });
+            return entity;
+        }
+        const entity = this.getEntity(ref);
+        if (entity) {
+            return entity;
+        }
+        if (typeof ref === "function") {
+            throw new Error(`unregistered component entity for component class '${ref.name}'`);
+        }
+        if (typeof ref === "number") {
+            throw new Error(`No entity with eid ${ref}`);
+        }
+        throw new Error(`No entity with eid ${ref.eid}`);
+    }
+    /** Destroy every entity currently tracked by the world. */
+    clearAllEntities() {
+        const pending = new Set(this._entities.values());
+        while (pending.size > 0) {
+            let destroyed = 0;
+            for (const entity of [...pending]) {
+                const instanceCount = entity.instanceCount();
+                if (instanceCount > (entity._get(entity.eid) ? 1 : 0)) {
+                    continue;
+                }
+                entity.destroy();
+                pending.delete(entity);
+                destroyed++;
+            }
+            if (destroyed === 0) {
+                throw new Error("Cannot clear entities because component eids are still in use");
+            }
+        }
+        this.flush();
+    }
+    /** @internal Create an entity with an id from the entity pool. */
+    _entity(Constructor) {
+        const eid = this._entityPool.alloc();
+        const e = new Constructor(this, eid);
+        if (this.deferred) {
+            this._enqueue({ kind: 0 /* CommandKind.CreateEntity */, entity: e });
+        }
+        else {
+            this._entities.set(eid, e);
+            this._notifyEntityCreated(e);
+        }
+        return e;
+    }
+}
+//# sourceMappingURL=world.entities.js.map

package/dist/world/world.entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.entities.js","sourceRoot":"","sources":["../../src/world/world.entities.ts"],"names":[],"mappings":"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"}

package/dist/world/world.js

@@ -0,0 +1,39 @@
+import { CleanupPolicy } from "../component_meta.js";
+import { Query } from "../query/index.js";
+import { ChildOf, SilenceSource } from "../relationship.js";
+import { System } from "../system.js";
+import { Pipeline } from "./world.pipeline.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** — call {@link component} 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.
+ *
+ * ## Deferred mode
+ *
+ * The world can be in **deferred mode**, in which case entity mutations
+ * (`add` / `attach` / `set` / `remove` / `destroy` / `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 extends Pipeline {
+    constructor(options = {}) {
+        super(options);
+        this.component(ChildOf).ownMeta.onDeleteTarget = CleanupPolicy.Delete;
+        this.component(Query).onRemove((_entity, query) => query.destroy());
+        this.component(System).onRemove((_entity, system) => system.destroy());
+        this.component(SilenceSource).onRemove((entity) => entity.get(Query)?._clearSilence());
+    }
+}
+//# sourceMappingURL=world.js.map

package/dist/world/world.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/world/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACjC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC;QACtE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IACzF,CAAC;CACF"}

package/dist/world/world.modules.d.ts

@@ -0,0 +1,12 @@
+import { Entity, type EntityClass } from "../entity/index.js";
+import { Components } from "./world.components.js";
+import type { WorldOptions } from "./world.base.js";
+import type { World } from "./world.js";
+type ModuleEntity = Entity & {
+    init(): void;
+};
+export declare class Modules extends Components {
+    constructor(options?: WorldOptions);
+    module<T extends ModuleEntity>(this: World, ModuleClass: EntityClass<T>, eid?: number): T;
+}
+export {};

package/dist/world/world.modules.js

@@ -0,0 +1,21 @@
+import { IdentityModule } from "../modules/identity.js";
+import { SingletonModule } from "../modules/singleton.js";
+import { Components } from "./world.components.js";
+const BUILTIN_MODULES = [IdentityModule, SingletonModule];
+export class Modules extends Components {
+    constructor(options = {}) {
+        super(options);
+        const world = this;
+        BUILTIN_MODULES.forEach((mod) => world.module(mod));
+    }
+    module(ModuleClass, eid) {
+        const ComponentClass = ModuleClass;
+        const isNew = !this._classRegistry.has(ComponentClass);
+        const mod = this._component(ModuleClass, ComponentClass, eid, this._modulePool);
+        if (isNew) {
+            mod.init();
+        }
+        return mod;
+    }
+}
+//# sourceMappingURL=world.modules.js.map

package/dist/world/world.modules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.modules.js","sourceRoot":"","sources":["../../src/world/world.modules.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD,MAAM,eAAe,GAAgC,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;AAEvF,MAAM,OAAO,OAAQ,SAAQ,UAAU;IACrC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,MAAM,KAAK,GAAG,IAAwB,CAAC;QACvC,eAAe,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IAEM,MAAM,CAAsC,WAA2B,EAAE,GAAY;QAC1F,MAAM,cAAc,GAAG,WAAwC,CAAC;QAChE,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACvD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAI,WAAW,EAAE,cAAc,EAAE,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACnF,IAAI,KAAK,EAAE,CAAC;YACV,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/world/world.pipeline.d.ts

@@ -0,0 +1,21 @@
+import { IPhase } from "../phase.js";
+import { System } from "../system.js";
+import type { WorldOptions } from "./world.base.js";
+import { Modules } from "./world.modules.js";
+export declare class Pipeline extends Modules {
+    constructor(options?: WorldOptions);
+    /** Add a named phase to the update pipeline. */
+    addPhase(name: string): IPhase;
+    /** Open a new frame and evaluate every registered tick source once. */
+    beginFrame(delta: number): void;
+    /** Close the current frame. */
+    endFrame(): void;
+    /** Run every phase in the pipeline in registration order. */
+    progress(now: number, delta: number): void;
+    /** Execute every system in `phase` within the current frame. */
+    runPhase(phase: IPhase, now: number, delta: number): void;
+    /** Freeze component registration and prepare the world for running. */
+    start(): void;
+    /** Create and return a new {@link System}, ready for fluent configuration. */
+    system(name: string): System;
+}

package/dist/world/world.pipeline.js

@@ -0,0 +1,105 @@
+import { Phase } from "../phase.js";
+import { System } from "../system.js";
+import { ALWAYS_TICK_SOURCE } from "../timer.js";
+import { Modules } from "./world.modules.js";
+export class Pipeline extends Modules {
+    constructor(options = {}) {
+        super(options);
+        /** @internal `true` once {@link start} has prepared the phase pipeline. */
+        this._started = false;
+        /** @internal Phase name -> phase. Insertion-ordered, matches pipeline execution order. */
+        this._pipeline = new Map();
+        /** @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;
+        this._tickSources.add(ALWAYS_TICK_SOURCE);
+    }
+    /** Add a named phase to the update pipeline. */
+    addPhase(name) {
+        const phase = new Phase(name, this);
+        this._pipeline.set(name, phase);
+        return phase;
+    }
+    /** Open a new frame and evaluate every registered tick source once. */
+    beginFrame(delta) {
+        if (this._frameInProgress) {
+            throw new Error("endFrame() not called before beginFrame()");
+        }
+        this._frameInProgress = true;
+        this._frameCounter++;
+        this.flush();
+        this._tickSources.forEach((t) => t._evalTick(delta, this._frameCounter));
+    }
+    /** Close the current frame. */
+    endFrame() {
+        if (!this._frameInProgress) {
+            throw new Error("beginFrame() not called before endFrame()");
+        }
+        this._frameInProgress = false;
+    }
+    /** Run every phase in the pipeline in registration order. */
+    progress(now, delta) {
+        this.beginFrame(delta);
+        try {
+            this._pipeline.forEach((phase) => {
+                this.runPhase(phase, now, delta);
+            });
+        }
+        finally {
+            this.endFrame();
+        }
+    }
+    /** Execute every system in `phase` within the current frame. */
+    runPhase(phase, now, delta) {
+        if (!this._frameInProgress) {
+            throw new Error("runPhase() called outside a frame — call beginFrame() first");
+        }
+        this.flush();
+        phase.systems.forEach((s) => {
+            s._run(now, delta);
+        });
+    }
+    /** Freeze component registration and prepare the world for running. */
+    start() {
+        this._buildPendingQueries();
+        this._componentRegistrationDisabled = true;
+        this._started = true;
+        this._reindexSystems();
+    }
+    /** Create and return a new {@link System}, ready for fluent configuration. */
+    system(name) {
+        if (this._started) {
+            throw new Error("systems cannot be added after world start");
+        }
+        return new System(name, this);
+    }
+    /** @internal Register a tick source with this world. */
+    _registerTickSource(t) {
+        this._tickSources.add(t);
+    }
+    /** @internal Distribute every registered system into its phase's `systems` list. */
+    _reindexSystems() {
+        let _defaultPhase = this._pipeline.get("update");
+        if (!_defaultPhase) {
+            _defaultPhase = new Phase("update", this);
+            this._pipeline.set(_defaultPhase.name, _defaultPhase);
+        }
+        const defaultPhase = _defaultPhase;
+        this._pipeline.forEach((phase) => {
+            phase.systems.length = 0;
+        });
+        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);
+        });
+    }
+}
+//# sourceMappingURL=world.pipeline.js.map

package/dist/world/world.pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.pipeline.js","sourceRoot":"","sources":["../../src/world/world.pipeline.ts"],"names":[],"mappings":"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"}

package/dist/world/world.pools.d.ts

@@ -0,0 +1,9 @@
+import { type IdPoolConfig } from "../util/id_pool.js";
+import { Base, type WorldOptions } from "./world.base.js";
+export declare const DEFAULT_POOLS: readonly IdPoolConfig[];
+export declare class Pools extends Base {
+    constructor(options?: WorldOptions);
+    get pools(): ReadonlyArray<IdPoolConfig>;
+    /** Return the id that the named pool will allocate next without reserving it. */
+    peekNextEid(poolName: string): number;
+}

package/dist/world/world.pools.js

@@ -0,0 +1,59 @@
+import { IdPool, validateIdPoolConfigs } from "../util/id_pool.js";
+import { Base } from "./world.base.js";
+const RESERVED_EID = 0;
+export const DEFAULT_POOLS = [
+    { name: "component", min: 1, max: 899 },
+    { name: "module", min: 900, max: 999 },
+    { name: "entity", min: 1000 },
+];
+export class Pools extends Base {
+    constructor(options = {}) {
+        super();
+        /** @internal Baked id pool configs for this world. */
+        this._poolConfigs = [];
+        /** @internal Runtime allocators for every configured id range. */
+        this._pools = [];
+        const idPools = options.idPools ?? DEFAULT_POOLS;
+        validateIdPoolConfigs(idPools);
+        this._poolConfigs.push(...idPools.map((pool) => ({ ...pool })));
+        this._pools.push(...this._poolConfigs.map((pool) => new IdPool(pool.name, pool.min, pool.max)));
+        this._cacheNamedPools();
+    }
+    get pools() {
+        return this._poolConfigs.map((pool) => ({ ...pool }));
+    }
+    /** Return the id that the named pool will allocate next without reserving it. */
+    peekNextEid(poolName) {
+        return this._poolByName(poolName).peek();
+    }
+    /** @internal Cache the well-known pools used by hot paths. */
+    _cacheNamedPools() {
+        this._componentPool = this._poolByName("component");
+        this._modulePool = this._poolByName("module");
+        this._entityPool = this._poolByName("entity");
+    }
+    /** @internal Look up a configured id pool by name. */
+    _poolByName(name) {
+        const pool = this._pools.find((candidate) => candidate.name === name);
+        if (!pool) {
+            throw new Error(`Unknown id pool '${name}'`);
+        }
+        return pool;
+    }
+    /** @internal Return the pool that owns `eid`. */
+    _poolFor(eid) {
+        if (eid === RESERVED_EID) {
+            throw new Error(`Eid ${eid} is reserved`);
+        }
+        const pool = this._pools.find((candidate) => candidate.owns(eid));
+        if (!pool) {
+            throw new Error(`No id pool owns eid ${eid}`);
+        }
+        return pool;
+    }
+    /** @internal Reserve an externally assigned id in its owning pool. */
+    _reserveEid(eid) {
+        this._poolFor(eid).reserve(eid);
+    }
+}
+//# sourceMappingURL=world.pools.js.map