blecsd 0.1.0

package/dist/gameLoop-BIPW7-OY.d.ts

@@ -0,0 +1,219 @@
+import { S as Scheduler } from './scheduler-DcfoFuum.js';
+import { W as World, S as System } from './types-BcsvoKzf.js';
+
+/**
+ * Game loop with input priority and lifecycle management.
+ * @module core/gameLoop
+ */
+
+/**
+ * Hook function called at specific points in the game loop.
+ * @param world - The current ECS world
+ * @param deltaTime - Time since last frame in seconds
+ */
+type LoopHook = (world: World, deltaTime: number) => void;
+/**
+ * Configuration for fixed timestep mode.
+ *
+ * Fixed timestep runs game logic at a consistent rate, independent of
+ * rendering frame rate. This is essential for:
+ * - Deterministic physics simulations
+ * - Network synchronization
+ * - Replays and recording
+ *
+ * @example
+ * ```typescript
+ * const loop = createGameLoop(world, {
+ *   fixedTimestepMode: {
+ *     tickRate: 60,           // 60 physics updates per second
+ *     maxUpdatesPerFrame: 5,  // Prevent spiral of death
+ *     interpolate: true,      // Smooth rendering between ticks
+ *   },
+ * });
+ * ```
+ */
+interface FixedTimestepConfig {
+    /**
+     * Number of fixed updates per second.
+     * Common values: 30, 60, 120 (higher = more precision, more CPU)
+     * @default 60
+     */
+    readonly tickRate: number;
+    /**
+     * Maximum fixed updates to run per frame.
+     * Prevents "spiral of death" when game can't keep up.
+     * If exceeded, game will run slower than real-time.
+     * @default 5
+     */
+    readonly maxUpdatesPerFrame: number;
+    /**
+     * Whether to interpolate render state between fixed updates.
+     * When true, rendering will be smooth even at low tick rates.
+     * When false, rendering shows the last completed tick state.
+     * @default true
+     */
+    readonly interpolate: boolean;
+}
+/**
+ * Configuration options for the game loop.
+ */
+interface GameLoopOptions {
+    /**
+     * Target frames per second. 0 means uncapped (as fast as possible).
+     * @default 60
+     */
+    targetFPS?: number;
+    /**
+     * Whether to use fixed timestep for physics stability.
+     * When true, deltaTime will be capped to prevent spiral of death.
+     * @default true
+     * @deprecated Use fixedTimestepMode for true fixed timestep with interpolation
+     */
+    fixedTimestep?: boolean;
+    /**
+     * Maximum delta time in seconds. Prevents large time jumps.
+     * @default 0.1 (100ms)
+     */
+    maxDeltaTime?: number;
+    /**
+     * Fixed timestep mode configuration.
+     * When set, the loop will use true fixed timestep with optional interpolation.
+     * INPUT is still processed every frame for responsiveness.
+     */
+    fixedTimestepMode?: FixedTimestepConfig;
+}
+/**
+ * Hook function for fixed timestep updates.
+ * @param world - The current ECS world
+ * @param fixedDeltaTime - Fixed delta time (always the same)
+ * @param tickNumber - The current tick number since loop start
+ */
+type FixedUpdateHook = (world: World, fixedDeltaTime: number, tickNumber: number) => void;
+/**
+ * Hook function for interpolated rendering.
+ * @param world - The current ECS world
+ * @param alpha - Interpolation factor (0-1) between previous and current tick
+ */
+type InterpolateHook = (world: World, alpha: number) => void;
+/**
+ * Lifecycle hooks for the game loop.
+ */
+interface GameLoopHooks {
+    onBeforeInput?: LoopHook;
+    onAfterInput?: LoopHook;
+    onBeforeUpdate?: LoopHook;
+    onAfterUpdate?: LoopHook;
+    onBeforeRender?: LoopHook;
+    onAfterRender?: LoopHook;
+    onStart?: () => void;
+    onStop?: () => void;
+    onPause?: () => void;
+    onResume?: () => void;
+    onBeforeFixedUpdate?: FixedUpdateHook;
+    onAfterFixedUpdate?: FixedUpdateHook;
+    onInterpolate?: InterpolateHook;
+}
+/**
+ * Statistics about the game loop performance.
+ */
+interface LoopStats {
+    fps: number;
+    frameTime: number;
+    frameCount: number;
+    runningTime: number;
+    tickCount: number;
+    ticksPerSecond: number;
+    interpolationAlpha: number;
+    skippedUpdates: number;
+}
+/**
+ * Game loop state enum.
+ */
+declare enum LoopState {
+    STOPPED = 0,
+    RUNNING = 1,
+    PAUSED = 2
+}
+/**
+ * GameLoop interface for type-safe access.
+ */
+interface GameLoop {
+    getState(): LoopState;
+    isRunning(): boolean;
+    isPaused(): boolean;
+    isStopped(): boolean;
+    getStats(): LoopStats;
+    getInterpolationAlpha(): number;
+    getFixedTimestepConfig(): FixedTimestepConfig | undefined;
+    isFixedTimestepMode(): boolean;
+    getScheduler(): Scheduler;
+    getWorld(): World;
+    setWorld(world: World): void;
+    setTargetFPS(fps: number): void;
+    getTargetFPS(): number;
+    registerSystem(phase: number, system: System, priority?: number): void;
+    unregisterSystem(system: System): void;
+    registerInputSystem(system: System, priority?: number): void;
+    setHooks(hooks: GameLoopHooks): void;
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    step(deltaTime?: number): void;
+    stepFixed(): void;
+}
+/**
+ * Creates a new game loop instance.
+ *
+ * The GameLoop wraps a Scheduler and provides:
+ * - Lifecycle management (start/stop/pause/resume)
+ * - Hook points for custom logic at specific phases
+ * - FPS limiting and frame timing
+ * - Performance statistics
+ *
+ * HARD REQUIREMENT: Input is ALWAYS processed first every frame.
+ *
+ * @param world - The ECS world to process
+ * @param options - Loop configuration options
+ * @param hooks - Lifecycle hooks
+ * @returns A new GameLoop instance
+ *
+ * @example
+ * ```typescript
+ * import { createGameLoop, createWorld, LoopPhase } from 'blecsd';
+ *
+ * const world = createWorld();
+ * const loop = createGameLoop(world, {
+ *   targetFPS: 60,
+ * }, {
+ *   onStart: () => console.log('Game started!'),
+ *   onStop: () => console.log('Game stopped!'),
+ * });
+ *
+ * // Register systems
+ * loop.registerSystem(LoopPhase.UPDATE, myUpdateSystem);
+ *
+ * // Start the game
+ * loop.start();
+ *
+ * // Stop after 5 seconds
+ * setTimeout(() => loop.stop(), 5000);
+ * ```
+ */
+declare function createGameLoop(initialWorld: World, options?: GameLoopOptions, initialHooks?: GameLoopHooks): GameLoop;
+/**
+ * Checks if a game loop exists and is running.
+ *
+ * @param loop - The game loop to check (may be undefined)
+ * @returns true if loop exists and is running
+ */
+declare function isLoopRunning(loop: GameLoop | undefined): boolean;
+/**
+ * Checks if a game loop exists and is paused.
+ *
+ * @param loop - The game loop to check (may be undefined)
+ * @returns true if loop exists and is paused
+ */
+declare function isLoopPaused(loop: GameLoop | undefined): boolean;
+
+export { type FixedTimestepConfig as F, type GameLoop as G, type InterpolateHook as I, type LoopStats as L, type FixedUpdateHook as a, type GameLoopHooks as b, type GameLoopOptions as c, type LoopHook as d, LoopState as e, createGameLoop as f, isLoopRunning as g, isLoopPaused as i };