@nice2dev/game-engine 1.1.5 → 1.1.6

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

@@ -0,0 +1,178 @@
+/**
+ * @file GameSaveSystem.ts
+ * @description Serialization with schema migration for game saves
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Save/load game state
+ * - Schema versioning
+ * - Migration system
+ * - Multiple save slots
+ * - Cloud save support
+ * - Compression
+ * - Encryption
+ * - Auto-save
+ */
+export type SaveFormat = 'json' | 'binary' | 'msgpack';
+export type StorageBackend = 'local' | 'session' | 'indexeddb' | 'cloud' | 'file';
+export interface SaveMetadata {
+    id: string;
+    name: string;
+    slot: number;
+    version: number;
+    schemaVersion: number;
+    createdAt: number;
+    modifiedAt: number;
+    playTime: number;
+    thumbnail?: string;
+    description?: string;
+    tags: string[];
+    checksum: string;
+    size: number;
+    compressed: boolean;
+    encrypted: boolean;
+    cloudSynced: boolean;
+    cloudId?: string;
+}
+export interface SaveData {
+    metadata: SaveMetadata;
+    state: GameSaveState;
+}
+export interface GameSaveState {
+    player: Record<string, unknown>;
+    world: Record<string, unknown>;
+    inventory: Record<string, unknown>;
+    quests: Record<string, unknown>;
+    settings: Record<string, unknown>;
+    custom: Record<string, unknown>;
+}
+export interface SchemaMigration {
+    fromVersion: number;
+    toVersion: number;
+    migrate: (data: GameSaveState) => GameSaveState;
+    description: string;
+}
+export interface SaveConfig {
+    format: SaveFormat;
+    backend: StorageBackend;
+    compress: boolean;
+    encrypt: boolean;
+    encryptionKey?: string;
+    maxSlots: number;
+    autoSaveInterval: number;
+    autoSaveSlot: number;
+    cloudSync: boolean;
+    schemaVersion: number;
+}
+export interface SaveSlot {
+    index: number;
+    isEmpty: boolean;
+    metadata?: SaveMetadata;
+}
+export interface SaveResult {
+    success: boolean;
+    slot: number;
+    metadata?: SaveMetadata;
+    error?: string;
+}
+export interface LoadResult {
+    success: boolean;
+    data?: GameSaveState;
+    metadata?: SaveMetadata;
+    error?: string;
+    migrated: boolean;
+    migratedFrom?: number;
+}
+export interface MigrationResult {
+    success: boolean;
+    fromVersion: number;
+    toVersion: number;
+    migrationsApplied: number;
+    error?: string;
+}
+export declare const DEFAULT_SAVE_CONFIG: SaveConfig;
+export interface IStorageAdapter {
+    save(key: string, data: string): Promise<boolean>;
+    load(key: string): Promise<string | null>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    list(prefix: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+export declare class LocalStorageAdapter implements IStorageAdapter {
+    private prefix;
+    constructor(prefix?: string);
+    save(key: string, data: string): Promise<boolean>;
+    load(key: string): Promise<string | null>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    list(prefix: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+export declare class IndexedDBAdapter implements IStorageAdapter {
+    private dbName;
+    private storeName;
+    private db;
+    constructor(dbName?: string, storeName?: string);
+    private getDB;
+    save(key: string, data: string): Promise<boolean>;
+    load(key: string): Promise<string | null>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    list(_prefix: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+export declare class GameSaveSystem {
+    private config;
+    private adapter;
+    private migrations;
+    private autoSaveTimer;
+    private onSaveStarted?;
+    private onSaveCompleted?;
+    private onLoadStarted?;
+    private onLoadCompleted?;
+    private onAutoSave?;
+    private onMigrationNeeded?;
+    private getGameState?;
+    private setGameState?;
+    constructor(config?: Partial<SaveConfig>);
+    private createAdapter;
+    registerMigration(migration: SchemaMigration): void;
+    private migrate;
+    save(slot: number, name?: string): Promise<SaveResult>;
+    load(slot: number): Promise<LoadResult>;
+    delete(slot: number): Promise<boolean>;
+    getSlots(): Promise<SaveSlot[]>;
+    getSlotMetadata(slot: number): Promise<SaveMetadata | null>;
+    hasSlot(slot: number): Promise<boolean>;
+    getNextEmptySlot(): Promise<number>;
+    startAutoSave(): void;
+    stopAutoSave(): void;
+    triggerAutoSave(): Promise<SaveResult>;
+    quickSave(): Promise<SaveResult>;
+    quickLoad(): Promise<LoadResult>;
+    exportSave(slot: number): Promise<string | null>;
+    importSave(slot: number, exportedData: string): Promise<boolean>;
+    private serialize;
+    private deserialize;
+    private compress;
+    private decompress;
+    private encrypt;
+    private decrypt;
+    private calculateChecksum;
+    private generateId;
+    private createEmptyState;
+    getConfig(): SaveConfig;
+    setConfig(config: Partial<SaveConfig>): void;
+    setAdapter(adapter: IStorageAdapter): void;
+    setOnSaveStarted(callback: (slot: number) => void): void;
+    setOnSaveCompleted(callback: (result: SaveResult) => void): void;
+    setOnLoadStarted(callback: (slot: number) => void): void;
+    setOnLoadCompleted(callback: (result: LoadResult) => void): void;
+    setOnAutoSave(callback: (result: SaveResult) => void): void;
+    setOnMigrationNeeded(callback: (from: number, to: number) => void): void;
+    setGetGameState(callback: () => GameSaveState): void;
+    setSetGameState(callback: (state: GameSaveState) => void): void;
+}
+export declare function createSaveSystem(config?: Partial<SaveConfig>): GameSaveSystem;
+export declare function createMigration(fromVersion: number, toVersion: number, migrate: (data: GameSaveState) => GameSaveState, description?: string): SchemaMigration;

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

@@ -0,0 +1,160 @@
+/**
+ * @file HotReload.ts
+ * @description Live code and asset reload without stopping the game
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Live code reloading
+ * - Asset hot-swap
+ * - State preservation
+ * - Module dependency tracking
+ * - WebSocket file watching
+ * - Graceful error handling
+ * - Rollback on failure
+ */
+export type ReloadableType = 'script' | 'shader' | 'texture' | 'audio' | 'model' | 'animation' | 'prefab' | 'scene' | 'config' | 'localization';
+export type ReloadStrategy = 'replace' | 'patch' | 'full';
+export interface ReloadableAsset {
+    id: string;
+    path: string;
+    type: ReloadableType;
+    version: number;
+    lastModified: number;
+    hash: string;
+    dependencies: string[];
+    dependents: string[];
+}
+export interface ReloadEvent {
+    assetId: string;
+    path: string;
+    type: ReloadableType;
+    oldVersion: number;
+    newVersion: number;
+    timestamp: number;
+    success: boolean;
+    error?: string;
+    duration: number;
+}
+export interface ModuleState {
+    id: string;
+    state: Record<string, unknown>;
+    exports: Record<string, unknown>;
+}
+export interface HotReloadConfig {
+    enabled: boolean;
+    watchPaths: string[];
+    excludePatterns: string[];
+    debounceMs: number;
+    retryAttempts: number;
+    preserveState: boolean;
+    rollbackOnError: boolean;
+    serverUrl?: string;
+    autoConnect: boolean;
+}
+export interface FileChangeEvent {
+    path: string;
+    type: 'add' | 'change' | 'delete';
+    timestamp: number;
+}
+export interface ReloadResult {
+    success: boolean;
+    assetId: string;
+    reloadedAssets: string[];
+    preservedState: boolean;
+    rollback: boolean;
+    error?: string;
+    duration: number;
+}
+export declare const DEFAULT_HOT_RELOAD_CONFIG: HotReloadConfig;
+export declare class ModuleRegistry {
+    private modules;
+    private states;
+    private loaders;
+    registerModule(asset: ReloadableAsset): void;
+    unregisterModule(id: string): void;
+    getModule(id: string): ReloadableAsset | undefined;
+    getModuleByPath(path: string): ReloadableAsset | undefined;
+    getAllModules(): ReloadableAsset[];
+    getDependents(id: string): string[];
+    saveState(id: string, state: Record<string, unknown>, exports: Record<string, unknown>): void;
+    getState(id: string): ModuleState | undefined;
+    clearState(id: string): void;
+    registerLoader(type: ReloadableType, loader: (path: string) => Promise<unknown>): void;
+    getLoader(type: ReloadableType): ((path: string) => Promise<unknown>) | undefined;
+}
+export declare class FileWatcher {
+    private config;
+    private ws;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private debounceTimers;
+    private onFileChange?;
+    private onConnected?;
+    private onDisconnected?;
+    private onError?;
+    constructor(config: HotReloadConfig);
+    connect(): void;
+    disconnect(): void;
+    private attemptReconnect;
+    private sendWatchConfig;
+    private handleFileChange;
+    private isExcluded;
+    setOnFileChange(callback: (event: FileChangeEvent) => void): void;
+    setOnConnected(callback: () => void): void;
+    setOnDisconnected(callback: () => void): void;
+    setOnError(callback: (error: Error) => void): void;
+    isConnected(): boolean;
+}
+export declare class HotReloadSystem {
+    private config;
+    private registry;
+    private watcher;
+    private history;
+    private backups;
+    private reloading;
+    private onReloadStarted?;
+    private onReloadCompleted?;
+    private onReloadFailed?;
+    private onStatePreserved?;
+    private onRollback?;
+    constructor(config?: Partial<HotReloadConfig>);
+    private setupWatcher;
+    private handleFileChange;
+    reload(assetId: string): Promise<ReloadResult>;
+    private reloadSingle;
+    private createBackup;
+    private performRollback;
+    private preserveState;
+    private restoreState;
+    private recordEvent;
+    register(id: string, path: string, type: ReloadableType, dependencies?: string[]): void;
+    unregister(id: string): void;
+    registerLoader(type: ReloadableType, loader: (path: string) => Promise<unknown>): void;
+    saveModuleState(id: string, state: Record<string, unknown>, exports: Record<string, unknown>): void;
+    private calculateHash;
+    private delay;
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+    connect(): void;
+    disconnect(): void;
+    isConnected(): boolean;
+    getHistory(): ReloadEvent[];
+    getRecentReloads(count?: number): ReloadEvent[];
+    getStats(): {
+        totalReloads: number;
+        successfulReloads: number;
+        failedReloads: number;
+        averageDuration: number;
+        registeredModules: number;
+    };
+    setOnReloadStarted(callback: (assetId: string) => void): void;
+    setOnReloadCompleted(callback: (result: ReloadResult) => void): void;
+    setOnReloadFailed(callback: (assetId: string, error: Error) => void): void;
+    setOnStatePreserved(callback: (assetId: string, state: ModuleState) => void): void;
+    setOnRollback(callback: (assetId: string) => void): void;
+}
+export declare function createHotReloadSystem(config?: Partial<HotReloadConfig>): HotReloadSystem;
+export declare function createModuleRegistry(): ModuleRegistry;
+export declare function createFileWatcher(config: HotReloadConfig): FileWatcher;

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

@@ -0,0 +1,167 @@
+/**
+ * @file InputRecording.ts
+ * @description Input recording for replays, testing, and demos
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Record all input events
+ * - Playback with speed control
+ * - Seek to any point
+ * - Export/import recordings
+ * - Compression
+ * - Frame-perfect accuracy
+ */
+export type InputEventType = 'keydown' | 'keyup' | 'mousedown' | 'mouseup' | 'mousemove' | 'wheel' | 'gamepadbutton' | 'gamepadaxis' | 'touch';
+export interface RecordedInput {
+    frame: number;
+    time: number;
+    type: InputEventType;
+    data: InputEventData;
+}
+export interface InputEventData {
+    key?: string;
+    code?: string;
+    button?: number;
+    x?: number;
+    y?: number;
+    deltaX?: number;
+    deltaY?: number;
+    gamepadIndex?: number;
+    buttonIndex?: number;
+    axisIndex?: number;
+    value?: number;
+    touchId?: number;
+    touches?: {
+        id: number;
+        x: number;
+        y: number;
+    }[];
+}
+export interface RecordingMetadata {
+    id: string;
+    name: string;
+    description: string;
+    createdAt: number;
+    duration: number;
+    frameCount: number;
+    inputCount: number;
+    version: string;
+    gameVersion: string;
+    seed?: number;
+    checksum: string;
+    tags: string[];
+}
+export interface Recording {
+    metadata: RecordingMetadata;
+    inputs: RecordedInput[];
+    initialState?: Record<string, unknown>;
+}
+export interface RecordingConfig {
+    maxDuration: number;
+    maxInputs: number;
+    captureMouseMove: boolean;
+    captureMouseMoveInterval: number;
+    compress: boolean;
+    recordSeed: boolean;
+}
+export type PlaybackState = 'stopped' | 'playing' | 'paused' | 'seeking';
+export interface PlaybackStatus {
+    state: PlaybackState;
+    currentFrame: number;
+    currentTime: number;
+    totalFrames: number;
+    totalDuration: number;
+    speed: number;
+    loop: boolean;
+}
+export declare const DEFAULT_RECORDING_CONFIG: RecordingConfig;
+export declare class InputRecorder {
+    private config;
+    private isRecording;
+    private startTime;
+    private currentFrame;
+    private inputs;
+    private initialState?;
+    private lastMouseMoveTime;
+    private seed?;
+    private handlers;
+    private onRecordingStarted?;
+    private onRecordingStopped?;
+    private onInputRecorded?;
+    constructor(config?: Partial<RecordingConfig>);
+    start(initialState?: Record<string, unknown>, seed?: number): void;
+    stop(): Recording | null;
+    tick(): void;
+    private attachEventListeners;
+    private detachEventListeners;
+    private recordKeyboard;
+    private recordMouse;
+    private recordMouseMove;
+    private recordWheel;
+    recordGamepadButton(gamepadIndex: number, buttonIndex: number, pressed: boolean): void;
+    recordGamepadAxis(gamepadIndex: number, axisIndex: number, value: number): void;
+    private recordInput;
+    private createRecording;
+    private generateId;
+    private calculateChecksum;
+    private compressInputs;
+    isActive(): boolean;
+    getCurrentFrame(): number;
+    getInputCount(): number;
+    getDuration(): number;
+    setOnRecordingStarted(callback: () => void): void;
+    setOnRecordingStopped(callback: (recording: Recording) => void): void;
+    setOnInputRecorded(callback: (input: RecordedInput) => void): void;
+}
+export declare class InputPlayer {
+    private recording;
+    private state;
+    private currentFrame;
+    private currentTime;
+    private speed;
+    private loop;
+    private inputIndex;
+    private startTime;
+    private decompressedInputs;
+    private onPlaybackStarted?;
+    private onPlaybackStopped?;
+    private onPlaybackPaused?;
+    private onPlaybackResumed?;
+    private onPlaybackComplete?;
+    private onInputPlayed?;
+    private dispatchInput?;
+    load(recording: Recording): void;
+    private decompressInputs;
+    play(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    reset(): void;
+    update(deltaTime?: number): RecordedInput[];
+    tick(): RecordedInput[];
+    seekToFrame(frame: number): void;
+    seekToTime(time: number): void;
+    seekToPercent(percent: number): void;
+    setSpeed(speed: number): void;
+    getSpeed(): number;
+    setLoop(loop: boolean): void;
+    isLooping(): boolean;
+    getStatus(): PlaybackStatus;
+    getProgress(): number;
+    isPlaying(): boolean;
+    isPaused(): boolean;
+    isStopped(): boolean;
+    setInputDispatcher(dispatcher: (input: RecordedInput) => void): void;
+    setOnPlaybackStarted(callback: () => void): void;
+    setOnPlaybackStopped(callback: () => void): void;
+    setOnPlaybackPaused(callback: () => void): void;
+    setOnPlaybackResumed(callback: () => void): void;
+    setOnPlaybackComplete(callback: () => void): void;
+    setOnInputPlayed(callback: (input: RecordedInput) => void): void;
+}
+export declare function exportRecording(recording: Recording): string;
+export declare function importRecording(data: string): Recording | null;
+export declare function exportRecordingToFile(recording: Recording, filename?: string): void;
+export declare function importRecordingFromFile(file: File): Promise<Recording | null>;
+export declare function createInputRecorder(config?: Partial<RecordingConfig>): InputRecorder;
+export declare function createInputPlayer(): InputPlayer;

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

@@ -0,0 +1,147 @@
+/**
+ * @file InterestManagement.ts
+ * @description Spatial partitioning for network optimization
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Spatial hashing
+ * - Area of Interest (AOI)
+ * - Visibility culling
+ * - Priority zones
+ * - Update rate control
+ * - Bandwidth budgeting
+ */
+export interface Vector2 {
+    x: number;
+    y: number;
+}
+export interface Vector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface AABB2D {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface AABB3D {
+    minX: number;
+    minY: number;
+    minZ: number;
+    maxX: number;
+    maxY: number;
+    maxZ: number;
+}
+export interface InterestEntity {
+    id: string;
+    position: Vector2 | Vector3;
+    radius: number;
+    priority: number;
+    tags: string[];
+    alwaysRelevant?: boolean;
+    ownerOnly?: boolean;
+    ownerId?: string;
+    updateRate: number;
+    lastUpdate: number;
+}
+export interface InterestZone {
+    id: string;
+    bounds: AABB2D | AABB3D;
+    priority: number;
+    updateRateMultiplier: number;
+    tags: string[];
+}
+export interface Observer {
+    id: string;
+    position: Vector2 | Vector3;
+    viewRadius: number;
+    viewAngle?: number;
+    viewDirection?: Vector2 | Vector3;
+    priorityEntities: string[];
+    ignoredEntities: string[];
+    bandwidthBudget: number;
+}
+export interface RelevanceResult {
+    entityId: string;
+    relevant: boolean;
+    priority: number;
+    distance: number;
+    updateRate: number;
+    reason: string;
+}
+export interface InterestConfig {
+    cellSize: number;
+    defaultViewRadius: number;
+    defaultUpdateRate: number;
+    minUpdateRate: number;
+    maxUpdateRate: number;
+    distanceFalloff: number;
+    priorityBoost: number;
+    bandwidthPerEntity: number;
+}
+export declare const DEFAULT_INTEREST_CONFIG: InterestConfig;
+export declare class SpatialHash {
+    private cellSize;
+    private cells;
+    private entityPositions;
+    constructor(cellSize?: number);
+    private getCellKey;
+    private getCellCoords;
+    insert(id: string, position: Vector2): void;
+    update(id: string, newPosition: Vector2): void;
+    remove(id: string): void;
+    query(center: Vector2, radius: number): string[];
+    queryBox(bounds: AABB2D): string[];
+    clear(): void;
+    getEntityPosition(id: string): Vector2 | undefined;
+    getCellCount(): number;
+    getEntityCount(): number;
+}
+export declare class InterestManager {
+    private config;
+    private spatialHash;
+    private entities;
+    private zones;
+    private observers;
+    private onEntityBecameRelevant?;
+    private onEntityBecameIrrelevant?;
+    constructor(config?: Partial<InterestConfig>);
+    addEntity(entity: InterestEntity): void;
+    updateEntity(id: string, position: Vector2 | Vector3, properties?: Partial<InterestEntity>): void;
+    removeEntity(id: string): void;
+    getEntity(id: string): InterestEntity | undefined;
+    addZone(zone: InterestZone): void;
+    removeZone(id: string): void;
+    getZone(id: string): InterestZone | undefined;
+    addObserver(observer: Observer): void;
+    updateObserver(id: string, position: Vector2 | Vector3, properties?: Partial<Observer>): void;
+    removeObserver(id: string): void;
+    getObserver(id: string): Observer | undefined;
+    calculateRelevance(observerId: string): RelevanceResult[];
+    private checkRelevance;
+    private calculateDistance;
+    private calculateAngle;
+    private getZonePriority;
+    private isInBounds;
+    private calculateUpdateRate;
+    private applyBandwidthBudget;
+    shouldUpdate(entityId: string, observerId: string, currentTime: number): boolean;
+    markUpdated(entityId: string, currentTime: number): void;
+    getRelevantEntitiesForAllObservers(): Map<string, RelevanceResult[]>;
+    getObserversForEntity(entityId: string): string[];
+    setOnEntityBecameRelevant(callback: (observerId: string, entityId: string) => void): void;
+    setOnEntityBecameIrrelevant(callback: (observerId: string, entityId: string) => void): void;
+    getStats(): {
+        entityCount: number;
+        observerCount: number;
+        zoneCount: number;
+        cellCount: number;
+    };
+    clear(): void;
+}
+export declare function createInterestManager(config?: Partial<InterestConfig>): InterestManager;
+export declare function createSpatialHash(cellSize?: number): SpatialHash;
+export declare function createInterestEntity(id: string, position: Vector2 | Vector3, options?: Partial<InterestEntity>): InterestEntity;
+export declare function createObserver(id: string, position: Vector2 | Vector3, viewRadius: number, options?: Partial<Observer>): Observer;