@nice2dev/game-engine 0.1.0

package/dist/types/performance/PerformanceAdvanced.d.ts

@@ -0,0 +1,220 @@
+import { EventBus } from '../core/EventBus';
+export interface FrameBudgetConfig {
+    /** Target frame time in ms (default: 16.67 → 60fps). */
+    targetFrameMs: number;
+    /** Budget allocation per subsystem (0-1, must sum to ≤ 1). */
+    allocations: Record<string, number>;
+    /** Warn if total frame time exceeds target by this factor (default: 1.5). */
+    warningThreshold: number;
+    /** Sample window for rolling averages (default: 60 frames). */
+    sampleWindow: number;
+}
+export interface BudgetReport {
+    subsystem: string;
+    budgetMs: number;
+    actualMs: number;
+    overBudget: boolean;
+    utilizationPercent: number;
+}
+export interface FrameBudgetSnapshot {
+    frameNumber: number;
+    totalMs: number;
+    overBudget: boolean;
+    subsystems: BudgetReport[];
+}
+export declare class FrameBudgetManager {
+    readonly events: EventBus;
+    private config;
+    private currentFrame;
+    private history;
+    private frameCount;
+    private startTimes;
+    private rollingTotals;
+    private rollingSubsystems;
+    constructor(config?: Partial<FrameBudgetConfig>);
+    /** Mark the start of a subsystem's work in this frame. */
+    beginSubsystem(name: string): void;
+    /** Mark the end of a subsystem's work in this frame. */
+    endSubsystem(name: string): void;
+    /** Complete the current frame, generate report, advance to next. */
+    endFrame(): FrameBudgetSnapshot;
+    /** Get the average frame time over the rolling window. */
+    getAverageFrameMs(): number;
+    /** Get average time for a specific subsystem. */
+    getSubsystemAverageMs(name: string): number;
+    /** Get latest snapshot. */
+    getLatest(): FrameBudgetSnapshot | null;
+    /** Get the worst-case frame in history. */
+    getWorstFrame(): FrameBudgetSnapshot | null;
+    /** Format a concise budget text report. */
+    formatReport(): string;
+    /** Reset all collected data. */
+    reset(): void;
+}
+export interface MemoryTracker {
+    category: string;
+    count: number;
+    peakCount: number;
+    totalAllocated: number;
+    totalFreed: number;
+}
+export interface MemorySnapshot {
+    timestamp: number;
+    trackers: Map<string, MemoryTracker>;
+    totalActive: number;
+    /** JS heap size in bytes (if available). */
+    heapUsed: number | null;
+    heapTotal: number | null;
+}
+export interface LeakSuspect {
+    category: string;
+    growthRate: number;
+    currentCount: number;
+    windowCount: number;
+    severity: 'low' | 'medium' | 'high';
+}
+export declare class MemoryLeakDetector {
+    readonly events: EventBus;
+    private trackers;
+    private snapshots;
+    private maxSnapshots;
+    private checkIntervalMs;
+    private lastCheckTime;
+    constructor(maxSnapshots?: number, checkIntervalMs?: number);
+    /** Track an allocation (e.g., new entity, texture, sound). */
+    trackAlloc(category: string, count?: number): void;
+    /** Track a deallocation / free. */
+    trackFree(category: string, count?: number): void;
+    /** Take a snapshot of current allocations. */
+    takeSnapshot(): MemorySnapshot;
+    /** Call from game loop — takes periodic snapshots and checks for leaks. */
+    update(): void;
+    /** Analyze snapshots for continuous growth patterns. */
+    detectLeaks(): LeakSuspect[];
+    /** Get current tracker for a category. */
+    getTracker(category: string): MemoryTracker | undefined;
+    /** Get all trackers. */
+    get allTrackers(): MemoryTracker[];
+    /** Format a human-readable leak report. */
+    formatReport(): string;
+    /** Reset all tracking data. */
+    reset(): void;
+}
+export type QualityLevel = 'ultra' | 'high' | 'medium' | 'low' | 'potato';
+export interface AutoLODConfig {
+    /** Target FPS (default: 60). */
+    targetFps: number;
+    /** FPS below which quality downgrades (default: 50). */
+    downgradeThreshold: number;
+    /** FPS above which quality upgrades (default: 58). */
+    upgradeThreshold: number;
+    /** Seconds of stable performance before upgrading (default: 5). */
+    stabilityWindow: number;
+    /** Minimum seconds between quality changes (default: 3). */
+    cooldownSec: number;
+}
+export interface QualitySettings {
+    level: QualityLevel;
+    /** Render scale (0.5 = half res, 1.0 = native). */
+    renderScale: number;
+    /** Max draw distance. */
+    drawDistance: number;
+    /** Shadow quality (0 = off, 1-3 = low-high). */
+    shadowQuality: number;
+    /** Particle multiplier (0-1). */
+    particleMultiplier: number;
+    /** Post-processing enabled. */
+    postProcessing: boolean;
+    /** Physics simulation rate multiplier (0.5 = half, 1.0 = full). */
+    physicsFidelity: number;
+}
+export declare const QUALITY_PRESETS: Record<QualityLevel, QualitySettings>;
+export declare class AutoLODManager {
+    readonly events: EventBus;
+    private config;
+    private currentLevel;
+    private currentSettings;
+    private fpsHistory;
+    private lastChangeTime;
+    private stableAboveSince;
+    constructor(initialLevel?: QualityLevel, config?: Partial<AutoLODConfig>);
+    get level(): QualityLevel;
+    get settings(): Readonly<QualitySettings>;
+    /** Call each frame with current FPS. */
+    update(currentFps: number): void;
+    private downgrade;
+    private upgrade;
+    /** Manually set quality level. */
+    setLevel(level: QualityLevel, now?: number): void;
+    /** Get a quality preset. */
+    getPreset(level: QualityLevel): QualitySettings;
+    private getAverageFps;
+}
+export type WorkerTaskStatus = 'pending' | 'running' | 'done' | 'error';
+export interface WorkerTask<T = unknown> {
+    id: number;
+    type: string;
+    data: unknown;
+    status: WorkerTaskStatus;
+    result: T | null;
+    error: string | null;
+    submittedAt: number;
+    completedAt: number | null;
+}
+export interface WorkerPoolConfig {
+    /** Number of worker threads (default: navigator.hardwareConcurrency - 1). */
+    poolSize: number;
+    /** Maximum queued tasks before rejecting (default: 100). */
+    maxQueueSize: number;
+}
+/**
+ * Abstract worker pool for offloading CPU-heavy tasks.
+ * Concrete implementations provide the actual Worker script.
+ */
+export declare class WorkerPool {
+    readonly events: EventBus;
+    private workers;
+    private busyWorkers;
+    private taskQueue;
+    private activeTasks;
+    private nextTaskId;
+    private config;
+    private workerScriptUrl;
+    constructor(workerScriptUrl: string, config?: Partial<WorkerPoolConfig>);
+    /** Initialize the worker pool. */
+    init(): void;
+    /** Submit a task to the worker pool. Returns a promise resolved when done. */
+    submit<T>(type: string, data: unknown): Promise<T>;
+    private dispatchNext;
+    private handleResult;
+    private handleError;
+    /** Number of idle workers. */
+    get idleCount(): number;
+    /** Number of queued tasks. */
+    get queueSize(): number;
+    /** Terminate all workers. */
+    dispose(): void;
+}
+/** Simple high-resolution timer. */
+export declare class PerfTimer {
+    private marks;
+    mark(name: string): void;
+    measure(startMark: string, endMark?: string): number;
+    clear(): void;
+}
+/** Object pool for reducing garbage collection pressure. */
+export declare class ObjectPool<T> {
+    private pool;
+    private factory;
+    private resetFn;
+    readonly maxSize: number;
+    constructor(factory: () => T, resetFn: (obj: T) => void, maxSize?: number);
+    /** Get an object from the pool (or create a new one). */
+    acquire(): T;
+    /** Return an object to the pool after use. */
+    release(obj: T): void;
+    /** Pre-populate the pool. */
+    prewarm(count: number): void;
+    get available(): number;
+    clear(): void;
+}

package/dist/types/performance/WASMModules.d.ts

@@ -0,0 +1,65 @@
+export interface WASMModuleConfig {
+    wasmUrl?: string;
+    fallbackToJS: boolean;
+    enableSIMD: boolean;
+}
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface AABB {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface CollisionResult {
+    collides: boolean;
+    overlapX: number;
+    overlapY: number;
+    depth: number;
+}
+export interface PathResult {
+    path: Vec2[];
+    cost: number;
+    nodesExplored: number;
+}
+export interface WASMExports {
+    memory: WebAssembly.Memory;
+    aabb_test: (ax: number, ay: number, aw: number, ah: number, bx: number, by: number, bw: number, bh: number) => number;
+    aabb_overlap: (ax: number, ay: number, aw: number, ah: number, bx: number, by: number, bw: number, bh: number, outPtr: number) => void;
+    circle_test: (ax: number, ay: number, ar: number, bx: number, by: number, br: number) => number;
+    vec2_dot: (ax: number, ay: number, bx: number, by: number) => number;
+    vec2_cross: (ax: number, ay: number, bx: number, by: number) => number;
+    vec2_length: (x: number, y: number) => number;
+    vec2_normalize: (x: number, y: number, outPtr: number) => void;
+    astar_init: (width: number, height: number, gridPtr: number) => void;
+    astar_find: (sx: number, sy: number, tx: number, ty: number, outPtr: number) => number;
+    batch_aabb_test: (aabbsPtr: number, count: number, outPtr: number) => number;
+    malloc: (size: number) => number;
+    free: (ptr: number) => void;
+}
+export declare class WASMAccelerator {
+    private config;
+    private wasmExports;
+    private initialized;
+    constructor(config?: Partial<WASMModuleConfig>);
+    init(wasmBytes?: ArrayBuffer): Promise<boolean>;
+    get isWASM(): boolean;
+    get ready(): boolean;
+    aabbTest(ax: number, ay: number, aw: number, ah: number, bx: number, by: number, bw: number, bh: number): boolean;
+    aabbOverlap(a: AABB, b: AABB): CollisionResult;
+    circleTest(ax: number, ay: number, ar: number, bx: number, by: number, br: number): boolean;
+    batchAABBTest(aabbs: AABB[]): [number, number][];
+    vec2Dot(ax: number, ay: number, bx: number, by: number): number;
+    vec2Cross(ax: number, ay: number, bx: number, by: number): number;
+    vec2Length(x: number, y: number): number;
+    vec2Normalize(x: number, y: number): Vec2;
+    findPath(grid: number[][], startX: number, startY: number, targetX: number, targetY: number): PathResult;
+    destroy(): void;
+}
+export declare function benchmarkWASMvsJS(accelerator: WASMAccelerator, iterations?: number): Record<string, {
+    wasm: number;
+    js: number;
+    speedup: number;
+}>;

package/dist/types/performance/WebGPUCompute.d.ts

@@ -0,0 +1,164 @@
+declare global {
+    interface GPUBuffer {
+        readonly size: number;
+        readonly usage: number;
+        getMappedRange(): ArrayBuffer;
+        unmap(): void;
+        destroy(): void;
+        mapAsync(mode: number): Promise<void>;
+    }
+    interface GPUDevice {
+        createBuffer(desc: {
+            size: number;
+            usage: number;
+            mappedAtCreation?: boolean;
+        }): GPUBuffer;
+        createShaderModule(desc: {
+            code: string;
+        }): GPUShaderModule;
+        createComputePipeline(desc: {
+            layout: string | GPUPipelineLayout;
+            compute: {
+                module: GPUShaderModule;
+                entryPoint: string;
+            };
+        }): GPUComputePipeline;
+        createCommandEncoder(): GPUCommandEncoder;
+        createBindGroup(desc: {
+            layout: GPUBindGroupLayout;
+            entries: {
+                binding: number;
+                resource: {
+                    buffer: GPUBuffer;
+                };
+            }[];
+        }): GPUBindGroup;
+        readonly queue: GPUQueue;
+        readonly lost: Promise<GPUDeviceLostInfo>;
+        destroy(): void;
+    }
+    interface GPUAdapter {
+        requestDevice(desc?: {
+            requiredLimits?: Record<string, number>;
+        }): Promise<GPUDevice>;
+    }
+    interface GPUComputePipeline {
+        getBindGroupLayout(index: number): GPUBindGroupLayout;
+    }
+    interface GPUShaderModule {
+    }
+    interface GPUPipelineLayout {
+    }
+    interface GPUBindGroupLayout {
+    }
+    interface GPUBindGroup {
+    }
+    interface GPUCommandEncoder {
+        beginComputePass(): GPUComputePassEncoder;
+        copyBufferToBuffer(src: GPUBuffer, srcOffset: number, dst: GPUBuffer, dstOffset: number, size: number): void;
+        finish(): GPUCommandBuffer;
+    }
+    interface GPUComputePassEncoder {
+        setPipeline(pipeline: GPUComputePipeline): void;
+        setBindGroup(index: number, bindGroup: GPUBindGroup): void;
+        dispatchWorkgroups(x: number, y?: number, z?: number): void;
+        end(): void;
+    }
+    interface GPUCommandBuffer {
+    }
+    interface GPUQueue {
+        submit(buffers: GPUCommandBuffer[]): void;
+    }
+    interface GPUDeviceLostInfo {
+        readonly message: string;
+    }
+    namespace GPUBufferUsage {
+        const STORAGE: number;
+        const COPY_SRC: number;
+        const COPY_DST: number;
+        const MAP_READ: number;
+        const UNIFORM: number;
+    }
+    namespace GPUMapMode {
+        const READ: number;
+    }
+    interface GPU {
+        requestAdapter(options?: {
+            powerPreference?: string;
+        }): Promise<GPUAdapter | null>;
+    }
+    interface Navigator {
+        readonly gpu?: GPU;
+    }
+}
+export interface WebGPUConfig {
+    maxWorkGroupSize: number;
+    preferredFormat: string;
+    powerPreference: 'low-power' | 'high-performance';
+}
+export interface ComputeBuffer {
+    gpuBuffer: GPUBuffer | null;
+    size: number;
+    usage: number;
+    data: Float32Array | Uint32Array;
+}
+export interface ComputePipeline {
+    id: string;
+    shaderSource: string;
+    entryPoint: string;
+    workGroupSize: [number, number, number];
+}
+export interface PhysicsBroadphaseResult {
+    pairs: [number, number][];
+    count: number;
+}
+export declare class WebGPUContext {
+    private device;
+    private adapter;
+    private config;
+    private pipelines;
+    constructor(config?: Partial<WebGPUConfig>);
+    init(): Promise<boolean>;
+    get isAvailable(): boolean;
+    getDevice(): GPUDevice;
+    createBuffer(data: Float32Array | Uint32Array, usage: number): GPUBuffer;
+    createComputePipeline(id: string, shaderSource: string, entryPoint?: string): GPUComputePipeline;
+    getPipeline(id: string): GPUComputePipeline | undefined;
+    readBuffer(buffer: GPUBuffer, size: number): Promise<ArrayBuffer>;
+    destroy(): void;
+}
+export declare class GPUPhysicsBroadphase {
+    private ctx;
+    private pipeline;
+    constructor(ctx: WebGPUContext);
+    init(): void;
+    computePairs(aabbs: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    }[]): Promise<PhysicsBroadphaseResult>;
+}
+export declare class GPUParticleSystem {
+    private ctx;
+    private pipeline;
+    private particleBuffer;
+    private maxParticles;
+    constructor(ctx: WebGPUContext, maxParticles?: number);
+    init(): void;
+    update(dt: number, gravity?: {
+        x: number;
+        y: number;
+    }): Promise<void>;
+    readParticles(): Promise<Float32Array>;
+    destroy(): void;
+}
+export declare class GPUPathfinder {
+    private ctx;
+    private pipeline;
+    constructor(ctx: WebGPUContext);
+    init(): void;
+    computeDistanceField(costGrid: number[][], targetX: number, targetY: number, maxIterations?: number): Promise<number[][]>;
+}
+export declare function isWebGPUAvailable(): Promise<boolean>;
+export declare function getWebGPUShaders(): Record<string, string>;

package/dist/types/performance/index.d.ts

@@ -0,0 +1 @@
+export * from './Performance';

package/dist/types/physics/PhysicsAdvanced.d.ts

@@ -0,0 +1,148 @@
+import type { Vec2 } from '../core/types';
+export interface FluidConfig {
+    particleCount: number;
+    particleRadius: number;
+    restDensity: number;
+    stiffness: number;
+    viscosity: number;
+    gravity: Vec2;
+    boundaryMin: Vec2;
+    boundaryMax: Vec2;
+    smoothingRadius: number;
+    timeStep: number;
+    surfaceTension: number;
+    colorMode: 'velocity' | 'density' | 'pressure' | 'solid';
+    renderMode: 'particles' | 'metaballs' | 'mesh';
+}
+export declare const DEFAULT_FLUID_CONFIG: FluidConfig;
+export interface FluidParticle {
+    position: Vec2;
+    velocity: Vec2;
+    acceleration: Vec2;
+    density: number;
+    pressure: number;
+    mass: number;
+}
+export declare function createFluidParticles(config: FluidConfig): FluidParticle[];
+export declare function stepFluid(particles: FluidParticle[], config: FluidConfig): void;
+export interface SoftBodyConfig {
+    stiffness: number;
+    damping: number;
+    gravity: Vec2;
+    pressure: number;
+    friction: number;
+    maxStretch: number;
+    iterations: number;
+}
+export declare const DEFAULT_SOFT_BODY: SoftBodyConfig;
+export interface SoftBodyNode {
+    position: Vec2;
+    prevPosition: Vec2;
+    velocity: Vec2;
+    mass: number;
+    pinned: boolean;
+}
+export interface SoftBodySpring {
+    nodeA: number;
+    nodeB: number;
+    restLength: number;
+    stiffness: number;
+    damping: number;
+}
+export interface SoftBody {
+    nodes: SoftBodyNode[];
+    springs: SoftBodySpring[];
+    config: SoftBodyConfig;
+}
+export declare function createSoftBodyCircle(center: Vec2, radius: number, segments: number, config: SoftBodyConfig): SoftBody;
+export declare function stepSoftBody(body: SoftBody, dt: number): void;
+export interface DestructionConfig {
+    maxFragments: number;
+    minFragmentSize: number;
+    explosionForce: number;
+    debrisLifetime: number;
+    cascadeChance: number;
+    cascadeForceMultiplier: number;
+    particlesPerBreak: number;
+}
+export declare const DEFAULT_DESTRUCTION: DestructionConfig;
+export interface DestructibleObject {
+    id: string;
+    health: number;
+    maxHealth: number;
+    position: Vec2;
+    width: number;
+    height: number;
+    material: 'wood' | 'stone' | 'metal' | 'glass' | 'ice';
+    fragments?: Fragment[];
+    destroyed: boolean;
+}
+export interface Fragment {
+    position: Vec2;
+    velocity: Vec2;
+    rotation: number;
+    angularVelocity: number;
+    width: number;
+    height: number;
+    lifetime: number;
+}
+export declare function shatterObject(obj: DestructibleObject, impactPoint: Vec2, force: number, config: DestructionConfig): Fragment[];
+export interface RopeConfig {
+    segmentCount: number;
+    segmentLength: number;
+    gravity: Vec2;
+    damping: number;
+    iterations: number;
+    stiffness: number;
+    breakForce: number;
+    collisionRadius: number;
+}
+export declare const DEFAULT_ROPE_CONFIG: RopeConfig;
+export interface RopePoint {
+    position: Vec2;
+    prevPosition: Vec2;
+    pinned: boolean;
+}
+export interface Rope {
+    points: RopePoint[];
+    config: RopeConfig;
+    broken: boolean;
+    breakIndex: number;
+}
+export declare function createRope(startPos: Vec2, endPos: Vec2, config: RopeConfig): Rope;
+export declare function stepRope(rope: Rope, dt: number): void;
+export interface ClothConfig {
+    width: number;
+    height: number;
+    resolutionX: number;
+    resolutionY: number;
+    gravity: Vec2;
+    damping: number;
+    stiffness: number;
+    tearThreshold: number;
+    windForce: Vec2;
+    windTurbulence: number;
+    iterations: number;
+    pinnedRow: 'top' | 'bottom' | 'none' | 'both';
+}
+export declare const DEFAULT_CLOTH: ClothConfig;
+export interface ClothNode {
+    position: Vec2;
+    prevPosition: Vec2;
+    pinned: boolean;
+}
+export interface ClothLink {
+    a: number;
+    b: number;
+    restLength: number;
+    torn: boolean;
+}
+export interface ClothMesh {
+    nodes: ClothNode[];
+    links: ClothLink[];
+    config: ClothConfig;
+    cols: number;
+    rows: number;
+}
+export declare function createCloth(originX: number, originY: number, config: ClothConfig): ClothMesh;
+export declare function stepCloth(cloth: ClothMesh, dt: number, time: number): void;

package/dist/types/physics/PhysicsEngine2D.d.ts

@@ -0,0 +1,66 @@
+import type { Vec2 } from '../core/types';
+import { EventBus } from '../core/EventBus';
+import type { EntityId } from '../core/types';
+import { World, System } from '../ecs/World';
+export interface CollisionInfo {
+    entityA: EntityId;
+    entityB: EntityId;
+    normal: Vec2;
+    depth: number;
+    point: Vec2;
+}
+export interface RaycastHit {
+    entityId: EntityId;
+    point: Vec2;
+    normal: Vec2;
+    distance: number;
+}
+export declare class PhysicsEngine2D {
+    readonly events: EventBus;
+    gravity: Vec2;
+    private hash;
+    private activeCollisions;
+    private activeTriggers;
+    step(world: World, dt: number): void;
+    private integrateForces;
+    private detectCollisions;
+    private narrowPhase;
+    private resolveCollisions;
+    private emitEvents;
+    raycast(world: World, origin: Vec2, direction: Vec2, maxDistance?: number, layerMask?: number): RaycastHit | null;
+    static testAABBvsAABB(a: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, b: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): boolean;
+    static testCircleVsCircle(a: {
+        x: number;
+        y: number;
+        radius: number;
+    }, b: {
+        x: number;
+        y: number;
+        radius: number;
+    }): boolean;
+    static testAABBvsCircle(aabb: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, circle: {
+        x: number;
+        y: number;
+        radius: number;
+    }): boolean;
+}
+export declare class PhysicsSystem extends System {
+    private engine;
+    constructor(engine: PhysicsEngine2D, priority?: number);
+    fixedUpdate(world: World, dt: number): void;
+}

package/dist/types/physics/index.d.ts

@@ -0,0 +1 @@
+export { PhysicsEngine2D, PhysicsSystem, type CollisionInfo, type RaycastHit, } from './PhysicsEngine2D';