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.

docs(comments): the contract, not the story

yhha7701ad24862
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 49ab58e0e..b566d3497 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -71,12 +71,9 @@ app.commandLine.appendSwitch('disable-gpu-sandbox');
// for a human). The pixel assertions do not: a composited read is colour
// managed, turning rgb(0,255,0) into rgb(58,254,32) switch or no switch.
app.commandLine.appendSwitch('force-color-profile', 'srgb');
-// ...and the same reason for the SIZE of a device pixel. The headless canvas is
-// never attached to a document, so its bounding rect is all zeros and a client
-// coordinate reaches the hit test as `client * devicePixelRatio` — the developer's
-// own monitor scaling. At Windows' 150% every ESTELLA_VERIFY_PICK landed 1.5x away
-// from the point it named and answered null, so two gates were red on one machine
-// and green on another, about nothing.
+// ...and the same for the SIZE of a device pixel: this canvas is never attached to
+// a document, so its rect is zeros and a client coordinate reaches the hit test as
+// `client * devicePixelRatio` — whatever the machine's display happens to scale by.
app.commandLine.appendSwitch('force-device-scale-factor', '1');
// WebGPU: the unsafe flag covers non-default platforms (Linux CI); the optional
// software adapter (ESTELLA_VERIFY_WEBGPU_ADAPTER=swiftshader) gives GPU-less
diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hpp
index 4ea218dec..113d21ecf 100644
--- a/src/esengine/renderer/draw/DrawList.hpp
+++ b/src/esengine/renderer/draw/DrawList.hpp
@@ -64,18 +64,10 @@ public:
/**
* @brief Whether a frame holding these draws has to be handed a depth buffer.
*
- * @details Two things resolve by depth and they are ONE question. A layer the
- * project declared depth-resolved is one; a draw that declared it for
- * ITSELF is the other — an opaque mesh writes and tests depth without
- * waiting for a layer to grant it, which is what lets one model hide
- * another in a project that never heard of 2.5D. Asking only the mask
- * is how an opaque mesh came to test against an attachment nobody
- * made: a depth test with no buffer behind it does not fail, it
- * passes, and an opaque draw sorts front-to-back for early-z — so the
- * furthest is painted last and the picture inverts rather than
- * degrading.
- *
- * This is the whole answer, so nobody downstream needs a second one.
+ * @details Two things resolve by depth and they are ONE question: a layer the
+ * project declared depth-resolved, and a draw that declared it for
+ * ITSELF (an opaque mesh). A depth test with no attachment behind it
+ * PASSES, and opaque sorts front-to-back — the furthest paints last.
*/
bool needsDepth() const { return depth_mask_ != 0 || depth_required_; }
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index aba9d7a60..b826b87aa 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -1117,11 +1117,9 @@ void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {
plugin->collect(collectCtx);
}
- // What this camera drew is part of what the FRAME drew: OR-ed across the
- // frame's cameras and applied at the next beginFrame, never mid-frame. The
- // capture is scratch each camera composites out of, so rebuilding it between
- // two of them would drop the pixels the first one has not composited yet —
- // and the editor's grid, which draws between begin() and this collect.
+ // OR-ed across the frame's cameras, applied at the next beginFrame and never
+ // mid-frame: the capture is scratch each camera composites out of, and the
+ // editor's grid draws into it between begin() and this collect.
frame_collected_ = true;
frame_depth_seen_ = frame_depth_seen_ || draw_list_.needsDepth();
}
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index cdcb79500..caa61ca68 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -108,13 +108,10 @@ public:
/**
* @brief Opens the FRAME, once, before any of its cameras.
*
- * @details begin()/end() bracket one CAMERA — a frame runs the pair once per
- * camera — so a decision that must hold steady across a frame cannot
- * be made there. This is where the scene's depth requirement is rolled
- * forward and applied (@ref applySceneDepthNeed): the attachment the
- * capture is built with then stays put for every camera in the frame,
- * instead of a 2D camera's answer dropping the buffer a 3D camera two
- * lines later is about to test against.
+ * @details begin()/end() bracket one CAMERA, so a decision that must hold
+ * steady across a frame cannot be made there. The scene's depth
+ * requirement is rolled forward and applied here
+ * (@ref applySceneDepthNeed), once, for every camera in the frame.
*/
void beginFrame();
@@ -315,29 +312,12 @@ private:
void buildClipState();
/**
- * @brief Tells the capture whether to carry a depth attachment, from the one
- * answer there is.
+ * @brief Tells the capture whether to carry a depth attachment.
*
- * @details The capture's attachments are chosen when it is BUILT, which is
- * before the frame has collected anything — so the frame cannot be
- * asked, and the previous one is asked instead. Three states, and the
- * conservative one is the default:
- *
- * - Nothing answered yet (boot): the frame gets depth. A 3D scene is
- * therefore right on the first frame it draws, which is the frame a
- * single-shot capture — a thumbnail, a preview, a pixel gate — takes.
- * - A frame answered and nothing in it resolved by depth: released, so
- * a 2D project pays for one frame's attachment and no more. That is
- * the cost this flag exists to save and it is still saved.
- * - Anything ever resolved by depth: kept, permanently. A latch and not
- * a per-frame answer, because culling makes a per-frame one flap —
- * the lone mesh that leaves the frustum would take the buffer with it
- * and the frame it comes back on would have none.
- *
- * What remains is one frame: a world with no depth-resolving renderable
- * that gains its first. It self-heals on the next frame and never
- * returns, which is the price of an attachment chosen before the
- * content that needs it is known.
+ * @details Chosen when the capture is BUILT, before this frame has collected,
+ * so the PREVIOUS frame answers and an unanswered one (boot) gets
+ * depth. Released once a frame proves nothing needs it, latched on
+ * once anything does — culling would make a per-frame answer flap.
*/
void applySceneDepthNeed();
/// Gathers the scene's enabled Light2D components into the per-frame LightConstants UBO
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index b1264b041..563381346 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -48,12 +48,9 @@ export const SCENES = [
{ id: "editor-grid", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_STEPS: "3" } },
// The same grid from straight above a 3D view. It stands on the ground there, so it fills the frame; the 2D plane would be edge-on and light one band.
{ id: "editor-grid-3d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,90", ESTELLA_VERIFY_STEPS: "3" } },
- // The same 3D view head-on, where the eye would stand IN the ground it works on.
- // It does not work that ground: a plane within ~6 degrees of edge-on hands over
- // to the plane the eye most faces, which head-on is the 2D plane — so the grid
- // covers the frame here rather than collapsing to the single horizontal stroke
- // an edge-on plane draws. This gate held the OLD rule ("no picture at all") and
- // was the last thing still asserting it.
+ // The same 3D view head-on. A plane within ~6 degrees of edge-on hands over to the
+ // plane the eye most faces, which head-on is the 2D plane — so the grid covers the
+ // frame instead of collapsing to the one stroke an edge-on plane draws.
{ id: "editor-grid-head-on", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,0", ESTELLA_VERIFY_STEPS: "3" } },
{ id: "mesh2d", tier: "pr", webgpu: true, env: { 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}]" } },
{ id: "parallax-shape", tier: "pr", webgpu: true, env: { 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}]" } },
@@ -94,14 +91,9 @@ export const SCENES = [
// read 255·cos22.5 and 255·cos67.5, swapped if the winding is inside out; the sphere
// reads 155 at -25 against 236 at its middle, which a flat quad could not.
{ id: "mesh-instanced", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_DRAW_CALLS: "1", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":20},{\"x\":0.75,\"y\":0.25,\"rgb\":[0,255,0],\"tol\":20},{\"x\":0.25,\"y\":0.75,\"rgb\":[0,0,255],\"tol\":20},{\"x\":0.75,\"y\":0.75,\"rgb\":[255,255,0],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },
- // Two opaque cubes overlapping on screen, the red one 120 units nearer. An opaque
- // draw sorts front-to-back, so with a depth buffer the red one owns the overlap and
- // without one the green is simply painted over it — the picture inverts rather than
- // degrading. Deliberately declares NO depth layer, because an opaque mesh has not
- // needed one since it began saying so itself, and boots LINEAR, which is the cheaper
- // of the two ways a project engages the post-process capture (a bloom pass is the
- // other). That is the whole scene: the frame's depth attachment is decided by the
- // project's depth-layer mask, and what asks for depth here never touched it.
+ // Two opaque cubes overlapping on screen, the red one 120 units nearer. Declares NO
+ // depth layer and boots LINEAR — the cheap way to engage the post-process capture.
+ // Opaque sorts front-to-back, so with no attachment the far cube paints over.
{ id: "mesh-depth-through-capture", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_SCENE: "/scenes/mesh-depth-through-capture.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.57,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.4,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.74,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":30},{\"x\":0.1,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },
{ id: "mesh-builtin", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-builtin.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.3667,\"y\":0.5,\"rgb\":[236,236,236],\"tol\":20},{\"x\":0.1333,\"y\":0.5,\"rgb\":[98,98,98],\"tol\":20},{\"x\":0.75,\"y\":0.5,\"rgb\":[236,236,236],\"tol\":20},{\"x\":0.6667,\"y\":0.5,\"rgb\":[155,155,155],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },
// A baked panorama lighting a surface BY DIRECTION: two coplanar triangles, one