unity-asset-reader-shader
v1.1.0
Published
Shader inspection text for unity-asset-reader: GL and Metal source and SPIR-V disassembly, as AssetStudio writes it.
Maintainers
Readme
unity-asset-reader-shader
Shader inspection text for unity-asset-reader:
shaderToText() turns a Unity Shader into the text
AssetStudio exports for it, byte for byte: the ShaderLab
as Unity parsed it, with each pass's compiled programs in it. OpenGL and Metal programs are their
stored source; Vulkan programs are SPIR-V disassembly. Pure TypeScript and synchronous: it runs
anywhere unity-asset-reader does, browsers, Workers, Node.js.
Install
npm install unity-asset-reader unity-asset-reader-shaderunity-asset-reader is a peer dependency (^1.3.0, the first core with formatSingle), so your
app has exactly one copy of the parser.
Usage
import { load } from "unity-asset-reader";
import { shaderToText } from "unity-asset-reader-shader";
const env = load(bytes);
for (const asset of env.assets("Shader")) {
const text = shaderToText(asset.reader.read()); // Shader, as obj.read() reads it
// The .shader file AssetStudio writes is this text in UTF-8.
const file = new TextEncoder().encode(text);
}shaderToText takes what obj.read() gives for a Shader (Unity's field names), not
asset.data.
What the text holds
As AssetStudio's ShaderConverter.Convert() writes it:
- A banner saying the text is not a valid shader file, then
Shader "<name>" {, thePropertiesblock, eachSubShaderwith its tags, LOD and passes,FallbackandCustomEditor. - Per pass: its name, tags and the render state that differs from ShaderLab's defaults (blend,
color mask, depth, culling, offset, stencil, fog), then a
Programblock per stage (vp,fp,gp,hp,dp,rtp) with aSubProgram "<platform> [hw_tierNN] "per variant, its keywords, and the program in quotes after a// hash:line. A shader built by Unity 2021.3.10, 2022.1.13, 2022.2 or later (every Unity 6 build) lists its variants inm_PlayerSubPrograms, which AssetStudio's converter does not read: each distinct blob index and program type there gets oneSubProgram "<platform> ", withouthw_tierNN, as the composite oracle of the plan's section 5 (revision 2026-11-08a) writes it; their parameters are not written:- OpenGL, OpenGL ES and OpenGL Core (
openGL,gles,gles3,glcore): the GLSL source. - Metal (
metal): the Metal source. - Vulkan (
vulkan): each stage decoded from SMOL-V and disassembled to SPIR-V assembly, as AssetStudio's CSspv disassembler prints it. Where AssetStudio cannot decode or disassemble a program, the text has the// disassembly error <message>line AssetStudio writes. Unity 2020.3 stores SMOL-V in a newer encoding (header version0x01010000) than AssetStudio's decoder reads; it is decoded as aras-p/smol-v decodes it, and disassembled as AssetStudio disassembles the SPIR-V, so Unity 2019.4 and 2020.3 Vulkan programs are both disassembled. - Console programs: their bytes as UTF-8.
- OpenGL, OpenGL ES and OpenGL Core (
UsePass "<name>"andGrabPass { "<texture>" }passes.- Lines end with
\n; there is no final newline. Floats are written as .NET writes afloatunder the en-US culture (0.5,1E-05).
Errors
UnsupportedError:- a Direct3D program (DX9, DX10 level 9, DX11): AssetStudio turns them into text with Windows' D3DCompiler or HLSLDecompiler, which do not run here;
- a property of type
Int(5, Unity 2021.1'sInteger), on which AssetStudio fails; - a platform AssetStudio does not know (NaCl, Flash, PSM, or a number it has no name for).
CorruptErrorwhen a platform's part of the blob does not decompress to its size, or a program's entry or bytes run past it.- Anything
obj.read()throws for the shader, beforeshaderToTextis called.
Requirements
Node.js 20.19+ or 22.12+ (engines: ^20.19.0 || >=22.12.0), the same as unity-asset-reader,
or any browser unity-asset-reader runs in.
API reference
| Export | What |
|---|---|
| shaderToText(shader) | A Shader as the inspection text AssetStudio exports. |
Full JSDoc is in the bundled index.d.ts.
Acknowledgements
- AssetStudio (MIT, © Perfare, RazTools, Razviar):
shaderToText()is hand-ported from itsAssetStudio.Utility/ShaderConverter.csandSpirVShaderConverter.cs, and the SMOL-V decoder from itsAssetStudio.Utility/Smolv/; the output is tested against AssetStudio's own.shaderfiles, and Unity 6 shaders, several keyword variants per stage included, against its converter's text in the composite oracle. - CSspv (BSD-2-Clause, © 2017 Matthäus G. Chajdas): the SPIR-V
disassembler is hand-ported from it, as AssetStudio vendors it in
AssetStudio.Utility/CSspv/. - smol-v (MIT or public domain, © 2016-2018 Aras Pranckevicius): the
SMOL-V format AssetStudio's decoder reads; the decoder of its newer encoding (Unity 2020.3 and
later) is hand-ported from smol-v's
source/smolv.cpp, which is also the oracle of its goldens. - UnityPy (MIT, © K0lb3): the oracle that names the inputs of the test goldens.
The full list is in the repository README, and a comparison with similar npm packages in COMPARISON.md.
License
MIT AND BSD-2-Clause: the SPIR-V disassembler, ported from CSspv, is under the BSD 2-Clause
License (LICENSE-BSD);
the rest is MIT (LICENSE).
See NOTICE.
