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.

feat(asset): a scene preload reports what each asset type cost

esengine62791dac7d3b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1182efaa9..08bd82c95 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@ published separately; it ships inside the editor.
- Web and mini-game packages decode KTX2 textures under Zstandard supercompression, as the native host already did. UASTC textures made outside Estella usually are, and every one failed to decode; the transcoder module grows by about 21KB compressed, in packages that carry KTX2.
- A KTX2 texture made outside Estella with a single level ships with a mip chain: the cook encodes the levels below it and keeps the file's own level 0 byte for byte, so it no longer shimmers into the distance. Bistro's 2048² textures each took about 0.3 s; the package grows by the chain's third.
- Exporting again is fast when the art has not changed: the cook keeps what it encoded under `.esengine/cache/cook/`, keyed by the source, the settings and the encoder. Re-exporting Bistro took 24 s against 131 s the first time.
+- A scene's preload logs what each asset type cost it — how many, their summed load time and the slowest one — and `preloadSceneAssets` returns the same as `timings` and `wallMs`. Bistro on a Windows machine: 132 materials 54 s, 107 textures 47 s and 1505 meshes 45 s of load time over 24 s of wall time.
- **Export profiles.** A project can name several exports of one target in `packaging.profiles` — a test and a production WeChat build, each with its own AppID, CDN root and development or shipping configuration, writing only what differs from the project's settings. The Build dialog creates, edits and deletes them per target, marking each setting a profile overrides with a reset that hands it back to the project; `estella export --profile <name>` and the agent's `export_game` build the same one, and the size history records which profile a build used.
### Changed
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 4cf04d781..02201b869 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -5,7 +5,7 @@ import { Catalog, type AtlasFrameInfo } from './Catalog';
import { ManifestModel, normalizeBundleMode, type AddressableManifest, type AddressableAssetType } from './AddressableManifest';
import { diffManifests, type UpdatePlan, type AssetChange } from './hotUpdate';
import { contentHashHex } from './contentHash';
-import { platformLoadSubpackage, platformGetStorageItem, platformSetStorageItem, platformRemoveStorageItem, platformWriteCacheFile } from '../platform';
+import { platformLoadSubpackage, platformGetStorageItem, platformSetStorageItem, platformRemoveStorageItem, platformWriteCacheFile, platformNow } from '../platform';
import type {
AssetLoader, LoadContext, TextureResult, SpineResult,
MaterialResult, FontResult, AudioResult, AnimClipResult,
@@ -331,6 +331,11 @@ export interface SceneAssetResult {
*/
scope: AssetScope;
missing: MissingAsset[];
+ /** Per asset type: how many loaded, the sum of their load times and the
+ * slowest one, in ms. Loads overlap, so the sums exceed the wall time. */
+ timings: Record<string, { count: number; ms: number; slowestMs: number }>;
+ /** Wall time of the whole preload, in ms. */
+ wallMs: number;
}
export type AssetRefResolver = (ref: string) => string | null;
@@ -1467,6 +1472,17 @@ export class Assets {
* SUCCEEDED — a failed load owns nothing, so there is nothing for the
* scene to give back and nothing to guess about at unload.
*/
+ const timings: SceneAssetResult['timings'] = {};
+ const timedLoad = <R>(label: string, load: () => Promise<R>): Promise<R> => {
+ const began = platformNow();
+ return load().finally(() => {
+ const ms = platformNow() - began;
+ const t = timings[label] ??= { count: 0, ms: 0, slowestMs: 0 };
+ t.count++;
+ t.ms += ms;
+ t.slowestMs = Math.max(t.slowestMs, ms);
+ });
+ };
const pushAcquire = <T>(
paths: Set<string>,
acquire: (p: string) => Promise<AssetLease<T>>,
@@ -1475,7 +1491,7 @@ export class Assets {
): void => {
for (const path of paths) {
tasks.push(() =>
- acquire(path).then(lease => {
+ timedLoad(label, () => acquire(path)).then(lease => {
scope.add(lease);
releaseCallbacks.push(() => lease.release());
if (handles) {
@@ -1545,9 +1561,16 @@ export class Assets {
onProgress?.(0, totalCount);
const maxConcurrent = Math.max(1, options?.maxConcurrent ?? DEFAULT_PRELOAD_CONCURRENCY);
+ const began = platformNow();
await runWithConcurrency(tasks, maxConcurrent, () => {
onProgress?.(++loadedCount, totalCount);
});
+ const wallMs = platformNow() - began;
+ if (totalCount > 0) {
+ const parts = Object.entries(timings).sort((a, b) => b[1].ms - a[1].ms)
+ .map(([k, t]) => `${k} ${t.count} (${Math.round(t.ms)}ms, slowest ${Math.round(t.slowestMs)}ms)`);
+ log.info('asset', `preloaded ${totalCount} asset(s) in ${Math.round(wallMs)}ms, ${maxConcurrent} at a time: ${parts.join(', ')}`);
+ }
// `unresolved` refs warn above; a load that THREW only reached `missing`,
// which callers may ignore — so a scene drew with no textures and no
@@ -1555,7 +1578,7 @@ export class Assets {
warnFailedLoads(missing.filter((m) => m.reason === 'load-failed'));
return { textureHandles, materialHandles, fontHandles, meshHandles, environmentHandles,
- probeVolumeHandles, releaseCallbacks, scope, missing };
+ probeVolumeHandles, releaseCallbacks, scope, missing, timings, wallMs };
}
resolveSceneAssetPaths(sceneData: SceneData, result: SceneAssetResult): void {
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 04c1680a1..c6aa6f686 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1218,4 +1218,6 @@ export const NOTED = {
{ note: 'A KTX2 texture made outside Estella with a single level ships with a mip chain: the cook encodes the levels below it and keeps the file\'s own level 0 byte for byte, so it no longer shimmers into the distance. Bistro\'s 2048² textures each took about 0.3 s; the package grows by the chain\'s third.' },
'perf(export): the cook reads back a texture encode it already did':
{ note: 'Exporting again is fast when the art has not changed: the cook keeps what it encoded under `.esengine/cache/cook/`, keyed by the source, the settings and the encoder. Re-exporting Bistro took 24 s against 131 s the first time.' },
+ 'feat(asset): a scene preload reports what each asset type cost':
+ { note: 'A scene\'s preload logs what each asset type cost it — how many, their summed load time and the slowest one — and `preloadSceneAssets` returns the same as `timings` and `wallMs`. Bistro on a Windows machine: 132 materials 54 s, 107 textures 47 s and 1505 meshes 45 s of load time over 24 s of wall time.' },
};