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(shaders): retire the last GLSL ES 1.00 sources — WGSL campaign phase 0 + design doc

yhhd01992f463be
diff --git a/sdk/src/filters.ts b/sdk/src/filters.ts
index 6a72c8d29..3a97b2a91 100644
--- a/sdk/src/filters.ts
+++ b/sdk/src/filters.ts
@@ -2,31 +2,37 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { Material, type ShaderHandle } from './material';
-const COLOR_MATRIX_VERT = `
-attribute vec2 a_position;
-attribute vec2 a_texCoord;
-attribute vec4 a_color;
-uniform mat4 u_projection;
-varying vec2 v_texCoord;
-varying vec4 v_color;
-void main() {
- gl_Position = u_projection * vec4(a_position, 0.0, 1.0);
- v_texCoord = a_texCoord;
- v_color = a_color;
-}
-`;
+// Fragment-only .esshader on the reflected #pragma param seam. The 5x4 color
+// matrix ships as four row vec4s + an offset vec4 (MaterialConstants params are
+// at most vec4 — a mat4 uniform could never cross setMaterialUniform, so the old
+// raw-GLSL form of this filter was unusable by construction).
+const COLOR_MATRIX_ESSHADER = `#pragma shader "ColorMatrixFilter"
+#pragma version 300 es
+#pragma domain Unlit2D
+#pragma param u_cmRow0 vec4 default(1,0,0,0)
+#pragma param u_cmRow1 vec4 default(0,1,0,0)
+#pragma param u_cmRow2 vec4 default(0,0,1,0)
+#pragma param u_cmRow3 vec4 default(0,0,0,1)
+#pragma param u_colorOffset vec4 default(0,0,0,0)
-const COLOR_MATRIX_FRAG = `
+#pragma fragment
precision mediump float;
-uniform sampler2D u_texture;
-uniform mat4 u_colorMatrix;
-uniform vec4 u_colorOffset;
-varying vec2 v_texCoord;
-varying vec4 v_color;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+
+uniform sampler2D u_textures[8];
+
+out vec4 fragColor;
+
void main() {
- vec4 texColor = texture2D(u_texture, v_texCoord) * v_color;
- vec4 result = u_colorMatrix * texColor + u_colorOffset;
- gl_FragColor = clamp(result, 0.0, 1.0);
+ vec4 texColor = texture(u_textures[0], v_texCoord) * v_color;
+ vec4 result = vec4(
+ dot(u_cmRow0, texColor),
+ dot(u_cmRow1, texColor),
+ dot(u_cmRow2, texColor),
+ dot(u_cmRow3, texColor)) + u_colorOffset;
+ fragColor = clamp(result, 0.0, 1.0);
}
`;
@@ -34,7 +40,7 @@ let colorMatrixShader_: ShaderHandle | null = null;
function getColorMatrixShader(): ShaderHandle {
if (colorMatrixShader_ === null || colorMatrixShader_ === 0) {
- colorMatrixShader_ = Material.createShader(COLOR_MATRIX_VERT, COLOR_MATRIX_FRAG);
+ colorMatrixShader_ = Material.compileShader(COLOR_MATRIX_ESSHADER);
}
return colorMatrixShader_!;
}
@@ -110,4 +116,19 @@ export const Filters = {
},
getColorMatrixShader,
+
+ /**
+ * Maps a 20-element (5x4 row-major) color matrix onto the shader's params:
+ * four row vec4s plus the offset column. Apply with Material.setUniform.
+ */
+ colorMatrixUniforms(matrix: number[]): Record<string, number[]> {
+ const row = (i: number) => [matrix[i * 5], matrix[i * 5 + 1], matrix[i * 5 + 2], matrix[i * 5 + 3]];
+ return {
+ u_cmRow0: row(0),
+ u_cmRow1: row(1),
+ u_cmRow2: row(2),
+ u_cmRow3: row(3),
+ u_colorOffset: [matrix[4], matrix[9], matrix[14], matrix[19]],
+ };
+ },
};
diff --git a/sdk/src/spriteFilter.ts b/sdk/src/spriteFilter.ts
index 54f8db01c..1d42dc2e6 100644
--- a/sdk/src/spriteFilter.ts
+++ b/sdk/src/spriteFilter.ts
@@ -11,41 +11,40 @@ import { Material, type MaterialHandle, type ShaderHandle } from './material';
// Outline/Glow Shader (single-pass, samples 8 neighbors)
// =============================================================================
-const OUTLINE_VERT = `
-attribute vec2 a_position;
-attribute vec2 a_texCoord;
-attribute vec4 a_color;
-uniform mat4 u_projection;
-varying vec2 v_texCoord;
-varying vec4 v_color;
-void main() {
- gl_Position = u_projection * vec4(a_position, 0.0, 1.0);
- v_texCoord = a_texCoord;
- v_color = a_color;
-}
-`;
-
-const OUTLINE_FRAG = `
+// Authored as fragment-only .esshader (the canonical 2D vertex stage is injected,
+// so attribute locations, u_projection, and the batch samplers all follow the
+// engine conventions) with #pragma param reflection — the same modern seam as the
+// builtin templates. The old raw GLSL ES 1.00 pair had no u_projection source and
+// no attribute bindings, and its loose uniforms bypassed the material system.
+const OUTLINE_ESSHADER = `#pragma shader "SpriteOutlineFilter"
+#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 param u_texelSize vec2 default(0.001953125,0.001953125)
+
+#pragma fragment
precision mediump float;
-uniform sampler2D u_texture;
-uniform vec2 u_texelSize;
-uniform vec4 u_outlineColor;
-uniform float u_outlineWidth;
-varying vec2 v_texCoord;
-varying vec4 v_color;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+
+uniform sampler2D u_textures[8];
+
+out vec4 fragColor;
+
void main() {
- vec4 texColor = texture2D(u_texture, v_texCoord) * v_color;
+ vec4 texColor = texture(u_textures[0], v_texCoord) * v_color;
float maxAlpha = 0.0;
for (float x = -1.0; x <= 1.0; x += 1.0) {
for (float y = -1.0; y <= 1.0; y += 1.0) {
if (x == 0.0 && y == 0.0) continue;
vec2 offset = vec2(x, y) * u_texelSize * u_outlineWidth;
- float a = texture2D(u_texture, v_texCoord + offset).a;
- maxAlpha = max(maxAlpha, a);
+ maxAlpha = max(maxAlpha, texture(u_textures[0], v_texCoord + offset).a);
}
}
vec4 outline = u_outlineColor * maxAlpha * (1.0 - texColor.a);
- gl_FragColor = texColor + outline;
+ fragColor = texColor + outline;
}
`;
@@ -53,15 +52,24 @@ void main() {
// Drop Shadow Shader (single-pass offset + blur)
// =============================================================================
-const SHADOW_FRAG = `
+const SHADOW_ESSHADER = `#pragma shader "SpriteShadowFilter"
+#pragma version 300 es
+#pragma domain Unlit2D
+#pragma param u_shadowColor color default(0,0,0,0.6)
+#pragma param u_shadowOffset vec2 default(3,3)
+#pragma param u_shadowBlur float default(2)
+#pragma param u_texelSize vec2 default(0.001953125,0.001953125)
+
+#pragma fragment
precision mediump float;
-uniform sampler2D u_texture;
-uniform vec2 u_texelSize;
-uniform vec2 u_shadowOffset;
-uniform vec4 u_shadowColor;
-uniform float u_shadowBlur;
-varying vec2 v_texCoord;
-varying vec4 v_color;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+
+uniform sampler2D u_textures[8];
+
+out vec4 fragColor;
+
void main() {
vec2 shadowUV = v_texCoord - u_shadowOffset * u_texelSize;
float shadowAlpha = 0.0;
@@ -70,14 +78,14 @@ void main() {
for (float x = -2.0; x <= 2.0; x += 1.0) {
for (float y = -2.0; y <= 2.0; y += 1.0) {
vec2 offset = vec2(x, y) * u_texelSize * radius;
- shadowAlpha += texture2D(u_texture, shadowUV + offset).a;
+ shadowAlpha += texture(u_textures[0], shadowUV + offset).a;
total += 1.0;
}
}
shadowAlpha /= total;
vec4 shadow = u_shadowColor * shadowAlpha;
- vec4 texColor = texture2D(u_texture, v_texCoord) * v_color;
- gl_FragColor = texColor + shadow * (1.0 - texColor.a);
+ vec4 texColor = texture(u_textures[0], v_texCoord) * v_color;
+ fragColor = texColor + shadow * (1.0 - texColor.a);
}
`;
@@ -90,14 +98,14 @@ let shadowShader_: ShaderHandle = 0;
function getOutlineShader(): ShaderHandle {
if (outlineShader_ === 0) {
- outlineShader_ = Material.createShader(OUTLINE_VERT, OUTLINE_FRAG);
+ outlineShader_ = Material.compileShader(OUTLINE_ESSHADER);
}
return outlineShader_;
}
function getShadowShader(): ShaderHandle {
if (shadowShader_ === 0) {
- shadowShader_ = Material.createShader(OUTLINE_VERT, SHADOW_FRAG);
+ shadowShader_ = Material.compileShader(SHADOW_ESSHADER);
}
return shadowShader_;
}
diff --git a/sdk/tests/filters.test.ts b/sdk/tests/filters.test.ts
index 322a98ab5..48a15fc0d 100644
--- a/sdk/tests/filters.test.ts
+++ b/sdk/tests/filters.test.ts
@@ -5,7 +5,7 @@ import { Filters } from '../src/filters';
vi.mock('../src/material', () => ({
Material: {
- createShader: vi.fn(() => 42),
+ compileShader: vi.fn(() => 42),
},
}));
diff --git a/sdk/tests/sprite-filter.test.ts b/sdk/tests/sprite-filter.test.ts
index a952667b7..0ee2ded08 100644
--- a/sdk/tests/sprite-filter.test.ts
+++ b/sdk/tests/sprite-filter.test.ts
@@ -19,7 +19,7 @@ let nextMaterialId = 1000;
vi.mock('../src/material', () => {
return {
Material: {
- createShader: vi.fn(() => {
+ compileShader: vi.fn(() => {
materialCalls.push({ kind: 'createShader' });
return nextShaderId++;
}),