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(spine): a released build's atlas pages are where the atlas was authored
esengine09ff6aac4c86
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d9e7ceb63..3b28e4bda 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,72 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **A sprite frame draws at its own size, so one clip can hold different+ pictures.** A clip owned the UV window and, since 1.4, the anchor — never the+ size. Every frame therefore drew at the one size the entity carried, which is+ right for a sheet whose cells are all alike and wrong for a flipbook built from+ separate images: they came out stretched to a common box. Three of the engine's+ own examples are that shape.++ `.esanim` 1.5 gives a frame `size` and `offset`, and the clip `frameSizing`.+ Absent size means the frame's natural one — its sheet cell, or its texture's+ pixels, which the loader already held and threw away. An offset is a shift in+ the same units, folded into the frame's anchor at load, so nothing downstream+ learns a new field: the runtime writes `Sprite.size` and `Sprite.pivot` and+ that is all.++ Authoring the shift in units rather than as a normalized anchor is the point.+ The same offset is the same visual shift on frames of any size; the same anchor+ is not. That is also why an offset makes the clip own size — there is no+ fraction to express a shift as until something says what it is a fraction of.+ Clips written before 1.5 own neither, so they play exactly as before.++- **A flipbook editor that reads in frames, sizes and offsets.** The panel was a+ strip of equal-width thumbnails with a bare number in each, and a preview that+ scaled every frame into one square. Time was a field to type in, geometry had+ nowhere to live, and a clip of separate images could not be authored at all —+ the only way to make one was to slice a sheet, and the only way to add a frame+ was to click a grid cell.++ It is now a viewport that draws the frame at its true size against the clip's+ anchor, with the neighbours ghosted in THEIR places (a frame that does not line+ up shows it, which is the entire job of onion skin); a timeline whose blocks+ are as wide as their frames are long, with a frame ruler, a playhead, and a+ right edge to drag for retiming; and the frame's own properties — duration,+ size, offset, anchor — in the Details inspector, through the same+ ComponentSection engine as entities and materials. Frames come from separate+ images too: multi-select in the Content Browser (file-name order, counting+ numerically, so `run_2` precedes `run_10`), or drop images onto the timeline.+ Edit-mode preview and the spawn path handle texture frames as well now; both+ used to skip them.++ The lane mapping is the Sequencer's, extracted and covered by criteria first —+ a lane that draws at one inset and reads a scrub back at another puts every+ keyframe beside the pointer that placed it, and nothing said so.++### Fixed++- **Every spine in a released build drew nothing.** A spine atlas names its page+ images as siblings — `spineboy.png` — and a content-addressed pack renames every+ asset to a hash under one flat directory, so resolving that sibling against the+ STAGED path asked for `assets/spineboy.png` and got a 404. The skeleton then+ posed with no texture: a package that starts, paints, and shows nothing.++ The scene-loading door had been fixed for exactly this and the registry door+ had not, with the regression test covering only the first of the two. Both now+ resolve pages against the atlas's AUTHORED address, and the test asks the+ question of both. Only content-addressed packs were affected — which is what a+ release build is, and why no `pr`-tier run ever saw it.++- **A box that mounts after a panel's empty state was measured as 0×0.**+ `useElementSize` bound its observer on mount and never again, so a panel that+ returns an empty state first — every asset editor does — attached to a null ref+ and reported nothing for the rest of the session. Anything placed against the+ box then landed at 0,0: the rebuilt Flipbook viewport drew its frame in the+ top-left corner instead of on the anchor, which is how this was found.+## [0.59.0] - 2026-08-28### Changeddiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 7b0a5fcc5..49570bd2a 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1833,6 +1833,7 @@ triangles: number | undefined## Catalog — class @experimental```+addressOf: (path: string) => string | nullgetAllLabels: () => string[]getAtlasFrame: (path: string) => AtlasFrameInfo | nullgetBuildPath: (path: string) => stringdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 28b5da880..35500b694 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1833,6 +1833,7 @@ triangles: number | undefined## Catalog — class @experimental```+addressOf: (path: string) => string | nullgetAllLabels: () => string[]getAtlasFrame: (path: string) => AtlasFrameInfo | nullgetBuildPath: (path: string) => stringdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 5d134b20b..567d1907e 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1828,6 +1828,7 @@ triangles: number | undefined## Catalog — class @experimental```+addressOf: (path: string) => string | nullgetAllLabels: () => string[]getAtlasFrame: (path: string) => AtlasFrameInfo | nullgetBuildPath: (path: string) => stringdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex b5b06570e..393ed57b4 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1828,6 +1828,7 @@ triangles: number | undefined## Catalog — class @experimental```+addressOf: (path: string) => string | nullgetAllLabels: () => string[]getAtlasFrame: (path: string) => AtlasFrameInfo | nullgetBuildPath: (path: string) => stringdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex e0afd3b2e..be5ffb466 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1828,6 +1828,7 @@ triangles: number | undefined## Catalog — class @experimental```+addressOf: (path: string) => string | nullgetAllLabels: () => string[]getAtlasFrame: (path: string) => AtlasFrameInfo | nullgetBuildPath: (path: string) => stringdiff --git a/sdk/src/asset/Catalog.ts b/sdk/src/asset/Catalog.tsindex 359fdfd3c..a2c3901f2 100644--- a/sdk/src/asset/Catalog.ts+++ b/sdk/src/asset/Catalog.ts@@ -60,6 +60,8 @@ export class Catalog {private entries_: Map<string, CatalogEntry>;private addresses_: Map<string, string>;private labels_: Map<string, string[]>;+ /** Built on first ask; a pack has thousands of entries and most callers never ask. */+ private addressByBuildPath_: Map<string, string> | null = null;private constructor(entries: Map<string, CatalogEntry>,@@ -105,6 +107,27 @@ export class Catalog {};}+ /**+ * The authored logical address a staged path came from, or null. A document+ * that names a SIBLING — a spine atlas page, a font page — resolves it against+ * where the document was AUTHORED, and content-addressed staging renames every+ * asset to a hash under one flat directory, which loses that.+ */+ addressOf(path: string): string | null {+ if (!this.addressByBuildPath_) {+ const byBuild = new Map<string, string>();+ for (const [key, entry] of this.entries_) {+ // `@uuid:` and the "/"-rooted spelling are alternative keys for the+ // same asset; the bare address is the authored one.+ if (key.startsWith('@uuid:') || key.startsWith('/')) continue;+ const built = entry.buildPath;+ if (built && built !== key && !byBuild.has(built)) byBuild.set(built, key);+ }+ this.addressByBuildPath_ = byBuild;+ }+ return this.addressByBuildPath_.get(path) ?? null;+ }+getBuildPath(path: string): string {const entry = this.entries_.get(path);return entry?.buildPath ?? path;diff --git a/sdk/src/asset/loaders/SpineAssetLoader.ts b/sdk/src/asset/loaders/SpineAssetLoader.tsindex 909710ec8..e1aacfec5 100644--- a/sdk/src/asset/loaders/SpineAssetLoader.ts+++ b/sdk/src/asset/loaders/SpineAssetLoader.ts@@ -10,6 +10,7 @@* here: it is per Spine version, per App, and dies with the entities* posing it.*/+import { log } from '../../util/logger';import type { AssetLoader, LoadContext } from '../AssetLoader';import { getAssetTypeEntry } from '../../assetTypes';import { prepareSpine, type SpineAssetValue, type SpineIO } from '../../spine/prepareSpine';@@ -39,7 +40,11 @@ export class SpineAssetLoader implements AssetLoader<SpineAssetValue> {/** The asset layer as a spine transport: documents through the source door,* pages through the acquisition door — so the era holds every page receipt. */function spineIo(ctx: LoadContext, atlasRef: string): SpineIO {- const dir = atlasRef.substring(0, atlasRef.lastIndexOf('/'));+ // Pages are named relative to where the atlas was AUTHORED, not where staging+ // put it — content-addressing renames it to a hash under one flat directory,+ // and a sibling resolved against THAT is a file nobody shipped.+ const logical = ctx.catalog.addressOf(atlasRef) ?? atlasRef;+ const dir = logical.substring(0, logical.lastIndexOf('/'));return {// Read, not loaded: what these bytes say decides what the asset becomes,// which is exactly when a change to them must rebuild it.diff --git a/sdk/tests/spine-atlas-page-resolve.test.ts b/sdk/tests/spine-atlas-page-resolve.test.tsindex 9d4926142..e932c975b 100644--- a/sdk/tests/spine-atlas-page-resolve.test.ts+++ b/sdk/tests/spine-atlas-page-resolve.test.ts@@ -26,6 +26,8 @@ vi.mock('../src/wasm/resourceManager', () => ({}));import { loadSpineAssets } from '../src/spine/loadSpineScene';+import { SpineAssetLoader } from '../src/asset/loaders/SpineAssetLoader';+import { Catalog } from '../src/asset/Catalog';import type { RuntimeAssetSource } from '../src/runtime/runtimeAssets';import type { BasisTranscoder } from '../src/asset/compressed';@@ -130,3 +132,54 @@ describe('loadSpineAssets resolves atlas page paths through the manifest', () =>expect(info.get('assets/spine/boy.skel:assets/spine/boy.atlas')!.era.value.textures.size).toBe(0);});});++/**+ * The SAME question of the OTHER door. A registry acquisition goes through+ * SpineAssetLoader, which resolved page siblings against the STAGED directory —+ * so every spine in a content-addressed build drew nothing.+ */+describe('SpineAssetLoader page paths', () => {+ /** A pack as staging leaves it: every asset a hash under one flat directory,+ * addressable by the path it was authored at. */+ function stagedCatalog() {+ return Catalog.fromJson({+ version: 1,+ entries: {+ 'assets/spine/boy.atlas': { type: 'spine', buildPath: 'assets/079064052ce23797.atlas' },+ 'assets/spine/boy.skel': { type: 'spine', buildPath: 'assets/2f68d725077a3ab0.skel' },+ 'assets/spine/spineboy.png': { type: 'texture', buildPath: 'assets/97fac9903b799107.png' },+ },+ });+ }++ function ctxOver(catalog: Catalog, acquired: string[]) {+ return {+ catalog,+ loadText: async () => ATLAS,+ loadBinary: async () => new Uint8Array([1, 2, 3]).buffer,+ acquireTexture: async (path: string) => {+ acquired.push(path);+ return { value: { handle: 5, width: 8, height: 8 } };+ },+ } as never;+ }++ it('names a page where the atlas was AUTHORED, not where staging put it', async () => {+ const acquired: string[] = [];+ await new SpineAssetLoader().prepare(+ 'assets/2f68d725077a3ab0.skel', 'assets/079064052ce23797.atlas',+ ctxOver(stagedCatalog(), acquired),+ );+ expect(acquired).toEqual(['assets/spine/spineboy.png']);+ });++ it('falls back to the ref itself when nothing staged it', async () => {+ // Editor and dev realms hand over authored paths and carry no catalog.+ const acquired: string[] = [];+ await new SpineAssetLoader().prepare(+ 'assets/spine/boy.skel', 'assets/spine/boy.atlas',+ ctxOver(Catalog.empty(), acquired),+ );+ expect(acquired).toEqual(['assets/spine/spineboy.png']);+ });+});