@playcraft/build 0.0.17 → 0.0.19

package/dist/analyzers/scene-asset-collector.js

@@ -259,6 +259,7 @@ function findAssetIds(obj, deps, assets, depth = 0) {
  * 收集间接依赖（材质 → 纹理，模型 → 材质等）
  */
 function collectIndirectDependencies(deps, assets) {
+    const scriptNameIndex = buildScriptNameIndex(assets);
     const visited = new Set();
     const queue = Array.from(deps.directAssets);
     while (queue.length > 0) {
@@ -269,122 +270,105 @@ function collectIndirectDependencies(deps, assets) {
         const asset = assets[assetId];
         if (!asset)
             continue;
-        // 检查不同类型资源的依赖
-        switch (asset.type) {
-            case 'material':
-                // 材质可能引用纹理
-                findAssetIdsInData(asset.data, deps, assets, queue, visited);
-                break;
-            case 'model':
-                // 模型可能引用材质
-                findAssetIdsInData(asset.data, deps, assets, queue, visited);
-                // 检查材质映射
-                if (asset.data?.mapping) {
-                    for (const [meshName, materialId] of Object.entries(asset.data.mapping)) {
-                        if (typeof materialId === 'number' || typeof materialId === 'string') {
-                            const id = String(materialId);
-                            if (assets[id] && !visited.has(id) && !deps.directAssets.has(id)) {
-                                deps.indirectAssets.add(id);
-                                queue.push(id);
-                            }
-                        }
-                    }
-                }
-                break;
-            case 'cubemap':
-                // Cubemap 引用 6 个纹理面（textures 数组）
-                if (asset.data?.textures && Array.isArray(asset.data.textures)) {
-                    for (const textureId of asset.data.textures) {
-                        if (textureId !== null && textureId !== undefined) {
-                            const id = String(textureId);
-                            if (assets[id] && !visited.has(id) && !deps.directAssets.has(id)) {
-                                deps.indirectAssets.add(id);
-                                queue.push(id);
-                            }
+        const foundIds = collectAssetDeps(asset, assets, scriptNameIndex);
+        for (const id of foundIds) {
+            if (!visited.has(id) && !deps.directAssets.has(id) && !deps.indirectAssets.has(id)) {
+                deps.indirectAssets.add(id);
+                queue.push(id);
+            }
+        }
+    }
+}
+/**
+ * 统一的单个资源依赖收集（核心 switch/case）
+ * 根据资源类型精确解析其依赖的其他资源 ID。
+ * 供 collectIndirectDependencies 和 collectAllTemplatesDependencies 共用。
+ */
+function collectAssetDeps(asset, assets, scriptNameIndex) {
+    const foundIds = new Set();
+    const data = asset.data;
+    switch (asset.type) {
+        case 'material':
+            // Material: precisely scan known texture/asset reference fields
+            if (data)
+                collectMaterialDeps(data, assets, foundIds);
+            break;
+        case 'model':
+            // Model: mapping of mesh → material ID
+            if (data?.mapping && typeof data.mapping === 'object') {
+                for (const val of Object.values(data.mapping)) {
+                    if (typeof val === 'object' && val !== null) {
+                        const matVal = val.material;
+                        if (matVal !== null && matVal !== undefined) {
+                            const id = String(matVal);
+                            if (assets[id])
+                                foundIds.add(id);
                         }
                     }
-                }
-                // 还要扫描其他可能的数据
-                findAssetIdsInData(asset.data, deps, assets, queue, visited);
-                break;
-            case 'texture':
-                // 纹理资源通常是叶子节点，但可能引用其他纹理（如合成纹理）
-                findAssetIdsInData(asset.data, deps, assets, queue, visited);
-                break;
-            case 'sprite':
-                // Sprite 可能引用纹理图集
-                if (asset.data?.textureAtlasAsset) {
-                    const id = String(asset.data.textureAtlasAsset);
-                    if (assets[id] && !visited.has(id) && !deps.directAssets.has(id)) {
-                        deps.indirectAssets.add(id);
-                        queue.push(id);
-                    }
-                }
-                findAssetIdsInData(asset.data, deps, assets, queue, visited);
-                break;
-            case 'template':
-                // 模板资产内部的 entities 可能引用其他资产（字体、纹理、脚本等）
-                if (asset.data?.entities) {
-                    for (const entity of Object.values(asset.data.entities)) {
-                        findAssetIdsInData(entity, deps, assets, queue, visited);
+                    else if (typeof val === 'number' || typeof val === 'string') {
+                        const id = String(val);
+                        if (assets[id])
+                            foundIds.add(id);
                     }
                 }
-                break;
-            case 'render':
-                // Render 资源引用 containerAsset (GLB/GLTF 模型)
-                if (asset.data?.containerAsset) {
-                    const id = String(asset.data.containerAsset);
-                    if (assets[id] && !visited.has(id) && !deps.directAssets.has(id)) {
-                        deps.indirectAssets.add(id);
-                        queue.push(id);
+            }
+            // Also scan other data fields for additional references
+            if (data)
+                scanComponentForAssetIds(data, assets, foundIds, 0);
+            break;
+        case 'cubemap':
+            // Cubemap: textures array holds 6 face texture IDs
+            if (data?.textures && Array.isArray(data.textures)) {
+                for (const textureId of data.textures) {
+                    if (textureId !== null && textureId !== undefined) {
+                        const id = String(textureId);
+                        if (assets[id])
+                            foundIds.add(id);
                     }
                 }
-                findAssetIdsInData(asset.data, deps, assets, queue, visited);
-                break;
-            case 'container':
-                // Container 可能引用内部的 render 和 material 资源
-                // 主要是 GLB/GLTF 文件，它本身是独立的
-                findAssetIdsInData(asset.data, deps, assets, queue, visited);
-                break;
-        }
-    }
-}
-/**
- * 在资源数据中查找资源 ID
- */
-function findAssetIdsInData(data, deps, assets, queue, visited) {
-    if (!data)
-        return;
-    // 递归扫描 data 对象
-    const scan = (obj, depth = 0) => {
-        if (depth > 10)
-            return;
-        if (obj === null || obj === undefined)
-            return;
-        if (typeof obj === 'number' || typeof obj === 'string') {
-            const id = String(obj);
-            if (assets[id] && !visited.has(id) && !deps.directAssets.has(id)) {
-                deps.indirectAssets.add(id);
-                queue.push(id);
             }
-        }
-        else if (Array.isArray(obj)) {
-            for (const item of obj) {
-                scan(item, depth + 1);
+            break;
+        case 'texture':
+            // Texture: usually a leaf node, no further deps
+            break;
+        case 'sprite':
+            // Sprite: textureAtlasAsset reference
+            if (data?.textureAtlasAsset) {
+                const id = String(data.textureAtlasAsset);
+                if (assets[id])
+                    foundIds.add(id);
             }
-        }
-        else if (typeof obj === 'object') {
-            for (const [key, value] of Object.entries(obj)) {
-                // 跳过明显不是资源引用的字段
-                if (key === 'name' || key === 'enabled' || key === 'position' ||
-                    key === 'rotation' || key === 'scale') {
-                    continue;
-                }
-                scan(value, depth + 1);
+            break;
+        case 'textureatlas':
+            // TextureAtlas: find associated texture by name + file hash
+            findAssociatedTexture(asset, assets, foundIds);
+            break;
+        case 'template':
+            // Template: precisely parse entities for component/script references
+            collectTemplateDeps(asset, assets, scriptNameIndex, foundIds);
+            break;
+        case 'render':
+            // Render: containerAsset (GLB/GLTF model)
+            if (data?.containerAsset) {
+                const id = String(data.containerAsset);
+                if (assets[id])
+                    foundIds.add(id);
             }
-        }
-    };
-    scan(data);
+            if (data)
+                scanComponentForAssetIds(data, assets, foundIds, 0);
+            break;
+        case 'container':
+            // Container (GLB/GLTF): may reference render and material assets
+            if (data)
+                scanComponentForAssetIds(data, assets, foundIds, 0);
+            break;
+        default:
+            // Other types: generic scan
+            if (data)
+                scanComponentForAssetIds(data, assets, foundIds, 0);
+            break;
+    }
+    return foundIds;
 }
 /**
  * 分析多个场景的资源依赖并合并
@@ -413,7 +397,7 @@ export async function collectScenesAssets(scenes, assets, globalScriptIds) {
     }
     // 收集所有 template 资源及其依赖（含 preload=false 的插件模板如 _Guide、_ExplodeBall）
     // template 通常由 GameplaySystem 等运行时通过 assets.find(name) 按名称动态加载
-    console.log(`\n📦 收集 Template 资源依赖...`);
+    console.log(`\n📦 收集 Template 资源依赖!!!...`);
     const templateDeps = collectAllTemplatesDependencies(assets);
     let templateAssetsCount = 0;
     for (const id of templateDeps) {
@@ -449,14 +433,17 @@ function collectAllTemplatesDependencies(assets) {
     const result = new Set();
     const visited = new Set();
     const queue = [];
-    // 收集所有 template（不再限制 preload=true，修复 "Failed to find plugin template" 错误）
+    // Build script name index for resolving script component references
+    const scriptNameIndex = buildScriptNameIndex(assets);
+    // Collect all templates (no longer restricted to preload=true)
     for (const [assetId, asset] of Object.entries(assets)) {
         if (asset.type === 'template') {
             result.add(assetId);
             queue.push(assetId);
         }
     }
-    // 然后递归收集这些 template 的所有依赖
+    // BFS: recursively collect dependencies of all templates and their transitive deps
+    // Reuses the same collectAssetDeps switch/case as collectIndirectDependencies
     while (queue.length > 0) {
         const assetId = queue.shift();
         if (visited.has(assetId))
@@ -465,58 +452,195 @@ function collectAllTemplatesDependencies(assets) {
         const asset = assets[assetId];
         if (!asset)
             continue;
-        // 扫描资源数据中引用的其他资源 ID
-        const foundIds = new Set();
-        scanForAssetIds(asset, assets, foundIds);
+        const foundIds = collectAssetDeps(asset, assets, scriptNameIndex);
+        // Only log for template-type assets (no nested logging for transitive deps)
+        if (asset.type === 'template' && foundIds.size > 0) {
+            const depDetails = [...foundIds].map(id => {
+                const dep = assets[id];
+                return dep ? `${id}(${dep.type}:${dep.name})` : id;
+            });
+            console.log(`  📦 template "${asset.name}" (${assetId}) → ${foundIds.size} deps: [${depDetails.join(', ')}]`);
+        }
         for (const id of foundIds) {
             if (!result.has(id)) {
                 result.add(id);
-                queue.push(id); // 继续递归收集依赖
+                queue.push(id); // continue BFS for transitive deps
             }
         }
     }
     return result;
 }
 /**
- * 扫描对象中可能的资源 ID 引用
+ * Find the texture asset associated with a textureatlas.
+ * In PlayCanvas, a textureatlas and its source texture are separate assets
+ * linked by having the same name and the same file hash.
  */
-function scanForAssetIds(obj, assets, foundIds, depth = 0) {
-    if (depth > 15)
+function findAssociatedTexture(atlasAsset, assets, foundIds) {
+    const atlasName = atlasAsset.name;
+    const atlasHash = atlasAsset.file?.hash;
+    for (const [assetId, asset] of Object.entries(assets)) {
+        if (asset.type !== 'texture')
+            continue;
+        // Match by name and file hash (both should match)
+        if (atlasHash && asset.file?.hash === atlasHash) {
+            foundIds.add(assetId);
+            return;
+        }
+        // Fallback: match by name if hash is not available
+        if (!atlasHash && asset.name === atlasName) {
+            foundIds.add(assetId);
+            return;
+        }
+    }
+}
+/**
+ * Collect texture dependencies from a PlayCanvas material's data object.
+ * Specifically targets known texture/asset reference fields rather than blind scanning,
+ * to avoid false positives from color arrays, tiling vectors, etc.
+ */
+function collectMaterialDeps(data, assets, foundIds) {
+    // Known material fields that hold asset IDs (texture maps and cubemaps)
+    const textureFields = [
+        'diffuseMap', 'specularMap', 'metalnessMap', 'glossMap',
+        'emissiveMap', 'opacityMap', 'normalMap', 'heightMap',
+        'aoMap', 'lightMap', 'cubeMap', 'sphereMap',
+        'clearCoatMap', 'clearCoatGlossMap', 'clearCoatNormalMap',
+        'diffuseDetailMap', 'normalDetailMap',
+        'sheenMap', 'sheenGlossMap',
+        'msdfMap', // MSDF font atlas texture
+    ];
+    for (const field of textureFields) {
+        const val = data[field];
+        if (val !== null && val !== undefined) {
+            const id = String(val);
+            if (assets[id])
+                foundIds.add(id);
+        }
+    }
+    // Also check cubeMapProjection if it references an asset
+    if (data.cubeMapProjectionBox?.asset) {
+        const id = String(data.cubeMapProjectionBox.asset);
+        if (assets[id])
+            foundIds.add(id);
+    }
+}
+/**
+ * Collect dependencies from a template asset by analyzing its entities structure.
+ * Uses precise parsing of PlayCanvas template data instead of blind recursive scanning.
+ *
+ * Template data structure:
+ *   asset.data.entities = {
+ *     "<resource_id>": {
+ *       name, components: { script: { order, scripts }, element, model, ... },
+ *       template_id, ...
+ *     }
+ *   }
+ */
+function collectTemplateDeps(asset, assets, scriptNameIndex, foundIds) {
+    const entities = asset.data?.entities;
+    if (!entities || typeof entities !== 'object')
+        return;
+    for (const entity of Object.values(entities)) {
+        if (!entity || typeof entity !== 'object')
+            continue;
+        // 1. Nested template reference (template_id)
+        if (entity.template_id) {
+            const tid = String(entity.template_id);
+            if (assets[tid])
+                foundIds.add(tid);
+        }
+        // 2. Parse components
+        if (entity.components && typeof entity.components === 'object') {
+            for (const [compName, compData] of Object.entries(entity.components)) {
+                if (!compData || typeof compData !== 'object')
+                    continue;
+                if (compName === 'script') {
+                    // 2a. Script component: resolve script names → asset IDs via index
+                    collectScriptDepsFromComponent(compData, assets, scriptNameIndex, foundIds);
+                }
+                else {
+                    // 2b. Other components (element, model, sound, sprite, etc.):
+                    //     scan for numeric/string asset IDs in their properties
+                    scanComponentForAssetIds(compData, assets, foundIds, 0);
+                }
+            }
+        }
+    }
+}
+/**
+ * Resolve script names in a script component to asset IDs,
+ * and also scan script attribute values for asset references.
+ */
+function collectScriptDepsFromComponent(scriptComponent, assets, scriptNameIndex, foundIds) {
+    // Collect script names from order + scripts keys
+    const scriptNames = new Set();
+    if (Array.isArray(scriptComponent.order)) {
+        for (const name of scriptComponent.order) {
+            if (typeof name === 'string')
+                scriptNames.add(name);
+        }
+    }
+    if (scriptComponent.scripts && typeof scriptComponent.scripts === 'object') {
+        for (const name of Object.keys(scriptComponent.scripts)) {
+            scriptNames.add(name);
+        }
+    }
+    // Map script names → asset IDs
+    for (const scriptName of scriptNames) {
+        const assetId = scriptNameIndex.get(scriptName);
+        if (assetId && assets[assetId]) {
+            foundIds.add(assetId);
+        }
+    }
+    // Scan script attribute values for asset references
+    // (e.g. asset-type attributes like "fontAsset", "spriteAsset", etc.)
+    if (scriptComponent.scripts && typeof scriptComponent.scripts === 'object') {
+        for (const scriptConfig of Object.values(scriptComponent.scripts)) {
+            if (scriptConfig?.attributes && typeof scriptConfig.attributes === 'object') {
+                scanComponentForAssetIds(scriptConfig.attributes, assets, foundIds, 0);
+            }
+        }
+    }
+}
+/**
+ * Recursively scan a component data object for numeric/string asset ID references.
+ * Skips known non-asset fields (position, rotation, scale, etc.).
+ */
+function scanComponentForAssetIds(obj, assets, foundIds, depth) {
+    if (depth > 10)
         return;
     if (obj === null || obj === undefined)
         return;
     if (typeof obj === 'number') {
         const id = String(obj);
-        if (assets[id]) {
+        if (assets[id])
             foundIds.add(id);
-        }
+        return;
     }
-    else if (typeof obj === 'string') {
-        // 直接检查字符串是否是有效的资源 ID（不再限制为纯数字）
-        if (assets[obj]) {
+    if (typeof obj === 'string') {
+        if (assets[obj])
             foundIds.add(obj);
-        }
+        return;
     }
-    else if (Array.isArray(obj)) {
-        // 跳过坐标/颜色数组（通常是 3 或 4 个小数或小整数）
-        // 资源 ID 通常是大于 10000 的正整数，不会被误跳过
-        if (obj.length <= 4 && obj.every(v => typeof v === 'number' && (!Number.isInteger(v) || // 浮点数（坐标/颜色）
-            (v >= 0 && v < 1000) // 小正整数（颜色分量等）
-        ))) {
+    if (Array.isArray(obj)) {
+        // Skip small numeric arrays (likely vectors / colors, not asset IDs)
+        if (obj.length <= 4 && obj.every(v => typeof v === 'number' && (!Number.isInteger(v) || (v >= 0 && v < 1000)))) {
             return;
         }
         for (const item of obj) {
-            scanForAssetIds(item, assets, foundIds, depth + 1);
+            scanComponentForAssetIds(item, assets, foundIds, depth + 1);
         }
+        return;
     }
-    else if (typeof obj === 'object') {
+    if (typeof obj === 'object') {
         for (const [key, value] of Object.entries(obj)) {
-            // 跳过明显不是资源引用的字段
-            if (['name', 'enabled', 'position', 'rotation', 'scale', 'tags',
-                'children', 'parent', 'resource_id'].includes(key)) {
+            // Skip known non-asset fields
+            if (key === 'name' || key === 'enabled' || key === 'position' ||
+                key === 'rotation' || key === 'scale' || key === 'tags' ||
+                key === 'children' || key === 'parent' || key === 'resource_id') {
                 continue;
             }
-            scanForAssetIds(value, assets, foundIds, depth + 1);
+            scanComponentForAssetIds(value, assets, foundIds, depth + 1);
         }
     }
 }

package/dist/audio-optimizer.d.ts

@@ -0,0 +1,70 @@
+export interface AudioAssetInfo {
+    /** Absolute path to the file */
+    filePath: string;
+    /** Path relative to build directory */
+    relativePath: string;
+    /** File size in bytes */
+    size: number;
+    /** Whether a matching .spectral.json exists */
+    hasSpectral: boolean;
+    /** Spectral JSON size if available */
+    spectralSize?: number;
+    /** Savings by switching to spectral */
+    potentialSavings?: number;
+}
+export interface AudioOptimizationReport {
+    /** All audio files found */
+    audioFiles: AudioAssetInfo[];
+    /** All .spectral.json files found */
+    spectralFiles: string[];
+    /** Total size of all MP3/audio files */
+    totalAudioSize: number;
+    /** Total size if all with spectral were replaced */
+    totalSpectralSize: number;
+    /** Whether SpectralAudioEngine runtime was injected */
+    runtimeInjected: boolean;
+    /** Size of injected runtime (bytes) */
+    runtimeSize: number;
+    /** Net savings from spectral replacement (bytes) */
+    netSavings: number;
+}
+export interface AudioOptimizerOptions {
+    /** Build output directory to scan */
+    buildDir: string;
+    /**
+     * Whether to auto-inject SpectralAudioEngine runtime when spectral files are present.
+     * Defaults to true.
+     */
+    injectRuntime?: boolean;
+    /**
+     * Path to an HTML file to inject the runtime into (e.g. index.html).
+     * If not provided, runtime injection is skipped even if injectRuntime=true.
+     */
+    htmlOutputPath?: string;
+    /** Verbose logging */
+    verbose?: boolean;
+}
+/**
+ * AudioOptimizer — Build-time audio analysis and optimization.
+ *
+ * Scans a build directory for audio files and .spectral.json counterparts.
+ * When spectral files are present, optionally injects the SpectralAudioEngine
+ * runtime (< 3KB) into the output HTML so the browser can synthesize them.
+ *
+ * Usage:
+ *   const optimizer = new AudioOptimizer({ buildDir: './dist', htmlOutputPath: './dist/index.html' });
+ *   const report = await optimizer.optimize();
+ *   console.log(report);
+ */
+export declare class AudioOptimizer {
+    private options;
+    constructor(options: AudioOptimizerOptions);
+    /**
+     * Run the optimizer. Returns a report with audio file details and optimization results.
+     */
+    optimize(): Promise<AudioOptimizationReport>;
+    /**
+     * Print a human-readable summary of the optimization report.
+     */
+    static printReport(report: AudioOptimizationReport): void;
+}