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.

feat(render): a surface can say what it is made of

esengine95c8df7ee1c2
diff --git a/desktop/public/scenes/mat-pbr.esscene b/desktop/public/scenes/mat-pbr.esscene
new file mode 100644
index 000000000..31bf4a550
--- /dev/null
+++ b/desktop/public/scenes/mat-pbr.esscene
@@ -0,0 +1,207 @@
+{
+ "version": 1,
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 519.615
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 60,
+ "nearPlane": 0.1,
+ "farPlane": 1000,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Gloss",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 160,
+ "y": 160
+ },
+ "color": {
+ "r": 0,
+ "g": 0.3,
+ "b": 0,
+ "a": 1
+ },
+ "material": "/scenes/mat-pbr/gloss.esmaterial"
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "Matte",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -180,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 160,
+ "y": 160
+ },
+ "color": {
+ "r": 0,
+ "g": 0.3,
+ "b": 0,
+ "a": 1
+ },
+ "material": "/scenes/mat-pbr/matte.esmaterial"
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "ViewVector",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 180,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 160,
+ "y": 160
+ },
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "material": "/scenes/mat-pbr/viewvec.esmaterial"
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 4,
+ "name": "GlossLight",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 0,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "radius": 150
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 5,
+ "name": "MatteLight",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -180,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 0,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "radius": 150
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/mat-pbr/gloss.esmaterial b/desktop/public/scenes/mat-pbr/gloss.esmaterial
new file mode 100644
index 000000000..e953c1ddb
--- /dev/null
+++ b/desktop/public/scenes/mat-pbr/gloss.esmaterial
@@ -0,0 +1,12 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "pbr.esshader",
+ "blendMode": 0,
+ "depthTest": false,
+ "properties": {
+ "u_metallic": 0,
+ "u_roughness": 0.25,
+ "u_specular": 1
+ }
+}
diff --git a/desktop/public/scenes/mat-pbr/matte.esmaterial b/desktop/public/scenes/mat-pbr/matte.esmaterial
new file mode 100644
index 000000000..8f1fc0e07
--- /dev/null
+++ b/desktop/public/scenes/mat-pbr/matte.esmaterial
@@ -0,0 +1,12 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "pbr.esshader",
+ "blendMode": 0,
+ "depthTest": false,
+ "properties": {
+ "u_metallic": 0,
+ "u_roughness": 0.25,
+ "u_specular": 0
+ }
+}
diff --git a/desktop/public/scenes/mat-pbr/pbr.esshader b/desktop/public/scenes/mat-pbr/pbr.esshader
new file mode 100644
index 000000000..a1410a3a0
--- /dev/null
+++ b/desktop/public/scenes/mat-pbr/pbr.esshader
@@ -0,0 +1,39 @@
+#pragma shader "PBRTest"
+#pragma version 300 es
+#pragma domain Lit2D
+#pragma param u_metallic float default(0) range(0,1)
+#pragma param u_roughness float default(1) range(0,1)
+#pragma param u_specular float default(0) range(0,1)
+
+#pragma fragment
+precision mediump float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+in highp vec2 v_worldPos;
+
+uniform sampler2D u_textures[8];
+
+out vec4 fragColor;
+
+// The general lighting form, called directly with the parameters a lit sprite
+// leaves at their zero. Same lights, same surface, same fixture — only the
+// microfacet lobe differs, so the two materials over this shader isolate it.
+void main() {
+ vec4 base = texture(u_textures[0], v_texCoord) * v_color;
+ highp vec3 P = vec3(v_worldPos, 0.0);
+ highp vec3 lit = applyLightingPBR(base.rgb, vec3(0.0, 0.0, 1.0), P, viewDirection(P),
+ u_metallic, u_roughness, u_specular, 1.0);
+ fragColor = vec4(lit, base.a);
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ let base = textureSampleLevel(t0, s0, v.v_texCoord, 0.0) * v.v_color;
+ let P = vec3f(v.v_worldPos, 0.0);
+ let lit = applyLightingPBR(base.rgb, vec3f(0.0, 0.0, 1.0), P, viewDirection(P),
+ mc.u_metallic, mc.u_roughness, mc.u_specular, 1.0);
+ return vec4f(lit, base.a);
+}
+#pragma end
diff --git a/desktop/public/scenes/mat-pbr/viewvec.esmaterial b/desktop/public/scenes/mat-pbr/viewvec.esmaterial
new file mode 100644
index 000000000..35eaef45c
--- /dev/null
+++ b/desktop/public/scenes/mat-pbr/viewvec.esmaterial
@@ -0,0 +1,8 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "viewvec.esshader",
+ "blendMode": 0,
+ "depthTest": false,
+ "properties": {}
+}
diff --git a/desktop/public/scenes/mat-pbr/viewvec.esshader b/desktop/public/scenes/mat-pbr/viewvec.esshader
new file mode 100644
index 000000000..ff938cb3e
--- /dev/null
+++ b/desktop/public/scenes/mat-pbr/viewvec.esshader
@@ -0,0 +1,28 @@
+#pragma shader "ViewVectorTest"
+#pragma version 300 es
+#pragma domain Lit2D
+
+#pragma fragment
+precision mediump float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+in highp vec2 v_worldPos;
+
+out vec4 fragColor;
+
+// The view vector itself, encoded as a color. An orthographic camera looking
+// down -z answers (0,0,1) -> (128,128,255); a frame block that never received
+// the camera answers (0,0,0) -> (128,128,128), which no probe can mistake.
+void main() {
+ highp vec3 V = viewDirection(vec3(v_worldPos, 0.0));
+ fragColor = vec4(V * 0.5 + 0.5, 1.0);
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ let V = viewDirection(vec3f(v.v_worldPos, 0.0));
+ return vec4f(V * 0.5 + 0.5, 1.0);
+}
+#pragma end
diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdx
index fbe33b2a2..ca0d4ff3a 100644
--- a/docs/astro/src/content/docs/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/graphics/lighting.mdx
@@ -146,6 +146,40 @@ The `N` you pass to `applyLighting2D` is the surface normal. Passing a constant
catches highlights and shadow from each light's direction. Add the normal texture as a
`#pragma param … texture` on your lit material (see [Materials & Shaders](/docs/graphics/materials/)).
+### Metal, roughness and highlights
+
+`applyLighting2D` is the shorthand for a surface that reflects nothing. The general
+form takes the same lights through a microfacet BRDF, and a Lit-2D shader can call
+it directly:
+
+```glsl
+highp vec3 P = vec3(v_worldPos, 0.0);
+highp vec3 lit = applyLightingPBR(
+ base.rgb, // albedo
+ N, // surface normal
+ P, // world position
+ viewDirection(P), // toward the camera, from the frame block
+ u_metallic, // 0 = dielectric, 1 = metal
+ u_roughness, // 0 = mirror, 1 = fully diffuse
+ u_specular, // glTF's specularFactor: 0 removes the highlight
+ 1.0 // ambient occlusion
+);
+```
+
+`applyLighting2D(albedo, N, worldPos)` is exactly this call with `metallic = 0`,
+`roughness = 1` and `specular = 0` — so a lit sprite keeps drawing the pixels it
+always did, and a surface that wants a highlight asks for one.
+
+`viewDirection(worldPos)` answers with the unit vector pointing at the camera; it
+reads the eye position the engine puts in the frame block each frame, so an
+orthographic camera returns a constant and a perspective one varies per pixel.
+
+<Aside>
+ Lights are still placed in the plane: a `Light2D` has no third coordinate, so
+ distance is measured in xy and a point light's height comes from its radius. The
+ normal and the view vector are the three-dimensional part of the model.
+</Aside>
+
## Casting shadows
Add a **`ShadowCaster2D`** to an entity to make it block light and cast a shadow:
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
index 48017bdf6..a4190ad42 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
@@ -142,6 +142,36 @@ const applyLit = defineSystem([Query(Mut(Sprite))], (q) => {
灯的方向产生高光和阴影。把法线纹理作为一个 `#pragma param … texture` 加到你的受光材质上
(见[材质与着色器](/docs/zh-cn/graphics/materials/))。
+### 金属度、粗糙度与高光
+
+`applyLighting2D` 是"这个表面什么都不反射"的简写。它的一般形式让同样的灯走一遍微表面
+BRDF,Lit2D 着色器可以直接调用:
+
+```glsl
+highp vec3 P = vec3(v_worldPos, 0.0);
+highp vec3 lit = applyLightingPBR(
+ base.rgb, // albedo
+ N, // 表面法线
+ P, // 世界位置
+ viewDirection(P), // 指向相机,来自 frame 块
+ u_metallic, // 0 = 电介质,1 = 金属
+ u_roughness, // 0 = 镜面,1 = 完全漫反射
+ u_specular, // glTF 的 specularFactor:0 让高光消失
+ 1.0 // 环境光遮蔽
+);
+```
+
+`applyLighting2D(albedo, N, worldPos)` 就是这个调用取 `metallic = 0`、`roughness = 1`、
+`specular = 0` —— 所以受光精灵画出的像素一个都没变,而想要高光的表面自己开口要。
+
+`viewDirection(worldPos)` 返回指向相机的单位向量;它读引擎每帧写进 frame 块的相机位置,
+所以正交相机返回一个常量,透视相机逐像素变化。
+
+<Aside>
+ 灯仍然摆在平面上:`Light2D` 没有第三个坐标,所以距离在 xy 内度量,点光的高度来自它的
+ 半径。法线与视线才是这个模型里三维的部分。
+</Aside>
+
## 投射阴影
给一个实体加 **`ShadowCaster2D`**,让它遮挡光并投出阴影:
diff --git a/src/esengine/renderer/frame/FrameConstants.hpp b/src/esengine/renderer/frame/FrameConstants.hpp
index 20cdb9fed..88f01a67a 100644
--- a/src/esengine/renderer/frame/FrameConstants.hpp
+++ b/src/esengine/renderer/frame/FrameConstants.hpp
@@ -26,12 +26,14 @@ namespace esengine {
/**
* @brief CPU mirror of the GLSL FrameConstants block (std140).
- * @details A lone mat4 occupies 64 bytes at offset 0 with 16-byte alignment, so the
- * std140 layout needs no padding. Append future per-frame fields here and in
- * the shader block in the same order (std140 keeps prior offsets stable).
+ * @details A mat4 at offset 0 and a vec4 at 64 need no std140 padding. Append future
+ * fields here and in ShaderParser's injected block in the same order.
+ * camera: w = 1 means xyz is the eye's world position (perspective), w = 0
+ * that xyz points at the viewer (orthographic has no eye point).
*/
struct FrameConstants {
glm::mat4 viewProjection{1.0f};
+ glm::vec4 camera{0.0f, 0.0f, 1.0f, 0.0f};
};
/** @brief Indexed uniform binding point the FrameConstants block is bound to. */
diff --git a/src/esengine/renderer/frame/RenderContext.cpp b/src/esengine/renderer/frame/RenderContext.cpp
index a45f4f750..7ce4732d4 100644
--- a/src/esengine/renderer/frame/RenderContext.cpp
+++ b/src/esengine/renderer/frame/RenderContext.cpp
@@ -18,6 +18,7 @@
#include "../store/SkinConstants.hpp"
#include "../../core/Log.hpp"
+#include <cmath>
#include <vector>
#include <glm/gtc/type_ptr.hpp>
@@ -154,9 +155,21 @@ void RenderContext::initFrameUbo() {
ES_LOG_DEBUG("FrameConstants UBO created (handle: {})", static_cast<u32>(frameUbo_));
}
+// Where the frame is seen from, read out of the matrix that projects it — every
+// path in hands over a view-projection and nothing else. inverse(VP) on the clip
+// z axis: perspective divides down to the eye, else negate to face the viewer.
+static glm::vec4 cameraFromViewProjection(const glm::mat4& viewProjection) {
+ const glm::vec4 axis = glm::inverse(viewProjection)[2];
+ if (std::abs(axis.w) > 1e-6f) return glm::vec4(glm::vec3(axis) / axis.w, 1.0f);
+ const f32 len = glm::length(glm::vec3(axis));
+ if (len < 1e-12f) return glm::vec4(0.0f, 0.0f, 1.0f, 0.0f);
+ return glm::vec4(-glm::vec3(axis) / len, 0.0f);
+}
+
void RenderContext::updateFrameConstants(const glm::mat4& viewProjection) {
viewProjection_ = viewProjection;
- device_.updateBuffer(frameUbo_, 0, glm::value_ptr(viewProjection), sizeof(glm::mat4));
+ const FrameConstants frame{viewProjection, cameraFromViewProjection(viewProjection)};
+ device_.updateBuffer(frameUbo_, 0, &frame, sizeof(FrameConstants));
// Re-arm the params fallback for this pass: a post-process or custom-draw
// commit from the previous pass left its own (differently sized) buffer on
// the shared slot.
diff --git a/src/esengine/renderer/frame/RenderContext.hpp b/src/esengine/renderer/frame/RenderContext.hpp
index fba3c255b..778da4ee9 100644
--- a/src/esengine/renderer/frame/RenderContext.hpp
+++ b/src/esengine/renderer/frame/RenderContext.hpp
@@ -155,6 +155,8 @@ public:
* @brief Uploads the per-frame view-projection into the shared FrameConstants UBO.
* @details Called once per render pass before its draws; every engine shader reads
* u_projection from this single UBO (bound at FRAME_CONSTANTS_BINDING).
+ * The camera's own placement rides along, recovered from the matrix — every
+ * path in hands over exactly one view-projection and nothing else.
*/
void updateFrameConstants(const glm::mat4& viewProjection);
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index b47ee2db4..1b9171947 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -624,8 +624,12 @@ const char* wgslTypeName(ShaderPropertyType t) {
// kTimeHeader's twin. Injected into every WGSL stage; the device's explicit
// layouts make a declared-but-unused block legal, same as GL.
const char* kFrameHeaderWGSL =
- "struct FrameConstants { projection : mat4x4f };\n"
- "@group(0) @binding(0) var<uniform> frame : FrameConstants;\n";
+ "struct FrameConstants { projection : mat4x4f, camera : vec4f };\n"
+ "@group(0) @binding(0) var<uniform> frame : FrameConstants;\n"
+ "fn viewDirection(worldPos : vec3f) -> vec3f {\n"
+ " if (frame.camera.w > 0.5) { return normalize(frame.camera.xyz - worldPos); }\n"
+ " return frame.camera.xyz;\n"
+ "}\n";
const char* kTimeHeaderWGSL =
"struct TimeConstants { u_time : vec4f, u_viewport : vec4f };\n"
@@ -751,8 +755,25 @@ fn shadowFactor2D(worldPos : vec2f, aim : vec2f, softness : f32) -> f32 {
}
return 1.0 - blocked / 5.0;
}
-fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> vec3f {
+fn distributionGGX(NdotH : f32, a : f32) -> f32 {
+ let a2 = a * a;
+ let d = NdotH * NdotH * (a2 - 1.0) + 1.0;
+ return a2 / max(3.14159265 * d * d, 1e-7);
+}
+fn geometrySmith(NdotV : f32, NdotL : f32, roughness : f32) -> f32 {
+ let k = (roughness + 1.0) * (roughness + 1.0) * 0.125;
+ return (NdotV / (NdotV * (1.0 - k) + k)) * (NdotL / (NdotL * (1.0 - k) + k));
+}
+fn fresnelSchlick(VdotH : f32, F0 : vec3f) -> vec3f {
+ return F0 + (vec3f(1.0) - F0) * pow(1.0 - VdotH, 5.0);
+}
+fn applyLightingPBR(albedo : vec3f, N : vec3f, worldPos : vec3f, V : vec3f, metallic : f32,
+ roughness : f32, specular : f32, ao : f32) -> vec3f {
+ let F0 = mix(vec3f(0.04), albedo, vec3f(metallic));
+ let a = max(roughness * roughness, 1e-3);
+ let NdotV = max(dot(N, V), 1e-4);
var lit = lc.u_ambient.rgb * ao;
+ var gloss = vec3f(0.0);
for (var i = 0; i < 16; i++) {
let pd = lc.u_lights[i].posDir;
let col = lc.u_lights[i].color;
@@ -762,7 +783,7 @@ fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> v
var aim = pd.xy;
var castShadow = true;
if (pd.z < 0.5) {
- let d = pd.xy - worldPos;
+ let d = pd.xy - worldPos.xy;
let dist = length(d);
atten = max(0.0, 1.0 - dist / max(pd.w, 0.0001));
L = normalize(vec3f(d, max(pd.w, 1.0)));
@@ -772,10 +793,10 @@ fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> v
var toLight = vec2f(0.0, 0.0);
if (dot(pd.xy, pd.xy) > 1e-8) { toLight = normalize(-pd.xy); }
castShadow = sh.y > 0.0 && dot(toLight, toLight) > 0.5;
- aim = worldPos + toLight * sh.y;
+ aim = worldPos.xy + toLight * sh.y;
} else {
let sp = lc.u_lights[i].spot;
- let d = pd.xy - worldPos;
+ let d = pd.xy - worldPos.xy;
let dist = length(d);
atten = max(0.0, 1.0 - dist / max(pd.w, 0.0001));
L = normalize(vec3f(d, max(pd.w, 1.0)));
@@ -784,12 +805,25 @@ fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> v
atten *= smoothstep(sp.w, sp.z, dot(sp.xy, toFrag));
}
if (castShadow && col.a > 0.0 && atten > 0.0) {
- atten *= shadowFactor2D(worldPos, aim, sh.x);
+ atten *= shadowFactor2D(worldPos.xy, aim, sh.x);
}
let ndotl = max(dot(N, L), 0.0);
- lit += col.rgb * (col.a * ndotl * atten);
+ let radiance = col.rgb * (col.a * ndotl * atten);
+ lit += radiance;
+ if (specular > 0.0) {
+ let H = normalize(L + V);
+ let brdf = distributionGGX(max(dot(N, H), 0.0), a)
+ * geometrySmith(NdotV, ndotl, roughness)
+ / max(4.0 * NdotV * ndotl, 1e-4);
+ gloss += radiance * fresnelSchlick(max(dot(V, H), 0.0), F0)
+ * (brdf * 3.14159265 * specular);
+ }
}
- return albedo * lit;
+ return albedo * (1.0 - metallic) * lit + gloss;
+}
+fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> vec3f {
+ let P = vec3f(worldPos, 0.0);
+ return applyLightingPBR(albedo, N, P, viewDirection(P), 0.0, 1.0, 0.0, ao);
}
fn applyLighting2D(albedo : vec3f, N : vec3f, worldPos : vec2f) -> vec3f {
return applyLighting2DAO(albedo, N, worldPos, 1.0);
@@ -1030,7 +1064,11 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
static const char* kFrameHeader =
"layout(std140) uniform FrameConstants {\n"
" highp mat4 u_projection;\n"
- "};\n";
+ " highp vec4 u_camera;\n" // xyz = eye (w=1) or direction toward it (w=0)
+ "};\n"
+ "highp vec3 viewDirection(in highp vec3 worldPos) {\n"
+ " return u_camera.w > 0.5 ? normalize(u_camera.xyz - worldPos) : u_camera.xyz;\n"
+ "}\n";
assembled << kFrameHeader;
headerLines += countNewlines(kFrameHeader);
@@ -1168,11 +1206,40 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" }\n"
" return 1.0 - blocked / float(K);\n"
"}\n"
- // Ambient occlusion darkens the light that arrives from everywhere, which is
- // the ambient term; a lit surface's own lights are unobstructed by it.
- "highp vec3 applyLighting2DAO(highp vec3 albedo, highp vec3 N, highp vec2 worldPos,\n"
- " highp float ao) {\n"
+ // The microfacet terms: GGX distribution, Smith geometry (the direct-light k,
+ // off perceptual roughness), Schlick fresnel. Guarded denominators, because a
+ // specular weight of zero must multiply a finite number to reach exactly zero.
+ "highp float distributionGGX(in highp float NdotH, in highp float a) {\n"
+ " highp float a2 = a * a;\n"
+ " highp float d = NdotH * NdotH * (a2 - 1.0) + 1.0;\n"
+ " return a2 / max(3.14159265 * d * d, 1e-7);\n"
+ "}\n"
+ "highp float geometrySmith(in highp float NdotV, in highp float NdotL,\n"
+ " in highp float roughness) {\n"
+ " highp float k = (roughness + 1.0) * (roughness + 1.0) * 0.125;\n"
+ " return (NdotV / (NdotV * (1.0 - k) + k)) * (NdotL / (NdotL * (1.0 - k) + k));\n"
+ "}\n"
+ "highp vec3 fresnelSchlick(in highp float VdotH, in highp vec3 F0) {\n"
+ " return F0 + (vec3(1.0) - F0) * pow(1.0 - VdotH, 5.0);\n"
+ "}\n"
+ // The lighting model in its general form; a lit 2D surface is its zero
+ // (metallic 0, roughness 1, specular 0 leaves albedo * NdotL, pixel for pixel
+ // what this engine has always drawn), so there is one model and not two.
+ "highp vec3 applyLightingPBR(in highp vec3 albedo, in highp vec3 N, in highp vec3 worldPos,\n"
+ " in highp vec3 V, in highp float metallic,\n"
+ " in highp float roughness, in highp float specular,\n"
+ " in highp float ao) {\n"
+ // glTF's specularFactor scales the whole lobe, so 0 removes it rather than
+ // leaving Schlick's grazing-angle rim behind.
+ " highp vec3 F0 = mix(vec3(0.04), albedo, metallic);\n"
+ " highp float a = max(roughness * roughness, 1e-3);\n"
+ " highp float NdotV = max(dot(N, V), 1e-4);\n"
+ // Occlusion darkens the light that arrives from everywhere, which is the
+ // ambient term; a surface's own lights are unobstructed by it.
" highp vec3 lit = u_ambient.rgb * ao;\n"
+ " highp vec3 gloss = vec3(0.0);\n"
+ // A Light2D has no third coordinate, so distance stays in the plane and a
+ // point light's height is its radius. Normal and view are the 3D part.
" for (int i = 0; i < 16; ++i) {\n"
" highp vec4 pd = u_lights[i].posDir;\n"
" highp vec4 col = u_lights[i].color;\n"
@@ -1182,7 +1249,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" highp vec2 target = pd.xy;\n" // shadow-ray aim point (light position by default)
" bool castShadow = true;\n"
" if (pd.z < 0.5) {\n"
- " highp vec2 d = pd.xy - worldPos;\n"
+ " highp vec2 d = pd.xy - worldPos.xy;\n"
" highp float dist = length(d);\n"
" atten = max(0.0, 1.0 - dist / max(pd.w, 0.0001));\n"
" L = normalize(vec3(d, max(pd.w, 1.0)));\n"
@@ -1193,10 +1260,10 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// a positive march distance, and require a real direction (a zeroed one casts nothing).
" highp vec2 toLight = (dot(pd.xy, pd.xy) > 1e-8) ? normalize(-pd.xy) : vec2(0.0);\n"
" castShadow = sh.y > 0.0 && dot(toLight, toLight) > 0.5;\n"
- " target = worldPos + toLight * sh.y;\n"
+ " target = worldPos.xy + toLight * sh.y;\n"
" } else {\n"
" highp vec4 sp = u_lights[i].spot;\n"
- " highp vec2 d = pd.xy - worldPos;\n"
+ " highp vec2 d = pd.xy - worldPos.xy;\n"
" highp float dist = length(d);\n"
" atten = max(0.0, 1.0 - dist / max(pd.w, 0.0001));\n"
" L = normalize(vec3(d, max(pd.w, 1.0)));\n"
@@ -1206,12 +1273,29 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// Only pay for the shadow test when the light actually reaches this fragment (skips the
// zeroed/inactive slots and unlit fragments — cheaper than the old unconditional call).
" if (castShadow && col.a > 0.0 && atten > 0.0) {\n"
- " atten *= shadowFactor2D(worldPos, target, sh.x);\n"
+ " atten *= shadowFactor2D(worldPos.xy, target, sh.x);\n"
" }\n"
" highp float ndotl = max(dot(N, L), 0.0);\n"
- " lit += col.rgb * (col.a * ndotl * atten);\n"
+ " highp vec3 radiance = col.rgb * (col.a * ndotl * atten);\n"
+ " lit += radiance;\n"
+ // A uniform branch: a surface that reflects nothing does not pay for the lobe.
+ // The pi turns the engine's light intensity into the irradiance the BRDF wants,
+ // which the diffuse side cancels against albedo/pi and never has to spell out.
+ " if (specular > 0.0) {\n"
+ " highp vec3 H = normalize(L + V);\n"
+ " highp float brdf = distributionGGX(max(dot(N, H), 0.0), a)\n"
+ " * geometrySmith(NdotV, ndotl, roughness)\n"
+ " / max(4.0 * NdotV * ndotl, 1e-4);\n"
+ " gloss += radiance * fresnelSchlick(max(dot(V, H), 0.0), F0)\n"
+ " * (brdf * 3.14159265 * specular);\n"
+ " }\n"
" }\n"
- " return albedo * lit;\n"
+ " return albedo * (1.0 - metallic) * lit + gloss;\n"
+ "}\n"
+ "highp vec3 applyLighting2DAO(highp vec3 albedo, highp vec3 N, highp vec2 worldPos,\n"
+ " highp float ao) {\n"
+ " highp vec3 P = vec3(worldPos, 0.0);\n"
+ " return applyLightingPBR(albedo, N, P, viewDirection(P), 0.0, 1.0, 0.0, ao);\n"
"}\n"
"highp vec3 applyLighting2D(highp vec3 albedo, highp vec3 N, highp vec2 worldPos) {\n"
" return applyLighting2DAO(albedo, N, worldPos, 1.0);\n"
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index fd2604e0e..a682662f2 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -122,6 +122,10 @@ export const SCENES = [
{ id: "material-lit-spot", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-spot.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-spot.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,228,0],\"tol\":55},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":35}]" } },
{ id: "material-lit-flatnormal", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-flatnormal.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-flatnormal.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":30}]" } },
{ id: "sprite-lit", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":30}]" } },
+ // The general lighting form and the camera it needs: three surfaces, a point
+ // light over each. Specular 1 saturates white, specular 0 stays diffuse green,
+ // and the view vector under a PERSPECTIVE camera no untouched block can fake.
+ { id: "mat-pbr", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-pbr.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,255,255],\"tol\":20},{\"x\":0.2,\"y\":0.5,\"rgb\":[0,76,0],\"tol\":20},{\"x\":0.8,\"y\":0.5,\"rgb\":[86,128,248],\"tol\":20},{\"x\":0.5,\"y\":0.08,\"rgb\":[0,0,0],\"tol\":20}]" } },
{ id: "material-builtin-lit", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-builtin-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-builtin-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":30}]" } },
{ id: "material-dissolve", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-dissolve.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-dissolve.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":30}]" } },
{ id: "material-graph", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-graph.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-graph.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },