Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

6.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  check-render-scenes.mjs — the pixel gates have one list, and it is run.
 *
 * The registry replaced two lists that had drifted both ways. A gate is what
 * stops a third from growing: a scene declared here must load a scene that
 * exists, sit in a tier something runs, and be reachable by name — and CI must
 * get its list from here rather than inlining its own again.
 */
import { existsSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { TIERS, SCENES, scenesAtTier, sceneFileOf, WEBGPU_GAP } from './renderScenes.mjs';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const FIXTURES = path.join(ROOT, 'fixtures');
const WORKFLOW = path.join(ROOT, '.github', 'workflows', 'build.yml');

const problems = [];
const fail = (m) => problems.push(m);

const seen = new Set();
for (const s of SCENES) {
  if (!s.id || /[^a-z0-9-]/.test(s.id)) fail(`"${s.id}" is not a usable scene id (lower-case, digits, dashes)`);
  if (seen.has(s.id)) fail(`"${s.id}" is listed twice — --only would run one and mean the other`);
  seen.add(s.id);
  if (!TIERS.includes(s.tier)) fail(`"${s.id}" has tier "${s.tier}" (have: ${TIERS.join(', ')})`);
  if (!s.env || typeof s.env !== 'object') fail(`"${s.id}" has no env — an empty one is {}, not missing`);

  // A scene path that does not resolve is a check that passes by never drawing
  // the thing it was written for.
  const file = sceneFileOf(s);
  if (file && !existsSync(path.join(FIXTURES, file))) {
    fail(`"${s.id}" loads ${s.env.ESTELLA_VERIFY_SCENE}, which is not under fixtures/`);
  }
  const manifest = s.env.ESTELLA_VERIFY_MANIFEST;
  if (manifest && !existsSync(path.join(FIXTURES, manifest.replace(/^\//, '')))) {
    fail(`"${s.id}" names manifest ${manifest}, which is not under fixtures/`);
  }
  // A scene with no expectation passes by rendering anything at all. A probe, a
  // count, a seam, a counter or a device-loss roundtrip each is one; otherwise
  // rendersOnly has to say why there is none.
  const asserts = s.env.ESTELLA_VERIFY_EXPECT || s.env.ESTELLA_VERIFY_COUNT
    || s.env.ESTELLA_VERIFY_DEVICE_LOSS === 'roundtrip'
    || s.env.ESTELLA_VERIFY_SEAM
    || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_STUDIO || s.env.ESTELLA_VERIFY_SHADING || s.env.ESTELLA_VERIFY_LIGHTING_SPLIT || s.env.ESTELLA_VERIFY_SKIN_WEIGHTS || s.env.ESTELLA_VERIFY_PREVIEW
    || s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS
    || s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_COUNTERS_MIN || s.env.ESTELLA_VERIFY_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE || s.env.ESTELLA_VERIFY_CUTOUT_EDGE || s.env.ESTELLA_VERIFY_MINIFIED || s.env.ESTELLA_VERIFY_TWINS
    || s.env.ESTELLA_VERIFY_DRAW_CALLS || s.env.ESTELLA_VERIFY_NINE_SLICE
    || s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';
  if (!asserts && !s.rendersOnly) {
    fail(`"${s.id}" asserts nothing — give it an ESTELLA_VERIFY_EXPECT, or say in rendersOnly why it has none`);
  }
  if (s.rendersOnly && asserts) fail(`"${s.id}" both probes pixels and says it cannot`);
  if (s.rendersOnly !== undefined && !(typeof s.rendersOnly === 'string' && s.rendersOnly.trim())) {
    fail(`"${s.id}" sets rendersOnly without a reason`);
  }
}

// The oracle scenes are generated from tools/oracle/, next to the numbers they must draw. A hand-edited fixture, or an edit to the
// generator that was never written out, would leave a scene and its expectation describing different frames.
{
  const { ORACLE } = await import('./oracle/index.mjs');
  for (const o of ORACLE) {
    const file = path.join(FIXTURES, 'scenes', `${o.id}.esscene`);
    const want = JSON.stringify(o.doc, null, 1) + String.fromCharCode(10);
    if (!existsSync(file) || readFileSync(file, 'utf8').split(String.fromCharCode(13)).join('') !== want) {
      fail(`"${o.id}" is not what tools/oracle generates — run node tools/make-oracle-scenes.mjs`);
    }
    for (const [name, body] of Object.entries(o.files ?? {})) {
      const extra = path.join(FIXTURES, 'scenes', name), content = JSON.stringify(body, null, 2) + String.fromCharCode(10);
      if (!existsSync(extra) || readFileSync(extra, 'utf8').split(String.fromCharCode(13)).join('') !== content) {
        fail(`"${name}" is not what tools/oracle generates — run node tools/make-oracle-scenes.mjs`);
      }
    }
    if (!o.expect?.length && !o.twins?.pairs?.length && !o.count?.length) fail(`"${o.id}" has no probes`);
  }
}

// CI has to take its list from here. Inlining scene invocations again is exactly
// how the two lists came to disagree in the first place.
if (existsSync(WORKFLOW)) {
  const wf = readFileSync(WORKFLOW, 'utf8');
  if (!wf.includes('tools/verify-render.mjs')) {
    fail('build.yml does not run tools/verify-render.mjs — CI would be back to a list of its own');
  }
  if (/^\s*run_scene\s+\S/m.test(wf)) {
    fail('build.yml still inlines run_scene invocations — the registry is the list');
  }
}

// The convenience scripts are shims over the registry. Letting one carry its own
// env again is how a package.json became the second list. Every manifest that
// declares them is checked — the editor is an optional submodule, so an absent
// one is nothing to check rather than a failure.
const MANIFESTS = ['package.json', path.join('desktop', 'package.json')]
  .filter((rel) => existsSync(path.join(ROOT, rel)));
for (const rel of MANIFESTS) {
  const pkg = JSON.parse(readFileSync(path.join(ROOT, rel), 'utf8'));
  for (const [name, body] of Object.entries(pkg.scripts ?? {})) {
    if (!name.startsWith('verify:render')) continue;
    if (body.includes('render-host/run.mjs')) {
      fail(`${rel} script "${name}" invokes the render host itself — make it a verify-render.mjs shim`);
    }
    const m = /verify-render\.mjs --only (\S+)$/.exec(body ?? '');
    if (m && !seen.has(m[1])) fail(`${rel} script "${name}" names scene "${m[1]}", which the registry does not have`);
  }
}

if (problems.length) {
  console.error('check-render-scenes: the pixel gates do not hold up.\n');
  for (const p of problems) console.error(`  ${p}`);
  process.exit(1);
}

const byTier = TIERS.map((t) => `${t} ${scenesAtTier(t).length}`).join(' / ');
const weak = SCENES.filter((s) => s.rendersOnly);
console.log(`check-render-scenes: ${SCENES.length} pixel gate(s) with a scene CI can find — ok (${byTier})`);
const gpu = SCENES.filter((s) => s.webgpu);
console.log(`  ${gpu.length} declare the second backend: ${WEBGPU_GAP}`);
console.log(`  ${SCENES.length - weak.length} probe pixels; ${weak.length} only assert that something drew:`);
for (const s of weak) console.log(`    ${s.id}: ${s.rendersOnly}`);