// Checks the scenes and prefabs for the mistakes that only show up at runtime, // and that the editor viewport actively hides from you. // // npm run check:scenes // // The one that cost a whole debugging round: a node created through the editor // tool server lands on the DEFAULT layer, but a Canvas camera renders UI_2D // only. The scene view draws every layer, so it looks perfect in the editor and // the build shows nothing but the camera's clear colour. import { readFileSync, readdirSync, statSync } from 'node:fs'; import { join } from 'node:path'; const UI_2D = 33554432; const ROOTS = ['assets/scenes', 'assets/prefabs']; const problems = []; function collect(dir, out = []) { for (const entry of readdirSync(dir)) { const path = join(dir, entry); if (statSync(path).isDirectory()) collect(path, out); else if (path.endsWith('.scene') || path.endsWith('.prefab')) out.push(path); } return out; } /** Scene files are a flat array of objects that reference each other by index. */ function load(path) { try { const parsed = JSON.parse(readFileSync(path, 'utf8')); return Array.isArray(parsed) ? parsed : []; } catch (error) { problems.push(`${path}: could not be parsed — ${error.message}`); return []; } } function checkLayers(path, objects) { const wrong = objects .filter((o) => o && o.__type__ === 'cc.Node' && o._layer !== UI_2D) .map((o) => `${o._name ?? '?'} (layer ${o._layer})`); if (wrong.length > 0) { problems.push( `${path}: ${wrong.length} node(s) are not on the UI_2D layer, so the ` + `Canvas camera will not draw them: ${wrong.slice(0, 6).join(', ')}` + `${wrong.length > 6 ? ', …' : ''}`, ); } } function checkCanvas(path, objects) { const canvases = objects.filter((o) => o && o.__type__ === 'cc.Canvas'); if (path.endsWith('.scene') && canvases.length === 0) { problems.push(`${path}: no cc.Canvas, so nothing 2D will render`); } for (const canvas of canvases) { if (!canvas._cameraComponent) { problems.push(`${path}: a Canvas has no camera assigned`); } } } function checkCameras(path, objects) { for (const camera of objects.filter((o) => o && o.__type__ === 'cc.Camera')) { if (typeof camera._visibility === 'number' && (camera._visibility & UI_2D) === 0) { problems.push(`${path}: a Camera cannot see the UI_2D layer (visibility ${camera._visibility})`); } } } /** Any script property left holding an empty uuid is an unwired inspector slot. */ function checkReferences(path, objects) { for (const object of objects) { if (!object || typeof object !== 'object') continue; const type = object.__type__; // Engine types legitimately leave optional slots empty; our own scripts // are the ones whose every reference is deliberate. if (typeof type !== 'string' || type.startsWith('cc.')) continue; for (const [key, value] of Object.entries(object)) { if (value && typeof value === 'object' && value.__uuid__ === '') { problems.push(`${path}: ${type}.${key} is an empty reference`); } } } } for (const root of ROOTS) { for (const path of collect(root)) { const objects = load(path); checkLayers(path, objects); checkCanvas(path, objects); checkCameras(path, objects); checkReferences(path, objects); } } if (problems.length > 0) { console.error(`Scene problems:\n - ${problems.join('\n - ')}`); process.exit(1); } console.log('scenes OK');