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
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.tsindex 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.tsindex 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): SideMif (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 sodiff --git a/sdk/tests/sideModuleHost.test.ts b/sdk/tests/sideModuleHost.test.tsindex 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();+ }+ });});