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(tools): naga vendored as a WASI wasm - twin generation drops the Rust toolchain

yhhcecbc483f484
diff --git a/.gitignore b/.gitignore
index 7bb913310..48cca0312 100644
--- a/.gitignore
+++ b/.gitignore
@@ -63,6 +63,10 @@ desktop/.cooked-src/
# Exception: the vendored build-time Basis KTX2 encoder (RC6 B4) is committed so
# asset cooking needs no emsdk. See build-tools/basis/README.md for provenance.
!build-tools/basis/basis_encoder.wasm
+# Exception: the vendored SPIR-V→WGSL converter (naga, WASI build) is committed so
+# shader-twin generation needs no Rust toolchain. Source: tools/naga-spv2wgsl;
+# provenance: build-tools/shader-twins/README.md.
+!build-tools/shader-twins/naga-spv2wgsl.wasm
# emsdk discovery cache (per-machine path written by build-tools auto-discovery)
.emsdk-path
diff --git a/build-tools/shader-twins/README.md b/build-tools/shader-twins/README.md
new file mode 100644
index 000000000..cc94f3364
--- /dev/null
+++ b/build-tools/shader-twins/README.md
@@ -0,0 +1,34 @@
+# shader-twins converters (vendored)
+
+Build-time converters for `tools/gen-shader-twins.mjs` — the WGSL-twin
+generation pipeline (REARCH_WGSL Phase 4): assembled GLSL → SPIR-V → WGSL,
+appended to a `.esshader` as self-contained `#pragma … wgsl full` sections.
+
+## naga-spv2wgsl.wasm (committed)
+
+SPIR-V → WGSL. A tiny stdin→stdout WASI executable wrapping
+[naga](https://github.com/gfx-rs/wgpu/tree/trunk/naga) 30 (`spv-in` +
+`wgsl-out`, naga-cli default options), run in-process under `node:wasi` by
+`naga.mjs`. Committed so twin generation needs **no Rust toolchain** — the
+same pattern as `build-tools/basis/` (the cook's KTX2 encoder).
+
+Source: `tools/naga-spv2wgsl/` (30-line wrapper crate, `Cargo.lock` pinned).
+Rebuild:
+
+```
+rustup target add wasm32-wasip1
+cd tools/naga-spv2wgsl
+cargo build --release --target wasm32-wasip1
+cp target/wasm32-wasip1/release/naga-spv2wgsl.wasm ../../build-tools/shader-twins/
+```
+
+Output is byte-identical to `naga-cli` 30 for the pipeline's inputs (verified
+against the fixture shaders when vendored).
+
+## GLSL → SPIR-V (still an external tool)
+
+`glslangValidator` (Vulkan semantics, `-V --auto-map-locations`) must be on
+PATH — it ships with the Vulkan SDK, Khronos also publishes standalone release
+binaries. Vendoring it as a wasm build (Khronos glslang has an official
+emscripten/JS target) needs the glslang source tree in-repo; that dependency
+addition is a project decision, tracked in docs/REARCHITECTURE.md.
diff --git a/build-tools/shader-twins/naga-spv2wgsl.wasm b/build-tools/shader-twins/naga-spv2wgsl.wasm
new file mode 100644
index 000000000..0e38c45ab
Binary files /dev/null and b/build-tools/shader-twins/naga-spv2wgsl.wasm differ
diff --git a/build-tools/shader-twins/naga.mjs b/build-tools/shader-twins/naga.mjs
new file mode 100644
index 000000000..3d7b356a5
--- /dev/null
+++ b/build-tools/shader-twins/naga.mjs
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * SPIR-V → WGSL via the vendored naga WASI build (naga-spv2wgsl.wasm) — the
+ * converter half of the shader-twin pipeline that needs no Rust toolchain.
+ * The wasm is stdin → stdout; node:wasi wires those to file descriptors, so a
+ * conversion is a fully in-process, deterministic function of the input bytes.
+ * See README.md for provenance and how to rebuild the artifact.
+ */
+import { closeSync, openSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const WASM_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), 'naga-spv2wgsl.wasm');
+
+let modulePromise = null;
+function compiledModule() {
+ modulePromise ??= WebAssembly.compile(readFileSync(WASM_PATH));
+ return modulePromise;
+}
+
+/**
+ * Convert a SPIR-V file to WGSL text. Throws (with naga's stderr already
+ * printed) when parsing/validation/writing fails.
+ * @param {string} spvPath input SPIR-V file
+ * @param {string} wgslPath output WGSL file (created/truncated)
+ */
+export async function spvFileToWgsl(spvPath, wgslPath) {
+ const { WASI } = await import('node:wasi');
+ const wasm = await compiledModule();
+ const inFd = openSync(spvPath, 'r');
+ const outFd = openSync(wgslPath, 'w');
+ try {
+ // A WASI instance is single-shot (wasi.start runs main once); the compiled
+ // module is shared, instantiation per call is cheap.
+ const wasi = new WASI({ version: 'preview1', stdin: inFd, stdout: outFd, stderr: 2 });
+ const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject());
+ const code = wasi.start(instance);
+ if (code !== 0) {
+ throw new Error(`naga-spv2wgsl exited with ${code} (see stderr above)`);
+ }
+ } finally {
+ closeSync(inFd);
+ closeSync(outFd);
+ }
+}
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index 65fbe8a7b..54463bd4b 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -194,7 +194,8 @@ TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:
**cook 集成第一层(2026-07-08)——资产依赖图现代化**:assetDb 依赖图从"仅 scene/prefab 的 @uuid:"扩展为**任意 JSON 资产 × 三种引用形态**——`@uuid:`、裸 uuid(anim 帧的 extractUuid 形态,仅命中索引才建边,防实体 id 误伤)、**路径引用**(项目路径 + 相对本文档目录,只有真实资产命中才建边零误报);扫描类型 scene/prefab/material/tileset/animclip/statemachine/behaviortree。真实项目(路径引用内容)的材质→shader→纹理链自此进入 cook 闭包(此前 deps 全空,整链被静默剔除)。cook manifest 新增 `sourcePath`(逻辑身份,内容寻址改名后路径引用的运行时映射依据);`.esshader` 无 WGSL 孪生 → cook 告警(生成是开发期步骤,保 cook 确定性 + 零转换器依赖)。
**cook 集成第二层(2026-07-08)——CA 构建运行时路径解析闭环**:三件套——① cook 期把材质的**相对引用重写为逻辑项目路径**(内容寻址摧毁了相对解析依赖的目录结构;非 assets/-根的逻辑路径写成 `/<logical>`,双拼写皆注册;@uuid:/URL/非资产字符串原样通过),顺带根治"@uuid: 引用的材质在 CA 构建下内部相对引用同样破损"的存量缺口——loader 零改动;② `resolvePlayAssetRef` 增 pathMap 参数(逻辑→staged,**先于扩展名嗅探**,.png→.ktx2 换名对 KTX2 检测可见,与 uuid 分支同契约);③ 生产首次喂 `Catalog` buildPath(`AssetsOptions.catalog` 一直存在但空转——loader 内部文本 fetch 如材质取 shader 走 `getBuildPath`),经 `RuntimeInitConfig.catalog`/`PlayRealmRuntimeConfig.catalogData` 管道在 per-App Assets 首次创建时注入,gameHost 从 manifest sourcePath 构建两张映射。验证:cooked e2e 升级为双象限——绿 KTX2 精灵(uuid 引用)+ **红材质精灵(全路径引用链:场景→材质项目路径→shader/纹理相对引用)**,发行运行时逐像素 PASS([0,181,0]/[255,0,0])。
**音频并入单一解析通道(2026-07-08)**:Audio 的自有 fetch 曾绕过 resolveRef(`baseUrl` 前缀并行逻辑,CA 构建下 `playSFX('assets/…')` 404)——新增 `Audio.setRefResolver`,play realm 统一接 `resolvePlayAssetRef`(编辑器 realm 输出与旧 baseUrl 前缀逐字符一致零行为变化;cooked 构建命中 logical→staged 映射;uuid 音频引用顺带可用)。`baseUrl` 保留为未接线宿主的 legacy 前缀。
-**剩余**:转换器 vendored wasm 交付(glslang wasm + naga wasm32-wasi,仿 build-tools/basis);wechat/playable 导出线采用 CA 时复用同一 sourcePath 机制;CI 无 WebGPU 适配器(webgpu verify 仅本地)。
+**naga vendored(2026-07-08)**:SPIR-V→WGSL 侧零外部依赖——`tools/naga-spv2wgsl`(30 行 stdin→stdout WASI 封装 crate,Cargo.lock 钉版)编 wasm32-wasip1 产物入库 `build-tools/shader-twins/naga-spv2wgsl.wasm`(674KB,basis 先例同款 gitignore 白名单),`naga.mjs` 经 node:wasi 进程内运行;gen-shader-twins 改走 vendored 路径,**全部 fixture 重生成零 diff**(与 naga-cli 30 逐字节一致)。
+**剩余**:glslang 侧 vendoring **待用户拍板**——加 KhronosGroup/glslang submodule 被权限门拒(引入外部代码源需明示同意);官方 emscripten/JS 目标(ENABLE_GLSLANG_JS)可产 wasm,或改用 Khronos release 二进制下载方案;当前 glslangValidator 仍需 PATH 提供(Vulkan SDK 附带)。wechat/playable 导出线采用 CA 时复用 sourcePath 机制;CI 无 WebGPU 适配器(webgpu verify 仅本地)。
见 `REARCH_WGSL.md`(本地 gitignore,同 RC6/2D_PARITY 约定):着色器版图盘点(uniform 数据已全后端中立,剩程序文本)、岔路拍板(有限集人工孪生 / 图材质 AST 双发射 / 用户材质 cook 期转换——拒绝运行时翻译器的 MB 级体积代价)、四期计划(源语言接缝 → WebGPUDevice 原型 → 双语发射 → cook 期用户材质)。**Phase 0 已落地**:最后 3 个 GLSL ES 1.00 残留(SDK outline/drop-shadow/color-matrix 滤镜)重写为 fragment-only `.esshader` 反射路径——顺带修复其设计性破损(raw 形态无 `u_projection` 来源、无属性绑定、mat4 超 `setMaterialUniform` 的 vec4 上限**从未能传入**;色彩矩阵改为 4×vec4 行 + 偏移列,新增 `Filters.colorMatrixUniforms` 助手)。全仓每个程序自此都在现代缝上(300 es + UBO 反射)。
**Phase 1(源语言接缝)已落地**:RHI 补上最后一块后端中立拼图——`createProgram` 收语言标签的 `GfxShaderSource`,新增 `supportsShaderLanguage` 能力查询(GL = 仅 GLSL ES 300;`Shader::compile` 在任何 GPU 调用前对不支持的语言快速失败);语言贯穿 Shader/ResourceManager(DrawParams 重写仅对 GLSL 生效);`ShaderParser::assembleStage` 获得 `ShaderTargetLanguage` 参数(WGSL 发射 = Phase 3)。MockGfxDevice 新增 `wgslSupported` 开关 + 语言门用例;行为零变化(8 harness + 场景抽样等价)。
**Phase 2 切片 1(WebGPU 后端启动)已落地**:emdawnwebgpu 端口(Dawn)集成为测试目标独立依赖(主构建零影响);`renderer/webgpu/` 新增纯映射层(GfxEnums→WGPU 全翻译,blend/模板表镜像 GLDevice 语义,load-op 规则与 RenderPassDesc 契约一致)+ 空设备安全的 `WebGPUDevice` 骨架(缓冲/纹理/WGSL 模块真实现,布局/管线描述符保留待惰性构建,pass/draw 为切片 2 结构化桩);`test_webgpu_device` 用真 Dawn 头编译验证全部描述符拼写,入 CI。
diff --git a/tools/gen-shader-twins.mjs b/tools/gen-shader-twins.mjs
index 8e9d5d274..9c03e554a 100644
--- a/tools/gen-shader-twins.mjs
+++ b/tools/gen-shader-twins.mjs
@@ -15,7 +15,8 @@
* group-1 unit map, explicit varying
* locations
* glslangValidator -V — GLSL ES 310 → SPIR-V (Vulkan semantics)
- * naga — SPIR-V → WGSL
+ * naga (vendored WASI wasm) — SPIR-V → WGSL, in-process — no Rust
+ * toolchain needed (build-tools/shader-twins)
* post (this file) — entry rename to vs_main/fs_main
*
* The emitted twins are FULL programs: ShaderParser skips its injected headers
@@ -29,9 +30,10 @@
* --check report what would change, write nothing (exit 1 if any)
* --force regenerate even when a twin exists (replaces generated sections)
*
- * Requires: a built engine (pnpm build:web), glslangValidator and naga on PATH.
- * Shaders using `#pragma switch` are skipped (permutations need per-set twins;
- * hand-author those) — the tool says so per file.
+ * Requires: a built engine (pnpm build:web) and glslangValidator on PATH (ships
+ * with the Vulkan SDK / Khronos release binaries; a vendored wasm build is a
+ * tracked follow-up). Shaders using `#pragma switch` are skipped (permutations
+ * need per-set twins; hand-author those) — the tool says so per file.
*/
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
@@ -39,6 +41,7 @@ import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spvFileToWgsl } from '../build-tools/shader-twins/naga.mjs';
const execFileP = promisify(execFile);
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -251,7 +254,7 @@ function assignVaryingLocations(vert, frag) {
return { vert: vertOut, frag: fragOut };
}
-/** GLSL (adapted) → WGSL via glslangValidator -V + naga, renaming the entry point. */
+/** GLSL (adapted) → WGSL via glslangValidator -V + vendored naga, renaming the entry. */
async function glslToWgsl(glsl, stage, entryName, workDir) {
const src = path.join(workDir, `stage.${stage}`);
const spv = path.join(workDir, `stage.${stage}.spv`);
@@ -260,13 +263,12 @@ async function glslToWgsl(glsl, stage, entryName, workDir) {
try {
await execFileP('glslangValidator', ['-V', '--auto-map-locations', '-o', spv, src]);
} catch (e) {
- throw new Error(`glslang failed for ${stage} stage:\n${e.stdout ?? ''}${e.stderr ?? ''}`);
- }
- try {
- await execFileP('naga', [spv, wgsl]);
- } catch (e) {
- throw new Error(`naga failed for ${stage} stage:\n${e.stdout ?? ''}${e.stderr ?? ''}`);
+ const hint = e.code === 'ENOENT'
+ ? 'glslangValidator not found on PATH (it ships with the Vulkan SDK / Khronos release binaries)'
+ : `${e.stdout ?? ''}${e.stderr ?? ''}`;
+ throw new Error(`glslang failed for ${stage} stage:\n${hint}`);
}
+ await spvFileToWgsl(spv, wgsl);
const text = await readFile(wgsl, 'utf8');
// naga emits `fn main(` as the entry (the inner body lands in main_1) - the
// engine's twin contract names entries vs_main/fs_main.
diff --git a/tools/naga-spv2wgsl/Cargo.lock b/tools/naga-spv2wgsl/Cargo.lock
new file mode 100644
index 000000000..c3b319fa7
--- /dev/null
+++ b/tools/naga-spv2wgsl/Cargo.lock
@@ -0,0 +1,307 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "bit-set"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2f926cc3060f09db9ebc5b52823d85268d24bb917e472c0c4bea35780a7d"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b71798fca2c1fe1086445a7258a4bc81e6e49dcd24c8d0dd9a1e57395b603f51"
+
+[[package]]
+name = "bitflags"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+
+[[package]]
+name = "codespan-reporting"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af491d569909a7e4dee0ad7db7f5341fef5c614d5b8ec8cf765732aba3cff681"
+dependencies = [
+ "unicode-width",
+]
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "fixedbitset"
+version = "0.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d674e81391d1e1ab681a28d99df07927c6d4aa5b027d7da16ba32d1d21ecd99"
+
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
+[[package]]
+name = "foldhash"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "num-traits",
+ "zerocopy",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash 0.1.5",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+dependencies = [
+ "foldhash 0.2.0",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+]
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "naga"
+version = "30.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23bf0a141a9ab6f07dbb492db53245e464bc9db42f407772d9ae03d83a2c1033"
+dependencies = [
+ "arrayvec",
+ "bit-set",
+ "bitflags",
+ "cfg-if",
+ "cfg_aliases",
+ "codespan-reporting",
+ "half",
+ "hashbrown 0.17.1",
+ "indexmap",
+ "libm",
+ "log",
+ "naga-types",
+ "num-traits",
+ "once_cell",
+ "petgraph",
+ "rustc-hash",
+ "spirv",
+ "thiserror",
+]
+
+[[package]]
+name = "naga-spv2wgsl"
+version = "0.1.0"
+dependencies = [
+ "naga",
+]
+
+[[package]]
+name = "naga-types"
+version = "30.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "658200ddc25c6c7b860747516d132d1b284c0fafb7a380233acee9a72fb30e11"
+dependencies = [
+ "hashbrown 0.17.1",
+ "indexmap",
+ "rustc-hash",
+ "thiserror",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+ "libm",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "petgraph"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8701b58ea97060d5e5b155d383a69952a60943f0e6dfe30b04c287beb0b27455"
+dependencies = [
+ "fixedbitset",
+ "hashbrown 0.15.5",
+ "indexmap",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
+
+[[package]]
+name = "spirv"
+version = "0.4.0+sdk-1.4.341.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9571ea910ebd84c86af4b3ed27f9dbdc6ad06f17c5f96146b2b671e2976744f"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75726053136156d419e285b9b7eddaaea9e3fea6ce32eed44a89901f0bd98de1"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4714fd92cf900833d49538023a9b3915155210801d1c1169eba513b2addefd71"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
diff --git a/tools/naga-spv2wgsl/Cargo.toml b/tools/naga-spv2wgsl/Cargo.toml
new file mode 100644
index 000000000..93596e431
--- /dev/null
+++ b/tools/naga-spv2wgsl/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "naga-spv2wgsl"
+version = "0.1.0"
+edition = "2021"
+publish = false
+description = "SPIR-V -> WGSL converter (naga) as a WASI executable for the shader-twin cook tooling. stdin: SPIR-V bytes; stdout: WGSL text."
+
+[dependencies]
+naga = { version = "30", features = ["spv-in", "wgsl-out"] }
+
+[profile.release]
+opt-level = "z"
+lto = true
+strip = true
+codegen-units = 1
diff --git a/tools/naga-spv2wgsl/src/main.rs b/tools/naga-spv2wgsl/src/main.rs
new file mode 100644
index 000000000..58e2438bb
--- /dev/null
+++ b/tools/naga-spv2wgsl/src/main.rs
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//! SPIR-V → WGSL for the shader-twin cook tooling (tools/gen-shader-twins.mjs).
+//!
+//! A deliberately tiny wrapper over naga's spv-in / wgsl-out so the whole
+//! program is stdin → stdout: no filesystem, no arguments — the shape that
+//! makes the wasm32-wasip1 build trivially runnable under node:wasi on any
+//! machine, with no cargo/naga-cli install. Options mirror naga-cli defaults
+//! (coordinate-space adjustment on, full validation).
+//!
+//! Build (artifact is committed, see build-tools/shader-twins/README.md):
+//! rustup target add wasm32-wasip1
+//! cargo build --release --target wasm32-wasip1
+
+use std::io::{Read, Write};
+
+fn fail(what: &str, detail: String) -> ! {
+ eprintln!("{what}: {detail}");
+ std::process::exit(1);
+}
+
+fn main() {
+ let mut spv = Vec::new();
+ if let Err(e) = std::io::stdin().read_to_end(&mut spv) {
+ fail("read stdin", e.to_string());
+ }
+
+ let options = naga::front::spv::Options {
+ adjust_coordinate_space: true,
+ strict_capabilities: false,
+ ..Default::default()
+ };
+ let module = match naga::front::spv::parse_u8_slice(&spv, &options) {
+ Ok(m) => m,
+ Err(e) => fail("spv parse", e.to_string()),
+ };
+
+ let mut validator = naga::valid::Validator::new(
+ naga::valid::ValidationFlags::all(),
+ naga::valid::Capabilities::all(),
+ );
+ let info = match validator.validate(&module) {
+ Ok(i) => i,
+ Err(e) => fail("validate", format!("{e:?}")),
+ };
+
+ let wgsl = match naga::back::wgsl::write_string(
+ &module,
+ &info,
+ naga::back::wgsl::WriterFlags::empty(),
+ ) {
+ Ok(s) => s,
+ Err(e) => fail("wgsl write", e.to_string()),
+ };
+
+ if let Err(e) = std::io::stdout().write_all(wgsl.as_bytes()) {
+ fail("write stdout", e.to_string());
+ }
+}