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(render): a shader warm-up waits for the scene still being made - it stopped at the first three frames with nothing compiling, and a ground still painting its pages or a field still growing its cells asks for its shaders seconds later: half the runs of one scene opened early and filled in; Terrain and Foliage now hold the warm-up while they prepare (holdShaderWarmup)
yhh05c6df50b430
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d8d9d43f1..279e4290a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -34,6 +34,8 @@ published separately; it ships inside the editor.### Fixed+- **Sprite and particle shaders compile in the background too.** With `quality.asyncShaderCompile`, mesh and material shaders were compiled without holding a frame, and the batch shader's variants (sprites, text, lit sprites) and the particle shader were not: each was linked in place when first needed, measured at 350 to 490 ms of one frame mid-play under ANGLE. They are deferred the same way now, their texture units set when the link lands. Without the setting nothing changes.+- **A shader warm-up waits for the scene still being made.** `warmShaders` (what `quality.prewarmShaders` runs behind the loading screen) stopped at the first three frames in which nothing was compiling. A ground still painting its pages or a field still growing its cells draws seconds later, with shaders nothing had asked for yet, so whether a scene opened complete depended on which arrived first: of the runs of one lake scene, about half opened at 13 s and went on compiling for eight more, the rest at 25 s and complete. Terrain and Foliage now hold the warm-up while they are preparing, and every run opens complete; `holdShaderWarmup(app, busy)` is how a game's own generated content does the same. The wait is still bounded by `prewarmTimeoutMs`.- **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.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 75ab92cee..5bade0d0c 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2190 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2191 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -11796,6 +11796,7 @@ loading: booleannormalAt: (x: number, z: number) => [number, number, number] | nullpaintAt: (x: number, z: number) => readonly number[] | nullpending: number+preparing: booleanraycast: (origin: { x: number; y: number; z: number; }, direction: { x: number; y: number; z: number; }, maxDistance: number) => { distance: number; point: { x: number; y: number; z: number; }; normal: { x: number; y: number; z: number; }; entity: Entity; } | nullrepaint: () => voidsetModifier: (modifier: TerrainModifier) => void@@ -16363,6 +16364,11 @@ Plugin(width: number, height: number, pixels: ArrayLike<number>, format?: number, wide?: ArrayLike<number>): Heightfield```+## holdShaderWarmup — function @experimental+```+(app: App, busy: () => boolean): () => void+```+## imageBitmapOptions — function @experimental```(flip: boolean): ImageBitmapOptionsdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c97527af1..1161bcd32 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 171 beta · 2210 experimental · 3 deprecated+Symbols: 115 public · 171 beta · 2211 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -12025,6 +12025,7 @@ loading: booleannormalAt: (x: number, z: number) => [number, number, number] | nullpaintAt: (x: number, z: number) => readonly number[] | nullpending: number+preparing: booleanraycast: (origin: { x: number; y: number; z: number; }, direction: { x: number; y: number; z: number; }, maxDistance: number) => { distance: number; point: { x: number; y: number; z: number; }; normal: { x: number; y: number; z: number; }; entity: Entity; } | nullrepaint: () => voidsetModifier: (modifier: TerrainModifier) => void@@ -16632,6 +16633,11 @@ Plugin(width: number, height: number, pixels: ArrayLike<number>, format?: number, wide?: ArrayLike<number>): Heightfield```+## holdShaderWarmup — function @experimental+```+(app: App, busy: () => boolean): () => void+```+## imageBitmapOptions — function @experimental```(flip: boolean): ImageBitmapOptionsdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 82aa80096..f701fa3e9 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 168 beta · 2189 experimental · 3 deprecated+Symbols: 115 public · 168 beta · 2190 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -11791,6 +11791,7 @@ loading: booleannormalAt: (x: number, z: number) => [number, number, number] | nullpaintAt: (x: number, z: number) => readonly number[] | nullpending: number+preparing: booleanraycast: (origin: { x: number; y: number; z: number; }, direction: { x: number; y: number; z: number; }, maxDistance: number) => { distance: number; point: { x: number; y: number; z: number; }; normal: { x: number; y: number; z: number; }; entity: Entity; } | nullrepaint: () => voidsetModifier: (modifier: TerrainModifier) => void@@ -16358,6 +16359,11 @@ Plugin(width: number, height: number, pixels: ArrayLike<number>, format?: number, wide?: ArrayLike<number>): Heightfield```+## holdShaderWarmup — function @experimental+```+(app: App, busy: () => boolean): () => void+```+## imageBitmapOptions — function @experimental```(flip: boolean): ImageBitmapOptionsdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 6bacf117a..48418580a 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2211 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2212 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -12088,6 +12088,7 @@ loading: booleannormalAt: (x: number, z: number) => [number, number, number] | nullpaintAt: (x: number, z: number) => readonly number[] | nullpending: number+preparing: booleanraycast: (origin: { x: number; y: number; z: number; }, direction: { x: number; y: number; z: number; }, maxDistance: number) => { distance: number; point: { x: number; y: number; z: number; }; normal: { x: number; y: number; z: number; }; entity: Entity; } | nullrepaint: () => voidsetModifier: (modifier: TerrainModifier) => void@@ -16666,6 +16667,11 @@ Plugin(width: number, height: number, pixels: ArrayLike<number>, format?: number, wide?: ArrayLike<number>): Heightfield```+## holdShaderWarmup — function @experimental+```+(app: App, busy: () => boolean): () => void+```+## imageBitmapOptions — function @experimental```(flip: boolean): ImageBitmapOptionsdiff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.mdindex 3ce7bad57..c920fe56c 100644--- a/sdk/etc/terrain.api.md+++ b/sdk/etc/terrain.api.md@@ -652,6 +652,7 @@ loading: booleannormalAt: (x: number, z: number) => [number, number, number] | nullpaintAt: (x: number, z: number) => readonly number[] | nullpending: number+preparing: booleanraycast: (origin: { x: number; y: number; z: number; }, direction: { x: number; y: number; z: number; }, maxDistance: number) => { distance: number; point: { x: number; y: number; z: number; }; normal: { x: number; y: number; z: number; }; entity: Entity; } | nullrepaint: () => voidsetModifier: (modifier: TerrainModifier) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex c7abf9649..3831dfc66 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2202 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2203 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -11798,6 +11798,7 @@ loading: booleannormalAt: (x: number, z: number) => [number, number, number] | nullpaintAt: (x: number, z: number) => readonly number[] | nullpending: number+preparing: booleanraycast: (origin: { x: number; y: number; z: number; }, direction: { x: number; y: number; z: number; }, maxDistance: number) => { distance: number; point: { x: number; y: number; z: number; }; normal: { x: number; y: number; z: number; }; entity: Entity; } | nullrepaint: () => voidsetModifier: (modifier: TerrainModifier) => void@@ -16392,6 +16393,11 @@ Plugin(width: number, height: number, pixels: ArrayLike<number>, format?: number, wide?: ArrayLike<number>): Heightfield```+## holdShaderWarmup — function @experimental+```+(app: App, busy: () => boolean): () => void+```+## imageBitmapOptions — function @experimental```(flip: boolean): ImageBitmapOptionsdiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex b00ede974..715ad7d2c 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -363,7 +363,7 @@ export type {QualityReport, QualitySample, FrameVerdict, DeviceQualityInfo, DeviceQualityRule,} from './render/quality';export { Quality } from './render/qualityRuntime';-export { warmShaders, shadersCompiled, pendingShaders } from './render/shaderWarmup';+export { warmShaders, shadersCompiled, pendingShaders, holdShaderWarmup } from './render/shaderWarmup';export { RenderDemand } from './render/renderDemand';export { buildPathGeometry, mergeGeometry, cubicBezier, quadraticBezier, circlePoints } from './render/vectorPath';export type { PathStyle, PathFill, PathStroke, PathColor, LineJoin, LineCap } from './render/vectorPath';diff --git a/sdk/src/foliage/foliagePlugin.ts b/sdk/src/foliage/foliagePlugin.tsindex ad3c173d8..a0681d7d8 100644--- a/sdk/src/foliage/foliagePlugin.ts+++ b/sdk/src/foliage/foliagePlugin.ts@@ -25,6 +25,7 @@ import { chunksOf, ProceduralChunksRes, type ChunkLayerStatus } from '../residenimport type { Entity } from '../types';import { TerrainsRes } from '../terrain/terrainPlugin';import { Material } from '../render/material';+import { holdShaderWarmup } from '../render/shaderWarmup';import { currentWeather, currentWeatherDrive, WeatherDrive } from '../postprocess/weather';import { isEditor, isPlayMode } from '../ecs/env';import type { Zones } from '../worldgen/zones';@@ -288,6 +289,8 @@ export class FoliagePlugin implements Plugin {const field = new FoliageField();field.app_ = app;app.insertResource(FoliageRes, field);+ // Cells still to be grown, or grown and not yet put in the world, draw with shaders nothing has asked for yet.+ holdShaderWarmup(app, () => app.hasResource(Assets) && (field.pending > 0 || field.landed_.length > 0));this.clearContacts_ = installFoliageContacts(app);app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {diff --git a/sdk/src/render/shaderWarmup.ts b/sdk/src/render/shaderWarmup.tsindex a3a92f34b..2c9afb981 100644--- a/sdk/src/render/shaderWarmup.ts+++ b/sdk/src/render/shaderWarmup.ts@@ -33,6 +33,30 @@ export interface ShaderWarmupOptions {onProgress?: (pending: number) => void;}+const holds = new WeakMap<App, Set<() => boolean>>();++/**+ * Tells {@link warmShaders} that part of the scene is still being made while `busy` answers true: a ground whose pages are being painted, a field+ * whose cells are being grown. What is made later draws with shaders nothing has asked for yet, and a warm-up that stopped at the first quiet+ * frames opened on a scene that then filled in. Returns what takes the hold away.+ * @experimental+ */+export function holdShaderWarmup(app: App, busy: () => boolean): () => void {+ let set = holds.get(app);+ if (!set) holds.set(app, set = new Set());+ set.add(busy);+ return () => { set.delete(busy); };+}++function held(app: App): boolean {+ const set = holds.get(app);+ if (!set) return false;+ for (const busy of set) {+ try { if (busy()) return true; } catch { /* a probe that throws holds nothing */ }+ }+ return false;+}+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));const now = (): number => (typeof performance !== 'undefined' ? performance.now() : Date.now());@@ -63,6 +87,7 @@ export async function shadersCompiled(module: ESEngineModule | null, timeoutMs =** The frames advance the world by a tenth of a millisecond each: they exist to make the renderer ask for the shaders the scene needs (a variant is* only asked for when something first draws with it), not to play the game. Meant for a loading screen, before the first visible frame.+ * It also waits for what {@link holdShaderWarmup} says is still being made.* @experimental*/export async function warmShaders(app: App, options: ShaderWarmupOptions = {}): Promise<ShaderWarmup> {@@ -81,7 +106,8 @@ export async function warmShaders(app: App, options: ShaderWarmupOptions = {}):++frames;pending = module.renderer_getPendingShaders?.() ?? 0;options.onProgress?.(pending);- quiet = pending === 0 ? quiet + 1 : 0;+ // Quiet is nothing compiling AND nothing still being made that will ask for more.+ quiet = pending === 0 && !held(app) ? quiet + 1 : 0;// The browser compiles between tasks: give it one.await sleep(8);}diff --git a/sdk/src/terrain/terrainPlugin.ts b/sdk/src/terrain/terrainPlugin.tsindex b7e830fbc..cc27d65dd 100644--- a/sdk/src/terrain/terrainPlugin.ts+++ b/sdk/src/terrain/terrainPlugin.ts@@ -29,6 +29,7 @@ import { decodeImagePixels } from '../asset/imageDecode';import { decodePngData } from '../asset/pngData';import { Material, MATERIAL_FORMAT_VERSION } from '../render/material';import { BlendMode } from '../render/blend';+import { holdShaderWarmup } from '../render/shaderWarmup';import { createTextureArrayFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';import { getResourceManager, withdrawTextureContent } from '../wasm/resourceManager';import { TextureContent } from '../wasm';@@ -593,6 +594,15 @@ export class Terrains {return false;}+ /** A ground is not drawn yet, or its layers are still being packed: what it draws with has not all been asked for. */+ get preparing(): boolean {+ for (const b of this.built_.values()) {+ if (b.failure) continue;+ if (b.loading || !b.instance || b.packing || b.wanted.size > 0) return true;+ }+ return false;+ }+/** How many pages every terrain still wants made for what is in view. */get pending(): number {let n = 0;@@ -673,6 +683,7 @@ export class TerrainPlugin implements Plugin {const terrains = new Terrains();terrains.app_ = app;app.insertResource(TerrainsRes, terrains);+ holdShaderWarmup(app, () => app.hasResource(Assets) && terrains.preparing);app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {// What the ground IS needs no renderer: a server or a test without one still makes the source and answers from it.diff --git a/sdk/tests/shader-warmup.test.ts b/sdk/tests/shader-warmup.test.tsindex 70fb985dd..19ce9e097 100644--- a/sdk/tests/shader-warmup.test.ts+++ b/sdk/tests/shader-warmup.test.ts@@ -4,7 +4,7 @@ import { describe, expect, it, vi } from 'vitest';import type { App } from '../src/app/app';import type { ESEngineModule } from '../src/wasm';import { parseQualityConfig } from '../src/render/quality';-import { pendingShaders, shadersCompiled, warmShaders } from '../src/render/shaderWarmup';+import { holdShaderWarmup, pendingShaders, shadersCompiled, warmShaders } from '../src/render/shaderWarmup';/** A module whose compile queue drains by one on every read after `drainAfter` reads. */function moduleWithQueue(initial: number, drainEvery = 1): ESEngineModule {@@ -43,6 +43,23 @@ describe('shader warm-up', () => {expect(seen.some((n) => n > 0)).toBe(true);});+ it('waits for what is still being made, though nothing is compiling', async () => {+ // Content that arrives later asks for shaders nobody has asked for yet: the queue being empty for a few frames is not the scene being ready.+ const { app, stepFrames } = appOf(moduleWithQueue(0));+ let making = 6;+ const release = holdShaderWarmup(app, () => making > 0);+ stepFrames.mockImplementation(async () => { if (making > 0) --making; });+ const held = await warmShaders(app, { settleFrames: 2 });+ expect(held.timedOut).toBe(false);+ expect(held.frames).toBe(6 + 1);++ // A hold that never lets go is bounded by the timeout, and one taken away holds nothing.+ making = Infinity;+ expect((await warmShaders(app, { timeoutMs: 40 })).timedOut).toBe(true);+ release();+ expect((await warmShaders(app, { settleFrames: 2, timeoutMs: 400 })).frames).toBe(2);+ });+it('does nothing where there is nothing to wait for', async () => {const { app, stepFrames } = appOf({} as ESEngineModule);expect(await warmShaders(app)).toEqual({ frames: 0, ms: 0, pending: 0, timedOut: false });diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 638d6c256..e84da2e8f 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4780,4 +4780,8 @@ export const NOTED = {{"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."},+ "fix(render): a shader warm-up waits for the scene still being made - it stopped at the first three frames with nothing compiling, and a ground still painting its pages or a field still growing its cells asks for its shaders seconds later: half the runs of one scene opened early and filled in; Terrain and Foliage now hold the warm-up while they prepare (holdShaderWarmup)":+ {"note": "A shader warm-up waits for the scene still being made."},+ "perf(render): sprite and particle shaders compile in the background too - the batch shader's variants and the particle shader were linked in place whatever asyncShaderCompile said, a third to half a second of one frame when a lit sprite or the first particle appeared; they are deferred as mesh shaders are, their samplers seeded when the link lands":+ {"note": "Sprite and particle shaders compile in the background too."},};