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(renderer): drop the es prefix from shader builtins + screenUV + effects gallery
yhh5fa0ec07d489
diff --git a/desktop/public/scenes/mat-builtin-lit/lit.esshader b/desktop/public/scenes/mat-builtin-lit/lit.esshaderindex 49d65cc67..2a794dc89 100644--- a/desktop/public/scenes/mat-builtin-lit/lit.esshader+++ b/desktop/public/scenes/mat-builtin-lit/lit.esshader@@ -18,7 +18,7 @@ out vec4 fragColor;// Unset u_normalMap = flat normal, so lighting works with no normal map assigned.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color * u_tint;- vec3 N = es_sampleNormal(u_normalMap, v_texCoord);- fragColor = vec4(es_applyLighting2D(base.rgb, N, v_worldPos), base.a);+ vec3 N = sampleNormal(u_normalMap, v_texCoord);+ fragColor = vec4(applyLighting2D(base.rgb, N, v_worldPos), base.a);}#pragma enddiff --git a/desktop/public/scenes/mat-dissolve/dissolve.esshader b/desktop/public/scenes/mat-dissolve/dissolve.esshaderindex 6a71111bc..f3527269c 100644--- a/desktop/public/scenes/mat-dissolve/dissolve.esshader+++ b/desktop/public/scenes/mat-dissolve/dissolve.esshader@@ -16,19 +16,19 @@ uniform sampler2D u_textures[8];out vec4 fragColor;-float es_hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }-float es_noise(vec2 p) {+float hash2d(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }+float noise2d(vec2 p) {vec2 i = floor(p);vec2 f = fract(p);f = f * f * (3.0 - 2.0 * f);- return mix(mix(es_hash(i), es_hash(i + vec2(1.0, 0.0)), f.x),- mix(es_hash(i + vec2(0.0, 1.0)), es_hash(i + vec2(1.0, 1.0)), f.x), f.y);+ return mix(mix(hash2d(i), hash2d(i + vec2(1.0, 0.0)), f.x),+ mix(hash2d(i + vec2(0.0, 1.0)), hash2d(i + vec2(1.0, 1.0)), f.x), f.y);}// u_progress 0 = intact, 1 = fully dissolved; a glowing edge leads the cut.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;- float n = es_noise(v_texCoord * u_noiseScale);+ float n = noise2d(v_texCoord * u_noiseScale);float cut = u_progress * (1.0 + u_edgeWidth);if (n < cut - u_edgeWidth) discard;vec3 rgb = (n < cut) ? u_edgeColor.rgb : base.rgb;diff --git a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshaderindex f6dca5a77..d8c67c136 100644--- a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader+++ b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader@@ -41,8 +41,8 @@ out vec4 fragColor;// straight-on light, a flat normal gives N·L = 1 (full bright); a wrong default would not.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;- vec3 N = es_sampleNormal(u_normal, v_texCoord);- vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ vec3 N = sampleNormal(u_normal, v_texCoord);+ vec3 lit = applyLighting2D(base.rgb, N, v_worldPos);fragColor = vec4(lit, base.a);}#pragma enddiff --git a/desktop/public/scenes/mat-lit-normal/lit-normal.esshader b/desktop/public/scenes/mat-lit-normal/lit-normal.esshaderindex c39d1cc4c..031b1e3f3 100644--- a/desktop/public/scenes/mat-lit-normal/lit-normal.esshader+++ b/desktop/public/scenes/mat-lit-normal/lit-normal.esshader@@ -36,13 +36,13 @@ uniform sampler2D u_textures[8];out vec4 fragColor;-// es_sampleNormal + es_applyLighting2D + the LightConstants block are injected by ShaderParser+// sampleNormal + applyLighting2D + the LightConstants block are injected by ShaderParser// for `#pragma domain Lit2D`. The surface normal comes from the material's u_normal map, so// lighting varies per texel.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;- vec3 N = es_sampleNormal(u_normal, v_texCoord);- vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ vec3 N = sampleNormal(u_normal, v_texCoord);+ vec3 lit = applyLighting2D(base.rgb, N, v_worldPos);fragColor = vec4(lit, base.a);}#pragma enddiff --git a/desktop/public/scenes/mat-lit/lit.esshader b/desktop/public/scenes/mat-lit/lit.esshaderindex 0376a220e..927b9238a 100644--- a/desktop/public/scenes/mat-lit/lit.esshader+++ b/desktop/public/scenes/mat-lit/lit.esshader@@ -36,12 +36,12 @@ uniform sampler2D u_textures[8];out vec4 fragColor;-// The LightConstants block + es_applyLighting2D() are injected by ShaderParser for+// The LightConstants block + applyLighting2D() are injected by ShaderParser for// `#pragma domain Lit2D`. A flat normal (no normal map in this fixture) faces the camera.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;vec3 N = vec3(0.0, 0.0, 1.0);- vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ vec3 lit = applyLighting2D(base.rgb, N, v_worldPos);fragColor = vec4(lit, base.a);}#pragma enddiff --git a/docs/astro/src/content/docs/guides/lighting.mdx b/docs/astro/src/content/docs/guides/lighting.mdxindex 979c1bd43..d3538018d 100644--- a/docs/astro/src/content/docs/guides/lighting.mdx+++ b/docs/astro/src/content/docs/guides/lighting.mdx@@ -105,11 +105,11 @@ uniform sampler2D u_textures[8];out vec4 fragColor;// #pragma domain Lit2D makes the engine inject the LightConstants block and the-// es_applyLighting2D() helper — you just call it with your base color and a normal.+// applyLighting2D() helper — you just call it with your base color and a normal.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;vec3 N = vec3(0.0, 0.0, 1.0); // flat normal, facing the camera- vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ vec3 lit = applyLighting2D(base.rgb, N, v_worldPos);fragColor = vec4(lit, base.a);}#pragma end@@ -140,7 +140,7 @@ You can also build a lit material visually — set the **Material Graph**'s doma### Normal maps-The `N` you pass to `es_applyLighting2D` is the surface normal. Passing a constant+The `N` you pass to `applyLighting2D` is the surface normal. Passing a constant`vec3(0, 0, 1)` gives flat, evenly-lit surfaces. For per-pixel relief, sample a**normal map** in the shader and use that as `N` instead — the same base color thencatches highlights and shadow from each light's direction. Add the normal texture as adiff --git a/docs/astro/src/content/docs/guides/material.mdx b/docs/astro/src/content/docs/guides/material.mdxindex de89dffa7..ff25fe86a 100644--- a/docs/astro/src/content/docs/guides/material.mdx+++ b/docs/astro/src/content/docs/guides/material.mdx@@ -92,11 +92,12 @@ The engine injects these into every compiled `.esshader` — never declare them| Injected | Available | What ||---|---|---|-| `u_esTime` | always | `vec4` frame clock: `.x` elapsed seconds, `.y` delta seconds. |+| `u_time` | always | `vec4` frame clock: `.x` elapsed seconds, `.y` delta seconds. |+| `u_viewport` | always | `vec4` canvas: `.xy` size in pixels, `.zw` = 1/size (screen UV = `gl_FragCoord.xy * u_viewport.zw`). || MaterialConstants block | when the shader has params | Your `#pragma param` values. |-| `es_applyLighting2D(albedo, N, worldPos)` | Lit2D | Applies every scene light (+shadows); returns the lit color. |-| `es_sampleNormal(map, uv)` | Lit2D | Unpacks a tangent-space normal map (RGB → [-1,1], normalized). |-| `es_shadowFactor2D(worldPos, target, softness)` | Lit2D | Occlusion factor toward a point (used by `es_applyLighting2D`). |+| `applyLighting2D(albedo, N, worldPos)` | Lit2D | Applies every scene light (+shadows); returns the lit color. |+| `sampleNormal(map, uv)` | Lit2D | Unpacks a tangent-space normal map (RGB → [-1,1], normalized). |+| `shadowFactor2D(worldPos, target, softness)` | Lit2D | Occlusion factor toward a point (used by `applyLighting2D`). |A `#pragma switch` selects a static shader permutation baked into the material atcompile time (via the `features` argument to `compileShader`).diff --git a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx b/docs/astro/src/content/docs/zh-cn/guides/lighting.mdxindex bc288beeb..3991c1f51 100644--- a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx@@ -101,12 +101,12 @@ in highp vec2 v_worldPos;uniform sampler2D u_textures[8];out vec4 fragColor;-// #pragma domain Lit2D 让引擎注入 LightConstants 块和 es_applyLighting2D() helper——+// #pragma domain Lit2D 让引擎注入 LightConstants 块和 applyLighting2D() helper——// 你只需用你的基础色和一个法线调用它。void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;vec3 N = vec3(0.0, 0.0, 1.0); // 平法线,朝向相机- vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ vec3 lit = applyLighting2D(base.rgb, N, v_worldPos);fragColor = vec4(lit, base.a);}#pragma end@@ -136,7 +136,7 @@ const applyLit = defineSystem([Query(Mut(Sprite))], (q) => {### 法线贴图-你传给 `es_applyLighting2D` 的 `N` 是表面法线。传一个常量 `vec3(0, 0, 1)` 得到平坦、均匀受光的+你传给 `applyLighting2D` 的 `N` 是表面法线。传一个常量 `vec3(0, 0, 1)` 得到平坦、均匀受光的表面。要有逐像素的凹凸感,就在着色器里采样一张**法线贴图**并用它作 `N`——同一张基础色便会随每盏灯的方向产生高光和阴影。把法线纹理作为一个 `#pragma param … texture` 加到你的受光材质上(见[材质与着色器](/docs/zh-cn/guides/material/))。diff --git a/docs/astro/src/content/docs/zh-cn/guides/material.mdx b/docs/astro/src/content/docs/zh-cn/guides/material.mdxindex cbbffd2f2..57c926df0 100644--- a/docs/astro/src/content/docs/zh-cn/guides/material.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/material.mdx@@ -85,11 +85,12 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一| 注入项 | 可用范围 | 说明 ||---|---|---|-| `u_esTime` | 总是 | `vec4` 帧时钟:`.x` 累计秒,`.y` 帧间隔秒。 |+| `u_time` | 总是 | `vec4` 帧时钟:`.x` 累计秒,`.y` 帧间隔秒。 |+| `u_viewport` | 总是 | `vec4` 画布:`.xy` 像素尺寸,`.zw` = 1/尺寸(屏幕 UV = `gl_FragCoord.xy * u_viewport.zw`)。 || MaterialConstants 块 | 着色器有参数时 | 你的 `#pragma param` 值。 |-| `es_applyLighting2D(albedo, N, worldPos)` | Lit2D | 应用场景所有灯光(含阴影),返回受光颜色。 |-| `es_sampleNormal(map, uv)` | Lit2D | 解包切线空间法线贴图(RGB → [-1,1],归一化)。 |-| `es_shadowFactor2D(worldPos, target, softness)` | Lit2D | 朝向目标点的遮挡系数(`es_applyLighting2D` 内部使用)。 |+| `applyLighting2D(albedo, N, worldPos)` | Lit2D | 应用场景所有灯光(含阴影),返回受光颜色。 |+| `sampleNormal(map, uv)` | Lit2D | 解包切线空间法线贴图(RGB → [-1,1],归一化)。 |+| `shadowFactor2D(worldPos, target, softness)` | Lit2D | 朝向目标点的遮挡系数(`applyLighting2D` 内部使用)。 |`#pragma switch` 选择编译期烘焙进材质的静态着色器排列(通过 `compileShader` 的 `features` 参数)。diff --git a/examples/ASSETS.md b/examples/ASSETS.mdindex 37753efef..ab6db9e89 100644--- a/examples/ASSETS.md+++ b/examples/ASSETS.md@@ -9,7 +9,7 @@ starting point for a real game. This credit is a courtesy, not an obligation.| Pack | License | Used by || --- | --- | --- |-| [Platformer Art Deluxe](https://kenney.nl/assets/platformer-art-deluxe) | CC0 | platformer, sprite-animation (walk/idle frames), hello-world (gem) |+| [Platformer Art Deluxe](https://kenney.nl/assets/platformer-art-deluxe) | CC0 | platformer, sprite-animation (walk/idle frames), hello-world (gem), effects-gallery (character + ground) || [Space Shooter Remastered](https://kenney.nl/assets/space-shooter-remastered) | CC0 | space-shooter (ships, lasers, enemies, life icon, starfield), input-demo (cursor), sprite-rendering (star) || [Simple Space](https://kenney.nl/assets/simple-space) | CC0 | input-demo (player ship) || [Particle Pack](https://kenney.nl/assets/particle-pack) | CC0 | particle-demo, space-shooter (explosion) |diff --git a/examples/README.md b/examples/README.mdindex 9d1f32c50..2f96a2cc6 100644--- a/examples/README.md+++ b/examples/README.md@@ -27,6 +27,7 @@ for your own game.| **particle-demo** | Effects | A configurable particle emitter with additive blending. || **postprocess-effects** | Effects | Full-screen post-processing: bloom, vignette, color grading. || **lighting-2d** | Rendering | 2D lights and shadow casters with a normal-mapped, Lit-2D material. |+| **effects-gallery** | Rendering | The built-in material effect templates — hit flash, outline, dissolve, pixelate, UV scroll — with params driven from code. || **tilemap-demo** | Tilemap | Two scenes: a Tiled `.tmj` import and an engine-native `.estileset` — multi-tileset, parallax, animated water, per-tile collision. || **ui-controls** | UI | Buttons, sliders, toggles and progress bars. || **ui-interaction** | UI | Dragging, focus and pointer interaction. |diff --git a/examples/effects-gallery/.gitignore b/examples/effects-gallery/.gitignorenew file mode 100644index 000000000..359472ac2--- /dev/null+++ b/examples/effects-gallery/.gitignore@@ -0,0 +1,7 @@+node_modules/+dist/+.vscode/+.idea/+.DS_Store+Thumbs.db+.esengine/cache/diff --git a/examples/effects-gallery/README.md b/examples/effects-gallery/README.mdnew file mode 100644index 000000000..62c815958--- /dev/null+++ b/examples/effects-gallery/README.md@@ -0,0 +1,19 @@+# Effects Gallery++The built-in material effect templates in one scene:++| Entity | Template | Driven by |+| --- | --- | --- |+| Plain | — (default batch shader) | reference |+| HitFlash | Hit Flash | `FlashPulseSystem` pulses `u_flash` |+| Outline | Outline | static params |+| Dissolve | Dissolve | `DissolveLoopSystem` ping-pongs `u_progress` |+| Pixelate | Pixelate | static params |+| Conveyor | UV Scroll | the shader itself, via the injected `u_time` clock |++Every material here was created from the Content Browser's **New Material**+template menu — each `.esshader` next to the material is an ordinary file you can+open and edit. The two animated ones show the code-driven pattern:+`Material.setUniform(sprite.material, 'u_flash', v)` from a per-frame system.++Art: [Kenney — Platformer Art Deluxe](https://kenney.nl/assets/platformer-art-deluxe) (CC0).diff --git a/examples/effects-gallery/assets/materials/dissolve.esmaterial b/examples/effects-gallery/assets/materials/dissolve.esmaterialnew file mode 100644index 000000000..78122a785--- /dev/null+++ b/examples/effects-gallery/assets/materials/dissolve.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "dissolve.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {}+}diff --git a/examples/effects-gallery/assets/materials/dissolve.esmaterial.meta b/examples/effects-gallery/assets/materials/dissolve.esmaterial.metanew file mode 100644index 000000000..377ea51b4--- /dev/null+++ b/examples/effects-gallery/assets/materials/dissolve.esmaterial.meta@@ -0,0 +1,6 @@+{+ "uuid": "784c5155-89eb-47e2-9f02-50f27eb45562",+ "version": "2.0",+ "type": "material",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/dissolve.esshader b/examples/effects-gallery/assets/materials/dissolve.esshadernew file mode 100644index 000000000..f3527269c--- /dev/null+++ b/examples/effects-gallery/assets/materials/dissolve.esshader@@ -0,0 +1,37 @@+#pragma shader "Dissolve"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_progress float default(0) range(0,1) ui(slider)+#pragma param u_edgeColor color default(1,0.5,0,1)+#pragma param u_edgeWidth float default(0.08) range(0,0.5)+#pragma param u_noiseScale float default(12) range(1,64)++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++uniform sampler2D u_textures[8];++out vec4 fragColor;++float hash2d(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }+float noise2d(vec2 p) {+ vec2 i = floor(p);+ vec2 f = fract(p);+ f = f * f * (3.0 - 2.0 * f);+ return mix(mix(hash2d(i), hash2d(i + vec2(1.0, 0.0)), f.x),+ mix(hash2d(i + vec2(0.0, 1.0)), hash2d(i + vec2(1.0, 1.0)), f.x), f.y);+}++// u_progress 0 = intact, 1 = fully dissolved; a glowing edge leads the cut.+void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color;+ float n = noise2d(v_texCoord * u_noiseScale);+ float cut = u_progress * (1.0 + u_edgeWidth);+ if (n < cut - u_edgeWidth) discard;+ vec3 rgb = (n < cut) ? u_edgeColor.rgb : base.rgb;+ fragColor = vec4(rgb, base.a);+}+#pragma enddiff --git a/examples/effects-gallery/assets/materials/dissolve.esshader.meta b/examples/effects-gallery/assets/materials/dissolve.esshader.metanew file mode 100644index 000000000..a65b50345--- /dev/null+++ b/examples/effects-gallery/assets/materials/dissolve.esshader.meta@@ -0,0 +1,6 @@+{+ "uuid": "a250e21f-55ad-467d-a66e-d7b9a76aeeb1",+ "version": "2.0",+ "type": "shader",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/hit-flash.esmaterial b/examples/effects-gallery/assets/materials/hit-flash.esmaterialnew file mode 100644index 000000000..489649c05--- /dev/null+++ b/examples/effects-gallery/assets/materials/hit-flash.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "hit-flash.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {}+}diff --git a/examples/effects-gallery/assets/materials/hit-flash.esmaterial.meta b/examples/effects-gallery/assets/materials/hit-flash.esmaterial.metanew file mode 100644index 000000000..598c0a5b6--- /dev/null+++ b/examples/effects-gallery/assets/materials/hit-flash.esmaterial.meta@@ -0,0 +1,6 @@+{+ "uuid": "c7ae8957-4cd5-4936-9976-3bd422a9246b",+ "version": "2.0",+ "type": "material",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/hit-flash.esshader b/examples/effects-gallery/assets/materials/hit-flash.esshadernew file mode 100644index 000000000..a65fd2707--- /dev/null+++ b/examples/effects-gallery/assets/materials/hit-flash.esshader@@ -0,0 +1,22 @@+#pragma shader "Hit Flash"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_flash float default(0) range(0,1) ui(slider)+#pragma param u_flashColor color default(1,1,1,1)++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++uniform sampler2D u_textures[8];++out vec4 fragColor;++// Drive u_flash 1 → 0 from code (tween) for the classic damage blink.+void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color;+ fragColor = vec4(mix(base.rgb, u_flashColor.rgb, u_flash), base.a);+}+#pragma enddiff --git a/examples/effects-gallery/assets/materials/hit-flash.esshader.meta b/examples/effects-gallery/assets/materials/hit-flash.esshader.metanew file mode 100644index 000000000..d7db2ea03--- /dev/null+++ b/examples/effects-gallery/assets/materials/hit-flash.esshader.meta@@ -0,0 +1,6 @@+{+ "uuid": "e2f29b44-754d-43f4-9706-a5d1084e38ad",+ "version": "2.0",+ "type": "shader",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/outline.esmaterial b/examples/effects-gallery/assets/materials/outline.esmaterialnew file mode 100644index 000000000..dd57f08a8--- /dev/null+++ b/examples/effects-gallery/assets/materials/outline.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "outline.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {}+}diff --git a/examples/effects-gallery/assets/materials/outline.esmaterial.meta b/examples/effects-gallery/assets/materials/outline.esmaterial.metanew file mode 100644index 000000000..1564cc825--- /dev/null+++ b/examples/effects-gallery/assets/materials/outline.esmaterial.meta@@ -0,0 +1,6 @@+{+ "uuid": "c3b6d8a4-ee76-47e1-9887-21e73e463452",+ "version": "2.0",+ "type": "material",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/outline.esshader b/examples/effects-gallery/assets/materials/outline.esshadernew file mode 100644index 000000000..e878f3c59--- /dev/null+++ b/examples/effects-gallery/assets/materials/outline.esshader@@ -0,0 +1,31 @@+#pragma shader "Outline"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_outlineColor color default(1,1,1,1)+#pragma param u_outlineWidth float default(1) range(0,8)++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++uniform sampler2D u_textures[8];++out vec4 fragColor;++void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color;+ highp vec2 texel = u_outlineWidth / vec2(textureSize(u_textures[0], 0));+ float edge = 0.0;+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2( texel.x, 0.0)).a);+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2(-texel.x, 0.0)).a);+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2(0.0, texel.y)).a);+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2(0.0, -texel.y)).a);+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2( texel.x, texel.y)).a);+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2( texel.x, -texel.y)).a);+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2(-texel.x, texel.y)).a);+ edge = max(edge, texture(u_textures[0], v_texCoord + vec2(-texel.x, -texel.y)).a);+ fragColor = mix(vec4(u_outlineColor.rgb, edge * u_outlineColor.a), base, base.a);+}+#pragma enddiff --git a/examples/effects-gallery/assets/materials/outline.esshader.meta b/examples/effects-gallery/assets/materials/outline.esshader.metanew file mode 100644index 000000000..b14135ee5--- /dev/null+++ b/examples/effects-gallery/assets/materials/outline.esshader.meta@@ -0,0 +1,6 @@+{+ "uuid": "1acb5aaa-097b-4f43-8067-066b4c31cc16",+ "version": "2.0",+ "type": "shader",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/pixelate.esmaterial b/examples/effects-gallery/assets/materials/pixelate.esmaterialnew file mode 100644index 000000000..033a1cdcf--- /dev/null+++ b/examples/effects-gallery/assets/materials/pixelate.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "pixelate.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {}+}diff --git a/examples/effects-gallery/assets/materials/pixelate.esmaterial.meta b/examples/effects-gallery/assets/materials/pixelate.esmaterial.metanew file mode 100644index 000000000..1d037440c--- /dev/null+++ b/examples/effects-gallery/assets/materials/pixelate.esmaterial.meta@@ -0,0 +1,6 @@+{+ "uuid": "366ada93-dba9-4837-bc4a-bf0af3963930",+ "version": "2.0",+ "type": "material",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/pixelate.esshader b/examples/effects-gallery/assets/materials/pixelate.esshadernew file mode 100644index 000000000..55b335db9--- /dev/null+++ b/examples/effects-gallery/assets/materials/pixelate.esshader@@ -0,0 +1,20 @@+#pragma shader "Pixelate"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_pixels float default(32) range(2,256)++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++uniform sampler2D u_textures[8];++out vec4 fragColor;++void main() {+ vec2 uv = (floor(v_texCoord * u_pixels) + 0.5) / u_pixels;+ fragColor = texture(u_textures[0], uv) * v_color;+}+#pragma enddiff --git a/examples/effects-gallery/assets/materials/pixelate.esshader.meta b/examples/effects-gallery/assets/materials/pixelate.esshader.metanew file mode 100644index 000000000..2685d5e70--- /dev/null+++ b/examples/effects-gallery/assets/materials/pixelate.esshader.meta@@ -0,0 +1,6 @@+{+ "uuid": "59bee49b-da6a-4ef9-9c3b-559b91e1f5d4",+ "version": "2.0",+ "type": "shader",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/uv-scroll.esmaterial b/examples/effects-gallery/assets/materials/uv-scroll.esmaterialnew file mode 100644index 000000000..ccc88fd35--- /dev/null+++ b/examples/effects-gallery/assets/materials/uv-scroll.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "uv-scroll.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {}+}diff --git a/examples/effects-gallery/assets/materials/uv-scroll.esmaterial.meta b/examples/effects-gallery/assets/materials/uv-scroll.esmaterial.metanew file mode 100644index 000000000..3d768ff40--- /dev/null+++ b/examples/effects-gallery/assets/materials/uv-scroll.esmaterial.meta@@ -0,0 +1,6 @@+{+ "uuid": "ae3aa524-a9dd-4378-b129-afc68a992d6f",+ "version": "2.0",+ "type": "material",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/materials/uv-scroll.esshader b/examples/effects-gallery/assets/materials/uv-scroll.esshadernew file mode 100644index 000000000..185c84492--- /dev/null+++ b/examples/effects-gallery/assets/materials/uv-scroll.esshader@@ -0,0 +1,21 @@+#pragma shader "UV Scroll"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_scrollSpeed vec2 default(0.1,0)++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++uniform sampler2D u_textures[8];++out vec4 fragColor;++// u_time.x is the engine frame clock (seconds), injected into every shader.+void main() {+ vec2 uv = fract(v_texCoord + u_time.x * u_scrollSpeed);+ fragColor = texture(u_textures[0], uv) * v_color;+}+#pragma enddiff --git a/examples/effects-gallery/assets/materials/uv-scroll.esshader.meta b/examples/effects-gallery/assets/materials/uv-scroll.esshader.metanew file mode 100644index 000000000..0282be9f1--- /dev/null+++ b/examples/effects-gallery/assets/materials/uv-scroll.esshader.meta@@ -0,0 +1,6 @@+{+ "uuid": "970d09d2-c446-44c5-b785-148cba3e8bf5",+ "version": "2.0",+ "type": "shader",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/scenes/main.esscene b/examples/effects-gallery/assets/scenes/main.esscenenew file mode 100644index 000000000..2ba9b036b--- /dev/null+++ b/examples/effects-gallery/assets/scenes/main.esscene@@ -0,0 +1,85 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 360, "isActive": true, "priority": 0, "backgroundColor": { "r": 0.09, "g": 0.1, "b": 0.13, "a": 1 } } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Plain",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": -520, "y": 60, "z": 0 } } },+ { "type": "Sprite", "data": { "texture": "assets/textures/player.png", "size": { "x": 132, "y": 184 } } }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "HitFlash",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": -260, "y": 60, "z": 0 } } },+ { "type": "Sprite", "data": { "texture": "assets/textures/player.png", "size": { "x": 132, "y": 184 }, "material": "assets/materials/hit-flash.esmaterial" } },+ { "type": "FlashPulse", "data": { "speed": 6 } }+ ],+ "visible": true+ },+ {+ "id": 3,+ "name": "Outline",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 60, "z": 0 } } },+ { "type": "Sprite", "data": { "texture": "assets/textures/player.png", "size": { "x": 132, "y": 184 }, "material": "assets/materials/outline.esmaterial" } }+ ],+ "visible": true+ },+ {+ "id": 4,+ "name": "Dissolve",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 260, "y": 60, "z": 0 } } },+ { "type": "Sprite", "data": { "texture": "assets/textures/player.png", "size": { "x": 132, "y": 184 }, "material": "assets/materials/dissolve.esmaterial" } },+ { "type": "DissolveLoop", "data": { "speed": 0.35 } }+ ],+ "visible": true+ },+ {+ "id": 5,+ "name": "Pixelate",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 520, "y": 60, "z": 0 } } },+ { "type": "Sprite", "data": { "texture": "assets/textures/player.png", "size": { "x": 132, "y": 184 }, "material": "assets/materials/pixelate.esmaterial" } }+ ],+ "visible": true+ },+ {+ "id": 6,+ "name": "Conveyor",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": -240, "z": 0 } } },+ { "type": "Sprite", "data": { "texture": "assets/textures/ground.png", "size": { "x": 1190, "y": 70 }, "uvScale": { "x": 17, "y": 1 }, "material": "assets/materials/uv-scroll.esmaterial" } }+ ],+ "visible": true+ }+ ]+}diff --git a/examples/effects-gallery/assets/scenes/main.esscene.meta b/examples/effects-gallery/assets/scenes/main.esscene.metanew file mode 100644index 000000000..200e41026--- /dev/null+++ b/examples/effects-gallery/assets/scenes/main.esscene.meta@@ -0,0 +1,6 @@+{+ "uuid": "3b11f504-a058-4963-9208-5ed0eecbde22",+ "version": "2.0",+ "type": "scene",+ "importer": {}+}diff --git a/examples/effects-gallery/assets/textures/ground.png b/examples/effects-gallery/assets/textures/ground.pngnew file mode 100644index 000000000..035addae8Binary files /dev/null and b/examples/effects-gallery/assets/textures/ground.png differdiff --git a/examples/effects-gallery/assets/textures/ground.png.meta b/examples/effects-gallery/assets/textures/ground.png.metanew file mode 100644index 000000000..2dcfeef09--- /dev/null+++ b/examples/effects-gallery/assets/textures/ground.png.meta@@ -0,0 +1,17 @@+{+ "uuid": "6bbef0f9-1cde-4bcc-b13b-d8f5bda7a816",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "maxSize": 2048,+ "filterMode": "linear",+ "wrapMode": "repeat",+ "premultiplyAlpha": false,+ "sliceBorder": {+ "left": 0,+ "right": 0,+ "top": 0,+ "bottom": 0+ }+ }+}diff --git a/examples/effects-gallery/assets/textures/player.png b/examples/effects-gallery/assets/textures/player.pngnew file mode 100644index 000000000..e7613ad5dBinary files /dev/null and b/examples/effects-gallery/assets/textures/player.png differdiff --git a/examples/effects-gallery/assets/textures/player.png.meta b/examples/effects-gallery/assets/textures/player.png.metanew file mode 100644index 000000000..04ae0b510--- /dev/null+++ b/examples/effects-gallery/assets/textures/player.png.meta@@ -0,0 +1,17 @@+{+ "uuid": "518f1a81-e270-40ac-ba79-80297cfc65d5",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "maxSize": 2048,+ "filterMode": "linear",+ "wrapMode": "repeat",+ "premultiplyAlpha": false,+ "sliceBorder": {+ "left": 0,+ "right": 0,+ "top": 0,+ "bottom": 0+ }+ }+}diff --git a/examples/effects-gallery/project.esproject b/examples/effects-gallery/project.esprojectnew file mode 100644index 000000000..2d2c704ba--- /dev/null+++ b/examples/effects-gallery/project.esproject@@ -0,0 +1,13 @@+{+ "formatVersion": "1",+ "name": "Effects Gallery",+ "description": "The built-in material effect templates in one scene — hit flash, outline, dissolve, pixelate, and a time-scrolled conveyor — with their parameters driven from code.",+ "tag": "Rendering",+ "version": "0.1.0",+ "defaultScene": "assets/scenes/main.esscene",+ "designResolution": {+ "width": 1280,+ "height": 720+ },+ "spineVersion": "none"+}diff --git a/examples/effects-gallery/src/components.ts b/examples/effects-gallery/src/components.tsnew file mode 100644index 000000000..03bbf215e--- /dev/null+++ b/examples/effects-gallery/src/components.ts@@ -0,0 +1,7 @@+import { defineComponent } from 'esengine';++/** Pulses the hit-flash material's u_flash from a sine wave. */+export const FlashPulse = defineComponent('FlashPulse', { speed: 6 });++/** Ping-pongs the dissolve material's u_progress between 0 and 1. */+export const DissolveLoop = defineComponent('DissolveLoop', { speed: 0.35 });diff --git a/examples/effects-gallery/src/main.ts b/examples/effects-gallery/src/main.tsnew file mode 100644index 000000000..1b8623b19--- /dev/null+++ b/examples/effects-gallery/src/main.ts@@ -0,0 +1,40 @@+// Effects Gallery — the built-in material effect templates in one scene.+//+// Each character uses a material created from a Content Browser template+// (New Material → Hit Flash / Outline / Dissolve / Pixelate); the conveyor at+// the bottom scrolls itself in the shader via the injected u_time clock. The+// two animated ones show the code-driven pattern: a system writes a material+// parameter each frame with Material.setUniform.+import {+ addSystemToSchedule, Schedule, defineSystem, Query, Res, Time,+ Material, Sprite,+} from 'esengine';+import { FlashPulse, DissolveLoop } from './components';++const flashSystem = defineSystem(+ [Query(Sprite, FlashPulse), Res(Time)],+ (q, time) => {+ for (const [, sprite, pulse] of q) {+ if (!sprite.material) continue;+ const s = Math.max(0, Math.sin(time.elapsed * pulse.speed));+ Material.setUniform(sprite.material, 'u_flash', s * s);+ }+ },+ { name: 'FlashPulseSystem' },+);++const dissolveSystem = defineSystem(+ [Query(Sprite, DissolveLoop), Res(Time)],+ (q, time) => {+ for (const [, sprite, loop] of q) {+ if (!sprite.material) continue;+ const t = time.elapsed * loop.speed;+ const pingpong = 1 - Math.abs((t % 2) - 1);+ Material.setUniform(sprite.material, 'u_progress', pingpong);+ }+ },+ { name: 'DissolveLoopSystem' },+);++addSystemToSchedule(Schedule.Update, flashSystem);+addSystemToSchedule(Schedule.Update, dissolveSystem);diff --git a/examples/effects-gallery/tsconfig.json b/examples/effects-gallery/tsconfig.jsonnew file mode 100644index 000000000..0a8528b29--- /dev/null+++ b/examples/effects-gallery/tsconfig.json@@ -0,0 +1,22 @@+{+ "compilerOptions": {+ "target": "ES2020",+ "module": "ESNext",+ "moduleResolution": "bundler",+ "strict": true,+ "esModuleInterop": true,+ "skipLibCheck": true,+ "forceConsistentCasingInFileNames": true,+ "declaration": false,+ "outDir": "./dist",+ "rootDir": ".",+ "baseUrl": ".",+ "paths": {+ "esengine": ["./.esengine/sdk/index.d.ts"],+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"],+ "@esengine/editor": ["./.esengine/editor/index.d.ts"]+ }+ },+ "include": ["src/**/*"],+ "exclude": ["node_modules"]+}diff --git a/examples/lighting-2d/assets/materials/lit.esshader b/examples/lighting-2d/assets/materials/lit.esshaderindex 4683b853b..c0b712e37 100644--- a/examples/lighting-2d/assets/materials/lit.esshader+++ b/examples/lighting-2d/assets/materials/lit.esshader@@ -2,29 +2,6 @@#pragma version 300 es#pragma domain Lit2D-#pragma vertex-layout(location = 0) in vec2 a_position;-layout(location = 1) in vec4 a_color;-layout(location = 2) in vec2 a_texCoord;-layout(location = 3) in float a_texIndex;--layout(std140) uniform FrameConstants {- mat4 u_projection;-};--out vec4 v_color;-out vec2 v_texCoord;-out highp vec2 v_worldPos;--void main() {- gl_Position = u_projection * vec4(a_position, 0.0, 1.0);- v_color = a_color;- v_texCoord = a_texCoord;- // The batch path bakes the transform into the vertices, so a_position is already world-space.- v_worldPos = a_position;-}-#pragma end-#pragma fragmentprecision mediump float;@@ -36,14 +13,14 @@ uniform sampler2D u_textures[8];out vec4 fragColor;-// The LightConstants block + es_applyLighting2D() are injected by the engine for-// `#pragma domain Lit2D`. These surfaces carry no texture, so u_textures[0] is the-// default 1×1 white — the sprite's `color` becomes the albedo the lights multiply.-// A flat normal faces the camera (2D has no per-sprite tangent frame).+// The LightConstants block + applyLighting2D() are injected by the engine for+// `#pragma domain Lit2D`; the vertex stage is engine-injected too. These surfaces+// carry no texture, so u_textures[0] is the default 1×1 white — the sprite's+// `color` is the albedo the lights multiply. A flat normal faces the camera.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;vec3 N = vec3(0.0, 0.0, 1.0);- vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ vec3 lit = applyLighting2D(base.rgb, N, v_worldPos);fragColor = vec4(lit, base.a);}#pragma enddiff --git a/sdk/src/builtinShaders.ts b/sdk/src/builtinShaders.tsindex ff4cc7414..6aea401c2 100644--- a/sdk/src/builtinShaders.ts+++ b/sdk/src/builtinShaders.ts@@ -56,8 +56,8 @@ out vec4 fragColor;// Unset u_normalMap = flat normal, so lighting works with no normal map assigned.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color * u_tint;- vec3 N = es_sampleNormal(u_normalMap, v_texCoord);- fragColor = vec4(es_applyLighting2D(base.rgb, N, v_worldPos), base.a);+ vec3 N = sampleNormal(u_normalMap, v_texCoord);+ fragColor = vec4(applyLighting2D(base.rgb, N, v_worldPos), base.a);}#pragma end`;@@ -137,19 +137,19 @@ uniform sampler2D u_textures[8];out vec4 fragColor;-float es_hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }-float es_noise(vec2 p) {+float hash2d(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }+float noise2d(vec2 p) {vec2 i = floor(p);vec2 f = fract(p);f = f * f * (3.0 - 2.0 * f);- return mix(mix(es_hash(i), es_hash(i + vec2(1.0, 0.0)), f.x),- mix(es_hash(i + vec2(0.0, 1.0)), es_hash(i + vec2(1.0, 1.0)), f.x), f.y);+ return mix(mix(hash2d(i), hash2d(i + vec2(1.0, 0.0)), f.x),+ mix(hash2d(i + vec2(0.0, 1.0)), hash2d(i + vec2(1.0, 1.0)), f.x), f.y);}// u_progress 0 = intact, 1 = fully dissolved; a glowing edge leads the cut.void main() {vec4 base = texture(u_textures[0], v_texCoord) * v_color;- float n = es_noise(v_texCoord * u_noiseScale);+ float n = noise2d(v_texCoord * u_noiseScale);float cut = u_progress * (1.0 + u_edgeWidth);if (n < cut - u_edgeWidth) discard;vec3 rgb = (n < cut) ? u_edgeColor.rgb : base.rgb;@@ -195,9 +195,9 @@ uniform sampler2D u_textures[8];out vec4 fragColor;-// u_esTime.x is the engine frame clock (seconds), injected into every shader.+// u_time.x is the engine frame clock (seconds), injected into every shader.void main() {- vec2 uv = fract(v_texCoord + u_esTime.x * u_scrollSpeed);+ vec2 uv = fract(v_texCoord + u_time.x * u_scrollSpeed);fragColor = texture(u_textures[0], uv) * v_color;}#pragma enddiff --git a/sdk/src/materialGraph.ts b/sdk/src/materialGraph.tsindex 2f4ff768c..d06e4d489 100644--- a/sdk/src/materialGraph.ts+++ b/sdk/src/materialGraph.ts@@ -20,7 +20,8 @@ export type GraphNodeType =| 'output' // the root: its `color` input becomes fragColor| 'uv' // v_texCoord| 'vertexColor' // v_color (the sprite's per-instance tint)- | 'time' // u_esTime.x — the injected engine frame clock (seconds)+ | 'time' // u_time.x — the injected engine frame clock (seconds)+ | 'screenUV' // gl_FragCoord over the canvas size (0..1, y-up)| 'constFloat' // a scalar material param (#pragma param ... float)| 'constColor' // an RGBA material param (#pragma param ... color)| 'textureSample' // sample a texture material param at a UV (#pragma param ... texture)@@ -118,8 +119,14 @@ export function compileMaterialGraph(graph: MaterialGraph): string {out = { expr: 'v_color', type: 'vec4' };break;case 'time':- out = { expr: 'u_esTime.x', type: 'float' };+ out = { expr: 'u_time.x', type: 'float' };break;+ case 'screenUV': {+ const t = `n${tmp++}`;+ body.push(`vec2 ${t} = gl_FragCoord.xy * u_viewport.zw;`);+ out = { expr: t, type: 'vec2' };+ break;+ }case 'constFloat': {const name = paramName(n);const v = typeof n.params?.value === 'number' ? n.params.value : 0;@@ -188,14 +195,14 @@ export function compileMaterialGraph(graph: MaterialGraph): string {helpers.add(NOISE_HELPER);const uv = n.inputs?.uv ? input('uv').expr : 'v_texCoord';const t = `n${tmp++}`;- body.push(`float ${t} = es_noise(${uv} * ${numParam(n, 'scale', 12)});`);+ body.push(`float ${t} = noise2d(${uv} * ${numParam(n, 'scale', 12)});`);out = { expr: t, type: 'float' };break;}case 'panner': {const uv = n.inputs?.uv ? input('uv').expr : 'v_texCoord';const t = `n${tmp++}`;- body.push(`vec2 ${t} = fract(${uv} + u_esTime.x * vec2(${numParam(n, 'speedX', 0.1)}, ${numParam(n, 'speedY', 0)}));`);+ body.push(`vec2 ${t} = fract(${uv} + u_time.x * vec2(${numParam(n, 'speedX', 0.1)}, ${numParam(n, 'speedY', 0)}));`);out = { expr: t, type: 'vec2' };break;}@@ -246,13 +253,13 @@ ${bodyBlock}`;}-const NOISE_HELPER = `float es_hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }-float es_noise(vec2 p) {+const NOISE_HELPER = `float hash2d(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }+float noise2d(vec2 p) {vec2 i = floor(p);vec2 f = fract(p);f = f * f * (3.0 - 2.0 * f);- return mix(mix(es_hash(i), es_hash(i + vec2(1.0, 0.0)), f.x),- mix(es_hash(i + vec2(0.0, 1.0)), es_hash(i + vec2(1.0, 1.0)), f.x), f.y);+ return mix(mix(hash2d(i), hash2d(i + vec2(1.0, 0.0)), f.x),+ mix(hash2d(i + vec2(0.0, 1.0)), hash2d(i + vec2(1.0, 1.0)), f.x), f.y);}`;// =============================================================================@@ -289,6 +296,7 @@ export const NODE_SPECS: Record<GraphNodeType, NodeSpec> = {uv: { label: 'UV', inputs: [], output: 'vec2', params: [], addable: true },vertexColor: { label: 'Vertex Color', inputs: [], output: 'vec4', params: [], addable: true },time: { label: 'Time', inputs: [], output: 'float', params: [], addable: true },+ screenUV: { label: 'Screen UV', inputs: [], output: 'vec2', params: [], addable: true },constFloat: { label: 'Float', inputs: [], output: 'float', params: [{ key: 'value', label: 'Value', kind: 'float' }], addable: true },constColor: { label: 'Color', inputs: [], output: 'vec4', params: [{ key: 'value', label: 'Color', kind: 'color' }], addable: true },textureSample: { label: 'Texture', inputs: [{ name: 'uv', type: 'vec2' }], output: 'vec4', params: [{ key: 'name', label: 'Param', kind: 'texture' }], addable: true },diff --git a/sdk/tests/materialGraph.test.ts b/sdk/tests/materialGraph.test.tsindex 7ffa10eb8..b1e0a49ba 100644--- a/sdk/tests/materialGraph.test.ts+++ b/sdk/tests/materialGraph.test.ts@@ -64,11 +64,23 @@ describe('compileMaterialGraph', () => {],};const src = compileMaterialGraph(g);- expect(src).toContain('fract(v_texCoord + u_esTime.x * vec2(0.2500, 0.0000))');- expect(src).toContain('sin(u_esTime.x)');- expect(src).toContain('es_noise(v_texCoord * 8.0000)');+ expect(src).toContain('fract(v_texCoord + u_time.x * vec2(0.2500, 0.0000))');+ expect(src).toContain('sin(u_time.x)');+ expect(src).toContain('noise2d(v_texCoord * 8.0000)');expect(src).toContain('smoothstep(0.2000, 0.8000,');- expect(src.match(/float es_noise/g)?.length).toBe(1); // helper emitted once+ expect(src.match(/float noise2d/g)?.length).toBe(1); // helper emitted once+ });++ it('compiles the screenUV node from the injected viewport', () => {+ const g: MaterialGraph = {+ output: 'out',+ nodes: [+ { id: 'suv', type: 'screenUV' },+ { id: 'tex', type: 'textureSample', inputs: { uv: 'suv' }, params: { name: 'u_albedo', default: 'white' } },+ { id: 'out', type: 'output', inputs: { color: 'tex' } },+ ],+ };+ expect(compileMaterialGraph(g)).toContain('gl_FragCoord.xy * u_viewport.zw');});it('reuses a shared node once (DAG, not a tree)', () => {diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex aaf67f048..13a45ee00 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -240,7 +240,9 @@ void renderer_resize(u32 width, u32 height) {void renderer_beginFrame(f32 elapsedSec) {ctx().state().transforms_updated = false;- if (auto* rc = ctx().tryGet<RenderContext>()) rc->setFrameTime(elapsedSec);+ if (auto* rc = ctx().tryGet<RenderContext>()) {+ rc->setFrameTime(elapsedSec, g_viewportWidth, g_viewportHeight);+ }}void renderer_begin(uintptr_t matrixPtr, u32 targetHandle) {diff --git a/src/esengine/data/shaders/batch.esshader b/src/esengine/data/shaders/batch.esshaderindex 7f2d4242e..c3ecd29b4 100644--- a/src/esengine/data/shaders/batch.esshader+++ b/src/esengine/data/shaders/batch.esshader@@ -7,7 +7,7 @@#pragma feature SDF// Compile-time variant: lit by the scene's 2D lights (Sprite.lit). Compiled as a-// Lit2D-domain shader, so es_applyLighting2D + LightConstants are injected.+// Lit2D-domain shader, so applyLighting2D + LightConstants are injected.#pragma feature LIT#pragma vertex@@ -78,7 +78,7 @@ void main() {#elif defined(LIT)// Flat normal; the tinted color is the albedo. Normal maps need a material.vec4 base = texColor * v_color;- fragColor = vec4(es_applyLighting2D(base.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), base.a);+ fragColor = vec4(applyLighting2D(base.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), base.a);#elsefragColor = texColor * v_color;#endifdiff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hppindex 40af22c18..4b536b2b7 100644--- a/src/esengine/ecs/components/Light2D.hpp+++ b/src/esengine/ecs/components/Light2D.hpp@@ -5,7 +5,7 @@* @brief 2D light source component for the Lit2D material domain.* @details A scene's Light2D components are gathered by the render collect path into the* per-frame LightConstants UBO (binding 2); Lit2D-domain material shaders read them- * via the injected es_applyLighting2D() helper. Point/Directional lights occupy a+ * via the injected applyLighting2D() helper. Point/Directional lights occupy a* light slot; Ambient lights sum into the ambient term. World position comes from the* entity's Transform — this component carries only the light's intrinsic parameters.*diff --git a/src/esengine/ecs/components/ShadowCaster2D.hpp b/src/esengine/ecs/components/ShadowCaster2D.hppindex a589b3c8a..f97ec141d 100644--- a/src/esengine/ecs/components/ShadowCaster2D.hpp+++ b/src/esengine/ecs/components/ShadowCaster2D.hpp@@ -6,7 +6,7 @@* @details The render collect path turns each enabled caster into a world-space AABB (centered* on the entity's Transform, `size` wide/tall) and feeds it to LightStore as an occluder.* A point/spot light is then blocked at any fragment whose segment to the light crosses- * the box (see ShaderParser's injected es_shadowFactor2D). Carries no geometry of its own.+ * the box (see ShaderParser's injected shadowFactor2D). Carries no geometry of its own.** @copyright Copyright (c) 2026 ESEngine Team* Licensed under the Apache License, Version 2.0.diff --git a/src/esengine/renderer/FrameConstants.hpp b/src/esengine/renderer/FrameConstants.hppindex 13494aa65..4f017aa9d 100644--- a/src/esengine/renderer/FrameConstants.hpp+++ b/src/esengine/renderer/FrameConstants.hpp@@ -42,11 +42,13 @@ inline constexpr const char* FRAME_CONSTANTS_BLOCK = "FrameConstants";/*** @brief CPU mirror of the injected TimeConstants block (std140).- * @details u_esTime = (elapsed seconds, delta seconds, 0, 0). Engine-owned: ShaderParser- * injects the block into every assembled stage — shaders never declare it.+ * @details u_time = (elapsed s, delta s, 0, 0); u_viewport = (w, h, 1/w, 1/h) of the+ * canvas in pixels. Engine-owned: ShaderParser injects the block into every+ * assembled stage — shaders never declare it.*/struct TimeConstants {glm::vec4 time{0.0f};+ glm::vec4 viewport{0.0f};};inline constexpr u32 TIME_CONSTANTS_BINDING = 3;diff --git a/src/esengine/renderer/LightConstants.hpp b/src/esengine/renderer/LightConstants.hppindex 81447501b..ba5ce453d 100644--- a/src/esengine/renderer/LightConstants.hpp+++ b/src/esengine/renderer/LightConstants.hpp@@ -33,7 +33,7 @@ inline constexpr u32 MAX_LIGHTS_2D = 16;/*** @brief Max 2D shadow occluders packed into the UBO (axis-aligned boxes in world space).- * The injected es_applyLighting2D loops up to the active count; 0 occluders = no+ * The injected applyLighting2D loops up to the active count; 0 occluders = no* shadowing (identity), so the feature is inert until the render path feeds boxes.* Must match the `u_occluders[..]` array size in ShaderParser's injected GLSL.*/@@ -49,7 +49,7 @@ inline constexpr u32 MAX_OCCLUDERS_2D = 8;* LightConstants::ambient instead of occupying a slot.* shadow: x = penumbra softness (light-source half-extent in world units; 0 = hard,* backward-compatible); y = directional shadow march distance (world units; 0 = a- * directional light casts no shadow). zw reserved (0). Read by es_shadowFactor2D.+ * directional light casts no shadow). zw reserved (0). Read by shadowFactor2D.*/struct GpuLight2D {glm::vec4 posDir{0.0f};diff --git a/src/esengine/renderer/RenderContext.cpp b/src/esengine/renderer/RenderContext.cppindex 3f7d96b4a..b26bb92a7 100644--- a/src/esengine/renderer/RenderContext.cpp+++ b/src/esengine/renderer/RenderContext.cpp@@ -125,10 +125,15 @@ void RenderContext::updateFrameConstants(const glm::mat4& viewProjection) {sizeof(glm::mat4));}-void RenderContext::setFrameTime(f32 elapsedSec) {+void RenderContext::setFrameTime(f32 elapsedSec, u32 viewportW, u32 viewportH) {const f32 dt = (lastElapsed_ > 0.0f && elapsedSec > lastElapsed_) ? elapsedSec - lastElapsed_ : 0.0f;lastElapsed_ = elapsedSec;- TimeConstants time{ glm::vec4(elapsedSec, dt, 0.0f, 0.0f) };+ const f32 w = static_cast<f32>(viewportW);+ const f32 h = static_cast<f32>(viewportH);+ TimeConstants time{+ glm::vec4(elapsedSec, dt, 0.0f, 0.0f),+ glm::vec4(w, h, w > 0.0f ? 1.0f / w : 0.0f, h > 0.0f ? 1.0f / h : 0.0f),+ };device_.bindUniformBuffer(timeUbo_);device_.bufferSubData(GfxBufferTarget::Uniform, 0, &time, sizeof(TimeConstants));}diff --git a/src/esengine/renderer/RenderContext.hpp b/src/esengine/renderer/RenderContext.hppindex 37f0d4655..8181fd935 100644--- a/src/esengine/renderer/RenderContext.hpp+++ b/src/esengine/renderer/RenderContext.hpp@@ -157,8 +157,8 @@ public:*/void updateFrameConstants(const glm::mat4& viewProjection);- /** @brief Uploads the frame clock into the injected TimeConstants UBO (u_esTime = elapsed, dt). */- void setFrameTime(f32 elapsedSec);+ /** @brief Uploads the frame clock + canvas size into the injected TimeConstants UBO. */+ void setFrameTime(f32 elapsedSec, u32 viewportW, u32 viewportH);/*** @brief The engine-side material registry (handle -> resolved render state).diff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cppindex 70ea06a73..bde084905 100644--- a/src/esengine/renderer/RenderFrame.cpp+++ b/src/esengine/renderer/RenderFrame.cpp@@ -527,7 +527,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {GpuLight2D gpu;gpu.color = glm::vec4(rgb, light.intensity);// shadow.x = penumbra softness (all types); shadow.y = directional march distance (only the- // directional branch of es_shadowFactor2D reads it; 0 keeps directional shadows off).+ // directional branch of shadowFactor2D reads it; 0 keeps directional shadows off).gpu.shadow = glm::vec4(std::max(light.shadowSoftness, 0.0f),std::max(light.shadowDistance, 0.0f), 0.0f, 0.0f);if (type == ecs::Light2DType::Directional) {@@ -560,7 +560,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {for (const auto& gpu : collected) lights.addLight(gpu);// Shadow occluders: each enabled ShadowCaster2D becomes a world-space AABB (centered on its- // Transform, `size` wide/tall). The injected es_shadowFactor2D blocks point/spot light at any+ // Transform, `size` wide/tall). The injected shadowFactor2D blocks point/spot light at any// fragment whose segment to the light crosses a box. Past the cap are silently dropped.auto occluders = registry.view<ecs::Transform, ecs::ShadowCaster2D>();for (auto entity : occluders) {diff --git a/src/esengine/renderer/Shader.cpp b/src/esengine/renderer/Shader.cppindex ba13dfbf8..0db467be8 100644--- a/src/esengine/renderer/Shader.cpp+++ b/src/esengine/renderer/Shader.cpp@@ -179,7 +179,7 @@ bool Shader::compile(const std::string& vertexSrc, const std::string& fragmentSrdevice_->uniformBlockBinding(programId_, lightBlock, LIGHT_CONSTANTS_BINDING);}- // Same for the injected frame clock (u_esTime).+ // Same for the injected frame clock (u_time).u32 timeBlock = device_->getUniformBlockIndex(programId_, TIME_CONSTANTS_BLOCK);if (timeBlock != GFX_INVALID_UNIFORM_BLOCK) {device_->uniformBlockBinding(programId_, timeBlock, TIME_CONSTANTS_BINDING);diff --git a/src/esengine/renderer/ShaderEmbeds.generated.hpp b/src/esengine/renderer/ShaderEmbeds.generated.hppindex 521923f2c..0701f00e6 100644--- a/src/esengine/renderer/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/ShaderEmbeds.generated.hpp@@ -11,7 +11,7 @@ inline constexpr const char* BATCH = R"esshader(#pragma shader "Batch"#pragma feature SDF// Compile-time variant: lit by the scene's 2D lights (Sprite.lit). Compiled as a-// Lit2D-domain shader, so es_applyLighting2D + LightConstants are injected.+// Lit2D-domain shader, so applyLighting2D + LightConstants are injected.#pragma feature LIT#pragma vertex@@ -82,7 +82,7 @@ void main() {#elif defined(LIT)// Flat normal; the tinted color is the albedo. Normal maps need a material.vec4 base = texColor * v_color;- fragColor = vec4(es_applyLighting2D(base.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), base.a);+ fragColor = vec4(applyLighting2D(base.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), base.a);#elsefragColor = texColor * v_color;#endifdiff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 0dcc9fa2f..6e063ab7d 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -202,7 +202,15 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR// Declarative material parameter: ShaderParser owns its std140 slot in the// generated MaterialConstants block (or a sampler unit for textures).ShaderProperty prop = parseParamDirective(argument);- if (!prop.name.empty()) result.properties.push_back(prop);+ if (!prop.name.empty()) {+ // Engine-injected uniforms — a param with the same name would redeclare them.+ if (prop.name == "u_time" || prop.name == "u_viewport" || prop.name == "u_projection") {+ result.errorMessage = "#pragma param '" + prop.name ++ "' is reserved (engine-injected uniform)";+ return result;+ }+ result.properties.push_back(prop);+ }continue;}@@ -429,10 +437,11 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p++headerLines;}- // Engine-owned frame clock, injected into every stage (identical in both, so the- // program links). u_esTime = (elapsed s, delta s, 0, 0); binding 3 (Shader::compile).+ // Engine-owned frame block, injected into every stage (identical in both, so the+ // program links). u_time = (elapsed s, delta s, 0, 0); u_viewport = canvas+ // (w, h, 1/w, 1/h) in pixels; binding 3 (Shader::compile).static const char* kTimeHeader =- "layout(std140) uniform TimeConstants { highp vec4 u_esTime; };\n";+ "layout(std140) uniform TimeConstants { highp vec4 u_time; highp vec4 u_viewport; };\n";assembled << kTimeHeader;headerLines += countNewlines(kTimeHeader);@@ -461,7 +470,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p}}- // Lit2D domain: inject the shared LightConstants block (std140) + the es_applyLighting2D()+ // Lit2D domain: inject the shared LightConstants block (std140) + the applyLighting2D()// helper into the fragment stage. Authors write the surface (albedo) and a world-position// varying, then call the helper — the engine owns the std140 layout so a hand-written struct// can't silently mismatch renderer/LightConstants.hpp and corrupt lighting. Members + locals@@ -471,23 +480,23 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// GpuLight2D = four vec4s).if (stage == ShaderStage::Fragment && parsed.domain == "Lit2D") {static const char* kLit2DHeader =- "struct es_Light2D { highp vec4 posDir; highp vec4 color; highp vec4 spot; highp vec4 shadow; };\n"+ "struct Light2D { highp vec4 posDir; highp vec4 color; highp vec4 spot; highp vec4 shadow; };\n""layout(std140) uniform LightConstants {\n"" highp vec4 u_ambient;\n"- " es_Light2D u_lights[16];\n"+ " Light2D u_lights[16];\n"" highp vec4 u_occluderCount;\n" // x = active occluder count" highp vec4 u_occluders[8];\n" // world AABBs (minX,minY,maxX,maxY)"};\n"// Engine-owned normal-map convention (RGB[0,1] -> normal[-1,1], normalized), so every// Lit2D shader unpacks tangent-space normals the same way. 2D applies it screen-space// (no per-sprite tangent frame); a flat surface uses vec3(0,0,1).- "highp vec3 es_sampleNormal(in highp sampler2D map, in highp vec2 uv) {\n"+ "highp vec3 sampleNormal(in highp sampler2D map, in highp vec2 uv) {\n"" return normalize(texture(map, uv).xyz * 2.0 - 1.0);\n""}\n"// 2D hard shadows: a slab test of the fragment->light segment against a world AABB.// Returns 1.0 when the segment crosses the box's interior, else 0.0. The [0,1] param// clamp means boxes behind the fragment or beyond the light don't occlude.- "highp float es_segHitsBox(in highp vec2 p0, in highp vec2 p1, in highp vec4 box) {\n"+ "highp float segHitsBox(in highp vec2 p0, in highp vec2 p1, in highp vec4 box) {\n"" highp vec2 d = p1 - p0;\n"" highp float tmin = 0.0;\n"" highp float tmax = 1.0;\n"@@ -515,13 +524,13 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// `target` is the point the rays aim at — the light position for point/spot, or a far// point along the light direction for directional — so one primitive shadows every type.// No occluders (count 0) -> always 1.0, inert until the render path feeds boxes.- "highp float es_shadowFactor2D(in highp vec2 worldPos, in highp vec2 target, in highp float softness) {\n"+ "highp float shadowFactor2D(in highp vec2 worldPos, in highp vec2 target, in highp float softness) {\n"" int n = int(u_occluderCount.x);\n"" if (n <= 0) return 1.0;\n"" if (softness < 1e-4) {\n"" for (int i = 0; i < 8; ++i) {\n"" if (i >= n) break;\n"- " if (es_segHitsBox(worldPos, target, u_occluders[i]) > 0.5) return 0.0;\n"+ " if (segHitsBox(worldPos, target, u_occluders[i]) > 0.5) return 0.0;\n"" }\n"" return 1.0;\n"" }\n"@@ -535,12 +544,12 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p" highp vec2 tp = target + perp * (t * softness);\n"" for (int i = 0; i < 8; ++i) {\n"" if (i >= n) break;\n"- " if (es_segHitsBox(worldPos, tp, u_occluders[i]) > 0.5) { blocked += 1.0; break; }\n"+ " if (segHitsBox(worldPos, tp, u_occluders[i]) > 0.5) { blocked += 1.0; break; }\n"" }\n"" }\n"" return 1.0 - blocked / float(K);\n""}\n"- "highp vec3 es_applyLighting2D(highp vec3 albedo, highp vec3 N, highp vec2 worldPos) {\n"+ "highp vec3 applyLighting2D(highp vec3 albedo, highp vec3 N, highp vec2 worldPos) {\n"" highp vec3 lit = u_ambient.rgb;\n"" for (int i = 0; i < 16; ++i) {\n"" highp vec4 pd = u_lights[i].posDir;\n"@@ -575,7 +584,7 @@ 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 *= es_shadowFactor2D(worldPos, target, sh.x);\n"+ " atten *= shadowFactor2D(worldPos, target, sh.x);\n"" }\n"" highp float ndotl = max(dot(N, L), 0.0);\n"" lit += col.rgb * (col.a * ndotl * atten);\n"diff --git a/tests/renderer/test_shader_variant.cpp b/tests/renderer/test_shader_variant.cppindex 9c95c1f0a..9e9b1bd13 100644--- a/tests/renderer/test_shader_variant.cpp+++ b/tests/renderer/test_shader_variant.cpp@@ -64,7 +64,7 @@ precision mediump float;in vec4 v_color;in highp vec2 v_worldPos;out vec4 fragColor;-void main() { fragColor = vec4(es_applyLighting2D(v_color.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), v_color.a); }+void main() { fragColor = vec4(applyLighting2D(v_color.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), v_color.a); }#pragma end)";@@ -92,7 +92,7 @@ static void testFragmentOnly() {const std::string lv = ShaderParser::assembleStage(lit, ShaderStage::Vertex);CHECK(lv.find("v_worldPos = a_position") != std::string::npos, "Lit2D canonical vertex forwards world position");const std::string lf = ShaderParser::assembleStage(lit, ShaderStage::Fragment);- CHECK(lf.find("es_applyLighting2D") != std::string::npos, "Lit2D fragment gets the lighting helper injected");+ CHECK(lf.find("applyLighting2D") != std::string::npos, "Lit2D fragment gets the lighting helper injected");ParsedShader pp = ShaderParser::parse(FRAG_ONLY_POSTPROCESS);CHECK(!pp.valid, "non-2D domain without a vertex stage still errors");@@ -104,7 +104,15 @@ static void testFragmentOnly() {const std::string af = ShaderParser::assembleStage(authored, ShaderStage::Fragment);CHECK(av.find("uniform TimeConstants") != std::string::npos &&af.find("uniform TimeConstants") != std::string::npos,- "u_esTime clock block injected into both stages");+ "u_time clock block injected into both stages");+ CHECK(af.find("vec4 u_viewport") != std::string::npos, "u_viewport rides the injected block");++ ParsedShader reserved = ShaderParser::parse(+ "#pragma shader \"R\"\n#pragma version 300 es\n#pragma domain Unlit2D\n"+ "#pragma param u_time float default(0)\n"+ "#pragma fragment\nvoid main() {}\n#pragma end\n");+ CHECK(!reserved.valid && reserved.errorMessage.find("reserved") != std::string::npos,+ "a param named after an injected uniform is rejected with a clear error");}int main() {