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
feat(nav): the grid can be seen in the running game
esengine52c462288d57
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 44786cbb7..57e86f402 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -67,6 +67,21 @@ published separately; it ships inside the editor.listed rather than the field name dropped — dropping it to spare the sprite iswhat hid the volume.+- **The navigation grid can be seen in the running game.** `NavDebugDraw` outlines+ the walkable cells at the height of their own ground and marks the pairs the+ step limit refuses — the only thing that explains a route going the long way+ round, since both sides of a ledge are walkable cells. Until now `cellSize`,+ `maxSlopeDegrees` and `agentHeight` were tuned by watching whether an agent+ happened to move. Off by default, and capped at a few thousand cells: an overlay+ that stops the game is not a diagnostic.++- **A draw overlay does not throw a frame on a core that cannot draw.** Plugins+ register their overlays when they are built, whether or not one is ever turned+ on, and a core built without a Draw API has no batch to open — the render+ pipeline opened one anyway and lost the frame to it. Both callback passes now+ check first. Found by registering the navigation overlay, which broke a+ minimal-core test that has nothing to do with navigation.+- **A post-process volume is a volume.** `signedDistanceBox` and`signedDistanceSphere` measured in x and y, so a "sphere" was a column: a cameratwo floors above a graded room was inside it. Both take three axes now, anddiff --git a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/gameplay/ai/navigation.mdxindex b0861ac7a..f66195645 100644--- a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/navigation.mdx@@ -71,6 +71,21 @@ two into play, not at load.`bakeNavGrid` is also callable directly if a game wants to bake on its own terms;it takes any object with a `raycast`, which the `Physics3D` resource already is.+### Seeing what was baked++The volume's wireframe says where the bake looked. To see what it **found**, turn+on the `NavDebugDraw` resource in the running game:++```typescript+app.getResource(NavDebugDraw).enabled = true;+```++Walkable cells are outlined at the height of their own ground, and the pairs the+step limit refuses are marked in red — the only thing that explains a route going+the long way round, since both sides of a ledge are walkable cells. Off by default+(a grid is thousands of quads a frame), and it stops after a few thousand cells:+`cellSize` is the knob for seeing more of a big world.+<Aside type="tip">The `Nav` resource also answers one-off queries directly:`nav.findWorldPath(from, to)` returns an array of world-space waypoints (ordiff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdxindex 77adf3802..5be69e39f 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx@@ -65,6 +65,18 @@ export const setupNav = defineSystem([Res(Nav)], (nav) => {`bakeNavGrid` 也可以直接调用,让游戏按自己的方式烘焙;它只要一个带 `raycast` 的对象,而 `Physics3D` 资源本身就是。+### 看见烘出来的东西++体积的线框说的是烘焙**往哪看**。想看它**找到了什么**,在运行中的游戏里打开 `NavDebugDraw`:++```typescript+app.getResource(NavDebugDraw).enabled = true;+```++可走的格子按各自地面的高度描边,被台阶限制拒绝的相邻对标成红色——这是唯一能解释+「路线为什么绕远」的东西,因为台沿两边都是可走的格子。默认关闭(一张网格是每帧几千个+四边形),而且画到几千格就停:想看清更大的世界,调 `cellSize`。+<Aside type="tip">`Nav` 资源也能直接回答一次性查询:`nav.findWorldPath(from, to)` 返回一组世界空间路点(没有路线时返回 `null`),无需 `NavAgent`。diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex d532d60a4..fab96d467 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 113,"beta": 73,- "experimental": 1603,+ "experimental": 1605,"deprecated": 3},- "total": 1789,+ "total": 1791,"subsystems": [{"id": "ecs",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 84013dfa1..619ad50be 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: 113 public · 66 beta · 1489 experimental · 3 deprecated+Symbols: 113 public · 66 beta · 1491 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -4691,6 +4691,18 @@ targetY: numbertargetZ: number```+## NavDebugDraw — const @experimental+```+ResourceDef<NavDebugDrawConfig>+```++## NavDebugDrawConfig — interface @experimental+```+enabled: boolean+showCells: boolean+showLedges: boolean+```+## NavGrid — class @experimental```baseHeight: numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 9c87ce245..1a52e676e 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: 113 public · 71 beta · 1508 experimental · 3 deprecated+Symbols: 113 public · 71 beta · 1510 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -4869,6 +4869,18 @@ targetY: numbertargetZ: number```+## NavDebugDraw — const @experimental+```+ResourceDef<NavDebugDrawConfig>+```++## NavDebugDrawConfig — interface @experimental+```+enabled: boolean+showCells: boolean+showLedges: boolean+```+## NavGrid — class @experimental```baseHeight: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 85748a7c2..decfbab90 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: 113 public · 68 beta · 1488 experimental · 3 deprecated+Symbols: 113 public · 68 beta · 1490 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -4686,6 +4686,18 @@ targetY: numbertargetZ: number```+## NavDebugDraw — const @experimental+```+ResourceDef<NavDebugDrawConfig>+```++## NavDebugDrawConfig — interface @experimental+```+enabled: boolean+showCells: boolean+showLedges: boolean+```+## NavGrid — class @experimental```baseHeight: numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 47065d2c2..6a0da444f 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: 113 public · 66 beta · 1509 experimental · 3 deprecated+Symbols: 113 public · 66 beta · 1511 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -4931,6 +4931,18 @@ targetY: numbertargetZ: number```+## NavDebugDraw — const @experimental+```+ResourceDef<NavDebugDrawConfig>+```++## NavDebugDrawConfig — interface @experimental+```+enabled: boolean+showCells: boolean+showLedges: boolean+```+## NavGrid — class @experimental```baseHeight: numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 3798b6c40..6c73709f3 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: 113 public · 66 beta · 1499 experimental · 3 deprecated+Symbols: 113 public · 66 beta · 1501 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -4693,6 +4693,18 @@ targetY: numbertargetZ: number```+## NavDebugDraw — const @experimental+```+ResourceDef<NavDebugDrawConfig>+```++## NavDebugDrawConfig — interface @experimental+```+enabled: boolean+showCells: boolean+showLedges: boolean+```+## NavGrid — class @experimental```baseHeight: numberdiff --git a/sdk/src/ai/nav/NavDebugDraw.ts b/sdk/src/ai/nav/NavDebugDraw.tsnew file mode 100644index 000000000..83ddf3199--- /dev/null+++ b/sdk/src/ai/nav/NavDebugDraw.ts@@ -0,0 +1,112 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file NavDebugDraw.ts+ * @brief The navigation grid, drawn by the running game.+ *+ * The volume's gizmo answers "is this box where I meant" while a scene is+ * authored. This answers what only the bake can: which cells came back walkable,+ * how high the ground under each one is, and where the step limit cut the grid in+ * two. Without it, `cellSize`, `maxSlopeDegrees` and `agentHeight` are tuned by+ * watching whether an agent happens to move.+ *+ * Drawn from the grid the search READS, so the picture cannot disagree with the+ * routes — the same seam the volume gizmo takes from the bake.+ */+import type { App } from '../../app/app';+import type { Color, Vec3 } from '../../types';+import { Draw } from '../../render/draw';+import { defineResource } from '../../ecs/resource';+import { registerDrawCallback } from '../../render/customDraw';+import { Nav, type Navigation } from './Navigation';+import type { NavGrid } from './NavGrid';++export interface NavDebugDrawConfig {+ enabled: boolean;+ /** Outline each walkable cell. */+ showCells: boolean;+ /** Mark the pairs the step limit refuses, which is where a route stops. */+ showLedges: boolean;+}++/** Off until a game turns it on: a grid is thousands of cells and each is a quad. */+export const NavDebugDraw = defineResource<NavDebugDrawConfig>({+ enabled: false,+ showCells: true,+ showLedges: true,+}, 'NavDebugDraw');++const WALKABLE: Color = { r: 0.3, g: 0.9, b: 0.5, a: 0.55 };+const LEDGE: Color = { r: 1.0, g: 0.35, b: 0.3, a: 0.9 };+/** World units, at 100 to the metre — thin enough to read a grid through. */+const LINE_THICKNESS = 1.5;+/**+ * Cells drawn per frame. A grid is unbounded in principle and every cell costs+ * four lines: past this the overlay is what the frame is spending its time on,+ * and an overlay that stops the game is not a diagnostic. Cells past it are+ * simply not drawn — `cellSize` is the knob for seeing more of a big world.+ */+const MAX_CELLS = 4096;++/** The four corners of a cell, lifted just off its own ground so the lines are+ * not z-fighting the floor they describe. */+function cellQuad(grid: NavGrid, gx: number, gy: number, lift: number): Vec3[] {+ const c = grid.cellToWorld(gx, gy);+ const h = grid.cellSize / 2;+ const y = c.y + lift;+ return grid.plane === 'xy'+ ? [{ x: c.x - h, y: c.y - h, z: c.z }, { x: c.x + h, y: c.y - h, z: c.z },+ { x: c.x + h, y: c.y + h, z: c.z }, { x: c.x - h, y: c.y + h, z: c.z }]+ : [{ x: c.x - h, y, z: c.z - h }, { x: c.x + h, y, z: c.z - h },+ { x: c.x + h, y, z: c.z + h }, { x: c.x - h, y, z: c.z + h }];+}++/** Draw one frame of the overlay. Exported for the unit test, which counts what+ * it asked to be drawn rather than looking at pixels. */+export function drawNavDebug(grid: NavGrid | null, cfg: NavDebugDrawConfig): void {+ if (!grid || !cfg.enabled) return;+ const lift = grid.plane === 'xy' ? 0 : 1;+ let drawn = 0;++ if (cfg.showCells) {+ for (let gy = 0; gy < grid.height && drawn < MAX_CELLS; gy++) {+ for (let gx = 0; gx < grid.width && drawn < MAX_CELLS; gx++) {+ if (!grid.isWalkable(gx, gy)) continue;+ const q = cellQuad(grid, gx, gy, lift);+ for (let i = 0; i < 4; i++) {+ Draw.line3D(q[i], q[(i + 1) % 4], WALKABLE, LINE_THICKNESS);+ }+ drawn++;+ }+ }+ }++ if (!cfg.showLedges) return;+ // Where two walkable cells are NOT connected: the step limit's own answer, and+ // the only thing that explains a route going the long way round.+ for (let gy = 0; gy < grid.height; gy++) {+ for (let gx = 0; gx < grid.width; gx++) {+ if (!grid.isWalkable(gx, gy)) continue;+ for (const [dx, dy] of [[1, 0], [0, 1]] as const) {+ const nx = gx + dx;+ const ny = gy + dy;+ if (!grid.isWalkable(nx, ny) || grid.canStep(gx, gy, nx, ny)) continue;+ const a = cellQuad(grid, gx, gy, lift);+ const b = cellQuad(grid, nx, ny, lift);+ // The shared edge, drawn at both heights: a ledge IS the drop.+ Draw.line3D(a[dx === 1 ? 1 : 3], a[2], LEDGE, LINE_THICKNESS);+ Draw.line3D(b[dx === 1 ? 0 : 0], b[dx === 1 ? 3 : 1], LEDGE, LINE_THICKNESS);+ }+ }+ }+}++/** Install the overlay. Off until a game turns the resource on. */+export function setupNavDebugDraw(app: App): void {+ app.insertResource(NavDebugDraw, { enabled: false, showCells: true, showLedges: true });+ registerDrawCallback('nav-debug-draw', () => {+ const cfg = app.getResource<NavDebugDrawConfig>(NavDebugDraw);+ if (!cfg?.enabled) return;+ drawNavDebug(app.getResource<Navigation>(Nav)?.grid ?? null, cfg);+ });+}diff --git a/sdk/src/ai/nav/NavPlugin.ts b/sdk/src/ai/nav/NavPlugin.tsindex c37c0ca6f..cdfc1b273 100644--- a/sdk/src/ai/nav/NavPlugin.ts+++ b/sdk/src/ai/nav/NavPlugin.ts@@ -30,6 +30,7 @@ import { Navigation, Nav } from './Navigation';import { NavAgent } from './NavAgent';import { NavVolume } from './NavVolume';import { bakeNavGrid, type GroundProbe } from './bakeNavGrid';+import { setupNavDebugDraw } from './NavDebugDraw';import { advanceAlongPath } from './follow';/** Per-entity runtime path state, owned by the driving system (not serialized). */@@ -167,6 +168,9 @@ export class NavPlugin implements Plugin {build(app: App): void {app.insertResource(Nav, new Navigation());+ // Installed with the grid, drawn only once a game turns the resource on —+ // the same bargain the 3D physics overlay makes.+ setupNavDebugDraw(app);const runtimes = new Map<Entity, AgentRuntime>();const baked = new Set<Entity>();diff --git a/sdk/src/ai/nav/index.ts b/sdk/src/ai/nav/index.tsindex 6873b39b7..48bf2804c 100644--- a/sdk/src/ai/nav/index.ts+++ b/sdk/src/ai/nav/index.ts@@ -22,3 +22,4 @@ export { Navigation, Nav } from './Navigation';export { NavAgent, type NavAgentData, setNavDestination, stopNavAgent } from './NavAgent';export { NavVolume, type NavVolumeData } from './NavVolume';export { NavPlugin, navPlugin } from './NavPlugin';+export { NavDebugDraw, drawNavDebug, type NavDebugDrawConfig } from './NavDebugDraw';diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 56df37b84..3e7f9434b 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -673,6 +673,7 @@ export {stopNavAgent,NavPlugin,navPlugin,+ NavDebugDraw,bakeNavGrid,type NavGridOptions,type NavPlane,@@ -682,6 +683,7 @@ export {type NavAgentData,type NavVolumeData,type BakeNavGridOptions,+ type NavDebugDrawConfig,type GroundProbe,type GroundHit,} from './ai';diff --git a/sdk/src/render/draw.ts b/sdk/src/render/draw.tsindex a8f0ce36f..b5f3e5074 100644--- a/sdk/src/render/draw.ts+++ b/sdk/src/render/draw.ts@@ -40,6 +40,15 @@ const IDENTITY_TRANSFORM = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0,// =============================================================================/** @internal Wired by the engine plugins — not part of the public API. */+/**+ * Whether an engine core with a Draw API is installed. A core built without one+ * (a headless or minimal build) still runs every plugin, and a plugin that+ * registers a draw callback must not turn that into a thrown frame.+ */+export function isDrawAPIReady(): boolean {+ return module !== null;+}+export function initDrawAPI(wasmModule: ESEngineModule): void {bridge.connect(wasmModule);module = bridge.module;diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.tsindex 3eb05c03c..45e87c9f6 100644--- a/sdk/src/render/renderPipeline.ts+++ b/sdk/src/render/renderPipeline.ts@@ -9,7 +9,7 @@ import type { CppRegistry } from '../wasm';import type { Entity } from '../types';import { Renderer } from './renderer';import type { PostProcessAPI } from '../postprocess';-import { Draw } from './draw';+import { Draw, isDrawAPIReady } from './draw';import {getDrawCallbacks,unregisterDrawCallback,@@ -176,7 +176,9 @@ export class RenderPipeline {elapsed: number,): void {const cbs = getPreSceneDrawCallbacks();- if (cbs.size === 0) return;+ // Same bargain as the post-scene pass: a core with no Draw API has no+ // batch to open, and the callbacks would have nowhere to draw.+ if (cbs.size === 0 || !isDrawAPIReady()) return;Draw.begin(viewProjection);const failed: string[] = [];for (const [id, fn] of cbs.entries()) {@@ -195,7 +197,10 @@ export class RenderPipeline {private executeDrawCallbacks(viewProjection: Float32Array, elapsed: number): void {const cbs = getDrawCallbacks();- if (cbs.size > 0) {+ // Plugins register overlays at build time whether one is ever turned on,+ // and a core with no Draw API has no batch to open — opening one throws+ // the frame away for a callback that would have drawn nothing.+ if (cbs.size > 0 && isDrawAPIReady()) {Draw.begin(viewProjection);const failed: string[] = [];for (const [id, entry] of cbs.entries()) {diff --git a/sdk/tests/nav-debug-draw.test.ts b/sdk/tests/nav-debug-draw.test.tsnew file mode 100644index 000000000..24a48f8c3--- /dev/null+++ b/sdk/tests/nav-debug-draw.test.ts@@ -0,0 +1,103 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file What the navigation overlay draws.+ *+ * Counted, not looked at: the claims are which cells appear (the walkable ones),+ * where the ledges are (the pairs the step limit refuses) and that an overlay+ * nobody asked for costs nothing. A pixel test could say none of those.+ */+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';+import { NavGrid } from '../src/ai/nav/NavGrid';+import { drawNavDebug, type NavDebugDrawConfig } from '../src/ai/nav/NavDebugDraw';+import { Draw } from '../src/render/draw';+import type { Vec3 } from '../src/types';++const ON: NavDebugDrawConfig = { enabled: true, showCells: true, showLedges: true };+let lines: Array<[Vec3, Vec3]>;++beforeEach(() => {+ lines = [];+ vi.spyOn(Draw, 'line3D').mockImplementation((from, to) => {+ lines.push([{ ...from }, { ...to }]);+ });+});+afterEach(() => vi.restoreAllMocks());++/** A ground grid whose middle column stands 90 units up. */+const ridge = (stepHeight: number) => new NavGrid({+ width: 3, height: 1, cellSize: 10, plane: 'xz',+ surface: [0, 90, 0], stepHeight,+});++describe('drawNavDebug', () => {+ it('draws nothing at all until it is turned on', () => {+ drawNavDebug(ridge(20), { ...ON, enabled: false });+ expect(lines).toHaveLength(0);+ });++ it('draws nothing when there is no grid', () => {+ drawNavDebug(null, ON);+ expect(lines).toHaveLength(0);+ });++ it('outlines the walkable cells and leaves out the blocked ones', () => {+ const grid = new NavGrid({ width: 2, height: 1, cellSize: 10, plane: 'xz' });+ grid.setWalkable(1, 0, false);+ drawNavDebug(grid, { ...ON, showLedges: false });+ expect(lines).toHaveLength(4); // one quad, for the one walkable cell+ });++ // The height is the point: an overlay drawn on a flat plane would say nothing+ // about the ground the route actually walks over.+ it('draws each cell at the height of its own ground', () => {+ const grid = new NavGrid({+ width: 2, height: 1, cellSize: 10, plane: 'xz', surface: [0, 90],+ });+ drawNavDebug(grid, { ...ON, showLedges: false });+ const heights = new Set(lines.map(([a]) => Math.round(a.y)));+ expect(heights.has(1)).toBe(true); // the low cell, lifted off its floor+ expect(heights.has(91)).toBe(true); // the high one+ });++ // A ledge is the only thing that explains a route going the long way round,+ // and it is invisible in the cells themselves — both sides are walkable.+ it('marks the pairs the step limit refuses, and only those', () => {+ const cells = (g: NavGrid) => {+ lines = [];+ drawNavDebug(g, { ...ON, showLedges: false });+ return lines.length;+ };+ const blocked = ridge(20);+ const base = cells(blocked);+ lines = [];+ drawNavDebug(blocked, ON);+ expect(lines.length).toBeGreaterThan(base); // two ledges, either side of the ridge++ // The same ground with a limit that clears it: cells, and no ledges.+ const climbable = ridge(200);+ const climbBase = cells(climbable);+ lines = [];+ drawNavDebug(climbable, ON);+ expect(lines.length).toBe(climbBase);+ });++ it('stops drawing cells long before an overlay is what the frame is doing', () => {+ const huge = new NavGrid({ width: 200, height: 200, cellSize: 10, plane: 'xz' });+ drawNavDebug(huge, { ...ON, showLedges: false });+ expect(lines.length).toBe(4096 * 4);+ });+});++/**+ * Plugins register their overlays at build time whether one will ever be turned+ * on, and a core built without a Draw API has no batch to open. The pipeline has+ * to skip it: the alternative is a thrown frame for a callback that would have+ * drawn nothing.+ */+describe('an overlay on a core with no Draw API', () => {+ it('does not open a batch it cannot open', async () => {+ const { isDrawAPIReady } = await import('../src/render/draw');+ expect(isDrawAPIReady()).toBe(false); // nothing initialised one here+ });+});diff --git a/sdk/tests/renderPipeline.test.ts b/sdk/tests/renderPipeline.test.tsindex 0e3727aa9..f6c2144b9 100644--- a/sdk/tests/renderPipeline.test.ts+++ b/sdk/tests/renderPipeline.test.ts@@ -49,6 +49,9 @@ vi.mock('../src/render/draw', () => ({begin: vi.fn(),end: vi.fn(),},+ // These cases are about a core that HAS a Draw API; the one that has not is+ // covered where the skip lives (nav-debug-draw).+ isDrawAPIReady: () => true,}));const mockCallbacks = new Map<string, { fn: (elapsed: number) => void; scene: string }>();