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.

feat(gates): the core runtime's pull on optional subsystems is a ratchet

esenginee359617e6733
diff --git a/tools/baselines/core-carries-options.json b/tools/baselines/core-carries-options.json
new file mode 100644
index 000000000..37bc64edb
--- /dev/null
+++ b/tools/baselines/core-carries-options.json
@@ -0,0 +1,14 @@
+{
+ "edges": [
+ "sdk/src/runtime/runtimeLoader.ts -> ../dragonbones/DragonBonesPlugin",
+ "sdk/src/runtime/runtimeLoader.ts -> ../dragonbones/loadDragonBonesScene",
+ "sdk/src/runtime/runtimeLoader.ts -> ../physics/Physics2DPlugin",
+ "sdk/src/runtime/runtimeLoader.ts -> ../physics3d/Physics3DPlugin",
+ "sdk/src/runtime/runtimeLoader.ts -> ../spine/SpineManager",
+ "sdk/src/runtime/runtimeLoader.ts -> ../spine/SpinePlugin",
+ "sdk/src/runtime/runtimeLoader.ts -> ../spine/loadSpineScene",
+ "sdk/src/runtime/runtimeLoader.ts -> ../video/VideoAPI",
+ "sdk/src/runtime/webAppFactory.ts -> ../dragonbones",
+ "sdk/src/runtime/webAppFactory.ts -> ../spine"
+ ]
+}
diff --git a/tools/check-core-carries-options.mjs b/tools/check-core-carries-options.mjs
new file mode 100644
index 000000000..0a3e87fe6
--- /dev/null
+++ b/tools/check-core-carries-options.mjs
@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-core-carries-options.mjs — the core runtime does not grow new
+ * static dependencies on optional subsystems.
+ *
+ * A mini-game inlines the SDK, and a bundler can only drop a chunk nothing
+ * reaches. `runtime/webAppFactory.ts` and `runtime/runtimeLoader.ts` are in every
+ * package there is, so every subsystem they `import` by value is too: measured on
+ * examples/hello-world, that is 259KB of spine, physics, 3D physics, dragonbones
+ * and video in a project using none of them.
+ *
+ * A ratchet, not a demand for zero — untangling those is the rest of RM-069, and
+ * this exists so the number cannot quietly go up while that is being done. A
+ * `import type` is free (TypeScript erases it) and is not counted.
+ *
+ * node tools/check-core-carries-options.mjs
+ * node tools/check-core-carries-options.mjs --update # bank the current state
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BASELINE = path.join(ROOT, 'tools', 'baselines', 'core-carries-options.json');
+
+/**
+ * The files that are in EVERY package: what a runtime must build an app with,
+ * and what it must load a scene with. Named rather than derived — a reachability
+ * walk would answer the same question and be the thing most likely to break
+ * silently — and a rename fails this loudly below rather than reporting zero.
+ */
+const CORE = ['sdk/src/runtime/webAppFactory.ts', 'sdk/src/runtime/runtimeLoader.ts'];
+
+/**
+ * Which source directory each optional module's code lives in. The IDS are not
+ * ours — they are checked against SIDE_MODULES below, so renaming one there
+ * fails here instead of silently dropping a subsystem from this check.
+ */
+const DIR_OF = {
+ physics: 'physics',
+ physics3d: 'physics3d',
+ dragonbones: 'dragonbones',
+ videodec: 'video',
+ basis: 'basis',
+ 'spine:4.3': 'spine',
+};
+
+const registry = readFileSync(path.join(ROOT, 'sdk/src/sideModules/registry.ts'), 'utf8');
+const declared = new Set(
+ [...registry.matchAll(/^\s{4}'?([a-z0-9:.]+)'?:\s*\{\s*file:/gim)].map((m) => m[1]),
+);
+const unknown = Object.keys(DIR_OF).filter((id) => !declared.has(id));
+if (unknown.length > 0) {
+ console.error('check-core-carries-options: these ids are no longer in SIDE_MODULES —'
+ + ` the map above is stale: ${unknown.join(', ')}`);
+ process.exit(1);
+}
+
+/** Value imports (not `import type`) out of @p file, as source-relative paths. */
+function valueImports(file) {
+ const src = readFileSync(path.join(ROOT, file), 'utf8');
+ const out = [];
+ for (const m of src.matchAll(/^import\s+(type\s+)?([^;]*?)\s*from\s*['"]([^'"]+)['"]/gim)) {
+ if (m[1]) continue;
+ // `import { type X, Y }` still pulls Y; `import { type X }` alone does not.
+ const clause = m[2] ?? '';
+ const named = clause.match(/\{([^}]*)\}/);
+ if (named && named[1].split(',').every((s) => s.trim() === '' || /^type\s/.test(s.trim()))) continue;
+ out.push(m[3]);
+ }
+ return out;
+}
+
+const found = [];
+for (const file of CORE) {
+ if (!existsSync(path.join(ROOT, file))) {
+ console.error(`check-core-carries-options: ${file} is not there — the core moved,`
+ + ' and this check is reporting about a file that no longer exists.');
+ process.exit(1);
+ }
+ for (const spec of valueImports(file)) {
+ for (const [id, dir] of Object.entries(DIR_OF)) {
+ if (new RegExp(`(^|/)\\.\\./${dir}(/|$)`).test(spec)) found.push({ file, dir, spec, id });
+ }
+ }
+}
+
+const key = (r) => `${r.file} -> ${r.spec}`;
+const now = found.map(key).sort();
+
+if (process.argv.includes('--update')) {
+ writeFileSync(BASELINE, `${JSON.stringify({ edges: now }, null, 2)}\n`);
+ console.log(`check-core-carries-options: banked ${now.length} edge(s).`);
+ process.exit(0);
+}
+
+if (!existsSync(BASELINE)) {
+ console.error('check-core-carries-options: no baseline — run with --update once.');
+ process.exit(2);
+}
+const before = new Set(JSON.parse(readFileSync(BASELINE, 'utf8')).edges);
+const added = now.filter((e) => !before.has(e));
+const gone = [...before].filter((e) => !now.includes(e));
+
+if (added.length > 0) {
+ console.error(`check-core-carries-options: ${added.length} new static dependency(ies)`
+ + ' from the core runtime onto an optional subsystem:\n');
+ for (const e of added) console.error(` ${e}`);
+ console.error('\nEvery package carries the core, so it now carries these too. Reach them'
+ + ' through the plugin set the runtime is BUILT with, or bank this with --update'
+ + ' and say why in the commit.');
+ process.exit(1);
+}
+
+const byDir = new Map();
+for (const r of found) byDir.set(r.dir, (byDir.get(r.dir) ?? 0) + 1);
+const spread = [...byDir.entries()].sort((a, b) => b[1] - a[1]).map(([d, n]) => `${d} ×${n}`);
+console.log(`check-core-carries-options: ${now.length} edge(s) onto ${byDir.size} optional`
+ + ` subsystem(s) — ${spread.join(', ')}`
+ + `${gone.length > 0 ? `; ${gone.length} fewer than banked (run --update to keep it down)` : ''}`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 6118ac600..79d33f338 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -135,6 +135,9 @@ export const GATES = [
// compiles src/ and vitest strips types. A ratchet, not a demand for zero —
// except in the net suites, which are held to none.
{ id: 'sdk-test-types', run: 'node tools/check-sdk-test-types.mjs' },
+ // Every mini-game package carries the core runtime, so a subsystem the core
+ // imports is in every package whether the project uses it or not.
+ { id: 'core-carries-options', run: 'node tools/check-core-carries-options.mjs' },
// Replication applies its inbox in arrival order, so reliable+ordered is a
// correctness condition. This compiles the claim: a transport that does not
// make it cannot reach replication.
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index bee7e7ad0..4f5bce13e 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ "feat(gates): the core runtime's pull on optional subsystems is a ratchet":
+ { internal: 'A repository gate over the SDK\'s own imports; no creator runs it.' },
+
'feat(export): a mini-game package says which subsystem each byte came from':
{ internal: 'A field on the export result; no panel shows it yet, so nothing a creator sees.' },