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(sdk): play realm resolves project-relative asset paths (spine 404)

esengineb1bf64047c8d
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index e37739345..816e62cbf 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -186,6 +186,13 @@ async function runScreenshot(w: BrowserWindow, out: string): Promise<void> {
await settleFrames(2); // was sleep(400)
}
}
+ if (process.env.ESTELLA_SHOT_PLAY) {
+ await exec('window.__estellaEditor.play()');
+ await waitFor('window.__estellaEditor.playState().ready || !!window.__estellaEditor.playState().error', 'play realm ready', 20000);
+ const err = await exec('window.__estellaEditor.playState().error');
+ if (err) console.log('[play] error:', err);
+ await settleFrames(30); // let the game loop run so animation/assets settle
+ }
await settleFrames(12); // was sleep(2500) — let the engine loop spin up + fully paint the WebGL viewport
const img = await w.webContents.capturePage();
await writeFile(out, img.toPNG());
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 58b210df0..16998c0d2 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -34,6 +34,7 @@ import { App } from './App';
import { ProjectStore } from './project/ProjectStore';
import { useEditorStore } from './store/editorStore';
import { useSelection } from './store/selectionStore';
+import { PlayRealm } from './engine/PlayRealm';
import { EditorControlSurface } from './engine/EditorSession';
import { LogStore } from './store/LogStore';
import { initFsWatch } from './project/fsWatch';
@@ -58,6 +59,8 @@ if (new URLSearchParams(location.search).has('automation')) {
enterEditor: () => useEditorStore.getState().enterEditor(),
openScene: (rel: string) => ProjectStore.openScene(rel),
selectAsset: (path: string | null) => useSelection.getState().selectAsset(path),
+ play: () => useEditorStore.getState().togglePlay(),
+ playState: () => PlayRealm.getSnapshot(),
surface: EditorControlSurface,
};
}
diff --git a/sdk/src/playRealmRuntime.ts b/sdk/src/playRealmRuntime.ts
index 018e2d56d..741558b5b 100644
--- a/sdk/src/playRealmRuntime.ts
+++ b/sdk/src/playRealmRuntime.ts
@@ -64,18 +64,28 @@ export interface PlayRealmRuntimeConfig {
* `estella://` is fetchable because it's a privileged supportFetchAPI scheme; the
* editor returns `access-control-allow-origin: *`.
*/
-function createPlayRealmSource(manifest: Record<string, string>): RuntimeAssetSource {
- const backend = new HttpBackend({ baseUrl: '' });
- const resolveRef = (ref: string): string => {
- if (!ref.startsWith(UUID_PREFIX)) return ref;
+/**
+ * Resolve a play-realm asset ref to a fetchable URL: `@uuid:` refs go through the
+ * editor-supplied manifest; any other ref is a project-relative path (spine
+ * skel/atlas, …) and resolves against the project root, not the `.esengine/play/`
+ * subdir the realm runs from. Pure.
+ */
+export function resolvePlayAssetRef(ref: string, manifest: Record<string, string>, assetBaseUrl?: string): string {
+ if (ref.startsWith(UUID_PREFIX)) {
const url = manifest[ref.slice(UUID_PREFIX.length).toLowerCase()];
if (!url) throw new Error(`asset not in play manifest: ${ref}`);
return url;
- };
+ }
+ const base = (assetBaseUrl ?? '').replace(/\/$/, '');
+ return base ? `${base}/${ref.replace(/^\//, '')}` : ref;
+}
+
+function createPlayRealmSource(manifest: Record<string, string>, assetBaseUrl?: string): RuntimeAssetSource {
+ const backend = new HttpBackend({ baseUrl: '' });
return {
backend,
decodePixels: (path) => fetchDecodePixels(backend.resolveUrl(path)),
- resolveRef,
+ resolveRef: (ref) => resolvePlayAssetRef(ref, manifest, assetBaseUrl),
};
}
@@ -86,10 +96,9 @@ function createPlayRealmSource(manifest: Record<string, string>): RuntimeAssetSo
*/
export async function initPlayRealmRuntime(config: PlayRealmRuntimeConfig): Promise<void> {
const { app, module, canvas, sceneData, assetManifest, assetBaseUrl } = config;
- const source = createPlayRealmSource(assetManifest);
- // Point the audio channel at the project root: playSFX/playBGM take project-
- // relative paths, not uuid refs, so without this they resolve against the
- // play-realm subdir and 404.
+ const source = createPlayRealmSource(assetManifest, assetBaseUrl);
+ // Audio has its own loader (not the asset source), so point it at the project
+ // root too: playSFX/playBGM take project-relative paths, not uuid refs.
if (assetBaseUrl && app.hasResource(Audio)) {
app.getResource(Audio).baseUrl = assetBaseUrl;
}
diff --git a/sdk/tests/play-asset-ref.test.ts b/sdk/tests/play-asset-ref.test.ts
new file mode 100644
index 000000000..9607d0e95
--- /dev/null
+++ b/sdk/tests/play-asset-ref.test.ts
@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Play-realm asset ref resolution: uuid refs → manifest, project-relative
+ * paths (spine skel/atlas, …) → the project root, not the play subdir.
+ */
+import { describe, it, expect } from 'vitest';
+import { resolvePlayAssetRef } from '../src/playRealmRuntime';
+
+const MANIFEST = { 'aaaa': 'estella://project/assets/textures/hero.png' };
+const BASE = 'estella://project';
+
+describe('resolvePlayAssetRef', () => {
+ it('resolves a uuid ref through the manifest', () => {
+ expect(resolvePlayAssetRef('@uuid:AAAA', MANIFEST, BASE)).toBe('estella://project/assets/textures/hero.png');
+ });
+
+ it('resolves a project-relative path against the project root (was 404 in the play subdir)', () => {
+ expect(resolvePlayAssetRef('assets/spine/spineboy.atlas', MANIFEST, BASE)).toBe('estella://project/assets/spine/spineboy.atlas');
+ });
+
+ it('normalizes a leading slash and a trailing slash on the base', () => {
+ expect(resolvePlayAssetRef('/assets/spine/x.skel', MANIFEST, 'estella://project/')).toBe('estella://project/assets/spine/x.skel');
+ });
+
+ it('leaves a path unchanged when no base is given (shipped game keeps its own manifest)', () => {
+ expect(resolvePlayAssetRef('assets/spine/x.atlas', MANIFEST, undefined)).toBe('assets/spine/x.atlas');
+ });
+
+ it('throws for a uuid ref missing from the manifest', () => {
+ expect(() => resolvePlayAssetRef('@uuid:zzzz', MANIFEST, BASE)).toThrow(/not in play manifest/);
+ });
+});