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
perf(renderer): own transform gizmos in the scene pass
yhhcf8b9c63420d
diff --git a/desktop b/desktopindex 929c93f33..fbff609d6 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 929c93f3322a1d1b2e4bddb9b367eb3920f65c13+Subproject commit fbff609d6e51f26a47d470a50aad07a2e7a48c79diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 7ab2cddac..d98ff019d 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": 99,- "experimental": 1824,+ "experimental": 1825,"deprecated": 3},- "total": 2036,+ "total": 2037,"subsystems": [{"id": "ecs",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 97c9c5b2f..52447b49f 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 · 92 beta · 1663 experimental · 3 deprecated+Symbols: 113 public · 92 beta · 1664 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2953,6 +2953,7 @@ getDrawCallCount: () => numbergetPrimitiveCount: () => numberline3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => voidline3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => voidline: (from: Vec2, to: Vec2, color: Color, thickness?: number) => voidrect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => voidrectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void@@ -2994,7 +2995,14 @@ vertexCount: number## DrawCallback — type @experimental```-(elapsed: number) => void+(elapsed: number, frame: DrawFrameInfo) => void+```++## DrawFrameInfo — interface @experimental+```+height: number+viewProjection: Float32Array<ArrayBufferLike>+width: number```## DrawRank — interface @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 2f0e7d668..b7f6131f1 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 · 97 beta · 1682 experimental · 3 deprecated+Symbols: 113 public · 97 beta · 1683 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2961,6 +2961,7 @@ getDrawCallCount: () => numbergetPrimitiveCount: () => numberline3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => voidline3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => voidline: (from: Vec2, to: Vec2, color: Color, thickness?: number) => voidrect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => voidrectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void@@ -3002,7 +3003,14 @@ vertexCount: number## DrawCallback — type @experimental```-(elapsed: number) => void+(elapsed: number, frame: DrawFrameInfo) => void+```++## DrawFrameInfo — interface @experimental+```+height: number+viewProjection: Float32Array<ArrayBufferLike>+width: number```## DrawRank — interface @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d12d7ea22..070792ddc 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 · 94 beta · 1662 experimental · 3 deprecated+Symbols: 113 public · 94 beta · 1663 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2948,6 +2948,7 @@ getDrawCallCount: () => numbergetPrimitiveCount: () => numberline3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => voidline3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => voidline: (from: Vec2, to: Vec2, color: Color, thickness?: number) => voidrect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => voidrectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void@@ -2989,7 +2990,14 @@ vertexCount: number## DrawCallback — type @experimental```-(elapsed: number) => void+(elapsed: number, frame: DrawFrameInfo) => void+```++## DrawFrameInfo — interface @experimental+```+height: number+viewProjection: Float32Array<ArrayBufferLike>+width: number```## DrawRank — interface @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 62a61c9dc..f7987d29a 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 · 92 beta · 1684 experimental · 3 deprecated+Symbols: 113 public · 92 beta · 1685 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2948,6 +2948,7 @@ getDrawCallCount: () => numbergetPrimitiveCount: () => numberline3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => voidline3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => voidline: (from: Vec2, to: Vec2, color: Color, thickness?: number) => voidrect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => voidrectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void@@ -2989,7 +2990,14 @@ vertexCount: number## DrawCallback — type @experimental```-(elapsed: number) => void+(elapsed: number, frame: DrawFrameInfo) => void+```++## DrawFrameInfo — interface @experimental+```+height: number+viewProjection: Float32Array<ArrayBufferLike>+width: number```## DrawRank — interface @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 98a1b53ea..24b09ba15 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -247,11 +247,13 @@ deviceStatus: (() => number) | undefineddraw_begin: (matrixPtr: number, viewportWidth: number, viewportHeight: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void+draw_deferEnd: () => voiddraw_end: () => voiddraw_getDrawCallCount: () => numberdraw_getPrimitiveCount: () => numberdraw_line3D: (fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number) => voiddraw_line3DScreen: (fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number) => void+draw_line3DScreenOffset: (anchorX: number, anchorY: number, anchorZ: number, fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number) => voiddraw_line: (fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number) => voiddraw_mesh: (geometryHandle: number, shaderHandle: number, transformPtr: number) => voiddraw_meshWithMaterial: (geometryHandle: number, materialId: number) => booleandiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex b36b4136f..1d3bec1a0 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 · 92 beta · 1674 experimental · 3 deprecated+Symbols: 113 public · 92 beta · 1675 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2948,6 +2948,7 @@ getDrawCallCount: () => numbergetPrimitiveCount: () => numberline3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => voidline3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => voidline: (from: Vec2, to: Vec2, color: Color, thickness?: number) => voidrect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => voidrectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void@@ -2989,7 +2990,14 @@ vertexCount: number## DrawCallback — type @experimental```-(elapsed: number) => void+(elapsed: number, frame: DrawFrameInfo) => void+```++## DrawFrameInfo — interface @experimental+```+height: number+viewProjection: Float32Array<ArrayBufferLike>+width: number```## DrawRank — interface @experimentaldiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 9c6927145..7e9e3b28d 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -277,6 +277,7 @@ export {unregisterDrawCallback,clearDrawCallbacks,type DrawCallback,+ type DrawFrameInfo,registerPreSceneDrawCallback,unregisterPreSceneDrawCallback,type PreSceneDrawCallback,diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 562a27ead..3a994f3e7 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -26,12 +26,14 @@ export interface NativeEngineApi {draw_begin?(matrixPtr: number, viewportWidth: number, viewportHeight: number): void;draw_circle?(centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number): void;draw_circleOutline?(centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number): void;+ draw_deferEnd?(): void;draw_end?(): void;draw_getDrawCallCount?(): number;draw_getPrimitiveCount?(): number;draw_line?(fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number): void;draw_line3D?(fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number): void;draw_line3DScreen?(fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number): void;+ draw_line3DScreenOffset?(anchorX: number, anchorY: number, anchorZ: number, fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number): void;draw_mesh?(geometryHandle: number, shaderHandle: number, transformPtr: number): void;draw_meshWithMaterial?(geometryHandle: number, materialId: number): boolean;draw_meshWithUniforms?(geometryHandle: number, shaderHandle: number, transformPtr: number, uniformsPtr: number, uniformCount: number): void;@@ -288,12 +290,14 @@ export function createNativeEngineApi(bind('draw_begin', 'es_draw_begin', false);bind('draw_circle', 'es_draw_circle', false);bind('draw_circleOutline', 'es_draw_circleOutline', false);+ bind('draw_deferEnd', 'es_draw_deferEnd', false);bind('draw_end', 'es_draw_end', false);bind('draw_getDrawCallCount', 'es_draw_getDrawCallCount', false);bind('draw_getPrimitiveCount', 'es_draw_getPrimitiveCount', false);bind('draw_line', 'es_draw_line', false);bind('draw_line3D', 'es_draw_line3D', false);bind('draw_line3DScreen', 'es_draw_line3DScreen', false);+ bind('draw_line3DScreenOffset', 'es_draw_line3DScreenOffset', false);bind('draw_mesh', 'es_draw_mesh', false);bind('draw_meshWithMaterial', 'es_draw_meshWithMaterial', false);bind('draw_meshWithUniforms', 'es_draw_meshWithUniforms', false);diff --git a/sdk/src/render/customDraw.ts b/sdk/src/render/customDraw.tsindex 745030013..322b42601 100644--- a/sdk/src/render/customDraw.ts+++ b/sdk/src/render/customDraw.ts@@ -5,7 +5,16 @@* @brief Custom draw callback registration for the render pipeline*/-export type DrawCallback = (elapsed: number) => void;+/** The camera facts used by the draw pass invoking a callback. */+export interface DrawFrameInfo {+ /** Canonical view-projection matrix for this render pass. Valid for the callback. */+ readonly viewProjection: Float32Array;+ /** Framebuffer viewport dimensions used by Draw.begin. */+ readonly width: number;+ readonly height: number;+}++export type DrawCallback = (elapsed: number, frame: DrawFrameInfo) => void;const callbacks = new Map<string, { fn: DrawCallback; scene: string }>();diff --git a/sdk/src/render/draw.ts b/sdk/src/render/draw.tsindex f857a03e7..c9de3c296 100644--- a/sdk/src/render/draw.ts+++ b/sdk/src/render/draw.ts@@ -76,6 +76,15 @@ export function shutdownDrawAPI(): void {module = null;}+/** @internal Close custom overlay collection for the owning renderer pass. */+export function endPresentedDraw(): void {+ try {+ getModule().draw_deferEnd();+ } catch (e) {+ handleWasmError(e, 'Draw.endPresented');+ }+}+// =============================================================================// Draw API Interface// =============================================================================@@ -119,6 +128,10 @@ export interface DrawAPI {*/line3DScreen(from: Vec3, to: Vec3, color: Color, thickness?: number): void;+ /** Draws a framebuffer-sized line at one world anchor. Offsets are pixels, +Y up. */+ line3DScreenOffset(anchor: Vec3, fromOffset: Vec2, toOffset: Vec2,+ color: Color, thickness?: number): void;+/*** Draws a filled or outlined rectangle.* @param position Center position@@ -306,6 +319,20 @@ export const Draw: DrawAPI = {}},+ line3DScreenOffset(anchor: Vec3, fromOffset: Vec2, toOffset: Vec2,+ color: Color, thickness = 1): void {+ try {+ getModule().draw_line3DScreenOffset(+ anchor.x, anchor.y, anchor.z,+ fromOffset.x, fromOffset.y, toOffset.x, toOffset.y,+ color.r, color.g, color.b, color.a,+ thickness,+ );+ } catch (e) {+ handleWasmError(e, 'Draw.line3DScreenOffset');+ }+ },+rect(position: Vec2, size: Vec2, color: Color, filled = true): void {try {getModule().draw_rect(diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.tsindex ff22c063a..67659584f 100644--- a/sdk/src/render/renderPipeline.ts+++ b/sdk/src/render/renderPipeline.ts@@ -10,7 +10,7 @@ import type { Entity } from '../types';import { Renderer } from './renderer';import type { PostProcessAPI } from '../postprocess';import type { ScreenOverlayData } from '../ui/core/screen-overlay';-import { Draw, isDrawAPIReady } from './draw';+import { Draw, endPresentedDraw, isDrawAPIReady } from './draw';import {getDrawCallbacks,unregisterDrawCallback,@@ -292,13 +292,17 @@ export class RenderPipeline {for (const [id, entry] of cbs.entries()) {if (entry.scene && this.activeScenes_ && !this.activeScenes_.has(entry.scene)) continue;try {- entry.fn(elapsed);+ entry.fn(elapsed, {+ viewProjection,+ width: viewport.w,+ height: viewport.h,+ });} catch (e) {log.error('render', `callback '${id}' error`, e);failed.push(id);}}- Draw.end();+ endPresentedDraw();for (const id of failed) {unregisterDrawCallback(id);}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 39b9a1ff1..148a63d1b 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -406,6 +406,7 @@ export interface ESEngineModule {// ImmediateDraw APIdraw_begin(matrixPtr: number, viewportWidth: number, viewportHeight: number): void;draw_end(): void;+ draw_deferEnd(): void;draw_line(fromX: number, fromY: number, toX: number, toY: number,r: number, g: number, b: number, a: number, thickness: number): void;draw_line3D(fromX: number, fromY: number, fromZ: number,@@ -414,6 +415,9 @@ export interface ESEngineModule {draw_line3DScreen(fromX: number, fromY: number, fromZ: number,toX: number, toY: number, toZ: number,r: number, g: number, b: number, a: number, thickness: number): void;+ draw_line3DScreenOffset(anchorX: number, anchorY: number, anchorZ: number,+ fromX: number, fromY: number, toX: number, toY: number,+ r: number, g: number, b: number, a: number, thickness: number): void;draw_rect(x: number, y: number, width: number, height: number,r: number, g: number, b: number, a: number, filled: boolean): void;draw_rectOutline(x: number, y: number, width: number, height: number,diff --git a/sdk/tests/draw.test.ts b/sdk/tests/draw.test.tsindex 1da2a1c56..cc1dced81 100644--- a/sdk/tests/draw.test.ts+++ b/sdk/tests/draw.test.ts@@ -27,7 +27,7 @@ vi.mock('../src/render/material', () => {});import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';-import { Draw, initDrawAPI, shutdownDrawAPI, BlendMode } from '../src/render/draw';+import { Draw, initDrawAPI, shutdownDrawAPI, endPresentedDraw, BlendMode } from '../src/render/draw';import { Material, isTextureRef } from '../src/render/material';import type { ESEngineModule } from '../src/wasm';@@ -50,9 +50,11 @@ function createDrawMockModule() {draw_begin: vi.fn(),draw_end: vi.fn(),+ draw_deferEnd: vi.fn(),draw_line: vi.fn(),draw_line3D: vi.fn(),draw_line3DScreen: vi.fn(),+ draw_line3DScreenOffset: vi.fn(),draw_rect: vi.fn(),draw_rectOutline: vi.fn(),draw_circle: vi.fn(),@@ -202,6 +204,14 @@ describe('Draw API', () => {});});+ describe('endPresentedDraw', () => {+ it('defers submission to the owning renderer pass', () => {+ endPresentedDraw();+ expect(mock.draw_deferEnd).toHaveBeenCalledOnce();+ expect(mock.draw_end).not.toHaveBeenCalled();+ });+ });+describe('Draw.line3DScreen', () => {it('passes world endpoints and pixel thickness to the native primitive', () => {Draw.line3DScreen(@@ -214,6 +224,18 @@ describe('Draw API', () => {});});+ describe('Draw.line3DScreenOffset', () => {+ it('passes one world anchor and framebuffer offsets to the native primitive', () => {+ Draw.line3DScreenOffset(+ { x: 1, y: 2, z: 3 }, { x: -4, y: 5 }, { x: 6, y: -7 },+ { r: 0.1, g: 0.2, b: 0.3, a: 0.4 }, 2,+ );+ expect(mock.draw_line3DScreenOffset).toHaveBeenCalledWith(+ 1, 2, 3, -4, 5, 6, -7, 0.1, 0.2, 0.3, 0.4, 2,+ );+ });+ });+// =========================================================================// Draw.rect// =========================================================================diff --git a/sdk/tests/renderPipeline.test.ts b/sdk/tests/renderPipeline.test.tsindex 0385e89d9..da98f779a 100644--- a/sdk/tests/renderPipeline.test.ts+++ b/sdk/tests/renderPipeline.test.ts@@ -51,12 +51,16 @@ vi.mock('../src/render/draw', () => ({begin: vi.fn(),end: vi.fn(),},+ endPresentedDraw: 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 }>();+const mockCallbacks = new Map<string, {+ fn: (elapsed: number, frame: { viewProjection: Float32Array; width: number; height: number }) => void;+ scene: string;+}>();const mockPreSceneCallbacks = new Map<string, (info: unknown) => void>();vi.mock('../src/render/customDraw', () => ({getDrawCallbacks: vi.fn(() => mockCallbacks),@@ -68,7 +72,7 @@ vi.mock('../src/render/customDraw', () => ({import { RenderPipeline } from '../src/render/renderPipeline';import { Renderer } from '../src/render/renderer';import { PostProcess } from '../src/postprocess';-import { Draw } from '../src/render/draw';+import { Draw, endPresentedDraw } from '../src/render/draw';import { unregisterDrawCallback } from '../src/render/customDraw';describe('RenderPipeline', () => {@@ -164,33 +168,45 @@ describe('RenderPipeline', () => {});describe('custom draw callbacks', () => {- it('does not call Draw.begin/end when no callbacks', () => {+ it('does not open or close a presented draw when no callbacks', () => {pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 0 });expect(Draw.begin).not.toHaveBeenCalled();- expect(Draw.end).not.toHaveBeenCalled();+ expect(endPresentedDraw).not.toHaveBeenCalled();});- it('calls Draw.begin/end and callback when callbacks exist', () => {+ it('collects a presented draw around callbacks', () => {const cb = vi.fn();mockCallbacks.set('test-cb', { fn: cb, scene: '' });pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 16 });expect(Draw.begin).toHaveBeenCalledWith(viewProjection, 800, 600);- expect(cb).toHaveBeenCalledWith(16);- expect(Draw.end).toHaveBeenCalled();+ expect(cb).toHaveBeenCalledWith(16, { viewProjection, width: 800, height: 600 });+ expect(endPresentedDraw).toHaveBeenCalled();});- it('calls callbacks in correct order within Draw.begin/end', () => {+ it('hands callbacks the exact draw-frame camera facts', () => {+ const cb = vi.fn();+ mockCallbacks.set('test-cb', { fn: cb, scene: '' });++ pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 7 });++ const [, frame] = cb.mock.calls[0]!;+ expect(frame.viewProjection).toBe(viewProjection);+ expect(frame).toEqual({ viewProjection, width: 800, height: 600 });+ });++ it('calls callbacks in order before closing the presented draw', () => {const callOrder: string[] = [];(Draw.begin as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('Draw.begin'));- (Draw.end as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('Draw.end'));+ (endPresentedDraw as ReturnType<typeof vi.fn>)+ .mockImplementation(() => callOrder.push('endPresentedDraw'));mockCallbacks.set('cb1', { fn: () => callOrder.push('cb1'), scene: '' });mockCallbacks.set('cb2', { fn: () => callOrder.push('cb2'), scene: '' });pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 0 });- expect(callOrder).toEqual(['Draw.begin', 'cb1', 'cb2', 'Draw.end']);+ expect(callOrder).toEqual(['Draw.begin', 'cb1', 'cb2', 'endPresentedDraw']);});it('filters callbacks by activeScenes', () => {@@ -221,13 +237,13 @@ describe('RenderPipeline', () => {errorSpy.mockRestore();});- it('still calls Draw.end even when callback throws', () => {+ it('still closes the presented draw when a callback throws', () => {vi.spyOn(console, 'error').mockImplementation(() => {});mockCallbacks.set('bad-cb', { fn: () => { throw new Error('fail'); }, scene: '' });pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 0 });- expect(Draw.end).toHaveBeenCalled();+ expect(endPresentedDraw).toHaveBeenCalled();vi.restoreAllMocks();});});@@ -258,8 +274,8 @@ describe('RenderPipeline', () => {pipeline.renderCamera({ registry, viewProjection, viewportPixels, clearFlags: 3, elapsed: 16 });expect(Draw.begin).toHaveBeenCalledWith(viewProjection, 400, 300);- expect(cb).toHaveBeenCalledWith(16);- expect(Draw.end).toHaveBeenCalled();+ expect(cb).toHaveBeenCalledWith(16, { viewProjection, width: 400, height: 300 });+ expect(endPresentedDraw).toHaveBeenCalled();});});diff --git a/src/esengine/bindings/ImmediateDrawBindings.cpp b/src/esengine/bindings/ImmediateDrawBindings.cppindex 1a29262bc..39708919a 100644--- a/src/esengine/bindings/ImmediateDrawBindings.cpp+++ b/src/esengine/bindings/ImmediateDrawBindings.cpp@@ -56,6 +56,13 @@ void draw_end() {ctx().state().immediate_draw_active = false;}+void draw_deferEnd() {+ if (!g_initialized || !g_immediateDraw || !g_immediateDrawActive) return;++ g_immediateDraw->deferEnd();+ ctx().state().immediate_draw_active = false;+}+void draw_line(f32 fromX, f32 fromY, f32 toX, f32 toY,f32 r, f32 g, f32 b, f32 a, f32 thickness) {if (!g_immediateDraw || !g_immediateDrawActive) return;@@ -92,6 +99,20 @@ void draw_line3DScreen(f32 fromX, f32 fromY, f32 fromZ, f32 toX, f32 toY, f32 to);}+void draw_line3DScreenOffset(f32 anchorX, f32 anchorY, f32 anchorZ,+ f32 fromX, f32 fromY, f32 toX, f32 toY,+ f32 r, f32 g, f32 b, f32 a, f32 thickness) {+ if (!g_immediateDraw || !g_immediateDrawActive) return;++ g_immediateDraw->line3DScreenOffset(+ glm::vec3(anchorX, anchorY, anchorZ),+ glm::vec2(fromX, fromY),+ glm::vec2(toX, toY),+ glm::vec4(r, g, b, a),+ thickness+ );+}+void draw_rect(f32 x, f32 y, f32 width, f32 height,f32 r, f32 g, f32 b, f32 a, bool filled) {if (!g_immediateDraw || !g_immediateDrawActive) return;diff --git a/src/esengine/bindings/ImmediateDrawBindings.hpp b/src/esengine/bindings/ImmediateDrawBindings.hppindex c645a7a67..59be56b80 100644--- a/src/esengine/bindings/ImmediateDrawBindings.hpp+++ b/src/esengine/bindings/ImmediateDrawBindings.hpp@@ -9,12 +9,16 @@ namespace esengine {void draw_begin(uintptr_t matrixPtr, i32 viewportWidth, i32 viewportHeight);void draw_end();+void draw_deferEnd();void draw_line(f32 fromX, f32 fromY, f32 toX, f32 toY,f32 r, f32 g, f32 b, f32 a, f32 thickness);void draw_line3D(f32 fromX, f32 fromY, f32 fromZ, f32 toX, f32 toY, f32 toZ,f32 r, f32 g, f32 b, f32 a, f32 thickness);void draw_line3DScreen(f32 fromX, f32 fromY, f32 fromZ, f32 toX, f32 toY, f32 toZ,f32 r, f32 g, f32 b, f32 a, f32 thickness);+void draw_line3DScreenOffset(f32 anchorX, f32 anchorY, f32 anchorZ,+ f32 fromX, f32 fromY, f32 toX, f32 toY,+ f32 r, f32 g, f32 b, f32 a, f32 thickness);void draw_rect(f32 x, f32 y, f32 width, f32 height,f32 r, f32 g, f32 b, f32 a, bool filled);void draw_rectOutline(f32 x, f32 y, f32 width, f32 height,diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex d8ad5e6af..a1a1b66d7 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -545,9 +545,11 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("draw_begin", &esengine::draw_begin);emscripten::function("draw_end", &esengine::draw_end);+ emscripten::function("draw_deferEnd", &esengine::draw_deferEnd);emscripten::function("draw_line", &esengine::draw_line);emscripten::function("draw_line3D", &esengine::draw_line3D);emscripten::function("draw_line3DScreen", &esengine::draw_line3DScreen);+ emscripten::function("draw_line3DScreenOffset", &esengine::draw_line3DScreenOffset);emscripten::function("draw_rect", &esengine::draw_rect);emscripten::function("draw_rectOutline", &esengine::draw_rectOutline);emscripten::function("draw_circle", &esengine::draw_circle);diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cppindex 82002638f..7d4397590 100644--- a/src/esengine/core/EstellaContext.cpp+++ b/src/esengine/core/EstellaContext.cpp@@ -216,6 +216,7 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {auto* rc = services_.getService<RenderContext>();auto immediateDraw = makeUnique<ImmediateDraw>(*gfxDevicePtr, *rc, *rm);immediateDraw->init();+ auto* immediateDrawPtr = immediateDraw.get();services_.registerOwned<ImmediateDraw>(std::move(immediateDraw));services_.registerOwned<GeometryManager>(makeUnique<GeometryManager>());@@ -225,6 +226,7 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {#endifauto renderFrame = makeUnique<RenderFrame>(*gfxDevicePtr, *rc, *rm);+ renderFrame->setPresentedOverlayDraw(immediateDrawPtr);renderFrame->addPlugin(std::make_unique<SpritePlugin>());renderFrame->addPlugin(std::make_unique<UIElementPlugin>());#ifdef ES_ENABLE_BITMAP_TEXTdiff --git a/src/esengine/renderer/draw/ImmediateDraw.cpp b/src/esengine/renderer/draw/ImmediateDraw.cppindex c2a6f5796..06718ded7 100644--- a/src/esengine/renderer/draw/ImmediateDraw.cpp+++ b/src/esengine/renderer/draw/ImmediateDraw.cpp@@ -66,6 +66,26 @@ bool clipLineToNearPlane(glm::vec3& from, glm::vec3& to, const glm::mat4& viewPrreturn true;}+/** Unproject one framebuffer-pixel offset at an anchor's clip depth. */+bool screenOffsetPoint(const glm::mat4& inverseViewProjection,+ const glm::vec4& clipAnchor,+ const glm::vec2& offset,+ f32 viewportWidth, f32 viewportHeight,+ glm::vec3& point) {+ const glm::vec4 clip = clipAnchor + glm::vec4(+ 2.0f * offset.x * clipAnchor.w / viewportWidth,+ 2.0f * offset.y * clipAnchor.w / viewportHeight,+ 0.0f, 0.0f);+ const glm::vec4 world = inverseViewProjection * clip;+ if (!std::isfinite(world.x) || !std::isfinite(world.y)+ || !std::isfinite(world.z) || !std::isfinite(world.w)+ || std::abs(world.w) < 1e-9f) {+ return false;+ }+ point = glm::vec3(world) / world.w;+ return std::isfinite(point.x) && std::isfinite(point.y) && std::isfinite(point.z);+}+} // namespaceImmediateDraw::ImmediateDraw(GfxDevice& device, RenderContext& context,@@ -225,6 +245,20 @@ void ImmediateDraw::end() {inFrame_ = false;}+void ImmediateDraw::deferEnd() {+ if (!inFrame_) return;+ deferredGeometry_ = pendingGeometry_;+ inFrame_ = false;+}++void ImmediateDraw::flushDeferred() {+ if (!deferredGeometry_) return;+ inFrame_ = true;+ flush();+ inFrame_ = false;+ deferredGeometry_ = false;+}+void ImmediateDraw::useTexture(u32 textureId) {if (textureId != currentTexture_) {if (pendingGeometry_) flush();@@ -394,6 +428,28 @@ void ImmediateDraw::line3DScreen(const glm::vec3& from, const glm::vec3& to,++primitiveCount_;}+void ImmediateDraw::line3DScreenOffset(const glm::vec3& anchor,+ const glm::vec2& fromOffset,+ const glm::vec2& toOffset,+ const glm::vec4& color, f32 thickness) {+ if (!inFrame_ || !(thickness > 0.0f)) return;++ const glm::vec4 clipAnchor = viewProjection_ * glm::vec4(anchor, 1.0f);+ if (!std::isfinite(clipAnchor.x) || !std::isfinite(clipAnchor.y)+ || !std::isfinite(clipAnchor.z) || !std::isfinite(clipAnchor.w)+ || std::abs(clipAnchor.w) < 1e-9f || clipAnchor.z + clipAnchor.w < 0.0f) {+ return;+ }++ glm::vec3 from;+ glm::vec3 to;+ if (!screenOffsetPoint(inverseViewProjection_, clipAnchor, fromOffset,+ viewportWidth_, viewportHeight_, from)+ || !screenOffsetPoint(inverseViewProjection_, clipAnchor, toOffset,+ viewportWidth_, viewportHeight_, to)) return;+ line3DScreen(from, to, color, thickness);+}+void ImmediateDraw::polyline(std::span<const glm::vec2> vertices,const glm::vec4& color, f32 thickness, bool closed) {if (!inFrame_ || vertices.size() < 2) return;diff --git a/src/esengine/renderer/draw/ImmediateDraw.hpp b/src/esengine/renderer/draw/ImmediateDraw.hppindex 89ea3aa30..71e7dd0bb 100644--- a/src/esengine/renderer/draw/ImmediateDraw.hpp+++ b/src/esengine/renderer/draw/ImmediateDraw.hpp@@ -91,6 +91,12 @@ public:/** @brief Ends the frame and submits all draw commands */void end();+ /** Close collection now and submit it when the owning scene pass executes. */+ void deferEnd();++ /** Submit a collection closed by deferEnd inside the active render pass. */+ void flushDeferred();+/*** @brief Flushes pending draw commands without ending the frame* @details Use before operations that change GL state to ensure accumulated@@ -119,6 +125,17 @@ public:void line3DScreen(const glm::vec3& from, const glm::vec3& to,const glm::vec4& color, f32 thickness = 1.0f);+ /**+ * @brief A framebuffer-sized line attached to one world-space anchor.+ * @details Offsets use framebuffer pixels (+X right, +Y up). The anchor is+ * projected through the active draw frame, so editor handles keep a+ * stable size without sampling a second camera.+ */+ void line3DScreenOffset(const glm::vec3& anchor,+ const glm::vec2& fromOffset,+ const glm::vec2& toOffset,+ const glm::vec4& color, f32 thickness = 1.0f);+void polyline(std::span<const glm::vec2> vertices, const glm::vec4& color,f32 thickness = 1.0f, bool closed = false);@@ -209,6 +226,7 @@ private:u32 white_texture_id_ = 0;u32 currentTexture_ = 0;bool pendingGeometry_ = false;+ bool deferredGeometry_ = false;/// Where the camera looks, from the view-projection this frame began with —/// what a 3D line is widened across.diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 7768edfbc..0116ca4df 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -5,6 +5,7 @@#include "../rhi/ShaderEmbeds.generated.hpp"#include "../store/LightStore.hpp"#include "../draw/BatchBuilder.hpp"+#include "../draw/ImmediateDraw.hpp"#include "../../ecs/components/Transform.hpp"#include "../../ecs/components/Light.hpp"#include "../../ecs/components/ShadowCaster2D.hpp"@@ -545,7 +546,10 @@ void RenderFrame::end() {if (shadow_resource_ != rg::kNoResource) {scene.dependencies.push_back(shadow_resource_);}- scene.execute = [this](const rg::PassContext&) { drawScene(); };+ scene.execute = [this](const rg::PassContext&) {+ drawScene();+ if (presented_overlay_draw_) presented_overlay_draw_->flushDeferred();+ };graph_.addPass(std::move(scene));}diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 829ae9699..9aedffce9 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -36,6 +36,7 @@namespace esengine {namespace ecs { struct Light; }+class ImmediateDraw;/// The one shadow texture every map a frame renders shares. One size for every/// scene: coverage adapts to the camera instead, so texel density is a property of@@ -102,6 +103,9 @@ public:void shutdown();void resize(u32 width, u32 height);+ /** Geometry collected for this camera and drawn after its scene. */+ void setPresentedOverlayDraw(ImmediateDraw* draw) { presented_overlay_draw_ = draw; }+/// Rebuilds everything this frame owns after a device loss: the transient/// pool, the render targets, the batch program ids and the post-process chain.void recreateGpuResources();@@ -454,6 +458,7 @@ private:GfxDevice& device_;RenderContext& context_;resource::ResourceManager& resource_manager_;+ ImmediateDraw* presented_overlay_draw_ = nullptr;#ifdef ES_ENABLE_POSTPROCESSUnique<PostProcessPipeline> post_process_;