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(viewport): fade occluded transform handles without writing scene depth
yhh193b57e35c2b
diff --git a/.github/workflows/editor-spatial.yml b/.github/workflows/editor-spatial.ymlindex 5df59ec04..f3b78d17d 100644--- a/.github/workflows/editor-spatial.yml+++ b/.github/workflows/editor-spatial.yml@@ -16,6 +16,14 @@ jobs:spatial:runs-on: ubuntu-latesttimeout-minutes: 15+ strategy:+ fail-fast: false+ matrix:+ include:+ - suite: spatial+ artifact: gizmo-planes-editor-checks+ - suite: interaction+ artifact: gizmo-interaction-editor-checksenv:ESTELLA_WIN_W: '1480'ESTELLA_WIN_H: '920'@@ -49,12 +57,26 @@ jobs:cp build/wasm/web/* desktop/public/wasm/pnpm --dir desktop exec vite build- name: Check trusted spatial gestures and undo+ if: matrix.suite == 'spatial'run: node tools/verify-gizmo-planes.mjs+ - name: Check handle occlusion against opaque scene depth+ if: matrix.suite == 'spatial'+ run: node tools/verify-gizmo-occlusion.mjs+ - name: Check transform hover without scene changes+ if: matrix.suite == 'interaction'+ run: node tools/verify-gizmo-hover.mjs+ - name: Check origins and universal gestures with undo and cancel+ if: matrix.suite == 'interaction'+ run: node tools/verify-gizmo-origins.mjs- name: Keep spatial acceptance evidenceif: always()uses: actions/upload-artifact@v7with:- name: gizmo-planes-editor-checks- path: output/gizmo-planes-ci+ name: ${{ matrix.artifact }}+ path: |+ output/gizmo-planes-ci+ output/gizmo-occlusion-ci+ output/gizmo-hover-ci+ output/gizmo-origins-ciif-no-files-found: warnretention-days: 3diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4e1d3714b..598b636ce 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,8 @@ published separately; it ships inside the editor.### Added+- **Spatial transform handles fade behind scene geometry.** A persistent Viewport setting can restore always-visible handles; flat 2D widgets retain their appearance. Scoped immediate-draw depth state disables overlay depth writes and restores the previous state, including when drawing throws. Older cores keep their existing overlay fallback.+- **Spatial rotation adds a view-axis outer ring.** The outer ring remains a screen circle and uses the presented camera axis captured at the press, with absolute twist snapping and the same undo/cancel path. Local inner rings use their rotated world axis; rotation writes, including Alt copies, convert through each target's parent frame. Flat 2D retains its existing Z ring.## [0.86.1] - 2026-10-15diff --git a/desktop b/desktopindex 02d1eed1c..918f30436 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 02d1eed1cdcf62beb84c4e9609db259fbede59d3+Subproject commit 918f304361890270dba66aafbdf256c4b39cdf72diff --git a/docs/astro/src/content/docs/editor/viewport.mdx b/docs/astro/src/content/docs/editor/viewport.mdxindex 95f6ec65f..687462b36 100644--- a/docs/astro/src/content/docs/editor/viewport.mdx+++ b/docs/astro/src/content/docs/editor/viewport.mdx@@ -64,6 +64,10 @@ arrows, center plane, rotation rings and hit areas together from 0.5 to 2 (defau1). The preference persists across editor sessions. Changing it during a handledrag takes effect after release; the current drag retains its size and sensitivity.+**Fade occluded transform handles**, in the same settings group, dims spatial+handle segments behind scene geometry. Disable it to keep all handles drawn on+top. This preference persists across sessions; flat 2D handles retain their appearance.+The viewport pivot button cycles **Center → Pivot → Individual Origins**. Centeruses the selection's centroid; Pivot uses the active object's position. IndividualOrigins draws one handle at the selection center, but rotation and scale keep eachdiff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxindex e4e4ad9b6..320850ecc 100644--- a/docs/astro/src/content/docs/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/graphics/drawing.mdx@@ -61,6 +61,7 @@ cleared every frame, so call it each frame you want the shape visible:| `drawMesh(geometry, shader, transform)` / `drawMeshWithMaterial(geometry, material, transform?)` | A custom mesh by handle (see the `Geometry` API below). || `setLayer(layer)` / `setDepth(depth)` | Sorting of subsequent commands. || `setBlendMode(mode)` / `setDepthTest(on)` | Blend / depth state for subsequent commands. |+| `withDepthState({ test, write }, draw)` | Run synchronous drawing with temporary depth testing and writes. Restores the native state even if drawing throws; returns `false` without invoking `draw` on older cores. || `getDrawCallCount()` / `getPrimitiveCount()` | Frame stats. |## Vector paths: `Graphics`diff --git a/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdxindex 5e49c9ed1..bb97bd86e 100644--- a/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx@@ -54,6 +54,9 @@ W / E / R 单独工具仍可使用,T 仍为 Rect。旋转环和命中范围,范围为 0.5–2,默认 1,并在重启编辑器后保留。拖动手柄期间修改尺寸会在松开后生效;当前拖拽保持原有尺寸与操作灵敏度。+同组的**淡化被遮挡的变换手柄**会让空间视图中被场景几何遮挡的手柄段半透明显示。+关闭后手柄始终完整显示。该设置在重启后保留,2D 平面手柄外观保持一致。+视口轴心按钮依次切换**中心 → 轴心 → 各自原点**。中心使用所选内容的平均位置,轴心使用活动对象的位置。各自原点仍在选择中心显示一个手柄,但旋转与缩放时保持每个变换对象的位置,只改变其自身姿态;平移行为在三种模式下相同。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxindex eaa2eba90..ea1fe8ae8 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx@@ -57,6 +57,7 @@ registerDrawCallback('debug-overlay', (elapsed) => {| `drawMesh(geometry, shader, transform)` / `drawMeshWithMaterial(geometry, material, transform?)` | 按句柄绘制自定义网格(见下面的 `Geometry` API)。 || `setLayer(layer)` / `setDepth(depth)` | 后续命令的排序。 || `setBlendMode(mode)` / `setDepthTest(on)` | 后续命令的混合 / 深度状态。 |+| `withDepthState({ test, write }, draw)` | 为同步绘制临时设置深度测试与写入,异常时也恢复原生状态。旧内核不支持时返回 `false`,不调用 `draw`,由调用方选择回退方式。 || `getDrawCallCount()` / `getPrimitiveCount()` | 本帧统计。 |## 矢量路径:`Graphics`diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 46aa63063..116bfead6 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -3252,6 +3252,7 @@ setDepthTest: (enabled: boolean) => voidsetLayer: (layer: number) => voidtexture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => voidtextureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```## DrawCallInfo — interface @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 06c8f83af..61b362316 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -3260,6 +3260,7 @@ setDepthTest: (enabled: boolean) => voidsetLayer: (layer: number) => voidtexture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => voidtextureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```## DrawCallInfo — interface @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex dfc5c5b99..b9e6ac591 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -3247,6 +3247,7 @@ setDepthTest: (enabled: boolean) => voidsetLayer: (layer: number) => voidtexture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => voidtextureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```## DrawCallInfo — interface @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d6607c949..06ba23a75 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -3247,6 +3247,7 @@ setDepthTest: (enabled: boolean) => voidsetLayer: (layer: number) => voidtexture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => voidtextureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```## DrawCallInfo — interface @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 0c6cb2e8e..dd57871fa 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -287,8 +287,10 @@ 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_deferBegin: (() => void) | undefineddraw_deferEnd: () => voiddraw_end: () => void+draw_getDepthState: (() => number) | undefineddraw_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) => void@@ -302,6 +304,7 @@ draw_rect: (x: number, y: number, width: number, height: number, r: number, g: ndraw_rectOutline: (x: number, y: number, width: number, height: number, r: number, g: number, b: number, a: number, thickness: number) => voiddraw_setBlendMode: (mode: number) => voiddraw_setDepth: (depth: number) => void+draw_setDepthState: ((flags: number) => void) | undefineddraw_setDepthTest: (enabled: boolean) => voiddraw_setLayer: (layer: number) => voiddraw_texture: (x: number, y: number, width: number, height: number, textureId: number, r: number, g: number, b: number, a: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 4aaa141a3..3f7295dd8 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -3247,6 +3247,7 @@ setDepthTest: (enabled: boolean) => voidsetLayer: (layer: number) => voidtexture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => voidtextureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```## DrawCallInfo — interface @experimentaldiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex c47251a8e..cf067f481 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -26,8 +26,10 @@ 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_deferBegin?(): void;draw_deferEnd?(): void;draw_end?(): void;+ draw_getDepthState?(): number;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;@@ -41,6 +43,7 @@ export interface NativeEngineApi {draw_rectOutline?(x: number, y: number, width: number, height: number, r: number, g: number, b: number, a: number, thickness: number): void;draw_setBlendMode?(mode: number): void;draw_setDepth?(depth: number): void;+ draw_setDepthState?(flags: number): void;draw_setDepthTest?(enabled: boolean): void;draw_setLayer?(layer: number): void;draw_texture?(x: number, y: number, width: number, height: number, textureId: number, r: number, g: number, b: number, a: number): void;@@ -312,8 +315,10 @@ 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_deferBegin', 'es_draw_deferBegin', false);bind('draw_deferEnd', 'es_draw_deferEnd', false);bind('draw_end', 'es_draw_end', false);+ bind('draw_getDepthState', 'es_draw_getDepthState', false);bind('draw_getDrawCallCount', 'es_draw_getDrawCallCount', false);bind('draw_getPrimitiveCount', 'es_draw_getPrimitiveCount', false);bind('draw_line', 'es_draw_line', false);@@ -327,6 +332,7 @@ export function createNativeEngineApi(bind('draw_rectOutline', 'es_draw_rectOutline', false);bind('draw_setBlendMode', 'es_draw_setBlendMode', false);bind('draw_setDepth', 'es_draw_setDepth', false);+ bind('draw_setDepthState', 'es_draw_setDepthState', false);bind('draw_setDepthTest', 'es_draw_setDepthTest', false);bind('draw_setLayer', 'es_draw_setLayer', false);bind('draw_texture', 'es_draw_texture', false);diff --git a/sdk/src/render/draw.ts b/sdk/src/render/draw.tsindex 3457bee4f..d2e61d5da 100644--- a/sdk/src/render/draw.ts+++ b/sdk/src/render/draw.ts@@ -76,6 +76,12 @@ export function shutdownDrawAPI(): void {module = null;}+/** @internal Collect primitive batches for the owning renderer pass. */+export function beginPresentedDraw(viewProjection: Float32Array, width: number, height: number): void {+ Draw.begin(viewProjection, width, height);+ getModule().draw_deferBegin?.();+}+/** @internal Close custom overlay collection for the owning renderer pass. */export function endPresentedDraw(): void {try {@@ -223,6 +229,10 @@ export interface DrawAPI {*/setDepthTest(enabled: boolean): void;+ /** Runs synchronous drawing with scoped depth state, restored even on throw.+ * Returns false without drawing on older cores without scoped depth support. */+ withDepthState(state: { test: boolean; write: boolean }, draw: () => void): boolean;+/*** Draws a custom mesh with a shader.* @param geometry Geometry handle@@ -440,6 +450,19 @@ export const Draw: DrawAPI = {getModule().draw_setDepthTest(enabled);},+ withDepthState(state: { test: boolean; write: boolean }, draw: () => void): boolean {+ const m = getModule();+ if (!m.draw_getDepthState || !m.draw_setDepthState) return false;+ const previous = m.draw_getDepthState();+ m.draw_setDepthState((state.test ? 1 : 0) | (state.write ? 2 : 0));+ try {+ draw();+ } finally {+ m.draw_setDepthState(previous);+ }+ return true;+ },+drawMesh(geometry: GeometryHandle, shader: ShaderHandle, transform: Float32Array): void {try {const m = getModule();diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.tsindex 2cd3090e2..b70c934d7 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, endPresentedDraw, isDrawAPIReady } from './draw';+import { Draw, beginPresentedDraw, endPresentedDraw, isDrawAPIReady } from './draw';import {getDrawCallbacks,unregisterDrawCallback,@@ -336,7 +336,7 @@ export class RenderPipeline {// 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, viewport.w, viewport.h);+ beginPresentedDraw(viewProjection, viewport.w, viewport.h);const failed: string[] = [];for (const [id, entry] of cbs.entries()) {if (entry.scene && this.activeScenes_ && !this.activeScenes_.has(entry.scene)) continue;diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex d6a2b7c3f..d7482ea87 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -488,6 +488,9 @@ export interface ESEngineModule {draw_getPrimitiveCount(): number;draw_setBlendMode(mode: number): void;draw_setDepthTest(enabled: boolean): void;+ draw_getDepthState?(): number;+ draw_setDepthState?(flags: number): void;+ draw_deferBegin?(): void;draw_mesh(geometryHandle: number, shaderHandle: number, transformPtr: number): void;draw_meshWithUniforms(geometryHandle: number, shaderHandle: number, transformPtr: number,uniformsPtr: number, uniformCount: number): void;diff --git a/sdk/tests/draw.test.ts b/sdk/tests/draw.test.tsindex 2edc3cafa..fba4ad438 100644--- a/sdk/tests/draw.test.ts+++ b/sdk/tests/draw.test.ts@@ -29,7 +29,7 @@ vi.mock('../src/render/material', () => {});import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';-import { Draw, initDrawAPI, shutdownDrawAPI, endPresentedDraw, BlendMode } from '../src/render/draw';+import { Draw, initDrawAPI, shutdownDrawAPI, beginPresentedDraw, endPresentedDraw, BlendMode } from '../src/render/draw';import { Material, isTextureRef } from '../src/render/material';import type { ESEngineModule } from '../src/wasm';@@ -207,6 +207,14 @@ describe('Draw API', () => {});describe('endPresentedDraw', () => {+ it('starts collection after opening the draw session, with an older-core fallback', () => {+ const calls: string[] = [];+ mock.draw_begin.mockImplementation(() => { calls.push('begin'); });+ Object.assign(mock, { draw_deferBegin: () => { calls.push('defer'); } });+ beginPresentedDraw(new Float32Array(16), 800, 600);+ expect(calls).toEqual(['begin', 'defer']);+ });+it('defers submission to the owning renderer pass', () => {endPresentedDraw();expect(mock.draw_deferEnd).toHaveBeenCalledOnce();@@ -430,6 +438,32 @@ describe('Draw API', () => {Draw.setDepthTest(true);expect(mock.draw_setDepthTest).toHaveBeenCalledWith(true);});++ it('restores actual native depth state across nested scopes and exceptions', () => {+ let flags = 3;+ const states: number[] = [];+ Object.assign(mock, {+ draw_getDepthState: () => flags,+ draw_setDepthState: (v: number) => { flags = v; states.push(v); },+ });+ expect(() => Draw.withDepthState({ test: false, write: false }, () => {+ expect(flags).toBe(0);+ expect(Draw.withDepthState({ test: true, write: false }, () => {+ expect(flags).toBe(1);+ })).toBe(true);+ expect(flags).toBe(0);+ throw new Error('draw failed');+ })).toThrow('draw failed');+ expect(flags).toBe(3);+ expect(states).toEqual([0, 1, 0, 3]);+ });++ it('lets callers fall back without drawing or changing state on older cores', () => {+ const draw = vi.fn();+ expect(Draw.withDepthState({ test: true, write: false }, draw)).toBe(false);+ expect(draw).not.toHaveBeenCalled();+ expect(mock.draw_setDepthTest).not.toHaveBeenCalled();+ });});// =========================================================================diff --git a/sdk/tests/renderPipeline.test.ts b/sdk/tests/renderPipeline.test.tsindex 20b3374f1..0536d1bce 100644--- a/sdk/tests/renderPipeline.test.ts+++ b/sdk/tests/renderPipeline.test.ts@@ -57,6 +57,7 @@ vi.mock('../src/render/draw', () => ({end: vi.fn(),},endPresentedDraw: vi.fn(),+ beginPresentedDraw: 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,@@ -77,7 +78,7 @@ vi.mock('../src/render/customDraw', () => ({import { RenderPipeline } from '../src/render/renderPipeline';import { Renderer } from '../src/render/renderer';import { PostProcess, type PostProcessAPI } from '../src/postprocess';-import { Draw, endPresentedDraw } from '../src/render/draw';+import { Draw, beginPresentedDraw, endPresentedDraw } from '../src/render/draw';import { defaultScreenOverlay } from '../src/ui/core/screen-overlay';import { unregisterDrawCallback } from '../src/render/customDraw';const postProcessFixture = PostProcess as unknown as PostProcessAPI;@@ -202,7 +203,7 @@ describe('RenderPipeline', () => {describe('custom draw 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(beginPresentedDraw).not.toHaveBeenCalled();expect(endPresentedDraw).not.toHaveBeenCalled();});@@ -212,7 +213,7 @@ describe('RenderPipeline', () => {pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 16 });- expect(Draw.begin).toHaveBeenCalledWith(viewProjection, 800, 600);+ expect(beginPresentedDraw).toHaveBeenCalledWith(viewProjection, 800, 600);expect(cb).toHaveBeenCalledWith(16, { viewProjection, width: 800, height: 600 });expect(endPresentedDraw).toHaveBeenCalled();});@@ -230,7 +231,7 @@ describe('RenderPipeline', () => {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'));+ (beginPresentedDraw as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('beginPresentedDraw'));(endPresentedDraw as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('endPresentedDraw'));mockCallbacks.set('cb1', { fn: () => callOrder.push('cb1'), scene: '' });@@ -238,7 +239,7 @@ describe('RenderPipeline', () => {pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 0 });- expect(callOrder).toEqual(['Draw.begin', 'cb1', 'cb2', 'endPresentedDraw']);+ expect(callOrder).toEqual(['beginPresentedDraw', 'cb1', 'cb2', 'endPresentedDraw']);});it('filters callbacks by activeScenes', () => {@@ -305,7 +306,7 @@ describe('RenderPipeline', () => {pipeline.renderCamera({ registry, viewProjection, viewportPixels, clearFlags: 3, elapsed: 16 });- expect(Draw.begin).toHaveBeenCalledWith(viewProjection, 400, 300);+ expect(beginPresentedDraw).toHaveBeenCalledWith(viewProjection, 400, 300);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 39708919a..bea11b4d0 100644--- a/src/esengine/bindings/ImmediateDrawBindings.cpp+++ b/src/esengine/bindings/ImmediateDrawBindings.cpp@@ -63,6 +63,11 @@ void draw_deferEnd() {ctx().state().immediate_draw_active = false;}+void draw_deferBegin() {+ if (!g_initialized || !g_immediateDraw || !g_immediateDrawActive) return;+ g_immediateDraw->deferBegin();+}+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;@@ -218,5 +223,16 @@ void draw_setDepthTest(bool enabled) {g_immediateDraw->setDepthTest(enabled);}+u32 draw_getDepthState() {+ if (!g_immediateDraw) return 0;+ return (g_immediateDraw->depthTest() ? 1u : 0u)+ | (g_immediateDraw->depthWrite() ? 2u : 0u);+}++void draw_setDepthState(u32 flags) {+ if (!g_immediateDraw) return;+ g_immediateDraw->setDepthState((flags & 1u) != 0, (flags & 2u) != 0);+}+} // namespace esenginediff --git a/src/esengine/bindings/ImmediateDrawBindings.hpp b/src/esengine/bindings/ImmediateDrawBindings.hppindex 59be56b80..8896af1ec 100644--- a/src/esengine/bindings/ImmediateDrawBindings.hpp+++ b/src/esengine/bindings/ImmediateDrawBindings.hpp@@ -37,6 +37,9 @@ u32 draw_getDrawCallCount();u32 draw_getPrimitiveCount();void draw_setBlendMode(i32 mode);void draw_setDepthTest(bool enabled);+u32 draw_getDepthState();+void draw_setDepthState(u32 flags);+void draw_deferBegin();} // namespace esenginediff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 0d1ce82a8..f262cc075 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -569,6 +569,9 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("draw_getPrimitiveCount", &esengine::draw_getPrimitiveCount);emscripten::function("draw_setBlendMode", &esengine::draw_setBlendMode);emscripten::function("draw_setDepthTest", &esengine::draw_setDepthTest);+ emscripten::function("draw_getDepthState", &esengine::draw_getDepthState);+ emscripten::function("draw_setDepthState", &esengine::draw_setDepthState);+ emscripten::function("draw_deferBegin", &esengine::draw_deferBegin);emscripten::function("draw_mesh", &esengine::draw_mesh);emscripten::function("draw_meshWithUniforms", &esengine::draw_meshWithUniforms);emscripten::function("draw_meshWithMaterial", &esengine::draw_meshWithMaterial);diff --git a/src/esengine/renderer/draw/ImmediateDraw.cpp b/src/esengine/renderer/draw/ImmediateDraw.cppindex 5ae3cff0a..7cdf8d13f 100644--- a/src/esengine/renderer/draw/ImmediateDraw.cpp+++ b/src/esengine/renderer/draw/ImmediateDraw.cpp@@ -180,6 +180,10 @@ void ImmediateDraw::begin(const glm::mat4& viewProjection, i32 viewportWidth, i3if (glm::length(forward) > 0.0001f) viewForward_ = glm::normalize(forward);pool_.beginFrame();+ deferredBatches_.clear();+ recordedIndices_ = 0;+ recording_ = false;+ deferredGeometry_ = false;currentTexture_ = white_texture_id_;pendingGeometry_ = false;primitiveCount_ = 0;@@ -202,15 +206,28 @@ void ImmediateDraw::setBlendMode(BlendMode mode) {}void ImmediateDraw::setDepthTest(bool enabled) {- if (current_desc_.depthTest == enabled) return;+ setDepthState(enabled, current_desc_.depthWrite);+}++void ImmediateDraw::setDepthState(bool test, bool write) {+ if (current_desc_.depthTest == test && current_desc_.depthWrite == write) return;if (pendingGeometry_) flush();- current_desc_.depthTest = enabled;+ current_desc_.depthTest = test;+ current_desc_.depthWrite = write;pipeline_ = device_.createPipeline(current_desc_);}void ImmediateDraw::flush() {if (!initialized_ || !inFrame_ || !pendingGeometry_) return;+ if (recording_) {+ const u32 end = pool_.indicesUsed(LayoutId::Batch);+ deferredBatches_.push_back({pipeline_, currentTexture_, recordedIndices_, end - recordedIndices_});+ recordedIndices_ = end;+ pendingGeometry_ = false;+ return;+ }+pool_.upload();device_.setPipeline(pipeline_);@@ -227,6 +244,12 @@ void ImmediateDraw::flush() {void ImmediateDraw::end() {if (!inFrame_) return;+ if (recording_) {+ deferEnd();+ flushDeferred();+ return;+ }+flush();// No state restore needed: the next render phase invalidates the pipeline cache and// binds its own pipeline, which sets blend/depth/stencil afresh.@@ -235,12 +258,29 @@ void ImmediateDraw::end() {void ImmediateDraw::deferEnd() {if (!inFrame_) return;- deferredGeometry_ = pendingGeometry_;+ if (recording_) flush();+ deferredGeometry_ = pendingGeometry_ || !deferredBatches_.empty();+ recording_ = false;inFrame_ = false;}void ImmediateDraw::flushDeferred() {if (!deferredGeometry_) return;+ if (!deferredBatches_.empty()) {+ pool_.upload();+ device_.invalidatePipelineCache();+ for (const auto& batch : deferredBatches_) {+ device_.setPipeline(batch.pipeline);+ device_.bindTexture(0, TextureHandle{batch.texture});+ pool_.bindLayout(LayoutId::Batch);+ device_.drawElements(batch.indexCount, GfxDataType::UnsignedInt, batch.firstIndex * sizeof(u32));+ ++drawCallCount_;+ }+ deferredBatches_.clear();+ pool_.beginFrame();+ deferredGeometry_ = false;+ return;+ }inFrame_ = true;flush();inFrame_ = false;diff --git a/src/esengine/renderer/draw/ImmediateDraw.hpp b/src/esengine/renderer/draw/ImmediateDraw.hppindex d1aa084dd..21f252eab 100644--- a/src/esengine/renderer/draw/ImmediateDraw.hpp+++ b/src/esengine/renderer/draw/ImmediateDraw.hpp@@ -186,8 +186,13 @@ public:void setBlendMode(BlendMode mode);/** Toggles depth testing for subsequent primitives (flushes pending geometry). */void setDepthTest(bool enabled);+ /** Changes depth testing and writes together, flushing the previous batch. */+ void setDepthState(bool test, bool write);BlendMode blendMode() const { return current_desc_.blend; }bool depthTest() const { return current_desc_.depthTest; }+ bool depthWrite() const { return current_desc_.depthWrite; }+ /** Collects all following primitive batches for the owning scene pass. */+ void deferBegin() { recording_ = true; }// =========================================================================// Statistics@@ -224,6 +229,15 @@ private:u32 currentTexture_ = 0;bool pendingGeometry_ = false;bool deferredGeometry_ = false;+ struct DeferredBatch {+ PipelineHandle pipeline;+ u32 texture;+ u32 firstIndex;+ u32 indexCount;+ };+ std::vector<DeferredBatch> deferredBatches_;+ u32 recordedIndices_ = 0;+ bool recording_ = false;/// Where the camera looks, from the view-projection this frame began with —/// what a 3D line is widened across.diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cppindex bc0dd5334..12187720d 100644--- a/tests/renderer/test_batch_builder.cpp+++ b/tests/renderer/test_batch_builder.cpp@@ -11,6 +11,7 @@#include "MockGfxDevice.hpp"#include "esengine/renderer/draw/BatchBuilder.hpp"+#include "esengine/renderer/draw/ImmediateDraw.hpp"#include "esengine/renderer/draw/DrawList.hpp"#include "esengine/renderer/store/MaterialStore.hpp"#include "esengine/renderer/rhi/TransientBufferPool.hpp"@@ -38,6 +39,55 @@using namespace esengine;+TEST_CASE("presented primitives retain depth state and order until the scene pass") {+ struct Device : MockGfxDevice {+ std::vector<PipelineDesc> states;+ std::vector<u32> offsets;+ void drawElements(u32 count, GfxDataType type, u32 offset) override {+ MockGfxDevice::drawElements(count, type, offset);+ states.push_back(lastPipelineDesc);+ offsets.push_back(offset);+ }+ } device;+ RenderContext context(device);+ resource::ResourceManager resources;+ resources.init(device);+ ImmediateDraw draw(device, context, resources);+ draw.init();+ draw.begin(glm::mat4(1.0f), 800, 600);+ draw.deferBegin();+ const int uploads = device.updateBufferCalls;+ const auto line = [&] { draw.line({0, 0}, {10, 0}, {1, 0, 0, 1}, 2); };+ line();+ draw.setDepthState(false, false);+ line();+ draw.setDepthState(true, false);+ line();+ draw.setDepthState(false, true);+ CHECK(device.drawElementsCalls == 0);+ CHECK(device.updateBufferCalls == uploads);+ draw.deferEnd();+ CHECK(device.drawElementsCalls == 0);+ draw.flushDeferred();+ REQUIRE(device.states.size() == 3);+ CHECK_FALSE(device.states[0].depthTest);+ CHECK(device.states[0].depthWrite);+ CHECK_FALSE(device.states[1].depthTest);+ CHECK_FALSE(device.states[1].depthWrite);+ CHECK(device.states[2].depthTest);+ CHECK_FALSE(device.states[2].depthWrite);+ CHECK((device.offsets == std::vector<u32>{0, 6 * sizeof(u32), 12 * sizeof(u32)}));+ draw.flushDeferred();+ CHECK(device.drawElementsCalls == 3);+ draw.begin(glm::mat4(1.0f), 800, 600);+ line();+ draw.end();+ CHECK(device.drawElementsCalls == 4);+ CHECK(device.offsets.back() == 0);+ draw.shutdown();+ resources.shutdown();+}+namespace {struct Harness {diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex d690edd63..c1eb4c9cb 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -32,6 +32,10 @@ export const NOTED = {{ note: 'Native text measurement wraps without rescanning growing prefixes.' },'fix(text): bound native measurement advance history':{ note: 'Public native text measurement retains a bounded advance cache.' },+ 'feat(viewport): fade occluded transform handles without writing scene depth':+ { note: 'Spatial transform handles fade behind scene geometry.' },+ 'feat(viewport): add configurable occluded handle fading':+ { note: 'Spatial transform handles fade behind scene geometry.' },'fix(text): isolate font reload ownership and glyph caches':{ note: 'Font reloads retain independent handles and glyph caches.' },'fix(text): encode font paths without identity collisions':diff --git a/tools/verify-gizmo-occlusion.mjs b/tools/verify-gizmo-occlusion.mjsnew file mode 100644index 000000000..f58ae222b--- /dev/null+++ b/tools/verify-gizmo-occlusion.mjs@@ -0,0 +1,96 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import fs from 'node:fs';+import path from 'node:path';+import assert from 'node:assert/strict';+import { fileURLToPath } from 'node:url';+import { runElectron } from './lib/electronRun.mjs';+import { readPNG } from './lib/png.mjs';++if (!process.env.CI) throw Error('Editor acceptance runs only in CI; do not launch the local editor.');+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const out = path.join(root, 'output/gizmo-occlusion-ci');+fs.mkdirSync(out, { recursive: true });+const project = fs.mkdtempSync(path.join(out, 'project-'));+fs.mkdirSync(path.join(project, 'assets/scenes'), { recursive: true });+fs.mkdirSync(path.join(project, 'src'));+fs.writeFileSync(path.join(project, 'project.esproject'), JSON.stringify({+ formatVersion: '1', name: 'Handle depth acceptance', defaultScene: 'assets/scenes/main.esscene', spineVersion: 'none',+}));+fs.writeFileSync(path.join(project, 'assets/scenes/main.esscene'), JSON.stringify({+ version: '1.0', name: 'Main', entities: [+ { id: 1, name: 'Pivot inside blocker', parent: null, children: [], visible: true,+ components: [{ type: 'Transform', data: { position: { x: 0, y: 0, z: 0 } } }] },+ { id: 2, name: 'Opaque blocker', parent: null, children: [], visible: true, components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 0 }, scale: { x: 200, y: 200, z: 200 } } },+ { type: 'MeshRenderer', data: { mesh: 'builtin:cube', lit: false, opaque: true,+ color: { r: 0.22, g: 0.22, b: 0.22, a: 1 } } },+ ] },+ ],+}));+for (const name of ['main', 'components']) fs.writeFileSync(path.join(project, 'src', name + '.ts'), 'export {};');+const records = [];+try {+ for (const blocked of [true, false]) for (const fade of [false, true]) {+ const name = `${blocked ? 'blocked' : 'clear'}-${fade ? 'fade' : 'solid'}`;+ const run = runElectron(['.'], { via: 'npx', encoding: 'utf8', cwd: path.join(root, 'desktop'), timeout: 180000, env: {+ ESTELLA_SHOT: path.join(out, name + '.png'), ESTELLA_SHOT_PROJECT: project,+ ESTELLA_SHOT_SCENE: 'assets/scenes/main.esscene',+ ESTELLA_SHOT_EVAL: `(async()=>{+ const e=window.__estellaEditor,wait=ms=>new Promise(r=>setTimeout(r,ms));+ const find=async s=>{for(let i=0;i<50;i++){const n=document.querySelector(s);if(n)return n;await wait(100);}throw Error('Missing '+s);};+ e.runCommand('settings.open');const search=await find('.set-search input');+ Object.getOwnPropertyDescriptor(HTMLInputElement.prototype,'value').set.call(search,'viewport.gizmoOcclusion');+ search.dispatchEvent(new Event('input',{bubbles:true}));await wait(200);+ if(document.querySelectorAll('.set-content .set-row').length!==1)throw Error('Occlusion setting is not unique');+ const toggle=await find('.set-content [role="switch"]');+ toggle.click();await wait(100);+ if((toggle.getAttribute('aria-checked')==='true')!==${fade})toggle.click();await wait(100);+ const saved=JSON.parse(localStorage.getItem('estella.settings')||'{}')['viewport.gizmoOcclusion'];+ if(saved!==${fade})throw Error('Occlusion preference was not saved');+ document.querySelector('.set-win').dispatchEvent(new KeyboardEvent('keydown',{key:'Escape',bubbles:true}));await wait(300);+ e.runCommand('mode.scene');e.surface.setViewPerspective(true);e.surface.setViewOrbit(45,30);+ e.surface.select(2);e.frame([2]);await wait(750);+ ${blocked ? '' : "e.surface.setField(2,'Transform','position','vec3',{x:10000,y:10000,z:10000});"}+ e.surface.select(1);e.runCommand('tool.rotate');await wait(300);+ const g=e.gizmoLayout(),r=document.querySelector('.viewport__stage canvas').getBoundingClientRect();+ if(!g?.spatial)throw Error('Missing spatial handles');+ return {layout:g,rect:{x:r.x,y:r.y},dpr:window.devicePixelRatio,saved};+ })()`,+ } });+ fs.writeFileSync(path.join(out, name + '.log'), run.stdout + '\n' + run.stderr);+ assert.equal(run.status, 0, run.stderr);+ const line = run.stdout.split('\n').find(s => s.startsWith('[eval] '));+ assert(line, 'Missing occlusion observation: ' + name);+ const observation = JSON.parse(line.slice(7));+ const image = readPNG(fs.readFileSync(path.join(out, name + '.png')));+ const { layout, rect, dpr } = observation;+ const radius = layout.rings.find(r => r.axis === 'view')?.radius;+ assert(radius > 0, 'Missing screen ring');+ const pixels = [];+ // Sample the outer ring away from inner-ring intersections and the mouse.+ for (const angle of [0.35, 1.15, 2.1, 2.8, 3.6, 4.3, 5.1, 5.8]) {+ const x = (rect.x + layout.screen.x + radius * Math.cos(angle)) * dpr;+ const y = (rect.y + layout.screen.y + radius * Math.sin(angle)) * dpr;+ let strongest = [0, 0, 0], score = -Infinity;+ for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {+ const p = image.px(Math.round(x) + dx, Math.round(y) + dy);+ if (p[2] - p[0] > score) { strongest = p; score = p[2] - p[0]; }+ }+ pixels.push(strongest);+ }+ records.push({ name, ...observation, pixels });+ fs.writeFileSync(path.join(out, 'observations.json'), JSON.stringify(records, null, 2));+ }+ const score = name => records.find(r => r.name === name).pixels.reduce((n, p) => n + p[2] - p[0], 0) / 8;+ assert(score('blocked-solid') > 70, 'Solid handles are missing behind the blocker');+ assert(score('blocked-fade') > 5, 'Occluded handles disappeared instead of fading');+ assert(score('blocked-fade') < score('blocked-solid') * 0.65, 'The blocker did not fade the spatial ring');+ assert(score('clear-fade') > 70, 'Unoccluded handles are missing');+ assert(Math.abs(score('clear-fade') - score('clear-solid')) < 12, 'Unoccluded handles changed opacity');+ fs.writeFileSync(path.join(out, 'checks.json'), JSON.stringify({ status: 'checks-passed', records }, null, 2));+ console.log('Spatial handles fade behind opaque geometry; visible handles and the setting override retain full ink.');+} finally {+ if (!project.startsWith(out + path.sep)) throw Error('Unexpected cleanup path');+ fs.rmSync(project, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+}