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(sdk): the optional subsystems are asserted against what ships, not what compiles
esengine50955b8b3187
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex f12258aaa..5ac9f6b43 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 97 beta · 1836 experimental · 3 deprecated+Symbols: 114 public · 97 beta · 1837 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -14408,6 +14408,11 @@ ServicesPlugin(grid: SheetGrid): number```+## shippedOptionalSubsystems — function @experimental+```+(): string[]+```+## shortestAngleDelta — function @experimental```(from: number, to: number): numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex e9fe80a14..34f9b8cb5 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 102 beta · 1855 experimental · 3 deprecated+Symbols: 114 public · 102 beta · 1856 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -14651,6 +14651,11 @@ ServicesPlugin(grid: SheetGrid): number```+## shippedOptionalSubsystems — function @experimental+```+(): string[]+```+## shortestAngleDelta — function @experimental```(from: number, to: number): numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex fd58a81d4..53532ab5f 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 99 beta · 1835 experimental · 3 deprecated+Symbols: 114 public · 99 beta · 1836 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -14413,6 +14413,11 @@ ServicesPlugin(grid: SheetGrid): number```+## shippedOptionalSubsystems — function @experimental+```+(): string[]+```+## shortestAngleDelta — function @experimental```(from: number, to: number): numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 9f6490cca..b75303a4e 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 97 beta · 1857 experimental · 3 deprecated+Symbols: 114 public · 97 beta · 1858 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -14675,6 +14675,11 @@ ServicesPlugin(grid: SheetGrid): number```+## shippedOptionalSubsystems — function @experimental+```+(): string[]+```+## shortestAngleDelta — function @experimental```(from: number, to: number): numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 81dbdff0f..2723a87f2 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 97 beta · 1847 experimental · 3 deprecated+Symbols: 114 public · 97 beta · 1848 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -14436,6 +14436,11 @@ ServicesPlugin(grid: SheetGrid): number```+## shippedOptionalSubsystems — function @experimental+```+(): string[]+```+## shortestAngleDelta — function @experimental```(from: number, to: number): numberdiff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 096c4ba8d..f8f640f91 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -196,6 +196,13 @@ export {// Resource census — how many of X are alive right now// =============================================================================+/**+ * Which optional subsystems this build ships. Diagnostic: a scene needing one+ * that is absent already warns, and this is how a report can name it. Untagged,+ * so it is @experimental — a shape nobody has lived with yet promises nothing.+ */+export { shippedOptionalSubsystems } from './runtime/sceneOptionals';+/** @beta Pre-1.0: the counter set is expected to grow as probes are added. */export {takeCensus, registerCensusProbe, censusProbeIds, collectGarbage,diff --git a/sdk/src/runtime/sceneOptionals.ts b/sdk/src/runtime/sceneOptionals.tsindex f3413909c..1219a47d9 100644--- a/sdk/src/runtime/sceneOptionals.ts+++ b/sdk/src/runtime/sceneOptionals.ts@@ -94,3 +94,25 @@ export const physics3dSupport = (): Physics3DSupport | null => physics3d;/** Null in a build that does not ship video. */export const videoSupport = (): VideoSupport | null => video;++/**+ * Which optional subsystems this BUILD ships, as the seam itself answers it.+ *+ * Exported because the only honest test of that question reads the shipped+ * bundle rather than the source. Every registration here is reached from an+ * entry, and an entry is the one thing a bundler is told to keep — but what the+ * entry reaches was dropped once already, and the SDK's own suite could not see+ * it: it imports `src`, where the wiring was never in doubt.+ *+ * Diagnostic, not a switch. A scene that needs a subsystem this build does not+ * ship already says so in the log; this is how a report can say it too.+ */+export function shippedOptionalSubsystems(): string[] {+ return [+ spine && 'spine',+ dragonBones && 'dragonBones',+ physics && 'physics',+ physics3d && 'physics3d',+ video && 'video',+ ].filter((s): s is string => typeof s === 'string');+}diff --git a/sdk/tests/soak/dist-optionals.test.ts b/sdk/tests/soak/dist-optionals.test.tsnew file mode 100644index 000000000..632c7a395--- /dev/null+++ b/sdk/tests/soak/dist-optionals.test.ts@@ -0,0 +1,38 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The optional subsystems survive bundling — asserted against dist, not src.+ *+ * The same shape as dist-probes: every other test imports `../../src`, where the+ * wiring was never in doubt, and 6,272 of them were green while the SHIPPED+ * bundle registered nothing. The editor's play realm loaded a scene full of+ * rigid bodies and logged "this build ships without the 3D physics runtime".+ *+ * Registration is a call now rather than a module's side effect, which is what+ * makes it survive; this is the gate that says it still does. The lean entry's+ * side of the claim — that it ships NONE of them — is check-entries-install-options'.+ *+ * Skips when dist is absent, because a source-only checkout has nothing to say.+ * CI builds the SDK before running tests, so there it is the real gate.+ */+import { describe, it, expect } from 'vitest';+import { existsSync } from 'node:fs';+import { resolve } from 'node:path';++const DIST = resolve(__dirname, '../../dist/index.js');+const HAS_DIST = existsSync(DIST);++describe.skipIf(!HAS_DIST)('the built SDK', () => {+ /** Content, not load time: importing this bundle is ~1s on its own, and at+ * the 5s default the timeout fired on the import rather than the claim. */+ it('ships every optional subsystem its entry installs', async () => {+ const sdk = await import(DIST) as { shippedOptionalSubsystems: () => string[] };++ expect(typeof sdk.shippedOptionalSubsystems).toBe('function');+ // Named, not counted: a bundler that drops one leaves the others+ // answering, and a length check would still pass.+ expect(sdk.shippedOptionalSubsystems().sort()).toEqual(+ ['dragonBones', 'physics', 'physics3d', 'spine', 'video'],+ );+ }, 30_000);+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex d57936994..d624c21c1 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 = {+ 'test(sdk): the optional subsystems are asserted against what ships, not what compiles':+ { internal: 'A repository test over the built bundle; no creator runs it.' },+'fix(sdk): a subsystem registers by being called, not by being imported':{ note: 'An optional subsystem is installed again in builds where a bundler had dropped it.' },