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.

test(tools): a project setting reaches every consumer, or says why not

yhhbcf2fa774d22
diff --git a/package.json b/package.json
index b51000fd7..6447a6968 100644
--- a/package.json
+++ b/package.json
@@ -17,7 +17,7 @@
"emsdk:setup": "node build-tools/toolchain/setup-emsdk.js",
"asset-meta": "node tools/asset-meta.js",
"migrate-asset-refs": "node tools/migrate-asset-refs.js",
- "verify": "pnpm --filter ./sdk exec tsc --noEmit && node tools/api-surface.mjs --check && node tools/check-cycles.mjs && node tools/check-layers.mjs && node tools/check-workflows.mjs",
+ "verify": "pnpm --filter ./sdk exec tsc --noEmit && node tools/api-surface.mjs --check && node tools/check-cycles.mjs && node tools/check-layers.mjs && node tools/check-project-settings.mjs && node tools/check-workflows.mjs",
"perf": "node tools/perf-guard.mjs --check",
"prepare": "git config core.hooksPath .githooks || true"
},
diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjs
new file mode 100644
index 000000000..64570f89b
--- /dev/null
+++ b/tools/check-project-settings.mjs
@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-project-settings.mjs — a project setting reaches everything, or says why not.
+ *
+ * A setting like "this layer resolves by depth" is only as real as its
+ * least-remembered site. The 2.5D depth mask was declared in the manifest,
+ * parsed, shown in Project Settings, and sent to the play realm — and reached
+ * neither the edit viewport nor ANY exported build, because the editor and the
+ * export each restate the list of settings by hand. It looked right in Play and
+ * shipped wrong, which is the one failure this file exists to make impossible.
+ *
+ * So the derivation lives once (desktop/src/project/runtimeConfig.ts) and this
+ * checks that every field of it is actually carried by each consumer:
+ *
+ * parse the manifest reader (format.ts) has a branch for the feature — that
+ * reader is a WHITELIST, so a field that persists and has no branch
+ * looks completely inert
+ * editor applied to the edit session, so authoring shows what ships
+ * play forwarded into the play realm
+ * packaged written into a shipped build
+ *
+ * A field that legitimately cannot reach one of them declares that HERE, with a
+ * reason. The point is not that everything reaches everywhere; it is that a gap
+ * is a sentence somebody wrote, not an omission nobody noticed.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+
+const RUNTIME_CONFIG = 'desktop/src/project/runtimeConfig.ts';
+const FORMAT = 'desktop/src/project/format.ts';
+const STORE = 'desktop/src/project/ProjectStore.ts';
+
+/**
+ * Where each field of RuntimeProjectConfig has to show up, and the reason when
+ * it deliberately does not. `null` = must be carried; a string = a declared gap,
+ * printed by `--list` so the gaps stay visible rather than becoming folklore.
+ */
+const DECLARED_GAPS = {
+ physicsEnabled: {
+ editor: 'edit mode does not simulate — bodies are authored, not stepped',
+ packaged: 'game.config.json has no physics field yet; a shipped build installs '
+ + 'physics only when a scene uses it, so a project that spawns bodies from '
+ + 'script still needs this carried (tracked follow-up)',
+ },
+ physicsConfig: {
+ editor: 'edit mode does not simulate — see physicsEnabled',
+ packaged: 'same follow-up as physicsEnabled: gravity/solver reach Play and not a build',
+ },
+ audioConfig: {
+ packaged: 'the mixer state reaches Play and not a shipped build yet (same '
+ + 'follow-up: PackagedGameConfig has no audio field)',
+ },
+ colorSpace: {
+ editor: 'boot-fixed — shaders compile against it, so the settings page asks '
+ + 'for a reload rather than applying live (EngineHost.resolveColorSpace)',
+ },
+ screenFit: {
+ editor: 'the device preview reads it through projectSeams, not by applying it '
+ + 'to the edit camera (the editor view is a free zoom by design)',
+ },
+ uiThemeColors: {
+ editor: 'applied together with uiTheme (one applyWidgetTheme call takes both)',
+ },
+};
+
+/** The feature branch in the manifest parser each field is read from. */
+const PARSE_KEY = {
+ physicsEnabled: 'p.enabled',
+ physicsConfig: 'physics',
+ audioConfig: 'parseAudioProjectConfig',
+ uiTheme: 'u.theme',
+ uiThemeColors: 'u.colors',
+ ySortLayers: 'r.ySortLayers',
+ depthLayers: 'r.depthLayers',
+ colorSpace: 'r.colorSpace',
+ screenFit: 'r.cameraScaleMode',
+};
+
+/** Field names of the RuntimeProjectConfig interface, in declaration order. */
+function runtimeConfigFields(src) {
+ const body = src.slice(src.indexOf('export interface RuntimeProjectConfig {'));
+ const end = body.indexOf('\n}');
+ return [...body.slice(0, end).matchAll(/^ {2}(\w+):/gm)].map((m) => m[1]);
+}
+
+const runtimeSrc = read(RUNTIME_CONFIG);
+const formatSrc = read(FORMAT);
+const storeSrc = read(STORE);
+const fields = runtimeConfigFields(runtimeSrc);
+
+if (fields.length === 0) {
+ console.error('check-project-settings: could not read RuntimeProjectConfig — has it moved?');
+ process.exit(1);
+}
+
+// The consumers, each as "does this text carry the field". Deliberately textual:
+// the alternative is importing the editor's module graph into a lint script.
+const editorApply = storeSrc.slice(
+ storeSrc.indexOf('private applyEditorRuntimeConfig'),
+ storeSrc.indexOf('private applyEditorRuntimeConfig') + 1200,
+);
+const playPayload = storeSrc.slice(
+ storeSrc.indexOf('playPayload()'),
+ storeSrc.indexOf('audioFeature()'),
+);
+const packagedFields = runtimeSrc.slice(runtimeSrc.indexOf('export function packagedRuntimeFields'));
+
+const inPackagedSlice = (f) => packagedFields.includes(`rc.${f}`);
+const CONSUMERS = {
+ parse: (f) => formatSrc.includes(PARSE_KEY[f] ?? f),
+ editor: (f) => editorApply.includes(`rc.${f}`),
+ // Either named in the payload, or carried by the packaged slice it spreads.
+ play: (f) => playPayload.includes(`rc.${f}`)
+ || (inPackagedSlice(f) && playPayload.includes('packagedRuntimeFields')),
+ packaged: inPackagedSlice,
+};
+
+const problems = [];
+const gaps = [];
+for (const field of fields) {
+ for (const [role, carries] of Object.entries(CONSUMERS)) {
+ const declared = DECLARED_GAPS[field]?.[role];
+ const carried = carries(field);
+ if (declared) {
+ gaps.push(` ${field} → ${role}: ${declared}`);
+ // A declared gap that is now carried anyway is stale bookkeeping, not an error.
+ continue;
+ }
+ if (!carried) {
+ problems.push(
+ `${field} never reaches "${role}". Either carry it there, or declare the gap `
+ + `with a reason in tools/check-project-settings.mjs (DECLARED_GAPS.${field}.${role}).`,
+ );
+ }
+ }
+ // A field nobody parses is a field a manifest can hold and nothing will read.
+ if (!PARSE_KEY[field]) {
+ problems.push(`${field} has no PARSE_KEY entry — say which manifest branch reads it.`);
+ }
+}
+
+if (process.argv.includes('--list')) {
+ console.log(`project settings (${fields.length}): ${fields.join(', ')}`);
+ if (gaps.length) console.log(`declared gaps:\n${gaps.join('\n')}`);
+}
+
+if (problems.length) {
+ console.error('check-project-settings: a project setting does not reach a consumer.\n');
+ for (const p of problems) console.error(` - ${p}`);
+ process.exit(1);
+}
+
+console.log(`check-project-settings: ${fields.length} settings, ${gaps.length} declared gaps — ok`);