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(export): a mini-game's assets are named by their content, so an update gets new URLs

esengine172fd2d762ba
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 966d481eb..0fbb26880 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,7 @@ published separately; it ships inside the editor.
### Fixed
+- Mini-game exports name assets by their content, as web exports already did: a hot update to a remote texture now shows on a phone (it kept the old picture under the same URL), and a CDN can hold two versions without v1 players getting v2 files.
- On a WeChat phone, a socket whose connection is refused now reports that it closed, so a development build keeps redialing the editor (and a game's socket reconnects) instead of giving up after the first refusal.
- A shipping package no longer carries the development debug channel's code (13 KB on a WeChat package): only a development export that names an editor imports it, as `esengine/debug-channel`.
- Capturing a development build whose tab is in the background says so at once, instead of waiting 30 seconds for a frame the browser will not draw.
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index becd79234..1f820c475 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -302,7 +302,9 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
emcc?: string | null;
/** Whether this export compiles `@compiled` systems; see exportGame. */
aotMode?: BuildMode;
- /** Emit content-addressed asset filenames (<hash><ext>) for dedup + immutable caching. */
+ /** Content-addressed asset filenames (<hash><ext>), on unless turned off: a remote
+ * asset whose content changed must have a new URL, or a hot update and the CDN
+ * serve the old bytes under it. */
contentAddressed?: boolean;
/** Encode raster textures to GPU-compressed KTX2 at cook time. */
compressTextures?: boolean;
@@ -372,7 +374,7 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
progress({ phase: 'Cooking assets' });
// `platform: profile.id` — the cook reads each texture's per-platform Import
// Settings under this key, so a vendor must cook against ITS OWN overrides.
- const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo: true, platform: profile.id, textureDecoderBytes: textureDecoderBytes(opts.wasmDir) });
+ const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: absOut, contentAddressed: opts.contentAddressed ?? true, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo: true, platform: profile.id, textureDecoderBytes: textureDecoderBytes(opts.wasmDir) });
warnings.push(...cook.warnings);
// 1a. Anything the packer will not upload ships as `<name>.<ext>.bin`. Scenes
diff --git a/pipeline/tests/export-minigame-remote-urls.test.ts b/pipeline/tests/export-minigame-remote-urls.test.ts
new file mode 100644
index 000000000..eef54a3ec
--- /dev/null
+++ b/pipeline/tests/export-minigame-remote-urls.test.ts
@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A mini-game's remote asset gets a new URL when its content changes.
+ * Under one name, a hot update re-read the old bytes (a WeChat phone kept
+ * showing v1's art after "update applied"), and uploading v2 to the CDN
+ * would hand v1 players v2's files.
+ */
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runtimeConfigOf } from '../src/project/runtimeConfig';
+import { exportGame } from '../src/export/exportGame';
+import { miniGameSdkStub } from './fixtures/miniGameSdkStub';
+import { wechatExportProfile } from '../src/export/miniGameExportProfile';
+import { OFFICIAL_PACKAGES } from './officialPackagesDir';
+
+const ART = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+const SCN = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
+
+async function exportWith(art: string): Promise<{ path: string; bytes: string }> {
+ const root = mkdtempSync(path.join(tmpdir(), 'estella-remote-urls-'));
+ try {
+ mkdirSync(path.join(root, 'assets', 'cdn'), { recursive: true });
+ writeFileSync(path.join(root, 'assets', 'cdn', 'art.png'), art);
+ writeFileSync(path.join(root, 'assets', 'cdn', 'art.png.meta'), meta(ART, 'texture'));
+ mkdirSync(path.join(root, '.esengine'), { recursive: true });
+ writeFileSync(path.join(root, '.esengine', 'asset-groups.json'), JSON.stringify({
+ version: '1.0', groups: { cdn: { folder: 'assets/cdn', mode: 'remote' } },
+ }));
+ mkdirSync(path.join(root, 'scenes'), { recursive: true });
+ writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({
+ version: '1.0', name: 'Main',
+ entities: [{ name: 'Art', components: [{ type: 'Sprite', data: { texture: `@uuid:${ART}` } }] }],
+ }));
+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
+ mkdirSync(path.join(root, '_sdk'), { recursive: true });
+ writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile));
+ mkdirSync(path.join(root, '_wxwasm'), { recursive: true });
+ writeFileSync(path.join(root, '_wxwasm', 'esengine.js'), 'module.exports = () => Promise.resolve({});');
+ writeFileSync(path.join(root, '_wxwasm', 'esengine.wasm'), 'wasmbytes');
+ const out = path.join(root, 'dist');
+ const res = await exportGame({
+ root, entryScene: 'scenes/main.esscene', hostsDir: 'unused-for-wechat', packagesDir: OFFICIAL_PACKAGES,
+ sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wxwasm'), outDir: out,
+ title: 'Remote', platform: 'wechat', miniGameAppid: 'wxTEST0123456789', orientation: 'landscape',
+ runtime: runtimeConfigOf({ designResolution: { width: 1280, height: 720 } }),
+ });
+ expect(res.errors).toEqual([]);
+ const manifest = JSON.parse(readFileSync(path.join(out, 'asset-manifest.json'), 'utf8'));
+ const entry = manifest.groups.cdn.assets[ART] as { path: string };
+ expect(existsSync(path.join(out, entry.path))).toBe(true);
+ return { path: entry.path, bytes: readFileSync(path.join(out, entry.path), 'utf8') };
+ } finally {
+ rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ }
+}
+
+describe('a mini-game remote asset', () => {
+ it('is named by its content, so a changed one is a new URL', async () => {
+ const v1 = await exportWith('GREEN-PIXELS');
+ const v2 = await exportWith('RED-PIXELS');
+ expect(v1.bytes).toBe('GREEN-PIXELS');
+ expect(v2.bytes).toBe('RED-PIXELS');
+ expect(v1.path).not.toBe(v2.path);
+ expect(v1.path).toMatch(/^remote\/cdn\/assets\/[0-9a-f]{16}\.png$/);
+ }, 60_000);
+});
diff --git a/pipeline/tests/export-wechat-audio-src.test.ts b/pipeline/tests/export-wechat-audio-src.test.ts
index b91d15fc9..eb0383f1e 100644
--- a/pipeline/tests/export-wechat-audio-src.test.ts
+++ b/pipeline/tests/export-wechat-audio-src.test.ts
@@ -88,9 +88,9 @@ describe('the source a cooked mini-game hands its audio player', () => {
expect(res.ok).toBe(true);
// The cook renamed it, so the authored name is not what ships.
- const staged = readdirSync(path.join(out, 'assets', 'audio'));
- expect(staged).toContain('tap.mp3');
- expect(staged).not.toContain('tap.wav');
+ const staged = readdirSync(path.join(out, 'assets'), { recursive: true }).map(String);
+ expect(staged.some((f) => f.endsWith('.mp3'))).toBe(true);
+ expect(staged.some((f) => f.endsWith('.wav'))).toBe(false);
// The runtime's OWN resolver, over the manifest the export wrote: this is
// the channel `Audio.preload` asks, and a miss here is silence on device.
@@ -100,10 +100,10 @@ describe('the source a cooked mini-game hands its audio player', () => {
);
const resolve = (ref: string): string => manifest.resolvePath(extractUuid(ref) ?? ref);
const src = resolve('assets/audio/tap.wav');
- expect(src).toBe('assets/audio/tap.mp3');
+ expect(src).toMatch(/^assets\/[0-9a-f]{16}\.mp3$/);
expect(existsSync(path.join(out, src))).toBe(true);
// And by uuid, which is how the scene names it.
- expect(resolve(`@uuid:${CLIP}`)).toBe('assets/audio/tap.mp3');
+ expect(resolve(`@uuid:${CLIP}`)).toBe(src);
}, 120_000);
});
diff --git a/pipeline/tests/export-wechat-subpackage.test.ts b/pipeline/tests/export-wechat-subpackage.test.ts
index 8b21153fe..63b116101 100644
--- a/pipeline/tests/export-wechat-subpackage.test.ts
+++ b/pipeline/tests/export-wechat-subpackage.test.ts
@@ -141,7 +141,11 @@ describe('WeChat 分包 declared through asset-groups.json', () => {
expect(gjson.subPackages).toBeUndefined();
// Nor a warning: nothing about this project is a 分包 that went wrong.
expect(res.warnings.filter((w) => w.includes('分包'))).toEqual([]);
- expect(existsSync(path.join(out2, 'assets', 'level2', 'extra.png'))).toBe(true);
+ const shipped = JSON.parse(readFileSync(path.join(out2, 'asset-manifest.json'), 'utf8'));
+ const extra = Object.values(shipped.groups as Record<string, { assets: Record<string, { path: string }> }>)
+ .flatMap((g) => Object.values(g.assets)).find((a) => a.path.endsWith('.png'))!;
+ expect(extra.path.startsWith('subpackages/')).toBe(false);
+ expect(existsSync(path.join(out2, extra.path))).toBe(true);
} finally {
rmSync(root2, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
}
diff --git a/pipeline/tests/export-wechat.test.ts b/pipeline/tests/export-wechat.test.ts
index 4fb0891bf..28656f7c7 100644
--- a/pipeline/tests/export-wechat.test.ts
+++ b/pipeline/tests/export-wechat.test.ts
@@ -90,7 +90,7 @@ describe('exportGame (wechat)', () => {
expect(existsSync(path.join(out, 'assets.manifest.json'))).toBe(false);
const manifest = JSON.parse(readFileSync(path.join(out, 'asset-manifest.json'), 'utf8'));
expect(manifest.version).toBe('2.0');
- expect(manifest.groups.main.assets[TEX].path).toBe('assets/hero.png');
+ expect(manifest.groups.main.assets[TEX].path).toMatch(/^assets\/[0-9a-f]{16}\.png$/);
expect(manifest.groups.main.assets[TEX].type).toBe('texture');
// Scene at scenes/<name>.json with @uuid: stripped to the bare uuid.
@@ -135,9 +135,9 @@ describe('exportGame (wechat)', () => {
// WeChat subPackage, with its file staged under the subpackage root.
expect(manifest.groups.level2.bundleMode).toBe('lazy');
expect(manifest.groups.main.bundleMode).toBe('local');
- expect(manifest.groups.level2.assets[SUBTEX].path).toBe('subpackages/level2/extra.png');
+ expect(manifest.groups.level2.assets[SUBTEX].path).toMatch(/^subpackages\/level2\/assets\/[0-9a-f]{16}\.png$/);
expect(gjson.subPackages).toContainEqual({ name: 'level2', root: 'subpackages/level2' });
- expect(existsSync(path.join(out, 'subpackages', 'level2', 'extra.png'))).toBe(true);
+ expect(existsSync(path.join(out, manifest.groups.level2.assets[SUBTEX].path))).toBe(true);
}, 60_000);
it('requires the glue by its actual -t wechat name; unneeded side modules stay out (4MB budget)', async () => {
@@ -436,11 +436,11 @@ describe('exportGame (wechat)', () => {
// WeChat's code-package suffix whitelist has no `ktx2` — the container is
// re-staged as .ktx2.bin (whitelisted), and the manifest tracks the rename
// while the logical identity stays on the source path.
- expect(existsSync(path.join(outKtx, 'assets', 'pre.ktx2.bin'))).toBe(true);
- expect(existsSync(path.join(outKtx, 'assets', 'pre.ktx2'))).toBe(false);
const manifest = JSON.parse(readFileSync(path.join(outKtx, 'asset-manifest.json'), 'utf8'));
const ktxAsset = manifest.groups.main.assets['ffffffff-ffff-ffff-ffff-ffffffffffff'];
- expect(ktxAsset.path).toBe('assets/pre.ktx2.bin');
+ expect(ktxAsset.path).toMatch(/^assets\/[0-9a-f]{16}\.ktx2\.bin$/);
+ expect(existsSync(path.join(outKtx, ktxAsset.path))).toBe(true);
+ expect(readdirSync(path.join(outKtx, 'assets')).some((f) => f.endsWith('.ktx2'))).toBe(false);
const pcfg = JSON.parse(readFileSync(path.join(outKtx, 'project.config.json'), 'utf8'));
expect(pcfg.packOptions.include).toContainEqual({ type: 'suffix', value: '.bin' });
expect(pcfg.packOptions.include).not.toContainEqual({ type: 'suffix', value: '.ktx2' });
@@ -557,7 +557,7 @@ describe('exportGame (wechat)', () => {
expect(manifest.groups.main.assets[LV2SCN].path).toBe('scenes/level2.json');
// The second scene is a cook root: its assets ship even though the entry
// scene never references them.
- expect(manifest.groups.main.assets[LV2TEX].path).toBe('assets/lv2.png');
+ expect(manifest.groups.main.assets[LV2TEX].path).toMatch(/^assets\/[0-9a-f]{16}\.png$/);
// Boot registers every scene, booting into the entry.
const bundle = readFileSync(path.join(outMulti, 'game-bundle.js'), 'utf8');
expect(bundle).toContain('"main"');
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 69ed25219..c546f688c 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1112,4 +1112,6 @@ export const NOTED = {
{ note: 'A shipping package no longer carries the development debug channel\'s code (13 KB on a WeChat package): only a development export that names an editor imports it, as `esengine/debug-channel`.' },
'fix(net): a mini-game socket whose dial is refused on a phone redials':
{ note: 'On a WeChat phone, a socket whose connection is refused now reports that it closed, so a development build keeps redialing the editor (and a game\'s socket reconnects) instead of giving up after the first refusal.' },
+ 'fix(export): a mini-game\'s assets are named by their content, so an update gets new URLs':
+ { note: 'Mini-game exports name assets by their content, as web exports already did: a hot update to a remote texture now shows on a phone (it kept the old picture under the same URL), and a CDN can hold two versions without v1 players getting v2 files.' },
};