blecsd 0.1.0

package/dist/debug/index.d.ts

@@ -0,0 +1,711 @@
+import { W as World, E as Entity } from '../types-BcsvoKzf.js';
+import { G as GameLoop } from '../gameLoop-BIPW7-OY.js';
+import 'bitecs';
+import '../scheduler-DcfoFuum.js';
+
+/**
+ * Memory Profiling and Leak Detection
+ *
+ * Tracks entity and component allocations to catch memory issues during
+ * development. Provides allocation counting, periodic snapshots, and
+ * leak detection for common patterns.
+ *
+ * @module debug/memoryProfiler
+ */
+
+/**
+ * Memory snapshot at a point in time.
+ */
+interface MemorySnapshot {
+    /** Timestamp of the snapshot */
+    readonly timestamp: number;
+    /** Total entity count */
+    readonly entityCount: number;
+    /** Component counts by name */
+    readonly componentCounts: Record<string, number>;
+    /** Node.js heap used in bytes */
+    readonly heapUsed: number;
+    /** Node.js heap total in bytes */
+    readonly heapTotal: number;
+    /** Node.js RSS in bytes */
+    readonly rss: number;
+    /** External memory in bytes */
+    readonly external: number;
+}
+/**
+ * Memory diff between two snapshots.
+ */
+interface MemoryDiff {
+    /** Time elapsed between snapshots in ms */
+    readonly elapsed: number;
+    /** Entity count change */
+    readonly entityCountDelta: number;
+    /** Component count changes by name */
+    readonly componentDeltas: Record<string, number>;
+    /** Heap used change in bytes */
+    readonly heapUsedDelta: number;
+    /** RSS change in bytes */
+    readonly rssDelta: number;
+    /** Possible leaks detected */
+    readonly possibleLeaks: readonly LeakWarning[];
+}
+/**
+ * Warning about a potential memory leak.
+ */
+interface LeakWarning {
+    /** Type of leak */
+    readonly type: 'entity' | 'component' | 'heap';
+    /** Description of the warning */
+    readonly message: string;
+    /** Growth rate (units per second) */
+    readonly growthRate: number;
+}
+/**
+ * Allocation tracker state.
+ */
+interface AllocationTracker {
+    /** Total entities allocated since tracking started */
+    readonly totalAllocated: number;
+    /** Total entities deallocated since tracking started */
+    readonly totalDeallocated: number;
+    /** Current entity count */
+    readonly currentCount: number;
+    /** Per-component allocation counts */
+    readonly componentAllocations: Record<string, number>;
+}
+/**
+ * Memory profiler configuration.
+ */
+interface MemoryProfilerConfig {
+    /** Interval between automatic snapshots in ms (0 = disabled) */
+    readonly snapshotInterval: number;
+    /** Maximum number of snapshots to keep */
+    readonly maxSnapshots: number;
+    /** Growth rate threshold for leak detection (entities per second) */
+    readonly entityLeakThreshold: number;
+    /** Heap growth threshold for leak detection (bytes per second) */
+    readonly heapLeakThreshold: number;
+    /** Components to track (all if empty) */
+    readonly trackedComponents: readonly {
+        component: unknown;
+        name: string;
+    }[];
+}
+/**
+ * Memory profiler state.
+ */
+interface MemoryProfiler {
+    /** Take a snapshot */
+    snapshot(world: World): MemorySnapshot;
+    /** Compare two snapshots */
+    diff(older: MemorySnapshot, newer: MemorySnapshot): MemoryDiff;
+    /** Get all snapshots */
+    getSnapshots(): readonly MemorySnapshot[];
+    /** Get the latest snapshot */
+    getLatestSnapshot(): MemorySnapshot | null;
+    /** Get a memory report string */
+    getReport(world: World): string;
+    /** Start automatic snapshotting */
+    startAutoSnapshot(world: World): void;
+    /** Stop automatic snapshotting */
+    stopAutoSnapshot(): void;
+    /** Reset all data */
+    reset(): void;
+}
+/**
+ * Creates a memory profiler for tracking allocations and detecting leaks.
+ *
+ * @param config - Optional configuration
+ * @returns Memory profiler instance
+ *
+ * @example
+ * ```typescript
+ * import { createMemoryProfiler } from 'blecsd';
+ *
+ * const profiler = createMemoryProfiler({
+ *   snapshotInterval: 5000,
+ *   trackedComponents: [
+ *     { component: Position, name: 'Position' },
+ *     { component: Renderable, name: 'Renderable' },
+ *   ],
+ * });
+ *
+ * // Take manual snapshots
+ * const snap1 = profiler.snapshot(world);
+ * // ... do work ...
+ * const snap2 = profiler.snapshot(world);
+ *
+ * // Check for leaks
+ * const diff = profiler.diff(snap1, snap2);
+ * if (diff.possibleLeaks.length > 0) {
+ *   console.warn('Possible leaks:', diff.possibleLeaks);
+ * }
+ *
+ * // Get a formatted report
+ * console.log(profiler.getReport(world));
+ * ```
+ */
+declare function createMemoryProfiler(config?: Partial<MemoryProfilerConfig>): MemoryProfiler;
+
+/**
+ * Debug overlay widget for visual debugging.
+ *
+ * Displays real-time debugging information:
+ * - FPS counter
+ * - Entity count
+ * - System timings
+ * - Memory usage
+ * - Input events
+ *
+ * @module debug/overlay
+ */
+
+/**
+ * Debug overlay configuration.
+ */
+interface DebugOverlayConfig {
+    /** X position (default: 0) */
+    readonly x?: number;
+    /** Y position (default: 0) */
+    readonly y?: number;
+    /** Width (default: 35) */
+    readonly width?: number;
+    /** Toggle key (default: 'F12') */
+    readonly toggleKey?: string;
+    /** Whether to show FPS (default: true) */
+    readonly showFPS?: boolean;
+    /** Whether to show entity count (default: true) */
+    readonly showEntityCount?: boolean;
+    /** Whether to show memory usage (default: true) */
+    readonly showMemory?: boolean;
+    /** Whether to show system timings (default: true) */
+    readonly showSystemTimings?: boolean;
+    /** Maximum number of systems to show (default: 5) */
+    readonly maxSystemsShown?: number;
+    /** Background color (default: dark blue) */
+    readonly bgColor?: number;
+    /** Foreground color (default: white) */
+    readonly fgColor?: number;
+    /** Whether visible on start (default: false) */
+    readonly visibleOnStart?: boolean;
+}
+/**
+ * Debug overlay state.
+ */
+interface DebugOverlay {
+    /** Whether the overlay is currently visible */
+    readonly visible: boolean;
+    /** The overlay entity (null if not created) */
+    readonly entity: Entity | null;
+    /** Configuration */
+    readonly config: Required<DebugOverlayConfig>;
+    /** Show the overlay */
+    show(): void;
+    /** Hide the overlay */
+    hide(): void;
+    /** Toggle visibility */
+    toggle(): void;
+    /** Update overlay content */
+    update(world: World, loop?: GameLoop): void;
+    /** Destroy the overlay */
+    destroy(): void;
+}
+/**
+ * Creates a debug overlay for the given world.
+ *
+ * The overlay displays real-time debugging information and can be
+ * toggled with a configurable key (default: F12).
+ *
+ * @param world - The ECS world
+ * @param config - Optional configuration
+ * @returns Debug overlay controller
+ *
+ * @example
+ * ```typescript
+ * import { createDebugOverlay } from 'blecsd/debug';
+ *
+ * const overlay = createDebugOverlay(world, {
+ *   toggleKey: 'F12',
+ *   showSystemTimings: true,
+ * });
+ *
+ * // In game loop
+ * game.onUpdate(() => {
+ *   overlay.update(world, loop);
+ * });
+ *
+ * // Toggle with key
+ * game.onKey('F12', () => overlay.toggle());
+ * ```
+ */
+declare function createDebugOverlay(world: World, config?: DebugOverlayConfig): DebugOverlay;
+/**
+ * Input event log entry.
+ */
+interface InputLogEntry {
+    readonly type: 'key' | 'mouse';
+    readonly detail: string;
+    readonly timestamp: number;
+}
+/**
+ * Input event logger state.
+ */
+interface InputLogger {
+    readonly entries: readonly InputLogEntry[];
+    readonly maxEntries: number;
+    log(type: 'key' | 'mouse', detail: string): void;
+    clear(): void;
+    getRecentEntries(count?: number): readonly InputLogEntry[];
+}
+/**
+ * Creates an input event logger for debugging.
+ *
+ * @param maxEntries - Maximum entries to keep (default: 20)
+ * @returns Input logger
+ *
+ * @example
+ * ```typescript
+ * import { createInputLogger } from 'blecsd/debug';
+ *
+ * const logger = createInputLogger(10);
+ *
+ * // In input handler
+ * game.onAnyKey((event) => {
+ *   logger.log('key', `${event.name} ${event.ctrl ? '+Ctrl' : ''}`);
+ * });
+ *
+ * game.onMouse((event) => {
+ *   logger.log('mouse', `${event.action} @ ${event.x},${event.y}`);
+ * });
+ *
+ * // Get recent entries
+ * console.log(logger.getRecentEntries(5));
+ * ```
+ */
+declare function createInputLogger(maxEntries?: number): InputLogger;
+/**
+ * Mini profiler for measuring code sections.
+ */
+interface MiniProfiler {
+    /** Start timing a section */
+    start(name: string): void;
+    /** End timing a section */
+    end(name: string): number;
+    /** Get average time for a section */
+    getAverage(name: string): number;
+    /** Get all timings */
+    getAll(): Record<string, {
+        avg: number;
+        min: number;
+        max: number;
+        count: number;
+    }>;
+    /** Reset all timings */
+    reset(): void;
+}
+/**
+ * Creates a mini profiler for measuring code sections.
+ *
+ * @returns Mini profiler instance
+ *
+ * @example
+ * ```typescript
+ * import { createMiniProfiler } from 'blecsd/debug';
+ *
+ * const profiler = createMiniProfiler();
+ *
+ * profiler.start('render');
+ * // ... render code ...
+ * const elapsed = profiler.end('render');
+ *
+ * console.log(`Render avg: ${profiler.getAverage('render').toFixed(2)}ms`);
+ * ```
+ */
+declare function createMiniProfiler(): MiniProfiler;
+/**
+ * Frame rate graph data.
+ */
+interface FrameRateGraph {
+    /** Add a frame time sample */
+    addSample(frameTimeMs: number): void;
+    /** Get samples for rendering */
+    getSamples(): readonly number[];
+    /** Get current FPS */
+    getCurrentFPS(): number;
+    /** Get average FPS */
+    getAverageFPS(): number;
+    /** Get min/max FPS */
+    getMinMaxFPS(): {
+        min: number;
+        max: number;
+    };
+    /** Reset the graph */
+    reset(): void;
+}
+/**
+ * Creates a frame rate graph for visualizing performance over time.
+ *
+ * @param sampleCount - Number of samples to keep (default: 60)
+ * @returns Frame rate graph
+ *
+ * @example
+ * ```typescript
+ * import { createFrameRateGraph } from 'blecsd/debug';
+ *
+ * const graph = createFrameRateGraph(120); // 2 seconds at 60fps
+ *
+ * // In game loop
+ * game.onUpdate((dt) => {
+ *   graph.addSample(dt * 1000);
+ *
+ *   // Render graph...
+ *   const samples = graph.getSamples();
+ *   // samples are frame times in ms, convert to FPS for display
+ * });
+ * ```
+ */
+declare function createFrameRateGraph(sampleCount?: number): FrameRateGraph;
+
+/**
+ * Debug utilities for development and debugging.
+ *
+ * These utilities help with:
+ * - Inspecting entity state
+ * - Viewing world statistics
+ * - Performance monitoring
+ * - Visual debugging
+ *
+ * @module debug
+ */
+
+/**
+ * Component information for inspection.
+ */
+interface ComponentInfo {
+    readonly name: string;
+    readonly data: Record<string, unknown>;
+}
+/**
+ * Entity inspection result.
+ */
+interface EntityInspection {
+    readonly entity: Entity;
+    readonly name: string | null;
+    readonly components: readonly ComponentInfo[];
+    readonly parent: Entity | null;
+    readonly children: readonly Entity[];
+}
+/**
+ * World inspection result.
+ */
+interface WorldInspection {
+    readonly entityCount: number;
+    readonly componentCounts: Record<string, number>;
+    readonly hierarchyRoots: readonly Entity[];
+}
+/**
+ * Performance statistics.
+ */
+interface PerformanceStats {
+    /** Current frames per second */
+    readonly fps: number;
+    /** Current frame time in milliseconds */
+    readonly frameTime: number;
+    /** Total frames rendered */
+    readonly frameCount: number;
+    /** Total running time in seconds */
+    readonly runningTime: number;
+    /** Entity count */
+    readonly entityCount: number;
+    /** Memory usage in MB (if available) */
+    readonly memoryUsageMB: number | null;
+    /** System timing in milliseconds per system */
+    readonly systemTimings: Record<string, number>;
+}
+/**
+ * Known components for inspection.
+ */
+declare const KNOWN_COMPONENTS: readonly {
+    component: unknown;
+    name: string;
+}[];
+/**
+ * Inspects an entity and returns detailed information about its components.
+ *
+ * @param world - The ECS world
+ * @param eid - The entity to inspect
+ * @returns Entity inspection data
+ *
+ * @example
+ * ```typescript
+ * import { inspectEntity } from 'blecsd/debug';
+ *
+ * const entity = addEntity(world);
+ * setPosition(world, entity, 10, 20);
+ *
+ * const info = inspectEntity(world, entity);
+ * console.log(info.components);
+ * // [{ name: 'Position', data: { x: 10, y: 20, z: 0, absolute: 0 } }]
+ * ```
+ */
+declare function inspectEntity(world: World, eid: Entity): EntityInspection;
+/**
+ * Formats an entity inspection as a human-readable string.
+ *
+ * @param inspection - The entity inspection data
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * import { inspectEntity, formatEntityInspection } from 'blecsd/debug';
+ *
+ * const info = inspectEntity(world, entity);
+ * console.log(formatEntityInspection(info));
+ * // Entity 1 (MyBox)
+ * // ├─ Position: x=10, y=20, z=0
+ * // ├─ Dimensions: width=40, height=10
+ * // └─ Renderable: visible=1
+ * ```
+ */
+declare function formatEntityInspection(inspection: EntityInspection): string;
+/**
+ * Inspects the world and returns statistics about entities and components.
+ *
+ * @param world - The ECS world to inspect
+ * @returns World inspection data
+ *
+ * @example
+ * ```typescript
+ * import { inspectWorld } from 'blecsd/debug';
+ *
+ * const info = inspectWorld(world);
+ * console.log(`Entities: ${info.entityCount}`);
+ * console.log(`Position components: ${info.componentCounts['Position']}`);
+ * ```
+ */
+declare function inspectWorld(world: World): WorldInspection;
+/**
+ * Formats a world inspection as a human-readable string.
+ *
+ * @param inspection - The world inspection data
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * import { inspectWorld, formatWorldInspection } from 'blecsd/debug';
+ *
+ * const info = inspectWorld(world);
+ * console.log(formatWorldInspection(info));
+ * // World Statistics
+ * // ────────────────
+ * // Entities: 42
+ * // Components:
+ * //   Position: 38
+ * //   Dimensions: 35
+ * //   ...
+ * ```
+ */
+declare function formatWorldInspection(inspection: WorldInspection): string;
+/**
+ * Enables or disables system timing tracking.
+ *
+ * When enabled, system execution times are tracked and can be retrieved
+ * via getPerformanceStats().
+ *
+ * @param enabled - Whether to enable timing
+ *
+ * @example
+ * ```typescript
+ * import { enableSystemTiming, getPerformanceStats } from 'blecsd/debug';
+ *
+ * // Enable timing
+ * enableSystemTiming(true);
+ *
+ * // Run game loop...
+ *
+ * // Get stats
+ * const stats = getPerformanceStats(world, loop);
+ * console.log(stats.systemTimings);
+ * ```
+ */
+declare function enableSystemTiming(enabled: boolean): void;
+/**
+ * Checks if system timing is enabled.
+ */
+declare function isSystemTimingEnabled(): boolean;
+/**
+ * Records system execution time.
+ * Called internally by timed system wrappers.
+ *
+ * @param systemName - Name of the system
+ * @param timeMs - Execution time in milliseconds
+ * @internal
+ */
+declare function recordSystemTime(systemName: string, timeMs: number): void;
+/**
+ * Wraps a system function with timing instrumentation.
+ *
+ * @param name - Name for the system (used in timing reports)
+ * @param system - The system function to wrap
+ * @returns Wrapped system that records execution time
+ *
+ * @example
+ * ```typescript
+ * import { timedSystem } from 'blecsd/debug';
+ *
+ * const movementSystem = timedSystem('movement', (world) => {
+ *   // movement logic
+ *   return world;
+ * });
+ *
+ * // Register the timed system
+ * loop.registerSystem(LoopPhase.UPDATE, movementSystem);
+ * ```
+ */
+declare function timedSystem<T extends (world: World) => World>(name: string, system: T): T;
+/**
+ * Gets the current system timing data.
+ * Returns average time per call for each system.
+ *
+ * @returns Map of system name to average time in milliseconds
+ */
+declare function getSystemTimings(): Record<string, number>;
+/**
+ * Resets all system timing data.
+ */
+declare function resetSystemTimings(): void;
+/**
+ * Resets the performance stats cache.
+ * Useful for testing.
+ * @internal
+ */
+declare function resetPerformanceStatsCache(): void;
+/**
+ * Gets current performance statistics.
+ *
+ * @param world - The ECS world
+ * @param loop - Optional game loop for frame stats
+ * @returns Performance statistics
+ *
+ * @example
+ * ```typescript
+ * import { getPerformanceStats } from 'blecsd/debug';
+ *
+ * const stats = getPerformanceStats(world, loop);
+ * console.log(`FPS: ${stats.fps}`);
+ * console.log(`Entities: ${stats.entityCount}`);
+ * console.log(`Memory: ${stats.memoryUsageMB?.toFixed(1)}MB`);
+ * ```
+ */
+declare function getPerformanceStats(world: World, loop?: {
+    getStats(): {
+        fps: number;
+        frameTime: number;
+        frameCount: number;
+        runningTime: number;
+    };
+}): PerformanceStats;
+/**
+ * Debug bounds drawing state.
+ */
+interface DebugBoundsState {
+    enabled: boolean;
+    showHitboxes: boolean;
+    showPadding: boolean;
+    showMargins: boolean;
+    color: number;
+}
+/**
+ * Enables or disables debug bounds visualization.
+ *
+ * When enabled, entity hitboxes and bounds are drawn as colored outlines.
+ * This is useful for debugging layout and collision issues.
+ *
+ * @param enabled - Whether to enable debug bounds
+ * @param options - Optional configuration
+ *
+ * @example
+ * ```typescript
+ * import { enableDebugBounds } from 'blecsd/debug';
+ *
+ * // Enable with default settings
+ * enableDebugBounds(true);
+ *
+ * // Enable with custom color
+ * enableDebugBounds(true, { color: 0xffff0000 }); // Red
+ * ```
+ */
+declare function enableDebugBounds(enabled: boolean, options?: {
+    showHitboxes?: boolean;
+    showPadding?: boolean;
+    showMargins?: boolean;
+    color?: number;
+}): void;
+/**
+ * Checks if debug bounds are enabled.
+ */
+declare function isDebugBoundsEnabled(): boolean;
+/**
+ * Gets debug bounds configuration.
+ */
+declare function getDebugBoundsConfig(): Readonly<DebugBoundsState>;
+/**
+ * Gets entities that should have debug bounds drawn.
+ * Returns entities with Position and Dimensions components.
+ *
+ * @param world - The ECS world
+ * @returns Array of entities to draw bounds for
+ */
+declare function getDebugBoundsEntities(world: World): Entity[];
+/**
+ * Gets a debug summary of an entity as a single line.
+ *
+ * @param world - The ECS world
+ * @param eid - The entity to summarize
+ * @returns Single-line summary string
+ *
+ * @example
+ * ```typescript
+ * import { getEntitySummary } from 'blecsd/debug';
+ *
+ * console.log(getEntitySummary(world, entity));
+ * // "Entity 1 (MyBox) @ 10,20 [40x10] focused hovered"
+ * ```
+ */
+declare function getEntitySummary(world: World, eid: Entity): string;
+/**
+ * Logs an entity to the console with formatting.
+ *
+ * @param world - The ECS world
+ * @param eid - The entity to log
+ *
+ * @example
+ * ```typescript
+ * import { logEntity } from 'blecsd/debug';
+ *
+ * logEntity(world, entity);
+ * // [DEBUG] Entity 1 (MyBox)
+ * // ├─ Position: x=10, y=20, z=0
+ * // └─ Dimensions: width=40, height=10
+ * ```
+ */
+declare function logEntity(world: World, eid: Entity): void;
+/**
+ * Logs world statistics to the console.
+ *
+ * @param world - The ECS world
+ *
+ * @example
+ * ```typescript
+ * import { logWorld } from 'blecsd/debug';
+ *
+ * logWorld(world);
+ * // [DEBUG] World Statistics
+ * // ────────────────
+ * // Entities: 42
+ * // ...
+ * ```
+ */
+declare function logWorld(world: World): void;
+
+export { type AllocationTracker, type ComponentInfo, type DebugOverlay, type DebugOverlayConfig, type EntityInspection, type FrameRateGraph, KNOWN_COMPONENTS, type LeakWarning, type MemoryDiff, type MemoryProfiler, type MemoryProfilerConfig, type MemorySnapshot, type MiniProfiler, type PerformanceStats, type WorldInspection, createDebugOverlay, createFrameRateGraph, createInputLogger, createMemoryProfiler, createMiniProfiler, enableDebugBounds, enableSystemTiming, formatEntityInspection, formatWorldInspection, getDebugBoundsConfig, getDebugBoundsEntities, getEntitySummary, getPerformanceStats, getSystemTimings, inspectEntity, inspectWorld, isDebugBoundsEnabled, isSystemTimingEnabled, logEntity, logWorld, recordSystemTime, resetPerformanceStatsCache, resetSystemTimings, timedSystem };

