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(shaders): the cook derives every shader's WGSL twin where the host ships the converters
yhhe36253a9df1e
diff --git a/desktop b/desktopindex f72c18dd8..0f49482e5 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit f72c18dd8a278f7cfe1b7f50698f244333ee71a4+Subproject commit 0f49482e5e7b4e0d9d733058070ee4cd68153c2bdiff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdxindex 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 authoring2D sprites bake their world transform into the batch vertices, so every 2D shaderdiff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdxindex 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.tsindex 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> | undefinfunction 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);