fool-cardgame/scripts/check-scenes.mjs

// 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');