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(viewport): fade occluded transform handles without writing scene depth

yhh193b57e35c2b
diff --git a/.github/workflows/editor-spatial.yml b/.github/workflows/editor-spatial.yml
index 5df59ec04..f3b78d17d 100644
--- a/.github/workflows/editor-spatial.yml
+++ b/.github/workflows/editor-spatial.yml
@@ -16,6 +16,14 @@ jobs:
spatial:
runs-on: ubuntu-latest
timeout-minutes: 15
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - suite: spatial
+ artifact: gizmo-planes-editor-checks
+ - suite: interaction
+ artifact: gizmo-interaction-editor-checks
env:
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 evidence
if: always()
uses: actions/upload-artifact@v7
with:
- 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-ci
if-no-files-found: warn
retention-days: 3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-15
diff --git a/desktop b/desktop
index 02d1eed1c..918f30436 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 02d1eed1cdcf62beb84c4e9609db259fbede59d3
+Subproject commit 918f304361890270dba66aafbdf256c4b39cdf72
diff --git a/docs/astro/src/content/docs/editor/viewport.mdx b/docs/astro/src/content/docs/editor/viewport.mdx
index 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 (defau
1). The preference persists across editor sessions. Changing it during a handle
drag 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**. Center
uses the selection's centroid; Pivot uses the active object's position. Individual
Origins draws one handle at the selection center, but rotation and scale keep each
diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdx
index 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.mdx
index 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.mdx
index 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.md
index 46aa63063..116bfead6 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -3252,6 +3252,7 @@ setDepthTest: (enabled: boolean) => void
setLayer: (layer: number) => void
texture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => void
textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void
+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
## DrawCallInfo — interface @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 06c8f83af..61b362316 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -3260,6 +3260,7 @@ setDepthTest: (enabled: boolean) => void
setLayer: (layer: number) => void
texture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => void
textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void
+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
## DrawCallInfo — interface @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index dfc5c5b99..b9e6ac591 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -3247,6 +3247,7 @@ setDepthTest: (enabled: boolean) => void
setLayer: (layer: number) => void
texture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => void
textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void
+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
## DrawCallInfo — interface @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index d6607c949..06ba23a75 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -3247,6 +3247,7 @@ setDepthTest: (enabled: boolean) => void
setLayer: (layer: number) => void
texture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => void
textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void
+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
## DrawCallInfo — interface @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 0c6cb2e8e..dd57871fa 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -287,8 +287,10 @@ deviceStatus: (() => number) | undefined
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) | undefined
draw_deferEnd: () => void
draw_end: () => void
+draw_getDepthState: (() => number) | undefined
draw_getDrawCallCount: () => number
draw_getPrimitiveCount: () => number
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
@@ -302,6 +304,7 @@ draw_rect: (x: number, y: number, width: number, height: number, r: number, g: n
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) | undefined
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
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 4aaa141a3..3f7295dd8 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -3247,6 +3247,7 @@ setDepthTest: (enabled: boolean) => void
setLayer: (layer: number) => void
texture: (position: Vec2, size: Vec2, textureHandle: number, tint?: Color) => void
textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: number, tint?: Color) => void
+withDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean
```
## DrawCallInfo — interface @experimental
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.cpp
index 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 esengine
diff --git a/src/esengine/bindings/ImmediateDrawBindings.hpp b/src/esengine/bindings/ImmediateDrawBindings.hpp
index 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 esengine
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 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.cpp
index 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, i3
if (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.hpp
index 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.cpp
index 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.mjs
index 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.mjs
new file mode 100644
index 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 });
+}