Troubleshooting and Known Issues
Errors after updating the plugin
The issue
You have updated the plugin to the latest version from the AssetStore, and you encounter some Shader errors such as:
Shader error in 'Hidden/VolumetricLightBeam2Pass': failed to open source
file: 'ShaderUtils.cginc' at
Assets/VolumetricLightBeam/Resources/VolumetricLightBeamShared.cginc(36)
(on d3d11)
or some Script errors like:
DynamicOcclusion.cs(9,21): error CS0117: 'Consts' does not contain a definition for 'HelpUrlDynamicOcclusion'
How to solve it?
Unity sometimes doesn't properly handle file changes when updating assets.
To make sure the latest version of the asset is fully and properly imported, it is usually safer to:
- Close the Unity Editor
- Remove the old plugin folder (by default it is "Assets/Plugins/VolumetricLightBeam/" or "Assets/VolumetricLightBeam/" depending on your version in use)
- Manually delete the AssetStore download cache to force Unity to re-download the proper package (only useful if you use multiple versions of Unity at the same time). This folder is located:
- Windows: C:/Users/USERNAME/AppData/Roaming/Unity/Asset Store-5.x/Tech Salad/
- Mac OSX: ~/Library/Unity/Asset Store/Tech Salad/
- Reopen the editor and import the new version from scratch from the AssetStore or the Package Manager.
- Make sure you don't have any script compilation error from any script in your project, in order to make sure the plugin is properly imported and functional.
Unity crashes after trying to open the sample scenes
The issue
You have just installed the plugin, and you try to open the sample scenes of the plugin. But Unity crashes.
The plugin tries to create mandatory assets (generated shaders) the first time you create a new Volumetric Light Beam, and so the first time you open the sample scene.
But with some versions of Unity, doing that while loading the sample scene makes Unity crash.
How to solve it?
There is bug in Unity causing this crash. It's fixed in Unity 2023.1.7. So upgrading to this version or higher will fix the issue.
If you cannot change your Unity version, there is a simple workaround that you have to do only once: just open an empty scene and create a Volumetric Light Beam in it.
This way the mandatory assets will be created, and the next time you will open the sample scene, Unity won't have to do it again and it won't crash.
'Invalid Beam Shader set in VLB Config' error
The issue
You have the following error and your beams appear pink:
Invalid Beam Shader set in VLB Config
How to solve it?
Go into your Config asset and click on the Reset internal data button:
Beams not visible in the scene view
The issue
You have placed some Volumetric Light Beams in your scene. But the beams are not visible in the Editor scene view.
How to solve it?
By default, the beam meshes are created on the TransparentFX layer. This behavior can be controlled via the configuration file. So you have to make sure the TransparentFX layer (or the layer you have specified in the configuration file) is not hidden the editor (top-right corner of your Unity editor):
Beams not visible in Reflection Probes
The issue
You have placed some Volumetric Light Beams and a baked Reflection Probe in your scene. But the beams are not visible in the reflection.
How to solve it?
Only GameObjects with the ReflectionProbeStatic editor flag will appear in a baked Reflection Probe. You have to enable this flag on the Volumetric Light Beam GameObject and rebake the probe.
Beams in prefabs always appears as "Overrides"
The issue
You have placed a Volumetric Light Beam in a prefab (while using the new prefab workflow). The Prefab's Overrides dropdown menu is always visible and highlights a Beam Geometry child object, even if the beam has not been modified.
How to solve it?
This is a known issue of Unity, which should not considered non-persistent objects (such as this Beam Geometry child object) as "overrides" of a prefab. Thankfully, the Unity dev team has worked on it. A fix is available in Unity 2019.3 (from alpha 13) and backported to 2018.4 and 2019.2.
Flickering when moving camera
The issue
You have placed some Volumetric Light Beams in your scene, near other objects. The beams seem to flicker when you move the camera.
This is probably an issue with the render queue.
First, find out if there are some specific objects in your scene your beams are flickering with. Check their material and shader render queue, which is probably the same than the beam's (Transparent or 3000).
 |
 |
