archetype-ecs-lib 0.5.0 → 0.6.1

package/lib/ecs/World.d.ts

@@ -1,7 +1,8 @@
 import { Commands } from "./Commands";
 import { EventChannel } from "./Events";
-import type { ComponentCtor, ComponentCtorBundleItem, Entity, QueryRow1, QueryRow2, QueryRow3, QueryRow4, QueryRow5, QueryRow6, SystemFn, WorldApi } from "./Types";
-export declare class World implements WorldApi {
+import type { ComponentCtor, ComponentCtorBundleItem, Entity, QueryRow1, QueryRow2, QueryRow3, QueryRow4, QueryRow5, QueryRow6, QueryTable1, QueryTable2, QueryTable3, QueryTable4, QueryTable5, QueryTable6, SnapshotCodec, SystemFn, WorldApi, WorldSnapshot, WorldStats, WorldStatsHistory } from "./Types";
+import { StatsOverlay, type StatsOverlayOptions } from "./stats/StatsOverlay";
+export declare class World extends StatsOverlay implements WorldApi {
     private readonly entities;
     private readonly archetypes;
     private readonly archByKey;
@@ -10,17 +11,51 @@ export declare class World implements WorldApi {
     private _iterateDepth;
     private readonly resources;
     private readonly eventChannels;
-    constructor();
+    private readonly snapshotStore;
+    /** @internal Phase -> systems mapping for Schedule */
+    readonly _scheduleSystems: Map<string, SystemFn[]>;
+    constructor(options?: {
+        statsOverlayOptions: StatsOverlayOptions;
+    });
+    statsHistory(): WorldStatsHistory;
+    /**
+     * Rich runtime statistics (counts + last-frame timings).
+     * Note: `aliveEntities` is computed on demand (O(n) over entity meta).
+     */
+    stats(): WorldStats;
     /** Queue structural changes to apply safely after systems run. */
     cmd(): Commands;
     addSystem(fn: SystemFn): this;
     /**
-     * Run a frame:
-     * - run systems in order
-     * - flush queued commands (structural changes)
+     * Simple single-phase update.
+     * Runs all systems added via `addSystem()`, flushes commands, and swaps events once.
+     *
+     * This is the recommended approach for:
+     * - Simple applications with basic game loops
+     * - Single-phase system execution
+     * - Rapid prototyping
+     *
+     * @example
+     * ```TypeScript
+     * // Simple game loop
+     * function gameLoop(dt: number) {
+     *   world.update(dt);
+     * }
+     * ```
+     *
+     * @note If you are using `Schedule` for multiphase updates, do NOT use this method.
+     *  Use `schedule.run(world, dt, phases)` instead.
+     *
+     * @throws {Error} If both World.update() and Schedule.run() are used on the same World instance
      */
     update(dt: number): void;
     flush(): void;
+    registerComponentSnapshot<T, D = unknown>(key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): this;
+    unregisterComponentSnapshot<T>(key: ComponentCtor<T>): boolean;
+    registerResourceSnapshot<T, D = unknown>(key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): this;
+    unregisterResourceSnapshot<T>(key: ComponentCtor<T>): boolean;
+    snapshot(): WorldSnapshot;
+    restore(snapshot: WorldSnapshot): void;
     setResource<T>(key: ComponentCtor<T>, value: T): void;
     getResource<T>(key: ComponentCtor<T>): T | undefined;
     requireResource<T>(key: ComponentCtor<T>): T;
@@ -55,6 +90,28 @@ export declare class World implements WorldApi {
     query<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>): Iterable<QueryRow4<A, B, C, D>>;
     query<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryRow5<A, B, C, D, E>>;
     query<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>): Iterable<QueryRow6<A, B, C, D, E, F>>;
+    /**
+     * Table query: yields one item per matching archetype (SoA columns + entity array).
+     * This avoids allocating one object per entity row.
+     */
+    queryTables<A>(c1: ComponentCtor<A>): Iterable<QueryTable1<A>>;
+    queryTables<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>): Iterable<QueryTable2<A, B>>;
+    queryTables<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>): Iterable<QueryTable3<A, B, C>>;
+    queryTables<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>): Iterable<QueryTable4<A, B, C, D>>;
+    queryTables<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryTable5<A, B, C, D, E>>;
+    queryTables<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>): Iterable<QueryTable6<A, B, C, D, E, F>>;
+    /**
+     * Callback query: calls `fn` for each matching entity row (no yield object allocations).
+     */
+    queryEach<A>(c1: ComponentCtor<A>, fn: (e: Entity, c1: A) => void): void;
+    queryEach<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, fn: (e: Entity, c1: A, c2: B) => void): void;
+    queryEach<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, fn: (e: Entity, c1: A, c2: B, c3: C) => void): void;
+    queryEach<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D) => void): void;
+    queryEach<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E) => void): void;
+    queryEach<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E, c6: F) => void): void;
+    private _snapshotRuntime;
+    private _resetArchetypes;
+    private static _buildQueryTypeIds;
     private _ensureNotIterating;
     private _getOrCreateArchetype;
     private _removeFromArchetype;
@@ -71,4 +128,12 @@ export declare class World implements WorldApi {
      */
     private _assertAlive;
     private _events;
+    /**
+     * @internal Warns about lifecycle method conflicts in development mode
+     */
+    _warnAboutLifecycleConflict(method: "World.update" | "Schedule.run"): void;
+    /**
+     * @internal Returns the number of systems registered via addSystem()
+     */
+    _getSystemCount(): number;
 }