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 metal reflects the environment it is in

esenginef9ade5919caa
diff --git a/desktop/public/scenes/mat-model-env.esscene b/desktop/public/scenes/mat-model-env.esscene
new file mode 100644
index 000000000..2a0a5d688
--- /dev/null
+++ b/desktop/public/scenes/mat-model-env.esscene
@@ -0,0 +1,136 @@
+{
+ "version": 1,
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Metal",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -150,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 160,
+ "y": 160
+ },
+ "color": {
+ "r": 0,
+ "g": 0.8,
+ "b": 0,
+ "a": 1
+ },
+ "material": "/scenes/mat-model/metal.esmaterial"
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Dielectric",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 150,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 160,
+ "y": 160
+ },
+ "color": {
+ "r": 0,
+ "g": 0.8,
+ "b": 0,
+ "a": 1
+ },
+ "material": "/scenes/mat-model/dielectric.esmaterial"
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Environment",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 2,
+ "color": {
+ "r": 0.5,
+ "g": 0.5,
+ "b": 0.5,
+ "a": 1
+ },
+ "intensity": 1
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdx
index ca0d4ff3a..ba39f0704 100644
--- a/docs/astro/src/content/docs/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/graphics/lighting.mdx
@@ -174,6 +174,12 @@ always did, and a surface that wants a highlight asks for one.
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.
+A metal has no diffuse term at all — it only reflects. What it reflects is the
+scene's **ambient** light, treated as an environment arriving equally from every
+direction, so an `Ambient` `Light2D` is what keeps a metal from being black
+everywhere no light happens to point. Raise its color to give metals something to
+show.
+
<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
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 a4190ad42..ef80a916c 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
@@ -167,6 +167,10 @@ highp vec3 lit = applyLightingPBR(
`viewDirection(worldPos)` 返回指向相机的单位向量;它读引擎每帧写进 frame 块的相机位置,
所以正交相机返回一个常量,透视相机逐像素变化。
+金属完全没有漫反射项 —— 它只反射。它反射的是场景的**环境光**(ambient),被当作从各个
+方向等量到达的环境:所以一盏 `Ambient` 的 `Light2D` 正是让金属在没有灯照到的地方不至于
+全黑的东西。把它的颜色调亮,金属才有东西可显。
+
<Aside>
灯仍然摆在平面上:`Light2D` 没有第三个坐标,所以距离在 xy 内度量,点光的高度来自它的
半径。法线与视线才是这个模型里三维的部分。
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 6ba3265f2..9ff06a065 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -812,6 +812,12 @@ fn geometrySmith(NdotV : f32, NdotL : f32, roughness : f32) -> f32 {
fn fresnelSchlick(VdotH : f32, F0 : vec3f) -> vec3f {
return F0 + (vec3f(1.0) - F0) * pow(1.0 - VdotH, 5.0);
}
+fn envBRDFApprox(NdotV : f32, roughness : f32) -> vec2f {
+ let r = roughness * vec4f(-1.0, -0.0275, -0.572, 0.022)
+ + vec4f(1.0, 0.0425, 1.04, -0.04);
+ let a = min(r.x * r.x, exp2(-9.28 * NdotV)) * r.x + r.y;
+ return vec2f(-1.04, 1.04) * a + r.zw;
+}
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));
@@ -864,6 +870,8 @@ fn applyLightingPBR(albedo : vec3f, N : vec3f, worldPos : vec3f, V : vec3f, meta
* (brdf * 3.14159265 * specular);
}
}
+ let ab = envBRDFApprox(NdotV, roughness);
+ gloss += lc.u_ambient.rgb * (ao * specular) * (F0 * ab.x + vec3f(ab.y));
return albedo * (1.0 - metallic) * lit + gloss;
}
fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> vec3f {
@@ -1267,6 +1275,15 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
"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 split-sum environment term, Karis' analytic fit: scale and bias for F0
+ // over a whole hemisphere. A lookup table is the usual carrier; the fit costs
+ // no texture unit and is within a value or two of one over the [0,1] range.
+ "highp vec2 envBRDFApprox(in highp float NdotV, in highp float roughness) {\n"
+ " highp vec4 r = roughness * vec4(-1.0, -0.0275, -0.572, 0.022)\n"
+ " + vec4(1.0, 0.0425, 1.04, -0.04);\n"
+ " highp float a = min(r.x * r.x, exp2(-9.28 * NdotV)) * r.x + r.y;\n"
+ " return vec2(-1.04, 1.04) * a + r.zw;\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.
@@ -1335,6 +1352,11 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" * (brdf * 3.14159265 * specular);\n"
" }\n"
" }\n"
+ // The environment, which for this engine is the ambient term: the same
+ // radiance from every direction. A metal has no diffuse, so without a
+ // reflection of it a metal is black wherever no light happens to point.
+ " highp vec2 ab = envBRDFApprox(NdotV, roughness);\n"
+ " gloss += u_ambient.rgb * (ao * specular) * (F0 * ab.x + ab.y);\n"
" return albedo * (1.0 - metallic) * lit + gloss;\n"
"}\n"
"highp vec3 applyLighting2DAO(highp vec3 albedo, highp vec3 N, highp vec2 worldPos,\n"
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 2e654dd66..095d6724e 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -134,6 +134,10 @@ export const SCENES = [
// roughness — metal 1 has no diffuse and reflects its own colour, metal 0
// keeps the diffuse and adds a white lobe (ignore roughness: white drops 97).
{ id: "mat-model-pbr", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-model.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":20},{\"x\":0.75,\"y\":0.5,\"rgb\":[100,253,100],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },
+ // The same two materials with NO light on them, only the ambient environment.
+ // A metal has no diffuse, so reflecting that environment is all it has: remove
+ // the reflection and the left probe is black while the right one barely moves.
+ { id: "mat-model-env", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-model-env.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.5,\"rgb\":[0,80,0],\"tol\":20},{\"x\":0.75,\"y\":0.5,\"rgb\":[4,106,4],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"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}]" } },