|---|---|
| Standard Shader | Custom Shader |
Usually, Unity manages to properly order objects even if they are in the same render queue. But with big objects, it can be harder to determine which object should be rendered first, and so it can be useful to set a different render queue for your beams.
How to solve it?
By default, the SD beam meshes are rendered on the Transparent (3000) queue. This behavior can be controlled via the configuration file. Try to change this value to fix the issue. For example, if your beams flicker with some windows using a Transparent material, try to set a Custom queue of 3001 so they can be rendered just after the windows.
Beams not animated when playing
The issue
You have animated some properties of your Volumetric Light Beam or the Unity's Light attached to it. But the beam doesn't change during playtime.
How to solve it?
By default, for performance optimization, the beams don't check properties changes during playtime.
-
For SD Beams: you can enable the trackChangesDuringPlaytime property to enable this feature and to be able to animate any of the beam properties during playtime.
-
For HD Beams: you have to add the Track Realtime Changes On Light HD component on your HD Beam.
SD Depth Occlusion Depth Buffer or HD Shadow make the beam invisible with URP on Android
The issue
You are using URP, and you've attached a Depth Occlusion Depth Buffer component on your SD Beam, or a Shadow HD component on your HD Beam. But your beam is not rendered when testing on Android devices.
How to solve it?
There is a bug with some Unity versions that make depth texture capture not working on Android and URP. This bug is know on Unity 2021.3.10 and versions arounds this one, but is know as fixed on 2021.3.15.
So we could recommend to update to Unity 2021.3.15. If you encounter this problem with more recent version of Unity, please get in touch with us.
SD Depth Occlusion Depth Buffer or HD Shadow not working with URP
The issue
You are using URP, and you've attached a Depth Occlusion Depth Buffer component on your SD Beam, or a Shadow HD component on your HD Beam. But the feature doesn't work and your beam is not occluded by any geometry.
How to solve it?
This is probably caused by the Depth Priming Mode set at Auto or Forced, which disables the writing into custom depth Render Textures. You have to set this option at Disabled, like explaining in the URP guidelines.
Depth "Banding" on mobile
The issue
You are running on mobile and experimenting weird artifacts and visual glitches when moving and rotating the camera.
This is probably due to "depth banding". On mobile, depending on the platform, depth buffer can have a very low precision.
The Soft Intersections with Opaque Geometry feature relies on depth sampling to smoothly blend the volumetric light beam with the environment. But if the depth buffer is encoded with a poor precision, this can provide poor results.
How to solve it?
First, make sure this is a problem with depth sampling: select the Volumetric Light Beam which causes the issue, and disable the Soft Intersections with Opaque Geometry feature (set the Opaque Geometry to 0). If the visual glitches are gone, this is a depth sampling: if you want to re-enable the feature, read the following steps. If the issue is still happening, contact us.
If you are running on Android, go in the Player Settings, under Resolution and Presentation, and make sure the Use 32-bit Display Buffer property is enabled.
If you are running on Mobile VR, go in the Player Settings, under your platform tab, XR Settings. For each Virtual SDKs you are supporting (Cardboard, GearVR, Daydream...), make sure the Depth Format property is at the highest value possible (24-bit depth).
It's recommended to keep a small depth range on your cameras clip planes: the difference between the near and far clip planes should be as narrow as possible: set the near distance as big as possible, and the far distance as low as possible.
if the issue is still occurring despites this changes, you are running on a platform which cannot provide depth sampling with good enough quality to have good results. In this case, the only workaround is to disable the Soft Intersections with Opaque Geometry feature by setting it to 0.
"Shadow" artifacts in one eye on mobile Single Pass VR (e.g. Oculus/Meta Quest)
The issue
Some weird artifacts are visible in the right eye through the Volumetric Light Beams when running on mobile VR devices (e.g. Gear VR, Oculus Go, Oculus/Meta Quest...) with Single Pass (Multiview or Instanced) Stereo Rendering enabled.
The depth sampling was broken until Unity 2019.3 for the right eye when Single Pass (Multiview or Instanced) stereo mode is enabled on Android (this is the case if you try to enable this optimization on Gear VR, Oculus Go or Oculus/Meta Quest for example)
This bug has been reported and is fixed in Unity 2019.3 or higher.
How to solve it?
Simply upgrade Unity to at least version 2019.3.
If you cannot upgrade your Unity version, you have 2 workarounds:
- Do not use Single Pass Stereo Mode on Android: use Multi-Pass.
- Set the property Soft Intersections with Opaque Geometry at 0 for all your VolumetricLightBeams: no depth sampling won't be performed and the issue won't be visible.
"Dynamic Occlusion" is not updated in Playmode in the Editor
The issue
You applied a Dynamic Occlusion (Raycasting or Depth Buffer) on a beam.
In playmode in the Editor, despite having set the desired Update Rate property, it's not properly updated when you move the beam or the occluder.
To maximize performance, when you are playing your game in the Editor, the Dynamic Occlusion will only be updated if at least one game camera looks at your beam.
This means you might see wrong occlusion effect applied on a beam in the Editor's Scene View if no game camera looks at it.
How to solve it?
Just make sure at least one Camera (on not the Editor Scene View's Camera) is looking at your beam.
"Dynamic Occlusion (Depth Texture)" is not working/makes the beam invisible when running on WebGL
The issue
When exporting your project to WebGL and running it in a web browser, the beam on which you have attached a Dynamic Occlusion (Depth Texture) component is not visible anymore, or the dynamic occlusion is not working properly.
The Dynamic Occlusion (Depth Texture) feature uses a depth RenderTexture. Depth RenderTextures are broken on WebGL builds in Unity versions lower than 2020.1. This is a known issue reported here.
How to solve it?
The only solution is to update your Unity version to 2020.1 or higher.
Error "RenderTexture.Create failed: colorFormat & depthStencilFormat cannot both be none."
The issue
You are using URP, and you can see the following errors triggered each frame when using the Dynamic Occlusion (Depth Texture) or Volumetric Shadow features:
RenderTexture.Create failed: colorFormat & depthStencilFormat cannot both be none.
Invalid surface for grabbing pixels. Verify that the RenderTexture is a valid color surface. Only a single color target may be grabbed.
How to solve it?
You are probably using a custom URP renderer that doesn't support writing to depth render texture. The 'Renderer list' is editable in the URP asset:
To fix it, you can use the Custom renderer index for Depth Camera property on the Config asset to specify a custom Renderer index used by the depth cameras for the Dynamic Occlusion (Depth Buffer) (with SD beams) and Volumetric Shadow (for HD Beams) features.
In this case, we recommend to specify a custom index referencing the URP default 'ForwardRenderer' (1 in the screenshot above).
Error "You can only call cameraColorTarget inside the scope of a ScriptableRenderPass"
The issue
You are using URP, and you can see the following errors triggered each frame when using the Dynamic Occlusion (Depth Texture) or Volumetric Shadow features:
You can only call cameraColorTarget inside the scope of a ScriptableRenderPass. Otherwise the pipeline camera target texture might have not been created or might have already been disposed.
How to solve it?
You are probably using a URP renderer with a custom Renderer Feature that doesn't support writing to depth render texture. The 'Renderer Features' list is editable in the URP Renderer Data asset:
To fix it, you can use the Custom renderer index for Depth Camera property on the Config asset to specify a custom Renderer index used by the depth cameras for the Dynamic Occlusion (Depth Buffer) (with SD beams) and Volumetric Shadow (for HD Beams) features.
Create a new URP Renderer asset (you can duplicate your current one), and remove all fancy features (post-processing, all renderer features...) to make it as simple and fast as possible.
Then add it to the Renderer List of your URP assets (make sure to change all your URP assets to make it work with all quality levels). Take note of the index of your custom renderer in this list (1 in the following screenshot).
Go into your VLB config asset and set the Custom renderer index for Depth Camera property to this value.
