@nice2dev/game-engine 1.1.5 → 1.1.7

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

@@ -0,0 +1,177 @@
+/**
+ * @file NetworkPrediction.ts
+ * @description Client-side prediction and rollback netcode
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Client-side prediction
+ * - Server reconciliation
+ * - Rollback netcode
+ * - Input buffering
+ * - State interpolation
+ * - Lag compensation
+ */
+export interface InputFrame {
+    frame: number;
+    tick: number;
+    timestamp: number;
+    inputs: PlayerInput[];
+}
+export interface PlayerInput {
+    playerId: string;
+    moveX: number;
+    moveY: number;
+    buttons: number;
+    mouseX?: number;
+    mouseY?: number;
+    sequence: number;
+}
+export interface GameSnapshot {
+    frame: number;
+    tick: number;
+    timestamp: number;
+    entities: EntitySnapshot[];
+    checksum: number;
+}
+export interface EntitySnapshot {
+    id: string;
+    ownerId?: string;
+    position: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    velocity: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    rotation: number;
+    state: Record<string, unknown>;
+}
+export interface PredictionConfig {
+    maxPredictionFrames: number;
+    snapshotBufferSize: number;
+    inputBufferSize: number;
+    reconciliationThreshold: number;
+    interpolationDelay: number;
+    maxRollbackFrames: number;
+    tickRate: number;
+    sendRate: number;
+}
+export interface PredictionStats {
+    predictedFrames: number;
+    rollbacks: number;
+    mispredictions: number;
+    averageRTT: number;
+    jitter: number;
+    packetsLost: number;
+    inputDelay: number;
+}
+export type SimulationFn = (snapshot: GameSnapshot, inputs: PlayerInput[]) => GameSnapshot;
+export declare const DEFAULT_PREDICTION_CONFIG: PredictionConfig;
+export declare class InputBuffer {
+    private buffer;
+    private maxSize;
+    private oldestFrame;
+    private newestFrame;
+    constructor(maxSize?: number);
+    add(frame: InputFrame): void;
+    get(frame: number): InputFrame | undefined;
+    getRange(startFrame: number, endFrame: number): InputFrame[];
+    getNewestFrame(): number;
+    getOldestFrame(): number;
+    clear(): void;
+    size(): number;
+}
+export declare class SnapshotBuffer {
+    private buffer;
+    private maxSize;
+    private oldestFrame;
+    private newestFrame;
+    constructor(maxSize?: number);
+    add(snapshot: GameSnapshot): void;
+    get(frame: number): GameSnapshot | undefined;
+    getClosest(frame: number): GameSnapshot | undefined;
+    getNewestFrame(): number;
+    getOldestFrame(): number;
+    clear(): void;
+    size(): number;
+}
+export declare class StateInterpolator {
+    private buffer;
+    private delay;
+    constructor(buffer: SnapshotBuffer, delay?: number);
+    interpolate(currentTime: number): GameSnapshot | undefined;
+    private interpolateSnapshots;
+    private interpolateEntity;
+    private lerpAngle;
+    setDelay(delay: number): void;
+    getDelay(): number;
+}
+export declare class ClientPrediction {
+    private config;
+    private localInputBuffer;
+    private predictedSnapshots;
+    private serverSnapshots;
+    private interpolator;
+    private simulate;
+    private localPlayerId;
+    private currentFrame;
+    private lastConfirmedFrame;
+    private pendingInputs;
+    private stats;
+    private onRollback?;
+    private onMisprediction?;
+    constructor(config?: Partial<PredictionConfig>);
+    setSimulation(fn: SimulationFn): void;
+    setLocalPlayer(playerId: string): void;
+    addLocalInput(input: Omit<PlayerInput, 'playerId' | 'sequence'>): InputFrame;
+    getPendingInputs(): InputFrame[];
+    acknowledgeInput(sequence: number): void;
+    predict(baseSnapshot: GameSnapshot): GameSnapshot;
+    receiveServerSnapshot(snapshot: GameSnapshot): void;
+    private calculatePredictionError;
+    private rollback;
+    tick(): void;
+    getCurrentFrame(): number;
+    setCurrentFrame(frame: number): void;
+    getLastConfirmedFrame(): number;
+    getInterpolatedState(currentTime: number): GameSnapshot | undefined;
+    setInterpolationDelay(delay: number): void;
+    getStats(): PredictionStats;
+    updateRTT(rtt: number): void;
+    recordPacketLoss(): void;
+    setOnRollback(callback: (fromFrame: number, toFrame: number) => void): void;
+    setOnMisprediction(callback: (frame: number, predicted: GameSnapshot, actual: GameSnapshot) => void): void;
+    reset(): void;
+}
+export declare class LagCompensation {
+    private snapshots;
+    private maxRewindMs;
+    constructor(maxRewindMs?: number);
+    recordSnapshot(snapshot: GameSnapshot): void;
+    rewind(targetTime: number, currentTime: number): GameSnapshot | undefined;
+    hitTest(shooterPos: {
+        x: number;
+        y: number;
+    }, direction: {
+        x: number;
+        y: number;
+    }, maxDistance: number, targetTime: number, currentTime: number): {
+        hit: boolean;
+        entityId?: string;
+        hitPos?: {
+            x: number;
+            y: number;
+        };
+    };
+    setMaxRewind(ms: number): void;
+    clear(): void;
+}
+export declare function createClientPrediction(config?: Partial<PredictionConfig>): ClientPrediction;
+export declare function createLagCompensation(maxRewindMs?: number): LagCompensation;
+export declare function createInputBuffer(maxSize?: number): InputBuffer;
+export declare function createSnapshotBuffer(maxSize?: number): SnapshotBuffer;
+export declare function createStateInterpolator(buffer: SnapshotBuffer, delay?: number): StateInterpolator;
+export declare function calculateChecksum(snapshot: GameSnapshot): number;

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

@@ -0,0 +1,263 @@
+/**
+ * @file ObjectPooling.ts
+ * @description Automatic object pool management for bullets, particles, etc.
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Generic object pooling
+ * - Automatic pool expansion
+ * - Pool warming
+ * - Pool shrinking/compaction
+ * - Multiple pool types
+ * - Statistics tracking
+ * - Async object creation
+ * - Pool groups/categories
+ */
+export interface Poolable {
+    reset(): void;
+    onAcquire?(): void;
+    onRelease?(): void;
+    isActive?: boolean;
+}
+export interface PoolConfig<T> {
+    name: string;
+    factory: () => T;
+    initialSize: number;
+    maxSize: number;
+    growthFactor: number;
+    shrinkThreshold: number;
+    shrinkDelay: number;
+    warmOnCreate: boolean;
+    resetOnRelease: boolean;
+    validateOnAcquire: boolean;
+    validator?: (obj: T) => boolean;
+}
+export interface PoolStats {
+    name: string;
+    totalCreated: number;
+    activeCount: number;
+    availableCount: number;
+    peakUsage: number;
+    acquireCount: number;
+    releaseCount: number;
+    missCount: number;
+    growCount: number;
+    shrinkCount: number;
+    lastUsed: number;
+}
+export interface PoolGroupStats {
+    groupName: string;
+    poolCount: number;
+    totalActive: number;
+    totalAvailable: number;
+    totalMemory: number;
+}
+export declare const DEFAULT_POOL_CONFIG: Omit<PoolConfig<unknown>, 'name' | 'factory'>;
+export declare class ObjectPool<T extends Poolable> {
+    private config;
+    private available;
+    private active;
+    private stats;
+    private shrinkTimer;
+    private lastLowUsageTime;
+    constructor(config: Partial<PoolConfig<T>> & Pick<PoolConfig<T>, 'name' | 'factory'>);
+    /**
+     * Pre-create objects to fill the pool
+     */
+    warm(count: number): void;
+    /**
+     * Acquire an object from the pool
+     */
+    acquire(): T | null;
+    /**
+     * Acquire multiple objects at once
+     */
+    acquireMultiple(count: number): T[];
+    /**
+     * Release an object back to the pool
+     */
+    release(obj: T): void;
+    /**
+     * Release all active objects
+     */
+    releaseAll(): void;
+    /**
+     * Clear the pool completely
+     */
+    clear(): void;
+    /**
+     * Get current statistics
+     */
+    getStats(): PoolStats;
+    /**
+     * Get pool configuration
+     */
+    getConfig(): PoolConfig<T>;
+    /**
+     * Update pool configuration
+     */
+    setConfig(config: Partial<PoolConfig<T>>): void;
+    /**
+     * Check if an object belongs to this pool
+     */
+    contains(obj: T): boolean;
+    /**
+     * Get iterator over active objects
+     */
+    getActive(): IterableIterator<T>;
+    /**
+     * Execute callback for each active object
+     */
+    forEachActive(callback: (obj: T) => void): void;
+    private totalSize;
+    private createObject;
+    private grow;
+    private checkShrink;
+    private shrink;
+    private cancelShrink;
+}
+export declare class PoolManager {
+    private pools;
+    private groups;
+    /**
+     * Create a new pool
+     */
+    createPool<T extends Poolable>(config: Partial<PoolConfig<T>> & Pick<PoolConfig<T>, 'name' | 'factory'>, groupName?: string): ObjectPool<T>;
+    /**
+     * Get an existing pool
+     */
+    getPool<T extends Poolable>(name: string): ObjectPool<T> | undefined;
+    /**
+     * Remove a pool
+     */
+    removePool(name: string): boolean;
+    /**
+     * Acquire from a specific pool
+     */
+    acquire<T extends Poolable>(poolName: string): T | null;
+    /**
+     * Release to a specific pool
+     */
+    release<T extends Poolable>(poolName: string, obj: T): void;
+    /**
+     * Release all objects in a pool
+     */
+    releaseAll(poolName: string): void;
+    /**
+     * Release all objects in all pools
+     */
+    releaseAllPools(): void;
+    /**
+     * Clear a specific pool
+     */
+    clearPool(poolName: string): void;
+    /**
+     * Clear all pools
+     */
+    clearAll(): void;
+    /**
+     * Warm a specific pool
+     */
+    warmPool(poolName: string, count: number): void;
+    /**
+     * Warm all pools to their initial size
+     */
+    warmAllPools(): void;
+    /**
+     * Get stats for a specific pool
+     */
+    getPoolStats(name: string): PoolStats | undefined;
+    /**
+     * Get stats for all pools
+     */
+    getAllStats(): PoolStats[];
+    /**
+     * Get stats for a pool group
+     */
+    getGroupStats(groupName: string): PoolGroupStats | undefined;
+    /**
+     * Get all pool names
+     */
+    getPoolNames(): string[];
+    /**
+     * Get pool names in a group
+     */
+    getGroupPoolNames(groupName: string): string[];
+}
+/**
+ * Simple poolable vector
+ */
+export declare class PoolableVector3 implements Poolable {
+    x: number;
+    y: number;
+    z: number;
+    isActive: boolean;
+    reset(): void;
+    set(x: number, y: number, z: number): this;
+    copy(other: PoolableVector3): this;
+    add(other: PoolableVector3): this;
+    scale(s: number): this;
+    length(): number;
+    normalize(): this;
+}
+/**
+ * Poolable particle
+ */
+export declare class PoolableParticle implements Poolable {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    life: number;
+    maxLife: number;
+    size: number;
+    color: number;
+    alpha: number;
+    rotation: number;
+    rotationSpeed: number;
+    isActive: boolean;
+    reset(): void;
+    update(dt: number): void;
+    get normalizedLife(): number;
+    get isDead(): boolean;
+}
+/**
+ * Poolable bullet/projectile
+ */
+export declare class PoolableBullet implements Poolable {
+    x: number;
+    y: number;
+    z: number;
+    dirX: number;
+    dirY: number;
+    dirZ: number;
+    speed: number;
+    damage: number;
+    ownerId: string;
+    lifetime: number;
+    maxLifetime: number;
+    isActive: boolean;
+    reset(): void;
+    update(dt: number): void;
+    get isExpired(): boolean;
+}
+/**
+ * Poolable generic event
+ */
+export declare class PoolableEvent<T = unknown> implements Poolable {
+    type: string;
+    data: T | null;
+    timestamp: number;
+    handled: boolean;
+    isActive: boolean;
+    reset(): void;
+    init(type: string, data: T): this;
+}
+export declare function createPoolManager(): PoolManager;
+export declare function createObjectPool<T extends Poolable>(config: Partial<PoolConfig<T>> & Pick<PoolConfig<T>, 'name' | 'factory'>): ObjectPool<T>;
+export declare function createVector3Pool(name?: string, initialSize?: number): ObjectPool<PoolableVector3>;
+export declare function createParticlePool(name?: string, initialSize?: number): ObjectPool<PoolableParticle>;
+export declare function createBulletPool(name?: string, initialSize?: number): ObjectPool<PoolableBullet>;
+export declare function createEventPool<T = unknown>(name?: string, initialSize?: number): ObjectPool<PoolableEvent<T>>;

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

@@ -1,86 +1,3 @@
-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;
-    }
-    interface GPU {
-        requestAdapter(options?: {
-            powerPreference?: string;
-        }): Promise<GPUAdapter | null>;
-    }
-    interface Navigator {
-        readonly gpu?: GPU;
-    }
-}
 export interface WebGPUConfig {
     maxWorkGroupSize: number;
     preferredFormat: string;