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(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.mdindex 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.tsindex 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`. Scenesdiff --git a/pipeline/tests/export-minigame-remote-urls.test.ts b/pipeline/tests/export-minigame-remote-urls.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.' },};