package/dist/debug/index.js

@@ -0,0 +1 @@
+export{f as KNOWN_COMPONENTS,b as createDebugOverlay,e as createFrameRateGraph,c as createInputLogger,a as createMemoryProfiler,d as createMiniProfiler,s as enableDebugBounds,k as enableSystemTiming,h as formatEntityInspection,j as formatWorldInspection,u as getDebugBoundsConfig,v as getDebugBoundsEntities,w as getEntitySummary,r as getPerformanceStats,o as getSystemTimings,g as inspectEntity,i as inspectWorld,t as isDebugBoundsEnabled,l as isSystemTimingEnabled,x as logEntity,y as logWorld,m as recordSystemTime,q as resetPerformanceStatsCache,p as resetSystemTimings,n as timedSystem}from'../chunk-TDXJDLY6.js';import'../chunk-OMMJ7B5P.js';import'../chunk-CIK4AMUA.js';import'../chunk-JKVHO4LH.js';import'../chunk-KD55INV7.js';import'../chunk-PSXXMBVJ.js';import'../chunk-LCN2ZITE.js';import'../chunk-FYEBZAWN.js';import'../chunk-W5OU7Z6J.js';import'../chunk-Z4EZERNE.js';import'../chunk-WNG4A3K7.js';import'../chunk-SHUC6JWA.js';import'../chunk-G7GIWWLE.js';import'../chunk-PXXGH3BV.js';import'../chunk-5PELJRUQ.js';