@nice2dev/game-engine 1.0.5 → 1.0.11

package/dist/cjs/performance/AssetStreaming.js

@@ -0,0 +1,656 @@
+'use strict';
+
+/**
+ * @file AssetStreaming.ts
+ * @description Progressive asset loading with LOD management
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - Progressive/streaming loading
+ * - Level of Detail (LOD) system
+ * - Priority-based loading queue
+ * - Memory budget management
+ * - Distance-based LOD selection
+ * - Asset reference counting
+ * - Async loading with cancellation
+ * - Texture streaming
+ * - Mesh LOD chains
+ */
+// ============================================================
+// Default Configuration
+// ============================================================
+const DEFAULT_STREAMING_CONFIG = {
+    maxConcurrentLoads: 4,
+    maxQueueSize: 100,
+    memoryBudget: {
+        total: 512 * 1024 * 1024, // 512 MB
+        textures: 256 * 1024 * 1024,
+        meshes: 128 * 1024 * 1024,
+        audio: 64 * 1024 * 1024,
+        other: 64 * 1024 * 1024,
+    },
+    lodBias: 0,
+    distanceScale: 1,
+    hysteresis: 0.1,
+    updateInterval: 100, // ms
+    unloadDelay: 5000, // ms
+};
+// ============================================================
+// LOD Calculator
+// ============================================================
+class LODCalculator {
+    constructor(config) {
+        this.config = config;
+    }
+    calculateScreenCoverage(instance, camera) {
+        const dx = instance.position.x - camera.position.x;
+        const dy = instance.position.y - camera.position.y;
+        const dz = instance.position.z - camera.position.z;
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (distance < 0.001) {
+            return 1;
+        }
+        // Approximate screen coverage based on scale and distance
+        const worldSize = instance.scale;
+        const fovRad = (camera.fov * Math.PI) / 180;
+        const screenHeight = 2 * distance * Math.tan(fovRad / 2);
+        const coverage = worldSize / screenHeight;
+        return Math.min(1, coverage * instance.importance);
+    }
+    calculateLODLevel(descriptor, instance, camera, currentLOD) {
+        if (!descriptor.lodLevels || descriptor.lodLevels.length === 0) {
+            return 0;
+        }
+        const coverage = this.calculateScreenCoverage(instance, camera);
+        const dx = instance.position.x - camera.position.x;
+        const dy = instance.position.y - camera.position.y;
+        const dz = instance.position.z - camera.position.z;
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz) * this.config.distanceScale;
+        // Find best LOD based on coverage and distance
+        let bestLOD = 0;
+        for (const lod of descriptor.lodLevels) {
+            if (coverage >= lod.screenCoverage - this.config.lodBias) {
+                bestLOD = lod.level;
+            }
+            if (distance >= lod.distance) {
+                bestLOD = Math.max(bestLOD, lod.level);
+            }
+        }
+        // Apply hysteresis to prevent LOD popping
+        if (Math.abs(bestLOD - currentLOD) === 1) {
+            this.config.hysteresis;
+            if (bestLOD > currentLOD) {
+                // Require more distance/less coverage to increase LOD
+                return currentLOD;
+            }
+        }
+        return bestLOD;
+    }
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+}
+// ============================================================
+// Priority Queue
+// ============================================================
+class PriorityQueue {
+    constructor() {
+        this.items = [];
+    }
+    enqueue(item) {
+        let i = this.items.length;
+        this.items.push(item);
+        // Bubble up
+        while (i > 0) {
+            const parent = Math.floor((i - 1) / 2);
+            if (this.items[parent].priority >= this.items[i].priority) {
+                break;
+            }
+            [this.items[parent], this.items[i]] = [this.items[i], this.items[parent]];
+            i = parent;
+        }
+    }
+    dequeue() {
+        if (this.items.length === 0) {
+            return undefined;
+        }
+        if (this.items.length === 1) {
+            return this.items.pop();
+        }
+        const result = this.items[0];
+        this.items[0] = this.items.pop();
+        // Bubble down
+        let i = 0;
+        while (true) {
+            const left = 2 * i + 1;
+            const right = 2 * i + 2;
+            let largest = i;
+            if (left < this.items.length && this.items[left].priority > this.items[largest].priority) {
+                largest = left;
+            }
+            if (right < this.items.length && this.items[right].priority > this.items[largest].priority) {
+                largest = right;
+            }
+            if (largest === i) {
+                break;
+            }
+            [this.items[i], this.items[largest]] = [this.items[largest], this.items[i]];
+            i = largest;
+        }
+        return result;
+    }
+    peek() {
+        return this.items[0];
+    }
+    size() {
+        return this.items.length;
+    }
+    clear() {
+        this.items = [];
+    }
+    remove(predicate) {
+        const index = this.items.findIndex(predicate);
+        if (index === -1) {
+            return false;
+        }
+        this.items.splice(index, 1);
+        // Rebuild heap (simplified, could be optimized)
+        const items = this.items;
+        this.items = [];
+        for (const item of items) {
+            this.enqueue(item);
+        }
+        return true;
+    }
+}
+// ============================================================
+// Asset Streaming Manager
+// ============================================================
+class AssetStreamingManager {
+    constructor(config) {
+        this.config = { ...DEFAULT_STREAMING_CONFIG };
+        // Asset registry
+        this.descriptors = new Map();
+        this.assets = new Map();
+        // Loading queue
+        this.loadQueue = new PriorityQueue();
+        this.activeLoads = new Map();
+        // Memory tracking
+        this.memoryUsage = new Map();
+        // Stats
+        this.stats = {
+            assetsLoaded: 0,
+            assetsStreaming: 0,
+            assetsQueued: 0,
+            memoryUsed: 0,
+            memoryBudget: this.config.memoryBudget.total,
+            loadBandwidth: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+        };
+        // Update timer
+        this.updateTimer = null;
+        this.lastUpdateTime = 0;
+        this.bytesLoadedSinceLastUpdate = 0;
+        // Loaders
+        this.loaders = new Map();
+        if (config) {
+            this.config = { ...this.config, ...config };
+        }
+        this.lodCalculator = new LODCalculator(this.config);
+        this.setupDefaultLoaders();
+    }
+    setupDefaultLoaders() {
+        // Texture loader
+        this.loaders.set('texture', async (url, signal, onProgress) => {
+            const response = await fetch(url, { signal });
+            const total = parseInt(response.headers.get('content-length') ?? '0');
+            const reader = response.body?.getReader();
+            if (!reader) {
+                throw new Error('No response body');
+            }
+            const chunks = [];
+            let loaded = 0;
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                chunks.push(value);
+                loaded += value.length;
+                if (total > 0) {
+                    onProgress(loaded / total);
+                }
+            }
+            const blob = new Blob(chunks);
+            const bitmap = await createImageBitmap(blob);
+            return bitmap;
+        });
+        // Mesh loader (placeholder)
+        this.loaders.set('mesh', async (url, signal, onProgress) => {
+            const response = await fetch(url, { signal });
+            onProgress(0.5);
+            const data = await response.json();
+            onProgress(1);
+            return data;
+        });
+        // Audio loader
+        this.loaders.set('audio', async (url, signal, onProgress) => {
+            const response = await fetch(url, { signal });
+            onProgress(0.5);
+            const buffer = await response.arrayBuffer();
+            onProgress(1);
+            return buffer;
+        });
+        // Data loader
+        this.loaders.set('data', async (url, signal, onProgress) => {
+            const response = await fetch(url, { signal });
+            onProgress(0.5);
+            const data = await response.json();
+            onProgress(1);
+            return data;
+        });
+    }
+    // ─── Registration ──────────────────────────────────────
+    registerAsset(descriptor) {
+        this.descriptors.set(descriptor.id, descriptor);
+        if (descriptor.preload) {
+            this.requestLoad(descriptor.id, descriptor.priority, 0);
+        }
+    }
+    registerAssets(descriptors) {
+        for (const desc of descriptors) {
+            this.registerAsset(desc);
+        }
+    }
+    unregisterAsset(assetId) {
+        this.descriptors.delete(assetId);
+        this.unloadAsset(assetId);
+    }
+    setLoader(type, loader) {
+        this.loaders.set(type, loader);
+    }
+    // ─── Loading ───────────────────────────────────────────
+    requestLoad(assetId, priority = 0, lodLevel = 0, callback, onProgress, onError) {
+        const descriptor = this.descriptors.get(assetId);
+        if (!descriptor) {
+            onError?.(`Asset not registered: ${assetId}`);
+            return;
+        }
+        // Check if already loaded at requested LOD
+        const existing = this.assets.get(assetId);
+        if (existing && existing.state === 'loaded' && existing.currentLOD <= lodLevel) {
+            this.stats.cacheHits++;
+            existing.refCount++;
+            existing.lastUsed = Date.now();
+            callback?.(existing);
+            return;
+        }
+        this.stats.cacheMisses++;
+        // Check queue size
+        if (this.loadQueue.size() >= this.config.maxQueueSize) {
+            // Remove lowest priority item if this is higher priority
+            const lowest = this.loadQueue.peek();
+            if (lowest && priority <= lowest.priority) {
+                onError?.('Load queue full');
+                return;
+            }
+            this.loadQueue.dequeue();
+        }
+        // Add to queue
+        const request = {
+            assetId,
+            priority,
+            lodLevel,
+            callback,
+            onProgress,
+            onError,
+        };
+        this.loadQueue.enqueue(request);
+        this.stats.assetsQueued = this.loadQueue.size();
+        // Start processing queue
+        this.processQueue();
+    }
+    async processQueue() {
+        // Check concurrent load limit
+        while (this.activeLoads.size < this.config.maxConcurrentLoads && this.loadQueue.size() > 0) {
+            const request = this.loadQueue.dequeue();
+            if (!request) {
+                break;
+            }
+            // Skip if already loading
+            if (this.activeLoads.has(request.assetId)) {
+                continue;
+            }
+            this.activeLoads.set(request.assetId, request);
+            this.loadAsset(request);
+        }
+        this.stats.assetsQueued = this.loadQueue.size();
+        this.stats.assetsStreaming = this.activeLoads.size;
+    }
+    async loadAsset(request) {
+        const descriptor = this.descriptors.get(request.assetId);
+        if (!descriptor) {
+            this.activeLoads.delete(request.assetId);
+            request.onError?.(`Asset not found: ${request.assetId}`);
+            return;
+        }
+        // Get or create streaming asset
+        let asset = this.assets.get(request.assetId);
+        if (!asset) {
+            asset = {
+                descriptor,
+                state: 'loading',
+                data: null,
+                currentLOD: request.lodLevel,
+                targetLOD: request.lodLevel,
+                refCount: 0,
+                lastUsed: Date.now(),
+                loadProgress: 0,
+            };
+            this.assets.set(request.assetId, asset);
+        }
+        asset.state = 'loading';
+        asset.targetLOD = request.lodLevel;
+        asset.abortController = new AbortController();
+        // Get URL for LOD level
+        let url = descriptor.url;
+        if (descriptor.lodLevels && descriptor.lodLevels.length > 0) {
+            const lodAsset = descriptor.lodLevels.find((l) => l.level === request.lodLevel);
+            if (lodAsset) {
+                url = lodAsset.url;
+            }
+        }
+        // Get loader
+        const loader = this.loaders.get(descriptor.type);
+        if (!loader) {
+            asset.state = 'error';
+            asset.error = `No loader for type: ${descriptor.type}`;
+            this.activeLoads.delete(request.assetId);
+            request.onError?.(asset.error);
+            this.onLoadError?.(request.assetId, asset.error);
+            return;
+        }
+        try {
+            // Check memory budget
+            const estimatedSize = this.getAssetSize(descriptor, request.lodLevel);
+            if (!this.canAllocate(descriptor.type, estimatedSize)) {
+                // Try to free memory
+                this.freeMemory(estimatedSize);
+                if (!this.canAllocate(descriptor.type, estimatedSize)) {
+                    throw new Error('Insufficient memory budget');
+                }
+            }
+            const startTime = performance.now();
+            const data = await loader(url, asset.abortController.signal, (progress) => {
+                asset.loadProgress = progress;
+                request.onProgress?.(progress);
+            });
+            const loadTime = performance.now() - startTime;
+            this.bytesLoadedSinceLastUpdate += estimatedSize;
+            asset.data = data;
+            asset.state = 'loaded';
+            asset.currentLOD = request.lodLevel;
+            asset.loadProgress = 1;
+            asset.refCount++;
+            asset.lastUsed = Date.now();
+            // Track memory
+            this.addMemoryUsage(descriptor.type, estimatedSize);
+            this.stats.assetsLoaded++;
+            request.callback?.(asset);
+            this.onAssetLoaded?.(asset);
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                asset.state = 'unloaded';
+            }
+            else {
+                asset.state = 'error';
+                asset.error = error.message;
+                request.onError?.(asset.error);
+                this.onLoadError?.(request.assetId, asset.error);
+            }
+        }
+        finally {
+            asset.abortController = undefined;
+            this.activeLoads.delete(request.assetId);
+            this.processQueue();
+        }
+    }
+    cancelLoad(assetId) {
+        const request = this.activeLoads.get(assetId);
+        if (request) {
+            const asset = this.assets.get(assetId);
+            asset?.abortController?.abort();
+            this.activeLoads.delete(assetId);
+        }
+        this.loadQueue.remove((r) => r.assetId === assetId);
+        this.stats.assetsQueued = this.loadQueue.size();
+    }
+    // ─── Unloading ─────────────────────────────────────────
+    releaseAsset(assetId) {
+        const asset = this.assets.get(assetId);
+        if (!asset) {
+            return;
+        }
+        asset.refCount = Math.max(0, asset.refCount - 1);
+        if (asset.refCount === 0 && !asset.descriptor.persistent) {
+            // Schedule unload
+            setTimeout(() => {
+                const current = this.assets.get(assetId);
+                if (current && current.refCount === 0) {
+                    this.unloadAsset(assetId);
+                }
+            }, this.config.unloadDelay);
+        }
+    }
+    unloadAsset(assetId) {
+        const asset = this.assets.get(assetId);
+        if (!asset) {
+            return;
+        }
+        // Cancel any active load
+        asset.abortController?.abort();
+        // Free memory
+        if (asset.state === 'loaded') {
+            const size = this.getAssetSize(asset.descriptor, asset.currentLOD);
+            this.removeMemoryUsage(asset.descriptor.type, size);
+            this.stats.assetsLoaded--;
+        }
+        this.assets.delete(assetId);
+        this.onAssetUnloaded?.(assetId);
+    }
+    unloadUnused() {
+        const now = Date.now();
+        for (const [id, asset] of this.assets) {
+            if (asset.refCount === 0 &&
+                !asset.descriptor.persistent &&
+                now - asset.lastUsed > this.config.unloadDelay) {
+                this.unloadAsset(id);
+            }
+        }
+    }
+    // ─── Memory Management ─────────────────────────────────
+    getAssetSize(descriptor, lodLevel) {
+        if (descriptor.lodLevels) {
+            const lod = descriptor.lodLevels.find((l) => l.level === lodLevel);
+            if (lod) {
+                return lod.size;
+            }
+        }
+        return descriptor.size;
+    }
+    canAllocate(type, size) {
+        const current = this.memoryUsage.get(type) ?? 0;
+        let budget;
+        switch (type) {
+            case 'texture':
+                budget = this.config.memoryBudget.textures;
+                break;
+            case 'mesh':
+                budget = this.config.memoryBudget.meshes;
+                break;
+            case 'audio':
+                budget = this.config.memoryBudget.audio;
+                break;
+            default:
+                budget = this.config.memoryBudget.other;
+        }
+        return current + size <= budget;
+    }
+    addMemoryUsage(type, size) {
+        const current = this.memoryUsage.get(type) ?? 0;
+        this.memoryUsage.set(type, current + size);
+        this.updateTotalMemory();
+    }
+    removeMemoryUsage(type, size) {
+        const current = this.memoryUsage.get(type) ?? 0;
+        this.memoryUsage.set(type, Math.max(0, current - size));
+        this.updateTotalMemory();
+    }
+    updateTotalMemory() {
+        let total = 0;
+        for (const size of this.memoryUsage.values()) {
+            total += size;
+        }
+        this.stats.memoryUsed = total;
+        if (total > this.config.memoryBudget.total * 0.9) {
+            this.onMemoryWarning?.(total, this.config.memoryBudget.total);
+        }
+    }
+    freeMemory(needed) {
+        // Sort assets by priority: unused, oldest, lowest LOD
+        const candidates = Array.from(this.assets.values())
+            .filter((a) => a.state === 'loaded' && !a.descriptor.persistent && a.refCount === 0)
+            .sort((a, b) => {
+            // Prefer older assets
+            return a.lastUsed - b.lastUsed;
+        });
+        let freed = 0;
+        for (const asset of candidates) {
+            if (freed >= needed) {
+                break;
+            }
+            const size = this.getAssetSize(asset.descriptor, asset.currentLOD);
+            this.unloadAsset(asset.descriptor.id);
+            freed += size;
+        }
+    }
+    // ─── LOD Updates ───────────────────────────────────────
+    updateLODs(camera, instances) {
+        const lodUpdates = new Map();
+        for (const instance of instances) {
+            const descriptor = this.descriptors.get(instance.assetId);
+            const asset = this.assets.get(instance.assetId);
+            if (!descriptor || !asset) {
+                continue;
+            }
+            const currentLOD = asset.currentLOD;
+            const newLOD = this.lodCalculator.calculateLODLevel(descriptor, instance, camera, currentLOD);
+            if (newLOD !== currentLOD && !lodUpdates.has(instance.assetId)) {
+                lodUpdates.set(instance.assetId, newLOD);
+            }
+        }
+        // Request LOD changes
+        for (const [assetId, lodLevel] of lodUpdates) {
+            const asset = this.assets.get(assetId);
+            if (asset && asset.state === 'loaded') {
+                this.requestLoad(assetId, asset.descriptor.priority, lodLevel);
+            }
+        }
+    }
+    // ─── Getters ───────────────────────────────────────────
+    getAsset(assetId) {
+        const asset = this.assets.get(assetId);
+        if (asset) {
+            asset.lastUsed = Date.now();
+        }
+        return asset;
+    }
+    getAssetState(assetId) {
+        return this.assets.get(assetId)?.state ?? 'unloaded';
+    }
+    getDescriptor(assetId) {
+        return this.descriptors.get(assetId);
+    }
+    getStats() {
+        return { ...this.stats };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─── Configuration ─────────────────────────────────────
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+        this.lodCalculator.setConfig(this.config);
+        this.stats.memoryBudget = this.config.memoryBudget.total;
+    }
+    // ─── Lifecycle ─────────────────────────────────────────
+    start() {
+        if (this.updateTimer) {
+            return;
+        }
+        this.lastUpdateTime = performance.now();
+        this.updateTimer = setInterval(() => {
+            const now = performance.now();
+            const dt = (now - this.lastUpdateTime) / 1000;
+            this.lastUpdateTime = now;
+            // Update bandwidth stat
+            this.stats.loadBandwidth = this.bytesLoadedSinceLastUpdate / dt;
+            this.bytesLoadedSinceLastUpdate = 0;
+            // Unload unused assets
+            this.unloadUnused();
+        }, this.config.updateInterval);
+    }
+    stop() {
+        if (this.updateTimer) {
+            clearInterval(this.updateTimer);
+            this.updateTimer = null;
+        }
+    }
+    // ─── Callbacks ─────────────────────────────────────────
+    setOnAssetLoaded(callback) {
+        this.onAssetLoaded = callback;
+    }
+    setOnAssetUnloaded(callback) {
+        this.onAssetUnloaded = callback;
+    }
+    setOnMemoryWarning(callback) {
+        this.onMemoryWarning = callback;
+    }
+    setOnLoadError(callback) {
+        this.onLoadError = callback;
+    }
+}
+// ============================================================
+// Factory Functions
+// ============================================================
+function createAssetStreamingManager(config) {
+    return new AssetStreamingManager(config);
+}
+function createAssetDescriptor(id, type, url, size, options = {}) {
+    return {
+        id,
+        type,
+        url,
+        size,
+        priority: options.priority ?? 0,
+        lodLevels: options.lodLevels,
+        mipLevels: options.mipLevels,
+        streamable: options.streamable ?? true,
+        persistent: options.persistent ?? false,
+        preload: options.preload ?? false,
+        tags: options.tags ?? [],
+    };
+}
+function createLODAsset(level, url, size, screenCoverage, distance) {
+    return { level, url, size, screenCoverage, distance };
+}
+
+exports.AssetStreamingManager = AssetStreamingManager;
+exports.DEFAULT_STREAMING_CONFIG = DEFAULT_STREAMING_CONFIG;
+exports.LODCalculator = LODCalculator;
+exports.createAssetDescriptor = createAssetDescriptor;
+exports.createAssetStreamingManager = createAssetStreamingManager;
+exports.createLODAsset = createLODAsset;
+//# sourceMappingURL=AssetStreaming.js.map