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 ? ', …' : ''}`,
        );
    }
}

const ALIGN_ALL = 45; // top | bottom | left | right

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`);
        }

        // The Canvas node needs its own Widget stretched to all four edges. It
        // is what keeps the Canvas the size of the screen; without it the Canvas
        // keeps whatever size it was authored at (1280x720 by default) and every
        // widget-stretched child inherits that wrong size. `alignCanvasWithScreen`
        // does NOT do this — it only adjusts the camera.
        const node = objects[canvas.node?.__id__];
        const components = (node?._components ?? []).map((ref) => objects[ref.__id__]);
        const widget = components.find((c) => c && c.__type__ === 'cc.Widget');

        if (!widget) {
            problems.push(
                `${path}: the Canvas node has no cc.Widget, so it will not resize `
                + `to the screen and every stretched child will be the wrong size`,
            );
        } else if (widget._alignFlags !== ALIGN_ALL) {
            problems.push(
                `${path}: the Canvas Widget is not stretched to all four edges `
                + `(alignFlags ${widget._alignFlags}, expected ${ALIGN_ALL})`,
            );
        }
    }
}

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