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.

fix(render): a fragment-only material's vertex stage declares its position invariant, so its colour lands on its prepass depth on Metal

yhh5376f6933bad
diff --git a/CHANGELOG.md b/CHANGELOG.md
index df8b2c99d..a12551165 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -89,6 +89,7 @@ published separately; it ships inside the editor.
- **Lit materials draw on WebGPU again.** A lit material on the engine's own vertex stage, and a 2D lit shader, built a WebGPU program with a preprocessor line left in it, so the material drew nothing (and a desktop build of a 3D scene came up black). `#if` and `#elif` conditions with `defined`, `!`, `&&`, `||` and parentheses now resolve in a WGSL twin as they do in GLSL.
- **A scanned preview reaches the game's own server.** The page a phone opens from the preview QR code allowed connections only to itself, so a game that logged in to a server on the LAN worked in Play and in a single-file build but not on the phone. The preview now connects as Play does; a shipping web export still connects only to the servers listed in Project Settings → Allowed server origins.
+- **The ground has no dark patches on a Mac.** With the depth prepass on (quality high and medium), a material written as a fragment shader alone, the terrain among them, drew its colour from a vertex stage that did not declare its position invariant, while its depth came from one that did. Metal is free to compute the two a bit apart, and wherever they differed the colour failed the equal-depth test: sand, sea floor and grass showed dark triangles. Both stages now declare it, on WebGL2 and WebGPU.
- **A subpath of an official package resolves.** Importing `estella-plugin-…/something` from a project script no longer hangs the script build.
- **Background shader compilation, the warm-up and on-demand drawing reach a build whose quality level is Off.** A build dropped the whole `quality` block when the level was Off, though these three choices hold whatever the level: a project that switched `asyncShaderCompile`, `prewarmShaders` or `renderOnDemand` on read them in the editor and shipped a game that ignored them. The block now ships when any of them is on.
- **A terrain and a streamed world run on the Android and iOS templates.** The terrain's layer textures were refused on a device (it has no wasm heap to copy them through), and a chunked world's maker threw on every tick because QuickJS has no `AbortController`. The layers now go over as bytes, as every other texture does, and the world uses a handle of its own where the host has none.
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index d4db00432..b2364283a 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -248,7 +248,8 @@ void fillHook(std::string& src, const std::string& token, const std::string& tex
std::string wgslCanonicalVSOut(bool lit) {
std::string src =
"struct VSOut {\n"
- " @builtin(position) pos : vec4f,\n"
+ // Invariant as mesh.esshader's: a material's depth prepass draws with that stage and its colour pass with this one.
+ " @builtin(position) @invariant pos : vec4f,\n"
" @location(0) v_color : vec4f,\n"
" @location(1) v_texCoord : vec2f,\n";
if (lit) {
@@ -571,6 +572,9 @@ std::string canonicalVertexStage(bool lit, const std::string& hook = {}) {
"}\n"
"#endif\n"
"\n"
+ // A material's depth prepass draws with mesh.esshader's vertex stage and its colour pass with this one, landing on that depth by an
+ // equal test: both declare the position invariant, or a compiler (Metal's) may order the arithmetic differently and miss by a bit.
+ "invariant gl_Position;\n"
"out vec4 v_color;\n"
"out vec2 v_texCoord;\n"
"#ifdef MESH_NORMALS\n"
diff --git a/tests/renderer/test_shader_variant.cpp b/tests/renderer/test_shader_variant.cpp
index 8f0735ea9..df9fa6776 100644
--- a/tests/renderer/test_shader_variant.cpp
+++ b/tests/renderer/test_shader_variant.cpp
@@ -256,6 +256,8 @@ static void testWGSLEmission() {
CHECK(vs.find("@group(0) @binding(0) var<uniform> frame") != std::string::npos,
"canonical WGSL vertex reads FrameConstants at binding 0");
CHECK(vs.find("v_worldPos") == std::string::npos, "Unlit WGSL vertex has no world-pos varying");
+ // See testFragmentOnly: the colour pass behind a material's depth prepass.
+ CHECK(vs.find("@builtin(position) @invariant pos") != std::string::npos, "canonical WGSL vertex declares its position invariant");
const std::string fs = wgsl(p, ShaderStage::Fragment);
CHECK(fs.find("struct VSOut") != std::string::npos, "canonical varying interface injected");
@@ -431,6 +433,12 @@ static void testFragmentOnly() {
"Lit canonical vertex forwards world position");
const std::string lf = ShaderParser::assembleStage(lit, ShaderStage::Fragment);
CHECK(lf.find("applyLighting2D") != std::string::npos, "Lit fragment gets the lighting helper injected");
+ // A material's depth prepass draws with mesh.esshader's vertex stage, which declares its position invariant; the colour pass lands on that
+ // depth by an equal test from this stage, so it must declare it too. The drivers the pixel gates run on happen to agree without it; Metal does not.
+ for (const ParsedShader* s : {&unlit, &lit}) {
+ CHECK(ShaderParser::assembleStage(*s, ShaderStage::Vertex, "", {"MESH"}).find("invariant gl_Position;") != std::string::npos,
+ "canonical GLSL vertex declares its position invariant");
+ }
ParsedShader pp = ShaderParser::parse(FRAG_ONLY_POSTPROCESS);
CHECK(pp.valid, "fragment-only PostProcess shader parses");
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index d334776fb..30b366777 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -3426,4 +3426,6 @@ export const NOTED = {
{"internal":"undoes a regression from after 0.96.0 that no release carried"},
"fix(editor): the loading screens take the type scale and the shadow token, and the play overlay's stop is a Button":
{"note":"The loading screens say how far they are."},
+ "fix(render): a fragment-only material's vertex stage declares its position invariant, so its colour lands on its prepass depth on Metal":
+ {"note":"The ground has no dark patches on a Mac."},
};