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.

fix(sdk): a module a realm never carried is not a failed load

esengine9bca62033f8a
diff --git a/sdk/src/ecs/bridge/nativeSideModules.ts b/sdk/src/ecs/bridge/nativeSideModules.ts
index 915a01033..ca9c9c9a3 100644
--- a/sdk/src/ecs/bridge/nativeSideModules.ts
+++ b/sdk/src/ecs/bridge/nativeSideModules.ts
@@ -21,7 +21,7 @@
* whose first call is a TypeError.
*/
-import { createSideModuleHost, type SideModuleHost, type SideModule } from '../../sideModules/host';
+import { createSideModuleHost, SideModuleAbsent, type SideModuleHost, type SideModule } from '../../sideModules/host';
import { SPINE_VERSIONS, spineModuleId, type SideModuleId } from '../../sideModules/registry';
import { log } from '../../util/logger';
import { createNativeHeap, type NativeHeap } from './nativeHeap';
@@ -149,7 +149,8 @@ export function createNativeSideModules(
return createSideModuleHost(async (_descriptor, id): Promise<SideModule> => {
const probe = NATIVE_SIDE_MODULE_PROBES[id];
if (!probe) {
- throw new Error(`[native] "${id}" is not compiled into this host`);
+ throw new SideModuleAbsent(id, 'a native host has no side modules beyond the '
+ + 'subsystems it compiles in (KTX2, for one, is decoded in C++)');
}
if (typeof scope[probe] !== 'function') {
throw new Error(
diff --git a/sdk/src/sideModules/host.ts b/sdk/src/sideModules/host.ts
index 7d06d46a1..ca2c8f7fc 100644
--- a/sdk/src/sideModules/host.ts
+++ b/sdk/src/sideModules/host.ts
@@ -26,6 +26,19 @@ export interface SideModuleHost {
/** A realm's transport: turn a descriptor into an instantiated module. */
export type SideModuleInstantiator = (descriptor: SideModuleDescriptor, id: SideModuleId) => Promise<SideModule>;
+/**
+ * Thrown by a transport for a module its realm was never built to carry, rather
+ * than one that should be there and would not load. A native host decodes KTX2 in
+ * C++ and so has no `basis` to give — reported as a failure, that made every game
+ * with a Spine atlas read as a broken boot.
+ */
+export class SideModuleAbsent extends Error {
+ constructor(id: SideModuleId, why: string) {
+ super(`"${id}" is not part of this realm — ${why}`);
+ this.name = 'SideModuleAbsent';
+ }
+}
+
/**
* Build a host over a transport. Caches per id (including failures-as-null so a
* missing artifact isn't refetched every frame). The transport is the only
@@ -39,8 +52,11 @@ export function createSideModuleHost(instantiate: SideModuleInstantiator): SideM
if (cached) return cached;
const descriptor = sideModuleDescriptor(id);
const pending: Promise<SideModule | null> = descriptor
- ? instantiate(descriptor, id).catch((e) => {
- log.error('sidemodule', `failed to load "${id}" (${descriptor.file}) — ${howToFix(id)}`, e);
+ ? instantiate(descriptor, id).catch((e: unknown) => {
+ // Absent BY DESIGN is the answer null already means; only a
+ // module that was meant to be here is a failure to report.
+ if (e instanceof SideModuleAbsent) log.info('sidemodule', e.message);
+ else log.error('sidemodule', `failed to load "${id}" (${descriptor.file}) — ${howToFix(id)}`, e);
return null;
})
// Unknown ids used to be impossible (the type was closed) and so
diff --git a/sdk/tests/sideModuleHost.test.ts b/sdk/tests/sideModuleHost.test.ts
index 567b575d4..2771a161c 100644
--- a/sdk/tests/sideModuleHost.test.ts
+++ b/sdk/tests/sideModuleHost.test.ts
@@ -6,7 +6,7 @@
* WeChat) is exercised by the per-realm export + runtime paths.
*/
import { describe, it, expect, vi } from 'vitest';
-import { createSideModuleHost } from '../src/sideModules/host';
+import { createSideModuleHost, SideModuleAbsent } from '../src/sideModules/host';
import { SIDE_MODULES, SPINE_VERSIONS, spineModuleId } from '../src/sideModules/registry';
describe('side-module registry', () => {
@@ -57,4 +57,23 @@ describe('createSideModuleHost', () => {
expect(await host.acquire('physics')).toBeNull();
expect(instantiate).toHaveBeenCalledTimes(1);
});
+
+ // Both answer null; only one of them is a fault. A native host carries no
+ // `basis` by design, and calling that a failed load made every game with a
+ // Spine atlas print an error and read as a broken boot on a device.
+ it('reports a module the realm never carried without calling it a failure', async () => {
+ const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+ try {
+ const absent = createSideModuleHost(
+ vi.fn().mockRejectedValue(new SideModuleAbsent('basis', 'decoded in C++ here')));
+ expect(await absent.acquire('basis')).toBeNull();
+ expect(spy).not.toHaveBeenCalled();
+
+ const broke = createSideModuleHost(vi.fn().mockRejectedValue(new Error('boom')));
+ expect(await broke.acquire('basis')).toBeNull();
+ expect(spy).toHaveBeenCalled();
+ } finally {
+ spy.mockRestore();
+ }
+ });
});