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
feat(render): toon and matcap materials
yhh429442435525
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 541ef089b..113b74885 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **Toon and Matcap materials.** `builtin:toon` lights in steps: each lamp's light is cut into flat bands with a shade colour where no lamp reaches, a flat highlight and a rim, and a lamp's shadow is part of its step; the same picture on WebGL2 and WebGPU. `builtin:matcap` shows a picture of a lit sphere looked up by the way the surface faces the camera, with no lamp asked and one texture read, for phones.- **Drawing only the frames that can look different.** `quality.renderOnDemand` (off unless a game turns it on): a still screen costs the game's logic and nothing else. A frame is drawn when the player did something (a key, a button, a finger, the pointer moved), the surface changed size, entities were created or destroyed, shaders are still compiling, or the game asked (`app.pipeline.demand.request()`), and for `renderOnDemandTail` frames (30) after the last of those; `demand.hold()` keeps every frame drawn while a tween, a video or an animation the engine cannot see move is playing. On the UI template a still screen made 11,600 draw calls in 3 seconds before and none with this on, and a click drew again at once. What the engine does not see is a script changing a value or an animation playing, which is what `request` and `hold` are for.- **Shaders that compile without stopping the frame.** `quality.asyncShaderCompile` (off unless a game turns it on): a draw whose shader the browser is still compiling is left out until it is ready, and every shader asked for in the meantime compiles at once, where before each was waited for in turn. On a first visit the Terrain & Water example's shaders took 43 seconds of a frozen page on Chrome and D3D11 (the heavy lit ones 3 to 10 seconds each, the worst frame 10 seconds); with this on the page was blocked for about a second in all and the whole scene was drawn at 20 seconds, not 56. The same scene, once everything has compiled, is the same picture. `renderer_getPendingShaders()` says how many are still compiling, for a loading screen. Off, nothing changes. WebGL2 only (a WebGPU pipeline is not compiled this way). With `quality.prewarmShaders` (and `prewarmTimeoutMs`, default 30 s) a packaged game draws its first scene out of sight behind the loading screen until nothing is compiling, and opens complete; `warmShaders(app)` does the same from code, `shadersCompiled(module)` waits for the queue, and a scene prepared ahead (`readyRenderPrograms`) now claims its programs ready only once they have compiled. The lit shaders also link about 23% faster on a first visit: a light that comes from the tiles no longer carries a second copy of the shadow lookup in the program.- **A depth prepass for the opaque scene.** A quality level can draw the opaque meshes twice, depth alone first, so a pixel is shaded for the surface that is in front of it and not for every one drawn there on the way: `QualityProfile.depthPrepass` (on for `high` and `medium`, off for `low` and with the quality system off), and `renderer_setDepthPrepass` for a host without one. Cut-out leaves take part, with the coverage their own shader writes. A surface whose material bends its vertices with a hook takes part too, unless it is also a cut-out. On the Terrain & Water example, on an RTX 3060, a frame is 4 to 39 ms shorter, most where trees stand thick.diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdxindex d9386850e..6fc193e07 100644--- a/docs/astro/src/content/docs/graphics/materials.mdx+++ b/docs/astro/src/content/docs/graphics/materials.mdx@@ -33,6 +33,8 @@ creates a material from a built-in template — the same list ships in code as| **Pixelate** | `sprite-pixelate` | Quantizes UVs to a `u_pixels` grid. || **UV Scroll** | `sprite-uv-scroll` | Scrolls the texture by `u_scrollSpeed` × time. || **Model** | `model` | What a glTF material says beyond base color: `u_normalMap`, `u_emissive`(`Map`), `u_occlusionMap` + `u_occlusionStrength`, `u_alphaCutoff`, `u_metallic` / `u_roughness` (+ `u_metallicRoughnessMap`), and the [shading layers](#shading-layers) — clear coat, sheen, anisotropy, translucency, thin film, index of refraction, transmission. Written by model import. |+| **Toon** | `toon` | Lit in steps: each lamp's light is cut into `u_bands` flat bands (`u_bandSoftness` softens the step), `u_shadeColor` is the colour of what no lamp reaches, a flat highlight of `u_specColor` above `u_specThreshold` (`u_specSize` is how glossy), and a rim (`u_rimColor`, `u_rimWidth`, `u_rimStrength`). A lamp's shadow is part of its step. Uses the sixteen lamps of the frame, and carries the lamp loop as Model does. |+| **Matcap** | `matcap` | What a picture of a lit sphere (`u_matcap`) shows, looked up by which way the surface faces the camera. No lamp is asked and no shadow is read: one texture read, which is why it suits a phone. `u_baseBlend` multiplies the base colour in. || **Terrain** | `terrain` | Four texture layers (grass, dirt, snow, rock) weighted by the [Terrain](/docs/graphics/terrain/) component and tiled by world position. || **Foliage** | `foliage` | Plants that sway in the wind: a vertex bend by weights painted in the vertex colour, two-sided and translucent, with an optional cutout texture. See [Foliage](/docs/graphics/foliage/). |diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdxindex 4fb57f4cb..f2fa68dae 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx@@ -29,6 +29,8 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一| **Pixelate** | `sprite-pixelate` | UV 量化到 `u_pixels` 网格。 || **UV Scroll** | `sprite-uv-scroll` | 按 `u_scrollSpeed` × 时间滚动纹理。 || **Model** | `model` | glTF 材质在 base color 之外说的东西:`u_normalMap`、`u_emissive`(`Map`)、`u_occlusionMap` + `u_occlusionStrength`、`u_alphaCutoff`、`u_metallic` / `u_roughness`(以及 `u_metallicRoughnessMap`),还有[着色层](#着色层)——清漆、绒面、各向异性、半透、薄膜干涉、折射率、透射。模型导入会写出它。 |+| **Toon** | `toon` | 分档受光:每盏灯的光被切成 `u_bands` 个平坦的档(`u_bandSoftness` 让档与档的交界变软),`u_shadeColor` 是灯照不到处的颜色,亮度超过 `u_specThreshold` 画一块平的高光(`u_specColor`,`u_specSize` 是光滑度),再加一圈边缘光(`u_rimColor`、`u_rimWidth`、`u_rimStrength`)。灯的阴影算进它的那一档。用帧里的 16 盏灯,和 Model 一样带着灯的循环。 |+| **Matcap** | `matcap` | 用一张"打好光的球"的图(`u_matcap`)按表面朝向相机的方向查色。不问任何灯、不读阴影,只读一次纹理,所以适合手机。`u_baseBlend` 把底色乘进去。 || **Terrain** | `terrain` | 四个纹理图层(草、泥土、雪、岩石),由 [Terrain](/docs/zh-cn/graphics/terrain/) 组件加权并按世界位置平铺。 || **Foliage** | `foliage` | 在风里摆动的植物:按顶点颜色里画好的权重做顶点弯曲,双面、半透光,可选镂空纹理。见[植被](/docs/zh-cn/graphics/foliage/)。 |diff --git a/fixtures/scenes/toon-sphere.esmesh b/fixtures/scenes/toon-sphere.esmeshnew file mode 100644index 000000000..5757f5cc9Binary files /dev/null and b/fixtures/scenes/toon-sphere.esmesh differdiff --git a/fixtures/scenes/toon-sphere.esmesh.meta b/fixtures/scenes/toon-sphere.esmesh.metanew file mode 100644index 000000000..3cece0ced--- /dev/null+++ b/fixtures/scenes/toon-sphere.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "acc1110e-6bd1-4460-af39-26b54d4b8548",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/fixtures/scenes/toon.esscene b/fixtures/scenes/toon.esscenenew file mode 100644index 000000000..8b89a7b00--- /dev/null+++ b/fixtures/scenes/toon.esscene@@ -0,0 +1,183 @@+{+ "version": "1.0",+ "name": "toon",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 420+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 0,+ "fov": 45,+ "nearPlane": 10,+ "farPlane": 2000,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Toon",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -180,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 80,+ "y": 80,+ "z": 80+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "/scenes/toon-sphere.esmesh",+ "color": {+ "r": 0.9,+ "g": 0.55,+ "b": 0.35,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "enabled": true,+ "material": "/scenes/toon/toon.esmaterial"+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Model",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 80,+ "y": 80,+ "z": 80+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "/scenes/toon-sphere.esmesh",+ "color": {+ "r": 0.9,+ "g": 0.55,+ "b": 0.35,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "enabled": true,+ "material": "/scenes/toon/model.esmaterial"+ }+ }+ ]+ },+ {+ "id": 3,+ "name": "Matcap",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 180,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 80,+ "y": 80,+ "z": 80+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "/scenes/toon-sphere.esmesh",+ "color": {+ "r": 0.9,+ "g": 0.55,+ "b": 0.35,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "enabled": true,+ "material": "/scenes/toon/matcap.esmaterial"+ }+ }+ ]+ },+ {+ "id": 4,+ "name": "Sun",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Light",+ "data": {+ "type": 1,+ "color": {+ "r": 1,+ "g": 0.97,+ "b": 0.9,+ "a": 1+ },+ "intensity": 1.2,+ "direction": {+ "x": 0.6,+ "y": -0.5+ },+ "directionZ": -0.7+ }+ }+ ]+ }+ ]+}\ No newline at end of filediff --git a/fixtures/scenes/toon.textures.json b/fixtures/scenes/toon.textures.jsonnew file mode 100644index 000000000..9e26dfeeb--- /dev/null+++ b/fixtures/scenes/toon.textures.json@@ -0,0 +1 @@+{}\ No newline at end of filediff --git a/fixtures/scenes/toon/matcap.esmaterial b/fixtures/scenes/toon/matcap.esmaterialnew file mode 100644index 000000000..81c126db4--- /dev/null+++ b/fixtures/scenes/toon/matcap.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "builtin:matcap",+ "blendMode": 0,+ "depthTest": true,+ "properties": {+ "u_matcap": "/scenes/toon/matcap.png"+ }+}\ No newline at end of filediff --git a/fixtures/scenes/toon/matcap.png b/fixtures/scenes/toon/matcap.pngnew file mode 100644index 000000000..04bdb622bBinary files /dev/null and b/fixtures/scenes/toon/matcap.png differdiff --git a/fixtures/scenes/toon/model.esmaterial b/fixtures/scenes/toon/model.esmaterialnew file mode 100644index 000000000..2e589ba6c--- /dev/null+++ b/fixtures/scenes/toon/model.esmaterial@@ -0,0 +1,11 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "builtin:model",+ "blendMode": 0,+ "depthTest": true,+ "properties": {+ "u_metallic": 0,+ "u_roughness": 0.5+ }+}\ No newline at end of filediff --git a/fixtures/scenes/toon/toon.esmaterial b/fixtures/scenes/toon/toon.esmaterialnew file mode 100644index 000000000..aa2a33910--- /dev/null+++ b/fixtures/scenes/toon/toon.esmaterial@@ -0,0 +1,12 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "builtin:toon",+ "blendMode": 0,+ "depthTest": true,+ "properties": {+ "u_bands": 3,+ "u_rimStrength": 0.6,+ "u_specThreshold": 0.5+ }+}\ No newline at end of filediff --git a/sdk/src/render/builtinShaders.ts b/sdk/src/render/builtinShaders.tsindex da0e805b4..b98cc8b5d 100644--- a/sdk/src/render/builtinShaders.ts+++ b/sdk/src/render/builtinShaders.ts@@ -692,6 +692,333 @@ fn packNormal(n : vec3f) -> vec2f {#pragma end`;+const TOON = `#pragma shader "Toon"+#pragma version 300 es+#pragma domain Lit+#pragma param u_tint color default(1,1,1,1)+// The light a surface keeps where no lamp reaches it, as a colour of its own (times the base colour) whatever the lamps do: black leaves it dark.+#pragma param u_shadeColor color default(0.55,0.5,0.7,1)+// How many steps the light is cut into, and how soft the step between two is (0 is a hard edge).+#pragma param u_bands float default(3) range(1,8) ui(slider)+#pragma param u_bandSoftness float default(0.03) range(0,0.5) ui(slider)+// A highlight is drawn where a lamp's gloss is above this (1 draws none), as a flat shape of its own colour; u_specSize is how glossy the surface is.+#pragma param u_specThreshold float default(0.6) range(0,1) ui(slider)+#pragma param u_specSoftness float default(0.02) range(0,0.5) ui(slider)+#pragma param u_specColor color default(1,1,1,1)+#pragma param u_specSize float default(0.35) range(0,1) ui(slider)+// A band of light at the silhouette, on the side the light reaches.+#pragma param u_rimColor color default(1,1,1,1)+#pragma param u_rimWidth float default(0.35) range(0,1) ui(slider)+#pragma param u_rimSoftness float default(0.05) range(0,0.5) ui(slider)+#pragma param u_rimStrength float default(0) range(0,1) ui(slider)+#pragma param u_occlusionMap texture default(white) texel(data)+#pragma param u_occlusionStrength float default(1) range(0,1) ui(slider)+#pragma param u_emissive color default(0,0,0,1)+#pragma param u_emissiveMap texture default(white)+#pragma param u_alphaCutoff float default(0) range(0,1) ui(slider)+#pragma coverage u_alphaCutoff++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;+in highp vec2 v_worldPos;+#ifdef MESH_NORMALS+in highp vec3 v_worldNormal;+in highp vec3 v_worldXYZ;+#endif++uniform sampler2D u_textures[1];++#ifdef ES_GBUFFER+layout(location = 0) out vec4 fragColor;+layout(location = 1) out vec4 fragSurface;+vec2 packNormal(vec3 n) {+ n /= (abs(n.x) + abs(n.y) + abs(n.z));+ vec2 sgn = vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);+ vec2 e = n.z >= 0.0 ? n.xy : (1.0 - abs(n.yx)) * sgn;+ return e * 0.5 + 0.5;+}+#else+out vec4 fragColor;+#endif++// A level in 0..1 cut into u_bands steps: each step is flat, and the step between two is a smoothstep as wide as u_bandSoftness.+float toonBand(float level) {+ float t = clamp(level, 0.0, 1.0) * u_bands;+ float i = floor(t);+ float f = t - i;+ float soft = max(u_bandSoftness, 1e-4);+ return min((i + smoothstep(0.5 - soft, 0.5 + soft, f)) / u_bands, 1.0);+}++void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color * u_tint;+ float alpha = base.a;+ if (u_alphaCutoff > 0.0) {+ alpha = cutoutCoverage(base.a, u_alphaCutoff, fwidth(base.a));+ if (alpha <= 0.0) discard;+ alpha = min(alpha, 1.0);+ }+#ifdef MESH_NORMALS+ highp vec3 N = normalize(v_worldNormal);+ if (!gl_FrontFacing) N = -N;+ highp vec3 P = v_worldXYZ;+#else+ highp vec3 N = vec3(0.0, 0.0, 1.0);+ highp vec3 P = vec3(v_worldPos, 0.0);+#endif+ float ao = mix(1.0, texture(u_occlusionMap, v_texCoord).r, u_occlusionStrength);+ vec3 V = viewDirection(P);+ float NdotV = max(dot(N, V), 1e-4);+ // A glossy dielectric for the lamps' highlight to be read from; how it looks is this material's own, not a metal-rough pair's.+ float roughness = mix(0.7, 0.1, clamp(u_specSize, 0.0, 1.0));+ float a = max(roughness * roughness, 1e-3);+ vec3 F0 = vec3(0.04);+ SurfaceExt ext = surfaceExtNone(N);+ // Each lamp is cut into steps by itself, and the shadow it casts is part of its step.+ vec3 lit = vec3(0.0);+ float glossLevel = 0.0;+ vec3 glossTint = vec3(0.0);+ for (int i = 0; i < 16; ++i) {+ vec3 l = vec3(0.0), g = vec3(0.0), x = vec3(0.0);+ shadeLight(u_lights[i].posDir, u_lights[i].color, u_lights[i].spot, u_lights[i].shadow,+ u_lights[i].shadowMap, u_lights[i].falloff, N, V, P, a, F0, NdotV, 1.0, roughness, ext, l, g, x, true);+ float level = max(l.r, max(l.g, l.b));+ if (level > 1e-4) lit += l * (toonBand(level) / level);+ float gl = max(g.r, max(g.g, g.b));+ if (gl > glossLevel) { glossLevel = gl; glossTint = g / max(gl, 1e-4); }+ }+ float lightAmount = clamp(max(lit.r, max(lit.g, lit.b)), 0.0, 1.0);+ vec3 ambient = indirectIrradiance(N) * ao;+ // The shade colour fills in where the steps leave off, so the cut between lit and shaded is a change of colour and not only of brightness.+ vec3 colour = base.rgb * (ambient + lit + u_shadeColor.rgb * (1.0 - lightAmount));+ float spec = smoothstep(u_specThreshold - u_specSoftness, u_specThreshold + u_specSoftness, glossLevel);+ colour = mix(colour, u_specColor.rgb * glossTint, spec * u_specColor.a * float(u_specThreshold < 1.0));+ float rim = smoothstep(1.0 - u_rimWidth - u_rimSoftness, 1.0 - u_rimWidth + u_rimSoftness, 1.0 - NdotV);+ colour += u_rimColor.rgb * rim * lightAmount * u_rimStrength;+ fragColor = vec4(colour + u_emissive.rgb * texture(u_emissiveMap, v_texCoord).rgb, alpha);+#ifdef ES_GBUFFER+ fragSurface = vec4(packNormal(normalize(N)), roughness, 0.75);+#endif+}+#pragma end++#pragma fragment wgsl+#ifdef ES_GBUFFER+struct FragOut {+ @location(0) color : vec4f,+ @location(1) surface : vec4f,+};++fn packNormal(n : vec3f) -> vec2f {+ let a = n / (abs(n.x) + abs(n.y) + abs(n.z));+ let sgn = vec2f(select(-1.0, 1.0, a.x >= 0.0), select(-1.0, 1.0, a.y >= 0.0));+ var e = a.xy;+ if (a.z < 0.0) { e = (vec2f(1.0) - abs(a.yx)) * sgn; }+ return e * 0.5 + 0.5;+}++@fragment fn fs_main(v : VSOut, @builtin(front_facing) front : bool) -> FragOut {+#else+@fragment fn fs_main(v : VSOut, @builtin(front_facing) front : bool) -> @location(0) vec4f {+#endif+ let duvx = dpdx(v.v_texCoord);+ let duvy = dpdy(v.v_texCoord);+ g_probeSlot = v.v_probeSlot;+#ifdef MESH_LIGHTMAP+ g_lightmap = v.v_lightmap;+#endif+ let base = textureSampleGrad(t0, s0, v.v_texCoord, duvx, duvy) * v.v_color * mc.u_tint;+ let edge = max(fwidth(base.a), 1e-4);+ var alpha = base.a;+ if (mc.u_alphaCutoff > 0.0) {+ alpha = cutoutCoverage(base.a, mc.u_alphaCutoff, edge);+ if (alpha <= 0.0) { discard; }+ alpha = min(alpha, 1.0);+ }+#ifdef MESH_NORMALS+ var N = normalize(v.v_worldNormal);+ if (!front) { N = -N; }+ let P = v.v_worldXYZ;+#else+ let N = vec3f(0.0, 0.0, 1.0);+ let P = vec3f(v.v_worldPos, 0.0);+#endif+ let occl = textureSampleGrad(u_occlusionMap, u_occlusionMap_s, v.v_texCoord, duvx, duvy).r;+ let ao = mix(1.0, occl, mc.u_occlusionStrength);+ let V = viewDirection(P);+ let NdotV = max(dot(N, V), 1e-4);+ let roughness = mix(0.7, 0.1, clamp(mc.u_specSize, 0.0, 1.0));+ let a = max(roughness * roughness, 1e-3);+ let F0 = vec3f(0.04);+ let ext = surfaceExtNone(N);+ var lit = vec3f(0.0);+ var glossLevel = 0.0;+ var glossTint = vec3f(0.0);+ for (var i = 0; i < 16; i++) {+ let term = shadeLight(lc.u_lights[i].posDir, lc.u_lights[i].color, lc.u_lights[i].spot, lc.u_lights[i].shadow,+ lc.u_lights[i].shadowMap, lc.u_lights[i].falloff, N, V, P, a, F0, NdotV, 1.0, roughness, ext, true);+ let level = max(term.lit.r, max(term.lit.g, term.lit.b));+ if (level > 1e-4) { lit += term.lit * (toonBand(level) / level); }+ let gl = max(term.gloss.r, max(term.gloss.g, term.gloss.b));+ if (gl > glossLevel) { glossLevel = gl; glossTint = term.gloss / max(gl, 1e-4); }+ }+ let lightAmount = clamp(max(lit.r, max(lit.g, lit.b)), 0.0, 1.0);+ let ambient = indirectIrradiance(N) * ao;+ var colour = base.rgb * (ambient + lit + mc.u_shadeColor.rgb * (1.0 - lightAmount));+ let spec = smoothstep(mc.u_specThreshold - mc.u_specSoftness, mc.u_specThreshold + mc.u_specSoftness, glossLevel);+ colour = mix(colour, mc.u_specColor.rgb * glossTint, vec3f(spec * mc.u_specColor.a * select(0.0, 1.0, mc.u_specThreshold < 1.0)));+ let rim = smoothstep(1.0 - mc.u_rimWidth - mc.u_rimSoftness, 1.0 - mc.u_rimWidth + mc.u_rimSoftness, 1.0 - NdotV);+ colour += mc.u_rimColor.rgb * rim * lightAmount * mc.u_rimStrength;+ let emit = mc.u_emissive.rgb * textureSampleGrad(u_emissiveMap, u_emissiveMap_s, v.v_texCoord, duvx, duvy).rgb;+#ifdef ES_GBUFFER+ var frag : FragOut;+ frag.color = vec4f(colour + emit, alpha);+ frag.surface = vec4f(packNormal(normalize(N)), roughness, 0.75);+ return frag;+#else+ return vec4f(colour + emit, alpha);+#endif+}++// A level in 0..1 cut into u_bands steps (see the GLSL twin).+fn toonBand(level : f32) -> f32 {+ let t = clamp(level, 0.0, 1.0) * mc.u_bands;+ let i = floor(t);+ let f = t - i;+ let soft = max(mc.u_bandSoftness, 1e-4);+ return min((i + smoothstep(0.5 - soft, 0.5 + soft, f)) / mc.u_bands, 1.0);+}+#pragma end+`;++const MATCAP = `#pragma shader "Matcap"+#pragma version 300 es+#pragma domain Lit+#pragma param u_tint color default(1,1,1,1)+// A picture of a lit sphere: what the surface shows is looked up by which way it faces the camera, so the lighting is the picture's+// and no lamp is asked. Costs one texture read, which is why it suits a phone.+#pragma param u_matcap texture default(white)+#pragma param u_matcapStrength float default(1) range(0,2) ui(slider)+#pragma param u_baseBlend float default(0) range(0,1) ui(slider)+#pragma param u_alphaCutoff float default(0) range(0,1) ui(slider)+#pragma coverage u_alphaCutoff++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;+in highp vec2 v_worldPos;+#ifdef MESH_NORMALS+in highp vec3 v_worldNormal;+in highp vec3 v_worldXYZ;+#endif++uniform sampler2D u_textures[1];++#ifdef ES_GBUFFER+layout(location = 0) out vec4 fragColor;+layout(location = 1) out vec4 fragSurface;+vec2 packNormal(vec3 n) {+ n /= (abs(n.x) + abs(n.y) + abs(n.z));+ vec2 sgn = vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);+ vec2 e = n.z >= 0.0 ? n.xy : (1.0 - abs(n.yx)) * sgn;+ return e * 0.5 + 0.5;+}+#else+out vec4 fragColor;+#endif++void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color * u_tint;+ float alpha = base.a;+ if (u_alphaCutoff > 0.0) {+ alpha = cutoutCoverage(base.a, u_alphaCutoff, fwidth(base.a));+ if (alpha <= 0.0) discard;+ alpha = min(alpha, 1.0);+ }+#ifdef MESH_NORMALS+ highp vec3 N = normalize(v_worldNormal);+ if (!gl_FrontFacing) N = -N;+ highp vec3 P = v_worldXYZ;+#else+ highp vec3 N = vec3(0.0, 0.0, 1.0);+ highp vec3 P = vec3(v_worldPos, 0.0);+#endif+ // The camera's own axes, found from where it looks: the picture is of a sphere as the camera sees it, whichever way the camera turns.+ vec3 V = viewDirection(P);+ vec3 right = normalize(cross(abs(V.y) > 0.99 ? vec3(0.0, 0.0, 1.0) : vec3(0.0, 1.0, 0.0), V));+ vec3 up = cross(V, right);+ vec2 uv = vec2(dot(N, right), dot(N, up)) * 0.5 + 0.5;+ vec3 sphere = texture(u_matcap, uv).rgb * u_matcapStrength;+ vec3 colour = mix(sphere, sphere * base.rgb, u_baseBlend);+ fragColor = vec4(colour, alpha);+#ifdef ES_GBUFFER+ fragSurface = vec4(packNormal(normalize(N)), 1.0, 0.75);+#endif+}+#pragma end++#pragma fragment wgsl+#ifdef ES_GBUFFER+struct FragOut {+ @location(0) color : vec4f,+ @location(1) surface : vec4f,+};++fn packNormal(n : vec3f) -> vec2f {+ let a = n / (abs(n.x) + abs(n.y) + abs(n.z));+ let sgn = vec2f(select(-1.0, 1.0, a.x >= 0.0), select(-1.0, 1.0, a.y >= 0.0));+ var e = a.xy;+ if (a.z < 0.0) { e = (vec2f(1.0) - abs(a.yx)) * sgn; }+ return e * 0.5 + 0.5;+}++@fragment fn fs_main(v : VSOut, @builtin(front_facing) front : bool) -> FragOut {+#else+@fragment fn fs_main(v : VSOut, @builtin(front_facing) front : bool) -> @location(0) vec4f {+#endif+ let duvx = dpdx(v.v_texCoord);+ let duvy = dpdy(v.v_texCoord);+ let base = textureSampleGrad(t0, s0, v.v_texCoord, duvx, duvy) * v.v_color * mc.u_tint;+ let edge = max(fwidth(base.a), 1e-4);+ var alpha = base.a;+ if (mc.u_alphaCutoff > 0.0) {+ alpha = cutoutCoverage(base.a, mc.u_alphaCutoff, edge);+ if (alpha <= 0.0) { discard; }+ alpha = min(alpha, 1.0);+ }+#ifdef MESH_NORMALS+ var N = normalize(v.v_worldNormal);+ if (!front) { N = -N; }+ let P = v.v_worldXYZ;+#else+ let N = vec3f(0.0, 0.0, 1.0);+ let P = vec3f(v.v_worldPos, 0.0);+#endif+ let V = viewDirection(P);+ var seed = vec3f(0.0, 1.0, 0.0);+ if (abs(V.y) > 0.99) { seed = vec3f(0.0, 0.0, 1.0); }+ let right = normalize(cross(seed, V));+ let up = cross(V, right);+ let uv = vec2f(dot(N, right) * 0.5 + 0.5, dot(N, up) * 0.5 + 0.5);+ let sphere = textureSampleLevel(u_matcap, u_matcap_s, uv, 0.0).rgb * mc.u_matcapStrength;+ let colour = mix(sphere, sphere * base.rgb, vec3f(mc.u_baseBlend));+#ifdef ES_GBUFFER+ var frag : FragOut;+ frag.color = vec4f(colour, alpha);+ frag.surface = vec4f(packNormal(normalize(N)), 1.0, 0.75);+ return frag;+#else+ return vec4f(colour, alpha);+#endif+}+#pragma end+`;+export const BUILTIN_SHADER_TEMPLATES: readonly BuiltinShaderTemplate[] = [template('sprite-unlit', 'Unlit', 'Texture × vertex color × tint, no lighting.', SPRITE_UNLIT),template('sprite-lit', 'Lit', 'Lit by the scene\'s 2D lights; optional normal map.', SPRITE_LIT),@@ -707,6 +1034,12 @@ export const BUILTIN_SHADER_TEMPLATES: readonly BuiltinShaderTemplate[] = [template('model', 'Model','What an imported model\'s material says: normal map, emission, occlusion, alpha cutoff.',MODEL),+ template('toon', 'Toon',+ 'Lit in steps: the light cut into flat bands, a shade colour where it does not reach, a flat highlight and a rim. Shadows are part of a step.',+ TOON),+ template('matcap', 'Matcap',+ 'What a picture of a lit sphere shows, looked up by which way the surface faces the camera. No lamps, one texture read.',+ MATCAP),];/** Where the templates that are not the core's sit in a list, so a menu reads the same whichever order the modules were installed in. */diff --git a/sdk/tests/builtin-shader-registry.test.ts b/sdk/tests/builtin-shader-registry.test.tsindex d8951c7ad..479b412d1 100644--- a/sdk/tests/builtin-shader-registry.test.ts+++ b/sdk/tests/builtin-shader-registry.test.ts@@ -15,7 +15,8 @@ describe('the built-in shaders that ship with modules', () => {it('are the module\'s to install, not the core list\'s', () => {// The core list carries the sprite and model shaders; water, terrain, foliage and the character shaders arrive when their module is installed.const coreIds = BUILTIN_SHADER_TEMPLATES.map((t) => t.id).filter((id) => !MODULE_IDS.includes(id));- expect(coreIds).toEqual(expect.arrayContaining(['sprite-unlit', 'sprite-lit', 'model']));+ expect(coreIds).toEqual(expect.arrayContaining(['sprite-unlit', 'sprite-lit', 'model', 'toon', 'matcap']));+ for (const id of ['toon', 'matcap']) expect(builtinShaderTemplate(id)!.source).toContain('#pragma fragment wgsl');expect(Object.keys(BUILTIN_SHADER_MODULE).sort()).toEqual([...MODULE_IDS].sort());});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 6cba29816..f1eb0ce2b 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3002,4 +3002,6 @@ export const NOTED = {{"note":"Shaders that compile without stopping the frame."},"feat(render): a game can draw only the frames that can look different":{"note":"Drawing only the frames that can look different."},+ "feat(render): toon and matcap materials":+ {"note":"Toon and Matcap materials."},};diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 9ee272894..d7f78c068 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -657,6 +657,7 @@ export const SCENES = [// 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,101,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-toon", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/toon.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/toon.textures.json", ESTELLA_VERIFY_W: "900", ESTELLA_VERIFY_H: "360", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2,\"y\":0.45,\"rgb\":[229,136,80],\"tol\":20},{\"x\":0.27,\"y\":0.4,\"rgb\":[195,114,74],\"tol\":20},{\"x\":0.3,\"y\":0.62,\"rgb\":[126,70,62],\"tol\":20},{\"x\":0.67,\"y\":0.42,\"rgb\":[255,255,255],\"tol\":20},{\"x\":0.77,\"y\":0.65,\"rgb\":[37,37,37],\"tol\":20},{\"x\":0.05,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":10}]" } },{ 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}]" } },{ id: "material-preview", tier: "pr", host: "editor", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-tint.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-tint.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_PREVIEW: "{\"w\":64,\"h\":64,\"rgb\":[255,0,0],\"tol\":45}" } },