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 package draws each atlas sprite as its own frame

esengine33ed533ef647
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index fce356b53..7a180ae4d 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -10,8 +10,7 @@
*
* asset-manifest.json AddressableManifest (groups.<g>.assets[uuid] = {path,…});
* the resolver keys by uuid → path.
- * scenes/<name>.json the entry scene with @uuid: refs STRIPPED to bare
- * uuids (the resolver looks up bare uuids, not @uuid:).
+ * scenes/<name>.json the entry scene, refs as authored (`@uuid:` like the web package).
* game-bundle.js esbuild CJS of [the vendor SDK (esengine aliased) +
* project scripts + a boot()] — one esengine instance
* so custom components/systems run.
@@ -105,20 +104,6 @@ interface CookManifest {
const brotliPack = promisify(brotliCompressCb);
-const UUID_PREFIX = '@uuid:';
-
-/** Strip @uuid: asset refs to the bare (lowercased) uuid the resolver keys by.
- * Deep, value-only — any string starting with @uuid: is a ref. */
-function stripUuidRefs(v: unknown): unknown {
- if (typeof v === 'string') return v.startsWith(UUID_PREFIX) ? v.slice(UUID_PREFIX.length).toLowerCase() : v;
- if (Array.isArray(v)) return v.map(stripUuidRefs);
- if (v && typeof v === 'object') {
- const o: Record<string, unknown> = {};
- for (const k of Object.keys(v as Record<string, unknown>)) o[k] = stripUuidRefs((v as Record<string, unknown>)[k]);
- return o;
- }
- return v;
-}
/** What this export stages into `wasm/`, and the engine path the loader is told. */
interface RuntimeLayout {
@@ -393,8 +378,7 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
warnings.push(...cook.warnings);
// 1a. Anything the packer will not upload ships as `<name>.<ext>.bin`. Scenes
- // have their own transform below (`<x>.esscene` → `scenes/<name>.json`,
- // @uuid: refs stripped to the bare uuids the resolver keys by).
+ // have their own transform below (`<x>.esscene` → `scenes/<name>.json`).
progress({ phase: 'Transforming scenes' });
const needsRestage = (p: string): boolean => {
if (!profile.packerSuffixes) return false;
@@ -431,7 +415,7 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
sceneRawByName.set(scene.name, raw);
const outPath = `scenes/${scene.name}.json`;
await mkdir(path.dirname(path.join(absOut, outPath)), { recursive: true });
- await writeFile(path.join(absOut, outPath), JSON.stringify(stripUuidRefs(raw)) + '\n');
+ await writeFile(path.join(absOut, outPath), JSON.stringify(raw) + '\n');
await rm(staged, { force: true });
e.path = outPath;
}
diff --git a/pipeline/tests/export-wechat.test.ts b/pipeline/tests/export-wechat.test.ts
index 0152c1f0b..2f915aa52 100644
--- a/pipeline/tests/export-wechat.test.ts
+++ b/pipeline/tests/export-wechat.test.ts
@@ -3,7 +3,7 @@
/**
* @file WeChat MiniGame export — structure / contract alignment. Asserts the
* output matches what initWeChatRuntime consumes: AddressableManifest
- * (asset-manifest.json), @uuid:-stripped scenes/<name>.json, the single
+ * (asset-manifest.json), scenes/<name>.json, the single
* CJS game-bundle (esengine aliased so project scripts share one instance),
* the game.js entry, the wasm copy, and game.json/project.config.json.
* (Runtime correctness is validated by the user in WeChat devtools — no
@@ -93,9 +93,10 @@ describe('exportGame (wechat)', () => {
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.
+ // Scene at scenes/<name>.json, its refs as authored — the web package's form.
+ // Stripping them to bare uuids lost every atlas frame, which is keyed `@uuid:`.
const scene = JSON.parse(readFileSync(path.join(out, 'scenes', 'main.json'), 'utf8'));
- expect(scene.entities[0].components[0].data.texture).toBe(TEX); // no @uuid: prefix
+ expect(scene.entities[0].components[0].data.texture).toBe(`@uuid:${TEX}`);
// One CJS bundle (SDK aliased + project scripts) exposing boot(), + the entry.
const bundle = readFileSync(path.join(out, 'game-bundle.js'), 'utf8');
diff --git a/sdk/src/asset/Catalog.ts b/sdk/src/asset/Catalog.ts
index a2c3901f2..b48a9a135 100644
--- a/sdk/src/asset/Catalog.ts
+++ b/sdk/src/asset/Catalog.ts
@@ -1,5 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { extractUuid, UUID_REF_PREFIX } from './AssetRegistry';
+
export interface AtlasFrameInfo {
atlas: string;
frame: { x: number; y: number; w: number; h: number };
@@ -96,7 +98,10 @@ export class Catalog {
}
getAtlasFrame(path: string): AtlasFrameInfo | null {
- const entry = this.entries_.get(path);
+ // A frame is keyed by its `@uuid:` spelling; a scene or clip may name the
+ // same asset by its bare uuid, in either case.
+ const uuid = extractUuid(path);
+ const entry = this.entries_.get(uuid ? `${UUID_REF_PREFIX}${uuid}` : path);
if (!entry?.atlas || !entry.frame || !entry.uv) return null;
return {
atlas: entry.atlas,
diff --git a/sdk/tests/atlas-catalog.test.ts b/sdk/tests/atlas-catalog.test.ts
index 880cbf358..5b192e1a8 100644
--- a/sdk/tests/atlas-catalog.test.ts
+++ b/sdk/tests/atlas-catalog.test.ts
@@ -37,4 +37,22 @@ describe('atlasCatalogFields', () => {
expect(frame.uvOffset).toEqual([0, 0.5]);
expect(frame.uvScale).toEqual([0.5, 0.5]);
});
+
+ // A mini-game scene named its sprites by bare uuid, and every packed sprite
+ // drew as the whole atlas page.
+ it('serves a frame to any spelling of its uuid', () => {
+ const uuid = '92f1ab5f-28f4-4b95-bb82-7182fdb33494';
+ const fields = atlasCatalogFields(
+ { frame: { x: 0, y: 0, width: 4, height: 4 }, pageWidth: 8, pageHeight: 8 },
+ 'page.png',
+ );
+ const catalog = Catalog.fromJson({
+ version: 1,
+ entries: { [`@uuid:${uuid}`]: { type: 'texture', buildPath: 'page.png', ...fields } },
+ });
+ for (const ref of [`@uuid:${uuid}`, uuid, uuid.toUpperCase(), `@uuid:${uuid.toUpperCase()}`]) {
+ expect(catalog.getAtlasFrame(ref)?.uvScale, ref).toEqual([0.5, 0.5]);
+ }
+ expect(catalog.getAtlasFrame('page.png')).toBeNull();
+ });
});