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.

feat(nav): the grid can be seen in the running game

esengine52c462288d57
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 is
what 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 camera
two floors above a graded room was inside it. Both take three axes now, and
diff --git a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/gameplay/ai/navigation.mdx
index 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 (or
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx
index 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.json
index 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.md
index 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: number
targetZ: number
```
+## NavDebugDraw — const @experimental
+```
+ResourceDef<NavDebugDrawConfig>
+```
+
+## NavDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showCells: boolean
+showLedges: boolean
+```
+
## NavGrid — class @experimental
```
baseHeight: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: number
targetZ: number
```
+## NavDebugDraw — const @experimental
+```
+ResourceDef<NavDebugDrawConfig>
+```
+
+## NavDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showCells: boolean
+showLedges: boolean
+```
+
## NavGrid — class @experimental
```
baseHeight: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: number
targetZ: number
```
+## NavDebugDraw — const @experimental
+```
+ResourceDef<NavDebugDrawConfig>
+```
+
+## NavDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showCells: boolean
+showLedges: boolean
+```
+
## NavGrid — class @experimental
```
baseHeight: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: number
targetZ: number
```
+## NavDebugDraw — const @experimental
+```
+ResourceDef<NavDebugDrawConfig>
+```
+
+## NavDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showCells: boolean
+showLedges: boolean
+```
+
## NavGrid — class @experimental
```
baseHeight: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: number
targetZ: number
```
+## NavDebugDraw — const @experimental
+```
+ResourceDef<NavDebugDrawConfig>
+```
+
+## NavDebugDrawConfig — interface @experimental
+```
+enabled: boolean
+showCells: boolean
+showLedges: boolean
+```
+
## NavGrid — class @experimental
```
baseHeight: number
diff --git a/sdk/src/ai/nav/NavDebugDraw.ts b/sdk/src/ai/nav/NavDebugDraw.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 }>();