When Beat Saber updated to 1.29.4, the developers changed the render type from Single Pass to Single Pass Instanced. Unfortunately, the Beat Saber model projects were not set up to handle this change gracefully, so all models created up until this point have invalid shaders.
These invalid shaders only show up in the left eye and completely ruin a model when wearing a VR headset.
Fortunately, there is a library and .unitypackage that can help you make this transition easily, even with large model projects.
AssetBundleLoadingTools is a library that aims to fix broken legacy models using pre-converted .shaderbundle files.
A .shaderbundle is a file that contains shaders that have been recompiled to comply with the Single Pass Instanced changes.
Unfortunately, this library of pre-converted shaders only includes common shaders like BeatSaber/Unlit and BS_Uber. If you've ever made a custom shader or downloaded one from a niche source, there's an extremely high chance it's not included.
The ShaderBundleExporter contains some useful utilities to automate shader conversion:
Convert All Shaders In Project
Convert All Shaders In Folder
Convert Shader By File
Convert All Shaders In Selected GameObject(s)
It's recommended that you Convert All Shaders In Project to convert everything out at once.
If you don't have much time or don't feel like potentially manually fixing up a bunch of shaders, you can always select a model and do Convert All Shaders In Selected GameObject(s) to just fix up that specific model.
You can also convert a specific shader by using Convert Shader By File.
These actions will overwrite the .shader files found within your Unity project. It will create .shaderbackup files, but it's always recommended to backup your full project before making any big changes.
After converting your shaders, the Console tab will contain useful information that tells you how much of your shader library was automatically converted.
As you can see, some of these shaders couldn't be autoconverted. Most shaders - especially shaders included by default in model Unity Projects - are fairly simple, and the Shader Converter will be able to convert them without issue.
However, there's a lot of different types of shaders, and the autoconverter is only so smart. Check out the Manual Shader Conversion instructions for more info on how to fix shaders that couldn't be automatically converted.
Once you've finished converting all your shaders, you can re-export models AND export new models without worrying. Converted shaders will function properly on both old and new Beat Saber versions!
You should double check that your shaders look fine in-VR before publishing models with them! If the autoconversion messed up a specific shader, you can always open the .shaderbackup, copy the source code into the .shader, and Manually Convert it.
This is the RECOMMENDED WAY to fix your shaders if you've released a lot of models. If you're just trying to fix one specific model or export new models, check out the Converting Project Shaders section.
.shaderbundles work using the same system as automatic shader conversion. If you've already converted your shaders to Single Pass Instanced, the .shaderbundle will use those - otherwise it will try to autoconvert them without saving the changes permanently.
The exported files are also identical to any other model file. All of your shaders are compiled into a bundle, and the source code isn't in the final product - exactly like a saber, platform, avatar, etc.
The Shaders/Create .shaderbundle window contains three ways to build a .shaderbundle
All Shaders In Project: The recommended way to export shaders. If you export this, you will have one .shaderbundle file that can fix the vast majority of your models!
All Shaders In Folder: Situationally useful. Good if you have a specific subfolder you want to export from.
All Shaders For Selected GameObject(s): Can be useful for exporting shaders for multiple models at once.
After selecting one of these options, the .shaderbundle compiler will do the following:
Once you've exported a .shaderbundle, the Console tab will contain useful information to see how your bundle export went.
There's a list of every shader that was successfully exported and some helpful stats:
If any of your shaders are unusual and unable to be autoconverted, they'll show errors in the console:
These errors are pretty verbose, and upon click will show more information on what exactly went wrong during the autoconversion. Read the Manual Shader Conversion instructions to learn how to fix these.
You can send the .shaderbundle to whoever you want, and it should work fine as long as they follow the above instructions.
However, this is clearly not ideal if you create public models. If somebody's downloaded your old models and they don't have the bundle, they'll still be broken!
This is where the extremely important.shaderbundle autoupdater comes in. AssetBundleLoadingTools automatically downloads .shaderbundle files from a web service, and you can easily add your own bundles to this service.
To add your bundles to the autoupdater, do one of the following:
Contact Bobbie#0001 on discord
Ask about it in the #pc-3d-modeling channel in the BSMG Discord
Once your .shaderbundle is added to the web service, everybody on new versions of Beat Saber will receive fixed versions of your shaders, making their experience smooth and not requiring them to hunt down updated copies of your models.
Sometimes the autoconverter will fail to make a shader support Single Pass Instanced. This can happen for many reasons, and a specific reason is usually printed as an error message. When this happens, you'll need to manually convert following these steps:
First, test if the shader already works! Some shaders are already converted to work with Single Pass Instanced, but the autoconverter can't detect it properly. This generally happens with complex shaders that use a lot of .cginc files, like BS Uber and Poyomi
If you're exporting a .shaderbundle:
Go to the settings in Editor/AssetBundleLoadingTools/ShaderBundleSettings and enable Export Broken Shaders. MAKE SURE TO TURN THIS OFF & RE-EXPORT BEFORE SHARING YOUR SHADERBUNDLE!
Load a legacy model that uses the same shader and see if it's only rendering in one eye
If you're converting your project's shaders:
Export a model that uses the shader that failed to convert
Load the model ingame and see if it's only rendering in one eye
If you've completed this step and it's already rendering properly, congratulations, you don't need to do any conversion!
Navigate to Editor/AssetBundleLoadingTools/ShaderBundleSettings and either drag the shader onto Already Converted Shaders or add the shader's name in Already Converted Shader Names
Shaders can be fairly complex and these rules don't always apply.
If you're not familiar with shaders, have questions about the general shader conversion process, or need help converting a specific shader, please ask in the #pc-3d-modeling channel in the BSMG Discord