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(sdk): play realm resolves project-relative asset paths (spine 404)
esengineb1bf64047c8d
diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 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 viewportconst img = await w.webContents.capturePage();await writeFile(out, img.toPNG());diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex 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.tsindex 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.tsnew file mode 100644index 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/);+ });+});