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(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.md
index 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): number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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): number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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): number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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): number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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): number
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.' },