The Day Our Shaders Went Missing From the Build

In the Unity editor, everything looked perfect. In the finished build: pink surfaces and missing effects. Welcome to one of the nastiest Unity traps — and a few of its relatives.

Shader stripping. When building, Unity throws out everything that apparently isn't needed — including shaders. The problem: if you load shaders at runtime via Shader.Find() (like we do with our more than 20 custom shaders for water, atmosphere, holograms, and more), Unity sees no reference to them in any scene. Result: the shader is there in the editor and gone in the build. The solution is unspectacular but essential: every one of these shaders has to go into the Always Included Shaders list in the graphics settings. Since then the rule with us is: new shader? Add it immediately.

The layer that was -1. Similar category: we resolved a physics layer in code by its name. In the editor: works. In the batch build on the build server: the layer doesn't exist, the lookup returns -1, and everything based on that layer silently behaves wrong. Since then we reference layers by their fixed index, not by name.

The moral: The Unity editor and the finished build are two different worlds. The editor is merciful — it has all the assets, all the names, all the shaders at hand. The build is merciless. That's why, with us, every change to the client comes with a real local build test, not just the Play button in the editor. It takes longer. It has still saved us many embarrassing releases.