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
test(render): a paired check that 2.5D depth actually resolves occlusion
esengine44cf312eb9be
diff --git a/desktop/package.json b/desktop/package.jsonindex 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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.esmaterialnew file mode 100644index 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.esshadernew file mode 100644index 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 enddiff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 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.tsindex 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 candiff --git a/desktop/src/headless.ts b/desktop/src/headless.tsindex 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,};