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(profiler): a long block in the render submit is work, not vsync, and text has a scope of its own

yhh52009c167781
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 751f0f900..c4d39a477 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,7 @@ published separately; it ships inside the editor.
### Fixed
+- **The profiler no longer calls a long render stall vsync.** Time in the render submit that nothing measured was all filed as "present · vsync", with a hint that it was idle: an 820 ms frame spent growing text outlines read as waiting, and its banner blamed two domains of 0.1 ms. A wait now counts up to 50 ms, the slowest a display presents; the rest shows as "untimed work", marked as a hotspot. Text drawing has its own `render.text` row, and when timed work explains under half an over-budget frame the banner says so instead of naming a domain. `ScopeCost` gains `parent`: a scope measured inside another is listed under it.
- **While editing, foliage and generated worlds follow the viewport.** A `WorldStreamingSource` in the scene used to hold foliage, generated worlds and voxels around itself in the edit view while terrain detail followed the viewport, and a 2D view counted as no viewpoint at all. Sculpting and painting a terrain also no longer copies the whole ground at each stroke: it keeps 32 by 32 tiles as they are first touched, so a diagonal stroke's undo holds what it reached and not the square around it.
- **Zooming in on outlined text no longer freezes the editor.** Growing a bitmap glyph into its outline cost the fourth power of its size on screen, and a label did it again for every glyph at each step of the zoom: past 1500% a single frame took more than 15 seconds, and showing a hidden label at full zoom hung the editor. The outline now costs what the glyph's size does and looks the same, a frame stays under about 70 ms through the whole zoom, and `Auto` text at 128 screen pixels or more draws from a distance field wide enough to hold its outline. `Bitmap` is still honored where it is set, at the new cost.
- **Labels no longer come back as black boxes after a change between Plays.** Stopping left each label's geometry in the engine, by entity number. Adding, removing or dragging anything before pressing Play again moved those numbers, so the old labels drew on other entities from an atlas already released.
diff --git a/desktop b/desktop
index 0a4da26fa..57e06b730 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 0a4da26fa04918d523c2f6133b48406ef19eb7ee
+Subproject commit 57e06b73031b31aa955d6b023af1ba34734a338b
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 7c245fd40..132c14bd4 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 · 2109 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2111 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6026,6 +6026,11 @@ Restart = 1
8
```
+## MAX_PRESENT_WAIT_MS — const @experimental
+```
+50
+```
+
## MAX_SEQUENCE_DEPTH — const @experimental
```
4
@@ -9578,6 +9583,7 @@ Update = 3
```
ms: number
name: string
+parent: string | undefined
remainder: ScopeRemainder
system: string
```
@@ -12827,6 +12833,11 @@ SolidColor = 1
Tiled = 4
```
+## UNTIMED_SCOPE_LABEL — const @experimental
+```
+"untimed"
+```
+
## UniformValue — type @experimental
```
number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index e5e4abdee..bde9048ec 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 · 2128 experimental · 3 deprecated
+Symbols: 115 public · 171 beta · 2130 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6034,6 +6034,11 @@ Restart = 1
8
```
+## MAX_PRESENT_WAIT_MS — const @experimental
+```
+50
+```
+
## MAX_SEQUENCE_DEPTH — const @experimental
```
4
@@ -9794,6 +9799,7 @@ Update = 3
```
ms: number
name: string
+parent: string | undefined
remainder: ScopeRemainder
system: string
```
@@ -13043,6 +13049,11 @@ SolidColor = 1
Tiled = 4
```
+## UNTIMED_SCOPE_LABEL — const @experimental
+```
+"untimed"
+```
+
## UniformValue — type @experimental
```
number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 53040ebb7..898cb732c 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 · 2108 experimental · 3 deprecated
+Symbols: 115 public · 168 beta · 2110 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6021,6 +6021,11 @@ Restart = 1
8
```
+## MAX_PRESENT_WAIT_MS — const @experimental
+```
+50
+```
+
## MAX_SEQUENCE_DEPTH — const @experimental
```
4
@@ -9573,6 +9578,7 @@ Update = 3
```
ms: number
name: string
+parent: string | undefined
remainder: ScopeRemainder
system: string
```
@@ -12822,6 +12828,11 @@ SolidColor = 1
Tiled = 4
```
+## UNTIMED_SCOPE_LABEL — const @experimental
+```
+"untimed"
+```
+
## UniformValue — type @experimental
```
number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2a1562fd9..bbf57255b 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 · 2130 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2132 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6021,6 +6021,11 @@ Restart = 1
8
```
+## MAX_PRESENT_WAIT_MS — const @experimental
+```
+50
+```
+
## MAX_SEQUENCE_DEPTH — const @experimental
```
4
@@ -9869,6 +9874,7 @@ Update = 3
```
ms: number
name: string
+parent: string | undefined
remainder: ScopeRemainder
system: string
```
@@ -13118,6 +13124,11 @@ SolidColor = 1
Tiled = 4
```
+## UNTIMED_SCOPE_LABEL — const @experimental
+```
+"untimed"
+```
+
## UniformValue — type @experimental
```
number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 0186ff597..afd51479a 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 · 2121 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2123 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6028,6 +6028,11 @@ Restart = 1
8
```
+## MAX_PRESENT_WAIT_MS — const @experimental
+```
+50
+```
+
## MAX_SEQUENCE_DEPTH — const @experimental
```
4
@@ -9580,6 +9585,7 @@ Update = 3
```
ms: number
name: string
+parent: string | undefined
remainder: ScopeRemainder
system: string
```
@@ -12829,6 +12835,11 @@ SolidColor = 1
Tiled = 4
```
+## UNTIMED_SCOPE_LABEL — const @experimental
+```
+"untimed"
+```
+
## UniformValue — type @experimental
```
number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index f2e10b7ad..c77917cff 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -248,6 +248,7 @@ export class App {
private frameScopes_: Map<string, ScopeCost> | null = null;
/** The system being run, so a scope opened inside one is filed under it. */
private currentSystem_ = '';
+ private readonly openScopes_: string[] = [];
private readonly frameObservers_: Array<(dtMs: number) => void> = [];
private frame_paused_ = false;
private user_paused_ = false;
@@ -1068,17 +1069,21 @@ export class App {
measureFrameScope<T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder }): T {
const scopes = this.frameScopes_;
if (!scopes) return fn();
+ const parent = this.openScopes_[this.openScopes_.length - 1];
+ this.openScopes_.push(name);
const t0 = performance.now();
try {
return fn();
} finally {
const elapsed = performance.now() - t0;
+ this.openScopes_.pop();
const prev = scopes.get(name);
scopes.set(name, {
name,
ms: (prev?.ms ?? 0) + elapsed,
system: prev?.system ?? this.currentSystem_,
remainder: options?.remainder ?? 'work',
+ ...(parent !== undefined ? { parent } : {}),
});
}
}
diff --git a/sdk/src/app/frameProfile.ts b/sdk/src/app/frameProfile.ts
index 460da7cd6..329d4c501 100644
--- a/sdk/src/app/frameProfile.ts
+++ b/sdk/src/app/frameProfile.ts
@@ -13,6 +13,12 @@ export const DOMAIN_SCRIPTS = 'scripts';
/** Systems registered outside both a plugin build and the project bundle. */
export const DOMAIN_UNATTRIBUTED = 'unattributed';
+/** No display refreshes slower than this, so a longer block is not a present. */
+export const MAX_PRESENT_WAIT_MS = 50;
+
+/** The label of the row holding render time that no scope measured and no present explains. */
+export const UNTIMED_SCOPE_LABEL = 'untimed';
+
/** Time under a scope that none of its children claimed. */
export type ScopeRemainder = 'work' | 'wait';
@@ -30,6 +36,8 @@ export interface ScopeCost {
/** The system this ran inside; '' when it ran outside every system. */
readonly system: string;
readonly remainder: ScopeRemainder;
+ /** The scope this ran inside. Its time is part of that scope's, not beside it. */
+ readonly parent?: string;
}
export interface FrameProfileInput {
@@ -178,11 +186,25 @@ export function buildFrameProfile(input: FrameProfileInput): FrameProfile {
if (list) list.push(n); else nativeByDomain.set(d, [n]);
}
+ const named = new Set(input.scopes.map((s) => s.name));
+ const nestedByParent = new Map<string, ScopeCost[]>();
const scopesBySystem = new Map<string, ScopeCost[]>();
for (const s of input.scopes) {
- const list = scopesBySystem.get(s.system);
- if (list) list.push(s); else scopesBySystem.set(s.system, [s]);
+ const nested = s.parent !== undefined && named.has(s.parent);
+ const groups = nested ? nestedByParent : scopesBySystem;
+ const key = nested ? s.parent! : s.system;
+ const list = groups.get(key);
+ if (list) list.push(s); else groups.set(key, [s]);
}
+ const nestedNodes = (parent: string, parentId: string): ProfileNode[] =>
+ (nestedByParent.get(parent) ?? []).map((s) => {
+ const id = `${parentId}/${s.name}`;
+ const children = nestedNodes(s.name, id);
+ const left = s.ms - sumMs(children);
+ if (children.length > 0 && left >= EPS_MS) children.push({ id: `${id}/~`, label: 'rest', ms: left, kind: 'rest', children: [] });
+ children.sort(byMsDesc);
+ return { id, label: s.name, ms: s.ms, kind: 'scope', children };
+ });
let waitTotal = 0;
const domains = new Map<string, ProfileNode[]>();
@@ -195,20 +217,26 @@ export function buildFrameProfile(input: FrameProfileInput): FrameProfile {
const adopted = scope.remainder === 'wait'
? (nativeByDomain.get(scopeDomain(scope.name)) ?? [])
: [];
- const grandChildren = adopted.map((n): ProfileNode => ({
+ const grandChildren = [...adopted.map((n): ProfileNode => ({
id: `${sys.name}/${scope.name}/${n.name}`,
label: n.name,
ms: n.ms,
kind: 'scope',
children: [],
- }));
+ })), ...nestedNodes(scope.name, `${sys.name}/${scope.name}`)];
const unclaimed = Math.max(0, scope.ms - sumMs(grandChildren));
- // A wait leaves the tree entirely rather than becoming a row in it:
- // the tree is work, and time blocked on a swapchain is not work. It
- // survives as the profile's waitMs, which the frame identity carries.
- if (scope.remainder === 'wait') {
- systemWait += unclaimed;
- } else if (unclaimed >= EPS_MS && grandChildren.length > 0) {
+ const waited = scope.remainder === 'wait' ? Math.min(unclaimed, MAX_PRESENT_WAIT_MS) : 0;
+ const untimed = scope.remainder === 'wait' ? unclaimed - waited : 0;
+ systemWait += waited;
+ if (untimed >= EPS_MS) {
+ grandChildren.push({
+ id: `${sys.name}/${scope.name}/~untimed`,
+ label: UNTIMED_SCOPE_LABEL,
+ ms: untimed,
+ kind: 'rest',
+ children: [],
+ });
+ } else if (scope.remainder !== 'wait' && unclaimed >= EPS_MS && grandChildren.length > 0) {
grandChildren.push({
id: `${sys.name}/${scope.name}/~`,
label: 'rest',
@@ -218,7 +246,7 @@ export function buildFrameProfile(input: FrameProfileInput): FrameProfile {
});
}
grandChildren.sort(byMsDesc);
- const scopeWork = scope.remainder === 'wait' ? scope.ms - unclaimed : scope.ms;
+ const scopeWork = scope.ms - waited;
children.push({
id: `${sys.name}/${scope.name}`,
label: scope.name,
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index d0e8fcd4a..51944497f 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -265,6 +265,8 @@ export {
scopeDomain,
DOMAIN_SCRIPTS,
DOMAIN_UNATTRIBUTED,
+ MAX_PRESENT_WAIT_MS,
+ UNTIMED_SCOPE_LABEL,
type FrameProfile,
type FrameProfileInput,
type ProfileNode,
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 4d44ee7f8..dc6d4d22d 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -304,8 +304,8 @@ export class TextPlugin implements Plugin {
// Two passes, because there are two lists: the world's glyphs go into the
// camera being collected, the screen's into the frame's overlay.
- pipeline.addPreFlushCallback((_registry, projection) => this.drawDomain(app, /*screen=*/false, projection));
- pipeline.addScreenOverlayCallback((_registry, projection) => this.drawDomain(app, /*screen=*/true, projection));
+ pipeline.addPreFlushCallback((_registry, projection) => app.measureFrameScope('render.text', () => this.drawDomain(app, false, projection)));
+ pipeline.addScreenOverlayCallback((_registry, projection) => app.measureFrameScope('render.text', () => this.drawDomain(app, true, projection)));
}
/**
diff --git a/sdk/tests/frame-profile.test.ts b/sdk/tests/frame-profile.test.ts
index fe88bc750..b646911b0 100644
--- a/sdk/tests/frame-profile.test.ts
+++ b/sdk/tests/frame-profile.test.ts
@@ -6,6 +6,8 @@ import {
meanFrameProfile,
scopeDomain,
DOMAIN_SCRIPTS,
+ MAX_PRESENT_WAIT_MS,
+ UNTIMED_SCOPE_LABEL,
type FrameProfileInput,
type ProfileNode,
} from '../src/app/frameProfile';
@@ -135,6 +137,47 @@ describe('buildFrameProfile', () => {
// The empty-scene reading this model has to reproduce: a 2.1ms RenderSystem
// that is 0.03ms of work and the rest blocked on the swapchain.
+ describe('a block no present can explain', () => {
+ const stalled = (submitMs: number, nested: { name: string; ms: number }[] = []) => buildFrameProfile({
+ frameMs: submitMs + 1,
+ systems: [{ name: 'RenderSystem', ms: submitMs, domain: 'render' }],
+ scopes: [
+ { name: 'render.submit', ms: submitMs, system: 'RenderSystem', remainder: 'wait' },
+ ...nested.map((s) => ({ ...s, system: 'RenderSystem', remainder: 'work' as const, parent: 'render.submit' })),
+ ],
+ nativeScopes: [{ name: 'render.collect', ms: 0.1, system: '', remainder: 'work' }],
+ });
+
+ it('stays a wait up to the slowest present', () => {
+ const profile = stalled(MAX_PRESENT_WAIT_MS);
+ expect(profile.waitMs).toBeCloseTo(MAX_PRESENT_WAIT_MS - 0.1, 4);
+ expect(findNode(profile.domains, 'RenderSystem/render.submit/~untimed')).toBeNull();
+ });
+
+ it('is work past it, in a row of its own that the cost totals count', () => {
+ const profile = stalled(820);
+ expect(profile.waitMs).toBe(MAX_PRESENT_WAIT_MS);
+ const row = findNode(profile.domains, 'RenderSystem/render.submit/~untimed')!;
+ expect(row.label).toBe(UNTIMED_SCOPE_LABEL);
+ expect(row.ms).toBeCloseTo(820 - 0.1 - MAX_PRESENT_WAIT_MS, 4);
+ expect(profile.domains[0].label).toBe('render');
+ expect(profile.domains[0].ms).toBeCloseTo(820 - MAX_PRESENT_WAIT_MS, 4);
+ expect(profile.cpuMs + profile.waitMs + profile.idleMs).toBeCloseTo(profile.frameMs, 4);
+ for (const domain of profile.domains) assertChildrenSum(domain);
+ });
+
+ it('names the scope that measured it, inside the one that holds it', () => {
+ const profile = stalled(820, [{ name: 'render.text', ms: 800 }]);
+ const submit = findNode(profile.domains, 'RenderSystem/render.submit')!;
+ expect(submit.children[0].label).toBe('render.text');
+ expect(submit.children[0].ms).toBe(800);
+ expect(findNode(profile.domains, 'RenderSystem/render.text')).toBeNull();
+ expect(findNode(profile.domains, 'RenderSystem/render.submit/~untimed')).toBeNull();
+ expect(profile.waitMs).toBeCloseTo(19.9, 4);
+ for (const domain of profile.domains) assertChildrenSum(domain);
+ });
+ });
+
describe('a scope whose remainder is a wait', () => {
const emptyScene: FrameProfileInput = {
frameMs: 16.7,
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 3a16d7aef..bc2dabac7 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4252,4 +4252,6 @@ export const NOTED = {
{"note": "A streamed world opens in the editor without its cells."},
"fix(editor): what grows round the view follows the viewport in 2D and 3D, and a terrain stroke keeps only the tiles it touched":
{"note": "While editing, foliage and generated worlds follow the viewport."},
+ "fix(profiler): a long block in the render submit is work, not vsync, and text has a scope of its own":
+ {"note": "The profiler no longer calls a long render stall vsync."},
};