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(spine): a released build's atlas pages are where the atlas was authored

esengine09ff6aac4c86
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Changed
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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 | null
getAllLabels: () => string[]
getAtlasFrame: (path: string) => AtlasFrameInfo | null
getBuildPath: (path: string) => string
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 | null
getAllLabels: () => string[]
getAtlasFrame: (path: string) => AtlasFrameInfo | null
getBuildPath: (path: string) => string
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | null
getAllLabels: () => string[]
getAtlasFrame: (path: string) => AtlasFrameInfo | null
getBuildPath: (path: string) => string
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 | null
getAllLabels: () => string[]
getAtlasFrame: (path: string) => AtlasFrameInfo | null
getBuildPath: (path: string) => string
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 | null
getAllLabels: () => string[]
getAtlasFrame: (path: string) => AtlasFrameInfo | null
getBuildPath: (path: string) => string
diff --git a/sdk/src/asset/Catalog.ts b/sdk/src/asset/Catalog.ts
index 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.ts
index 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.ts
index 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']);
+ });
+});