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.

test(render): a paired check that 2.5D depth actually resolves occlusion

esengine44cf312eb9be
diff --git a/desktop/package.json b/desktop/package.json
index 9896e6e85..6e3c43899 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -63,7 +63,9 @@
"verify:render:mesh2d": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mesh2d.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mesh2d.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=4 ESTELLA_VERIFY_EXPECT='[{\"x\":0.30,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.30,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40}]' electron scripts/headless-verify.mjs",
"verify:render:parallax:shape": "vite build && ESTELLA_VERIFY_SCENE=/scenes/parallax-shape.esscene ESTELLA_VERIFY_MANIFEST=/scenes/parallax-shape.textures.json ESTELLA_VERIFY_STEPS=4 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.25,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
"verify:render:trail": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/trail.esscene ESTELLA_VERIFY_MANIFEST=/scenes/trail.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_TRAIL='{\"from\":[-200,0],\"to\":[200,0],\"steps\":20}' ESTELLA_VERIFY_EXPECT='[{\"x\":0.80,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50},{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":60},{\"x\":0.5,\"y\":0.15,\"rgb\":[0,0,0],\"tol\":30}]' electron scripts/headless-verify.mjs",
- "verify:render:postprocess:lut": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/lut-grade.esscene ESTELLA_VERIFY_MANIFEST=/scenes/lut-grade.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.292,\\\"y\\\":0.5,\\\"rgb\\\":[0,0,255],\\\"tol\\\":40},{\\\"x\\\":0.708,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs"
+ "verify:render:postprocess:lut": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/lut-grade.esscene ESTELLA_VERIFY_MANIFEST=/scenes/lut-grade.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.292,\\\"y\\\":0.5,\\\"rgb\\\":[0,0,255],\\\"tol\\\":40},{\\\"x\\\":0.708,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
+ "verify:render:depth": "vite build && ESTELLA_VERIFY_SCENE=/scenes/depth-layers.esscene ESTELLA_VERIFY_MANIFEST=/scenes/depth-layers.textures.json ESTELLA_VERIFY_DEPTH_LAYERS=6 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.573,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":60}]\" electron scripts/headless-verify.mjs",
+ "verify:render:depth:off": "vite build && ESTELLA_VERIFY_SCENE=/scenes/depth-layers.esscene ESTELLA_VERIFY_MANIFEST=/scenes/depth-layers.textures.json ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.573,\\\"y\\\":0.5,\\\"rgb\\\":[0,0,255],\\\"tol\\\":60}]\" electron scripts/headless-verify.mjs"
},
"dependencies": {
"@anthropic-ai/sdk": "^0.115.0",
diff --git a/desktop/public/scenes/depth-layers.esscene b/desktop/public/scenes/depth-layers.esscene
new file mode 100644
index 000000000..734f90699
--- /dev/null
+++ b/desktop/public/scenes/depth-layers.esscene
@@ -0,0 +1,106 @@
+{
+ "version": "1.0",
+ "name": "DepthLayers",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 128,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Near red (layer 1, z=+5)",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 5
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 150,
+ "y": 150
+ },
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "layer": 1,
+ "material": "/scenes/depth-layers/opaque.esmaterial"
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "Far blue (layer 2, z=-5)",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 50,
+ "y": 0,
+ "z": -5
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 150,
+ "y": 150
+ },
+ "color": {
+ "r": 0,
+ "g": 0,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 2,
+ "material": "/scenes/depth-layers/opaque.esmaterial"
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/depth-layers.textures.json b/desktop/public/scenes/depth-layers.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/depth-layers.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/public/scenes/depth-layers/opaque.esmaterial b/desktop/public/scenes/depth-layers/opaque.esmaterial
new file mode 100644
index 000000000..f562ed0fa
--- /dev/null
+++ b/desktop/public/scenes/depth-layers/opaque.esmaterial
@@ -0,0 +1,8 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "opaque.esshader",
+ "blendMode": 9,
+ "depthTest": false,
+ "properties": {}
+}
diff --git a/desktop/public/scenes/depth-layers/opaque.esshader b/desktop/public/scenes/depth-layers/opaque.esshader
new file mode 100644
index 000000000..d620af04b
--- /dev/null
+++ b/desktop/public/scenes/depth-layers/opaque.esshader
@@ -0,0 +1,145 @@
+#pragma shader "Opaque Unlit"
+#pragma version 300 es
+#pragma domain Unlit2D
+
+// Fragment-only on purpose: the vertex stage is the one ShaderParser injects, so
+// this scene also proves that the INHERITED stage carries z. A material that
+// declared its own stage would be testing its own copy instead.
+#pragma fragment
+precision mediump float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+
+uniform sampler2D u_textures[8];
+
+out vec4 fragColor;
+
+void main() {
+ fragColor = texture(u_textures[0], v_texCoord) * v_color;
+}
+#pragma end
+
+#pragma vertex wgsl full
+// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
+// Regenerate after changing the GLSL stages above.
+// source-hash: 28a0ea120b8a9996
+struct gl_PerVertex {
+ @builtin(position) gl_Position: vec4<f32>,
+ gl_PointSize: f32,
+}
+
+struct FrameConstants {
+ u_projection: mat4x4<f32>,
+}
+
+struct TimeConstants {
+ u_time: vec4<f32>,
+ u_viewport: vec4<f32>,
+}
+
+struct VertexOutput {
+ @builtin(position) gl_Position: vec4<f32>,
+ @location(0) member: vec4<f32>,
+ @location(1) member_1: vec2<f32>,
+}
+
+var<private> unnamed: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);
+@group(0) @binding(0)
+var<uniform> unnamed_1: FrameConstants;
+var<private> a_position_1: vec3<f32>;
+var<private> v_color: vec4<f32>;
+var<private> a_color_1: vec4<f32>;
+var<private> v_texCoord: vec2<f32>;
+var<private> a_texCoord_1: vec2<f32>;
+@group(0) @binding(3)
+var<uniform> unnamed_2: TimeConstants;
+
+fn main_1() {
+ let _e11 = unnamed_1.u_projection;
+ let _e12 = a_position_1;
+ unnamed.gl_Position = (_e11 * vec4<f32>(_e12.x, _e12.y, _e12.z, 1f));
+ let _e19 = a_color_1;
+ v_color = _e19;
+ let _e20 = a_texCoord_1;
+ v_texCoord = _e20;
+ return;
+}
+
+@vertex
+fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>, @location(2) a_texCoord: vec2<f32>) -> VertexOutput {
+ a_position_1 = a_position;
+ a_color_1 = a_color;
+ a_texCoord_1 = a_texCoord;
+ main_1();
+ let _e10 = unnamed.gl_Position;
+ let _e11 = v_color;
+ let _e12 = v_texCoord;
+ return VertexOutput(_e10, _e11, _e12);
+}
+#pragma end
+
+#pragma fragment wgsl full
+// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
+// Regenerate after changing the GLSL stages above.
+// source-hash: 28a0ea120b8a9996
+struct TimeConstants {
+ u_time: vec4<f32>,
+ u_viewport: vec4<f32>,
+}
+
+var<private> fragColor: vec4<f32>;
+@group(1) @binding(0)
+var es_bt0_est: texture_2d<f32>;
+@group(1) @binding(8)
+var es_bt0_ess: sampler;
+var<private> v_texCoord_1: vec2<f32>;
+var<private> v_color_1: vec4<f32>;
+@group(0) @binding(3)
+var<uniform> unnamed: TimeConstants;
+@group(1) @binding(1)
+var es_bt1_est: texture_2d<f32>;
+@group(1) @binding(9)
+var es_bt1_ess: sampler;
+@group(1) @binding(2)
+var es_bt2_est: texture_2d<f32>;
+@group(1) @binding(10)
+var es_bt2_ess: sampler;
+@group(1) @binding(3)
+var es_bt3_est: texture_2d<f32>;
+@group(1) @binding(11)
+var es_bt3_ess: sampler;
+@group(1) @binding(4)
+var es_bt4_est: texture_2d<f32>;
+@group(1) @binding(12)
+var es_bt4_ess: sampler;
+@group(1) @binding(5)
+var es_bt5_est: texture_2d<f32>;
+@group(1) @binding(13)
+var es_bt5_ess: sampler;
+@group(1) @binding(6)
+var es_bt6_est: texture_2d<f32>;
+@group(1) @binding(14)
+var es_bt6_ess: sampler;
+@group(1) @binding(7)
+var es_bt7_est: texture_2d<f32>;
+@group(1) @binding(15)
+var es_bt7_ess: sampler;
+
+fn main_1() {
+ let _e20 = v_texCoord_1;
+ let _e21 = textureSample(es_bt0_est, es_bt0_ess, _e20);
+ let _e22 = v_color_1;
+ fragColor = (_e21 * _e22);
+ return;
+}
+
+@fragment
+fn fs_main(@location(1) v_texCoord: vec2<f32>, @location(0) v_color: vec4<f32>) -> @location(0) vec4<f32> {
+ v_texCoord_1 = v_texCoord;
+ v_color_1 = v_color;
+ main_1();
+ let _e5 = fragColor;
+ return _e5;
+}
+#pragma end
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 8dc5bbba3..02656bced 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -18,6 +18,7 @@
* ESTELLA_VERIFY_W / _H capture size (default 640×480)
* ESTELLA_VERIFY_STEPS fixed-dt frames to advance before capture (default 30)
* ESTELLA_VERIFY_GRID editor-grid on/off pixel-diff assertion (value = spacing)
+ * ESTELLA_VERIFY_DEPTH_LAYERS bitmask of layers resolved by depth (2.5D)
*/
import { app, BrowserWindow } from 'electron';
import http from 'node:http';
@@ -47,6 +48,8 @@ const BACKEND = process.env.ESTELLA_VERIFY_BACKEND === 'webgpu' ? 'webgpu' : 'we
// ESTELLA_VERIFY_COLORSPACE=linear boots the linear-light pipeline (sRGB decode
// + linear blending + final OETF) — point expectations must be linear-derived.
const COLORSPACE = process.env.ESTELLA_VERIFY_COLORSPACE === 'linear' ? 'linear' : '';
+// ESTELLA_VERIFY_DEPTH_LAYERS=<mask> turns layers into depth-resolved ones (2.5D).
+const DEPTH_LAYERS = process.env.ESTELLA_VERIFY_DEPTH_LAYERS ?? '';
// Headless / GPU-less (CI) WebGL2 falls back to SwiftShader; harmless with a GPU.
app.commandLine.appendSwitch('enable-unsafe-swiftshader');
@@ -113,7 +116,7 @@ app.whenReady().then(async () => {
let server;
try {
server = await serveDist();
- const url = `http://127.0.0.1:${server.address().port}/headless.html?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}`;
+ const url = `http://127.0.0.1:${server.address().port}/headless.html?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}${DEPTH_LAYERS ? `&depthLayers=${DEPTH_LAYERS}` : ''}`;
// useContentSize: the capture rectangle must be the page area, not the
// outer frame (the same trap the parity runner documents).
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index f74ed5a43..ed749275c 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -498,6 +498,7 @@ class EngineHostImpl {
height: number;
backend?: 'webgl2' | 'webgpu';
colorSpace?: 'gamma' | 'linear';
+ depthLayers?: number;
}): Promise<void> {
if (this.booted) return;
this.booted = true;
@@ -511,6 +512,7 @@ class EngineHostImpl {
loadInitialScene: false,
backend: size.backend,
colorSpace: size.colorSpace,
+ depthLayers: size.depthLayers,
});
} catch (err) {
this.swallowUnwind(err);
@@ -526,6 +528,7 @@ class EngineHostImpl {
opts: {
runLoop: boolean; loadInitialScene: boolean;
backend?: 'webgl2' | 'webgpu'; colorSpace?: 'gamma' | 'linear';
+ depthLayers?: number;
},
) {
const backend = opts.backend ?? 'webgl2';
@@ -649,6 +652,7 @@ class EngineHostImpl {
const app = await bootProfiler.phase('createWebApp', () => createWebApp(module, {
renderSurface,
colorSpace: opts.colorSpace,
+ depthLayers: opts.depthLayers,
getViewportSize: () => ({ width: canvas.width, height: canvas.height }),
// The per-version spine side modules are served next to esengine.wasm
// (same /wasm/ dir as locateFile above), so the web spine provider can
diff --git a/desktop/src/headless.ts b/desktop/src/headless.ts
index c3c27b24d..2a0ad8166 100644
--- a/desktop/src/headless.ts
+++ b/desktop/src/headless.ts
@@ -35,8 +35,11 @@ const width = Number(params.get('w')) || 1280;
const height = Number(params.get('h')) || 720;
const backend = params.get('backend') === 'webgpu' ? 'webgpu' : 'webgl2';
const colorSpace = params.get('colorSpace') === 'linear' ? 'linear' : undefined;
+// A depth-layer mask, so the harness can exercise the 2.5D path the same way a
+// project setting would — the engine takes a mask, not a checkbox list.
+const depthLayers = Number(params.get('depthLayers')) || undefined;
window.__estellaHeadless = {
- ready: EngineHost.bootHeadless({ width, height, backend, colorSpace }),
+ ready: EngineHost.bootHeadless({ width, height, backend, colorSpace, depthLayers }),
api: EditorControlSurface,
};