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
docs(comments): the contract, not the story
yhha7701ad24862
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 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-lessdiff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hppindex 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.cppindex 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.hppindex 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 UBOdiff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 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