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(playable): a playable waits for its shaders when the project asks it to - prewarmShaders was read by the web host alone, so a single-file page opened on an empty scene that filled in over seconds; its canvas is now kept out of sight while the first scene's shaders compile, for prewarmTimeoutMs at most

yhhded7dada5bff
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5186268c2..d8d9d43f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,8 @@ published separately; it ships inside the editor.
### Fixed
+- **A ground's layer pictures are read together.** A Terrain with layers is not drawn until every layer's albedo, normal and mask have been read, and they were read one after another. A picture that is an `.esimage` recipe is drawn when it is read, so a ground of four layers with recipes for all three stayed out of sight for as long as twelve drawings took in a row. They are now all asked for at once, and recipes are drawn on as many workers as the device has. How much sooner a ground appears was not timed.
+- **A playable waits for its shaders when the project asks it to.** `quality.prewarmShaders` (with `asyncShaderCompile`) was acted on by the web host alone: a single-file playable opened at once on a scene with most of it missing and filled in over the next seconds. A playable has no splash to draw behind, so its canvas is kept out of sight while the first scene's frames are drawn and its shaders compile, and shown when nothing is compiling any more or after `prewarmTimeoutMs`. `initPlayableRuntime` takes it as `prewarmShaders`.
- **A wide blurred text shadow is one soft shape.** `Text.shadowBlur` was drawn as one ring of eight copies of the label at the blur's own radius, whatever that radius was. At two or three pixels that is a soft edge; at eighteen it is the label nine times over, fourteen pixels apart, and a title set large stood in blocks of dark squares round every stroke. Past three pixels a shadow is now as many rings of copies as keep each within a stroke's thickness of its neighbours (a share of the font size), sixty-four copies at the most, so it reads as one soft shape. A blur of three pixels or less is drawn as it was.
- **A mesh scattered with no material keeps its own colours.** A `Foliage` field with no material is painted, since nothing reads the wind's weights then, and it painted every plant the stock green of grass from root to tip, whatever the mesh's own vertex colours said: a grey rock scattered along a shore came out a smooth green one, and a dark spruce a pale one. A mesh that has colours of its own is now painted in them, each plant a little lighter or darker by its shade; a mesh with no colour channel, or white throughout, is painted as before.
- **A playable samples its textures as their import settings say.** A single-file playable was handed no manifest, which is the only way a texture's `.meta` reaches a package, so its wrap mode, its filter, whether it is colour and its 9-slice border were all lost and every texture took the defaults. A ground or a wall whose picture repeats then drew one copy of it and smeared its last row of pixels over everything past the first tile: cliffs came out one flat colour with level stripes along the waterline, while the same scene was right in the editor and in a web export. The settings of the textures a playable inlines now ride in the page and reach the runtime the way they reach every other package.
diff --git a/pipeline/src/runtime/playableHost.ts b/pipeline/src/runtime/playableHost.ts
index ea83e3101..280f5bfa4 100644
--- a/pipeline/src/runtime/playableHost.ts
+++ b/pipeline/src/runtime/playableHost.ts
@@ -156,6 +156,9 @@ async function boot(): Promise<void> {
manifest: typeof __GAME_MANIFEST__ !== 'undefined' ? __GAME_MANIFEST__ : undefined,
scenes: __GAME_SCENES__,
firstScene: __GAME_FIRST__,
+ // The same condition the web host warms on: shaders compiled in the background, and the project asked to open on a complete picture.
+ ...(runtimeConfig.quality?.asyncShaderCompile && runtimeConfig.quality.prewarmShaders
+ ? { prewarmShaders: { timeoutMs: runtimeConfig.quality.prewarmTimeoutMs } } : {}),
// Everything the config APPLIES to a live app: physics, the mixer, the theme.
...packagedRuntimeInit(runtimeConfig),
});
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 4c4e8d496..75ab92cee 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -8095,6 +8095,7 @@ physics3dBackend: Physics3DBackend | undefined
physics3dWorld: Partial<Physics3DWorldConfig> | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
+prewarmShaders: { timeoutMs?: number; } | undefined
runtime: RuntimeBuildConfig | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "light" | "dark" | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 54b754349..c97527af1 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -8309,6 +8309,7 @@ physics3dBackend: Physics3DBackend | undefined
physics3dWorld: Partial<Physics3DWorldConfig> | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
+prewarmShaders: { timeoutMs?: number; } | undefined
runtime: RuntimeBuildConfig | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "light" | "dark" | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 13e221558..82aa80096 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -8090,6 +8090,7 @@ physics3dBackend: Physics3DBackend | undefined
physics3dWorld: Partial<Physics3DWorldConfig> | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
+prewarmShaders: { timeoutMs?: number; } | undefined
runtime: RuntimeBuildConfig | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "light" | "dark" | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index c069b0a12..6bacf117a 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -8387,6 +8387,7 @@ physics3dBackend: Physics3DBackend | undefined
physics3dWorld: Partial<Physics3DWorldConfig> | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
+prewarmShaders: { timeoutMs?: number; } | undefined
runtime: RuntimeBuildConfig | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "light" | "dark" | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f6af70038..c7abf9649 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -8097,6 +8097,7 @@ physics3dBackend: Physics3DBackend | undefined
physics3dWorld: Partial<Physics3DWorldConfig> | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
+prewarmShaders: { timeoutMs?: number; } | undefined
runtime: RuntimeBuildConfig | undefined
scenes: { name: string; data: SceneData; }[]
uiTheme: "light" | "dark" | undefined
diff --git a/sdk/src/runtime/playableRuntime.ts b/sdk/src/runtime/playableRuntime.ts
index 386833dc5..1297ad797 100644
--- a/sdk/src/runtime/playableRuntime.ts
+++ b/sdk/src/runtime/playableRuntime.ts
@@ -16,6 +16,8 @@ import type { ESEngineModule } from '../wasm';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
import type { RuntimeBuildConfig } from '../defaults';
import { initRuntime } from './runtimeLoader';
+import { warmShaders } from '../render/shaderWarmup';
+import { log } from '../util/logger';
import type { ThemeOverrides } from '../ui';
import type { RuntimeAssetSource } from './runtimeAssets';
import { EmbeddedBackend } from '../asset/Backend';
@@ -68,6 +70,11 @@ export interface PlayableRuntimeConfig {
/** Bitmask of render layers (0..31) that resolve by real depth (2.5D). */
depthLayers?: number;
manifest?: AddressableManifest | null;
+ /**
+ * Draw the first scene out of sight (the canvas hidden) until its shaders have compiled, and show it complete: `quality.prewarmShaders` of a
+ * project that also compiles them in the background. The wait is at most `timeoutMs`.
+ */
+ prewarmShaders?: { timeoutMs?: number };
}
function decodeDataUrlBinary(dataUrl: string): Uint8Array {
@@ -195,6 +202,20 @@ export async function initPlayableRuntime(config: PlayableRuntimeConfig): Promis
},
});
}
+ if (config.prewarmShaders) {
+ // A playable has no splash to draw behind: the canvas itself is kept out of sight, and the page's background is what shows.
+ const style = config.canvas.style;
+ const shown = style.visibility;
+ style.visibility = 'hidden';
+ try {
+ const warmed = await warmShaders(app, { timeoutMs: config.prewarmShaders.timeoutMs });
+ if (warmed.timedOut) log.warn('playable', `${warmed.pending} shader(s) still compiling after ${Math.round(warmed.ms)} ms; opening anyway`);
+ } catch (e) {
+ log.warn('playable', 'shader warm-up failed', e);
+ } finally {
+ style.visibility = shown;
+ }
+ }
await app.run();
bridge?.ready?.();
}
diff --git a/sdk/tests/playableRuntime.test.ts b/sdk/tests/playableRuntime.test.ts
index c1024fbbe..c22ee0121 100644
--- a/sdk/tests/playableRuntime.test.ts
+++ b/sdk/tests/playableRuntime.test.ts
@@ -75,6 +75,26 @@ describe('initPlayableRuntime', () => {
app.quit(); expect(release).toHaveBeenCalledTimes(1);
});
+ it('draws out of sight until the shaders have compiled, when asked to', async () => {
+ let compiling = 2;
+ const seen: string[] = [];
+ const canvas = { width: 320, height: 480, style: { visibility: '' } } as unknown as HTMLCanvasElement;
+ const config = createMockConfig({ canvas, prewarmShaders: { timeoutMs: 5000 } });
+ (config.app as any).wasmModule = { renderer_getPendingShaders: () => compiling };
+ (config.app as any).stepFrames = vi.fn(async () => { seen.push(`frame:${canvas.style.visibility}`); if (compiling > 0) --compiling; });
+ (config.app as any).run = vi.fn(async () => { seen.push(`run:${canvas.style.visibility}`); });
+ await initPlayableRuntime(config);
+ expect(seen.filter((s) => s.startsWith('frame')).every((s) => s === 'frame:hidden')).toBe(true);
+ expect(seen.length).toBeGreaterThan(3);
+ expect(seen.at(-1)).toBe('run:');
+
+ // Not asked: no frame is drawn before the loop starts.
+ const plain = createMockConfig();
+ (plain.app as any).stepFrames = vi.fn();
+ await initPlayableRuntime(plain);
+ expect((plain.app as any).stepFrames).not.toHaveBeenCalled();
+ });
+
it('passes scenes array and firstScene to initRuntime', async () => {
const scenes = [
{ name: 'level1', data: { version: '1', name: 'level1', entities: [] } as any },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index af1792ebb..638d6c256 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4776,4 +4776,8 @@ export const NOTED = {
{"note": "A mesh scattered with no material keeps its own colours."},
"fix(text): a wide blurred shadow is one soft shape - a blur was always one ring of eight copies of the label at its own radius, which is a soft edge at two or three pixels and nine separate labels at eighteen: a title set large stood in blocks of dark squares; past three pixels the copies are as many rings as keep each within a stroke's thickness of its neighbours, sixty-four at the most":
{"note": "A wide blurred text shadow is one soft shape."},
+ "fix(playable): a playable waits for its shaders when the project asks it to - prewarmShaders was read by the web host alone, so a single-file page opened on an empty scene that filled in over seconds; its canvas is now kept out of sight while the first scene's shaders compile, for prewarmTimeoutMs at most":
+ {"note": "A playable waits for its shaders when the project asks it to."},
+ "perf(terrain): a ground's layer pictures are read together - each layer's albedo, normal and mask were read one after another, and a picture that is a recipe is drawn when it is read, so a ground of four layers stayed out of sight for as long as twelve drawings took in a row; they are asked for at once and drawn on as many workers as there are":
+ {"note": "A ground's layer pictures are read together."},
};