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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
test(tools): a project setting reaches every consumer, or says why not
yhhbcf2fa774d22
diff --git a/package.json b/package.jsonindex 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.mjsnew file mode 100644index 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`);