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(assets): a group load names what failed instead of returning an empty bundle

esenginef22c20926c59
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88ddf88b0..851707d4e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Added
+- **A group that failed to load says so instead of handing back an empty bundle.** `Assets.loadGroup` settled every asset and returned whatever survived, so a subpackage that downloaded but staged nothing — or a CDN answering 404 — read exactly like a group that was always empty. It now names the assets that failed, the way a scene preload already did.
+
- **A mini-game's side modules compress too, not just its engine.** Brotli was applied to the engine binary alone, so a package that transcodes KTX2 textures still carried Basis at its full 1.1MB — 27% of WeChat's 4MB main-package cap on its own. They compress on the same switch now, and the loader is told which suffix the build staged instead of spelling `.wasm` itself. Measured on the platformer template: its WeChat package was 108% of the cap and is now 51.5%, with the side modules accounting for 902KB of that.
- **A mini-game says it is starting before it parses the game.** The host's loading indicator only appeared once `initMiniGameRuntime` ran, which is after the entry has required a megabyte of bundle — the longest silent stretch of a cold start. The generated entry now raises it on its first line.
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 2fa47867d..3c78d1749 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -273,6 +273,16 @@ export interface MissingAsset {
error?: string;
}
+/**
+ * Say what failed, wherever it failed. Two loading doors reached this same dead
+ * end — a caller holding an empty result it cannot tell from an empty group —
+ * so the sentence is written once rather than at each of them.
+ */
+function warnFailedLoads(failed: readonly MissingAsset[], where?: string): void {
+ if (failed.length === 0) return;
+ log.warn('asset', `${where ? `${where}: ` : ''}${failed.length} asset(s) failed to load`, failed);
+}
+
export interface SceneAssetResult {
textureHandles: Map<string, number>;
materialHandles: Map<string, number>;
@@ -886,14 +896,20 @@ export class Assets {
let loadedCount = 0;
const promises: Promise<void>[] = [];
- const track = (p: Promise<void>): Promise<void> =>
+ // A subpackage that downloads but stages nothing reads exactly like a
+ // group that was always empty, so the failures are named, not counted.
+ const failed: MissingAsset[] = [];
+ const track = (p: Promise<void>, ref: string, type: string): Promise<void> =>
p.then(() => { onProgress?.(++loadedCount, totalCount); })
- .catch(() => { onProgress?.(++loadedCount, totalCount); });
+ .catch((e: unknown) => {
+ failed.push({ ref, type, reason: 'load-failed', error: String(e) });
+ onProgress?.(++loadedCount, totalCount);
+ });
for (const asset of model.assetsInGroup(groupName)) {
const path = this.manifestAssetUrl_(asset.path, mode === 'remote');
const task = this.groupLoadTask_(path, asset.type, bundle);
- if (task) promises.push(track(task));
+ if (task) promises.push(track(task, path, asset.type));
}
const totalCount = promises.length;
@@ -901,6 +917,7 @@ export class Assets {
loadedCount = 0;
await Promise.allSettled(promises);
+ warnFailedLoads(failed, `loadGroup('${groupName}')`);
return bundle;
}
@@ -1418,10 +1435,7 @@ export class Assets {
// `unresolved` refs warn above; a load that THREW only reached `missing`,
// which callers may ignore — so a scene drew with no textures and no
// complaint, indistinguishable from a scene that has none.
- const failed = missing.filter((m) => m.reason === 'load-failed');
- if (failed.length > 0) {
- log.warn('asset', `${failed.length} asset(s) failed to load`, failed);
- }
+ warnFailedLoads(missing.filter((m) => m.reason === 'load-failed'));
return { textureHandles, materialHandles, fontHandles, meshHandles, environmentHandles,
probeVolumeHandles, releaseCallbacks, scope, missing };
diff --git a/sdk/tests/asset-group-loading.test.ts b/sdk/tests/asset-group-loading.test.ts
index 0c3a0433b..8e0ba9654 100644
--- a/sdk/tests/asset-group-loading.test.ts
+++ b/sdk/tests/asset-group-loading.test.ts
@@ -6,6 +6,7 @@ import { Catalog, type CatalogData } from '../src/asset/Catalog';
import type { AddressableManifest } from '../src/asset/AddressableManifest';
import type { Backend } from '../src/asset/Backend';
import * as platform from '../src/platform';
+import { log } from '../src/util/logger';
const mockModule = {
_malloc: vi.fn(() => 0),
@@ -202,6 +203,41 @@ describe('Assets.loadGroup', () => {
expect(sub).toHaveBeenCalledWith('extra');
});
+ /**
+ * A 分包 that downloads but stages nothing, a CDN that 404s every file: the
+ * group loads, the bundle is empty, and a caller cannot tell that from a
+ * group that was always empty. It has to say so.
+ */
+ it('says which assets failed instead of handing back a silently empty bundle', async () => {
+ const warn = vi.spyOn(log, 'warn').mockImplementation(() => {});
+ const assets = createAssets();
+ assets.setManifest(createManifest());
+ vi.spyOn(assets, 'acquireTexture').mockRejectedValue(new Error('404'));
+
+ const bundle = await assets.loadGroup('main');
+ expect(bundle.textures.size).toBe(0);
+
+ const said = warn.mock.calls.find((c) => String(c[1]).includes('failed to load'));
+ expect(said, 'loadGroup returned an empty bundle without saying why').toBeDefined();
+ // Named, not counted: "2 assets failed" sends nobody anywhere.
+ expect(String(said![1])).toContain("loadGroup('main')");
+ expect((said![2] as Array<{ ref: string }>).map((f) => f.ref).sort())
+ .toEqual(['tex1.png', 'tex2.png']);
+ warn.mockRestore();
+ });
+
+ it('stays quiet when every asset in the group loaded', async () => {
+ const warn = vi.spyOn(log, 'warn').mockImplementation(() => {});
+ const assets = createAssets();
+ assets.setManifest(createManifest());
+ vi.spyOn(assets, 'acquireTexture').mockResolvedValue({
+ key: 'texture:x', generation: 1, value: { handle: 1, width: 1, height: 1 }, release: () => {},
+ } as any);
+ await assets.loadGroup('main');
+ expect(warn.mock.calls.filter((c) => String(c[1]).includes('failed to load'))).toEqual([]);
+ warn.mockRestore();
+ });
+
it('does not download a subpackage for a local (main-package) group', async () => {
const sub = vi.mocked(platform.platformLoadSubpackage);
sub.mockClear();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index dd5961ce8..3dde13911 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -700,6 +700,10 @@ export const NOTED = {
{ internal: "the editor's preview page names the same subpaths it always did" },
'fix(settings): the module page reads the same asset table the build installs from':
{ note: 'The Engine Modules page no longer calls a module unused that the build then carries.' },
+ 'fix(assets): a group load names what failed instead of returning an empty bundle':
+ { note: 'A group that failed to load says so instead of handing back an empty bundle.' },
+ 'docs(settings): the wasm compression switch names what it now compresses':
+ { internal: 'the switch now compresses the side modules too, which its own label did not say' },
'feat(export): a mini-game compresses its side modules, not just its engine':
{ note: "A mini-game's side modules compress too, not just its engine." },
'feat(export): a mini-game entry raises the host indicator on its first line':