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): the cook derives every shader's WGSL twin where the host ships the converters

yhhe36253a9df1e
diff --git a/desktop b/desktop
index f72c18dd8..0f49482e5 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit f72c18dd8a278f7cfe1b7f50698f244333ee71a4
+Subproject commit 0f49482e5e7b4e0d9d733058070ee4cd68153c2b
diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdx
index 8edccb0cf..6184e5137 100644
--- a/docs/astro/src/content/docs/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/graphics/materials.mdx
@@ -178,6 +178,14 @@ One file holds every stage plus its metadata, separated by pragmas:
| `#pragma vertex` / `#pragma fragment` … `#pragma end` | Stage bodies. **The vertex block is optional for 2D domains** — the engine injects the canonical stage. |
| `#include "path"` | Textual include (resolved by the host). |
+**Write the GLSL; the WGSL is derived.** The editor's viewport draws through WebGPU,
+and a web build may too, so every shader also needs a WGSL version. You do not write
+it: the editor derives it from your GLSL as the shader is read, and every export
+derives it as the shader is packaged (a generated twin that no longer matches the
+GLSL is derived again). A shader with its own hand-written `#pragma fragment wgsl`
+block keeps it untouched. If a GLSL construct cannot be translated, the build warns
+and that shader runs on the WebGL2 path only.
+
### Fragment-only authoring
2D sprites bake their world transform into the batch vertices, so every 2D shader
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
index 4f4597cce..a603936cc 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
@@ -147,6 +147,11 @@ Terrain、Foliage、Water、Hair、Skin、Eye 这几个模板属于各自的模
| `#pragma vertex` / `#pragma fragment` … `#pragma end` | Stage 代码体。**2D 域的顶点段可省略**——引擎注入规范顶点段。 |
| `#include "path"` | 文本 include(由宿主解析)。 |
+**只写 GLSL,WGSL 自动生成。** 编辑器视口走 WebGPU,网页构建也可能用到,所以每个 shader 都需要一份
+WGSL。不用自己写:编辑器读取 shader 时会从 GLSL 自动派生,每次导出打包时也会派生(已有的生成版本与 GLSL
+不一致时会重新生成)。自己手写了 `#pragma fragment wgsl` 块的 shader 保持原样。若某段 GLSL 无法转换,
+构建会给出警告,该 shader 只在 WebGL2 下运行。
+
### 只写片元
2D 精灵的世界变换烘焙进批处理顶点,所以所有 2D 着色器共享同一个顶点段。省略
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index 9d38131a5..c8943678d 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -22,6 +22,7 @@ import { writeFile, mkdir, readFile, open } from 'node:fs/promises';
import { statSync } from 'node:fs';
import { isInsideRoot } from '../fs/pathSandbox';
import path from 'node:path';
+import { pathToFileURL } from 'node:url';
import { scanAssetDatabase, type AssetEntry } from './assetDb';
import { packAtlas, decodePngImage, encodePagePng, type AtlasInputImage } from './atlasPacker';
// Per-asset texture cook settings (compress opt-out / format / size cap), read
@@ -468,7 +469,12 @@ let twinDeriver: Promise<((source: string) => Promise<string>) | null> | undefin
function shaderTwinDeriver(): Promise<((source: string) => Promise<string>) | null> {
twinDeriver ??= (async () => {
try {
- const specifier = '../../../tools/lib/derivedTwin.mjs';
+ // A host that ships the converters (the packaged editor) says where they are;
+ // a checkout of the engine finds them beside this file.
+ const root = process.env.ESTELLA_SHADER_TWINS_ROOT;
+ const specifier = root
+ ? pathToFileURL(path.join(root, 'tools', 'lib', 'derivedTwin.mjs')).href
+ : '../../../tools/lib/derivedTwin.mjs';
return ((await import(/* @vite-ignore */ specifier)) as { withDerivedTwin: (source: string) => Promise<string> }).withDerivedTwin;
} catch {
return null;
@@ -933,16 +939,17 @@ export async function cookAssets(
// sources carry none, so one is derived here from the GLSL when the converters
// are at hand (a checkout of the engine); a project that ships its own twin has it
// already, and one with neither is worth a cook-time warning.
- if (ext.toLowerCase() === '.esshader' &&
- !Buffer.from(data).toString('utf8').includes('#pragma fragment wgsl')) {
+ // Asked of every shader: a generated twin that no longer matches its GLSL is
+ // derived afresh, and a hand-written one is left exactly as it is.
+ if (ext.toLowerCase() === '.esshader') {
const derive = await shaderTwinDeriver();
if (derive) data = Buffer.from(await derive(Buffer.from(data).toString('utf8')), 'utf8');
}
if (ext.toLowerCase() === '.esshader' &&
!Buffer.from(data).toString('utf8').includes('#pragma fragment wgsl')) {
warnings.push(
- `${entry.path}: no WGSL twin — this shader will not render on the WebGPU backend ` +
- '(run tools/gen-shader-twins.mjs to generate one)',
+ `${entry.path}: no WGSL twin, and it could not be derived from the GLSL here — this shader will not ` +
+ 'render on the WebGPU backend (export from the editor, which derives it, or add a `#pragma fragment wgsl` twin)',
);
}
const hash = contentHashHex(data);