Stylized Water 2 documentation

Stylized Water 2

Stylized Water 2
Version: 1.6.7
Review

6.Troubleshooting/FAQ #

At all times you must ensure your project is free of any console errors. Unresolved code errors will prevent this asset’s code from compiling and executing. The shader may display as pink in this case or functionality may appear to be missing from the editor.

Rendering

Transparent materials (+sprites & particle effects) always appear either below, or in front of water

Since transparent surfaces do not have any depth, it’s not possible to sort them on a per-pixel basis. This is the case for any transparent shader, not just this water shader.

Instead, transparent material are sorted based on:

  • Their position (pivot point distance from camera)
  • Material’s render queue value
  • Renderer’s sorting group value

This determines which material should draw over the other. For more information see the Unity manual page (also applies to perspective camera setups).

To remedy this:

  • Set the “Order in layer” value on the Sprite/Particle System (found in the Rendering section) to a value higher than 0. This way it’ll always draw over the water
  • (Or) On the particle material, increase the “Priority” value by one
  • (Or) Set the render queue on the water material to 2999 (found under the “Rendering” tab). It’ll render behind everything else.
  • Fallback: Enable the “Alpha clipping” option on the transparent material

    Alternatively, turn on the “ZWrite” option on the water material, found under the “Rendering” tab.

    ZWrite ON: Transparent materials will properly intersect with the water, parts can be above and below the water. As long as they’re on the same render queue.
    ZWrite OFF: Transparent materials are sorted based on their position, order in layer and the material’s render queue (labeled “Priority” on URP’s particle shader). They will either render behind or in front of the water.

    Water doesn't appear to be transparent and has a gray tint

    This only applies when the “Refraction” feature is enabled, which relies on the render pipeline creating an “Opaque texture”, for the shader to then use.

    Ensure this option is enabled in your (currently active) pipeline asset:

    You may have different pipeline assets associated with the different Quality Settings, check that this option is also enabled on them.

    Without this, the shader receives a gray texture as an input (Unity’s default “null” texture)

    If you have an older version of the Buto asset installed, this may also occur. This has been fixed in a later version.

    Water turns invisible when applying a River material to it

    Water materials that have River Mode enabled may have the vertex-color transparency option enabled. If your (custom) river mesh is filled with White vertex colors, it will be rendered 100% transparent as a result.

    Disable this here:

    The River material used in the demo scene has this option enabled, because the geometry used there uses vertex colors. The River material included in the “Materials” folder does not have this enabled, to avoid users encountering seemingly invisible water geometry.

    (Unity 6+) Water (typically an ocean) only moves up and down as a whole when Waves are used

    Using the GPU Resident Drawer with Tessellation enabled is not supported. Either disable Tessellation on the water material (under the Rendering tab), or disable GPU Resident Drawer in your pipeline settings.

    Transparent materials underneath the water aren't refracted

    The refraction features make use of the Opaque Texture URP renders. As the name implies, this texture represents the screen’s image right after opaque geometry is drawn but before transparent materials are rendered (including water).

    Because of this, transparent materials aren’t captured in this texture, thus can’t be refracted.

    Refraction shows red/blue artefacts around geometry

    First, ensure the “Opaque downsampling” option in the pipeline asset in use is set to “None”. This will mitigate the issue.

    Finally, turn down the Chromatic Aberration parameter on the water material (under the Underwater tab)

    Water depth and intersection effects aren't visible in a build

    It’s likely, when the game is running on the device, a different Quality profile is used than in the editor.

    If you have different pipeline assets assigned, per quality level, ensure the “Depth Texture” option is also enabled for them.

    See the Getting Started page for more details.

    Water depth and intersection effects do not appear on some objects

    The effect relies on the depth texture Unity renders, which provides a means to measure the distance from the water surface to an object’s pixel on screen.

    As such, materials that don’t write to the depth texture will not be affected. This usually means:

    • Transparent materials (water/particles/etc)
    • Unlit materials (before Unity 2021.1)
    • Sprites
    • UI elements
    • Details/grass rendered through the terrain system
    • Custom (handwritten) shaders without a DepthOnly pass
    • Anything rendered through a custom render loop, without a depth buffer (if you’re developing this, you probably already know this)

    Lights no longer affect the water beyond a certain distance when using Forward+ rendering

    This is a known issue, but the exact reason why this happens is still unknown at the time.

    The shader code implementation for Forward+ rendering has been copied from Unity’s URP shaders, yet something appears to be wrong or missing. There is absolutely no documentation on how this feature works and how to implement this. Hence, further investigation is necessary.

    Errors

    Shader error: OUTPUT_SH4: too few arguments in macro call

    This shader error is specific to Unity 6 and using the Adaptive Probe Volumes (APV) feature.

    Unity 6 is a preview version and is not supported, fixing this error means something else will just break a week later. Once a release version is available, compatibility is investigated and update will follow with fixes.

    Editor

    Water is transparent in the Scene view, but not in the Game view

    On the water material, you’ll notice an error that indicates that the “Depth texture” option is disabled in your URP settings. Click the “Enable” button next to it to enable this. After which, the water will render correctly.

    Water is not visible in the scene view with an orthographic camera

    Ensure Dynamic Clipping is enabled:

    Alternatively, disabled it and bump up the “Near” value to ~0.5, or select a nearby object (F-key)

    Shader error: Failed to include source file Underwater/UnderwaterFog.hlsl

    As of 2022.1 Unity changed the behaviour of their shader compiler, which causes this falsepositive error to be thrown. That part of the shader code is not supposed to be activated normally, and it’ll be stripped during the build process. So ultimately it’s harmless, and doesn’t actually mean anything is practically wrong.

    This has been addressed in version 1.4.0.

    Shader error: Failed to include source file Libraries/<filename>hlsl

    The error is absolutely false, since the file it refers to is actually there. But sometimes Unity’s shader compiler messes up the importing order, or caches too aggressively. 

    You can right-click on the Shaders folder and choose “Re-import”, to give the compiler a good kick. You may need to delete the Library/ShaderCache folder from your Unity project (perfectly safe!), in order to really-really clear the faulty compiled shader.

    Shader error: Couldn't open include file 'Packages/com.unity.render-pipelines.universal/ShaderLibrary/DOTS.hlsl'

    When using Unity 2022.2, this shader library file is only available starting from 2022.2.15f1 (URP version 14.0.7).
    You must update your project to a more recent version of Unity.

    Water animations don't always work in scene view, or aren't smooth

    In the scene view bar, check if the “Always Refresh” option is enabled. In Unity <2020 this was called “Animated Materials“.

    If not, any kind of shader animation only update when the scene view is refreshed (eg. selecting something or moving the camera).

    Mobile hardware

    Rendering large distances is challenging on mobile hardware, due to limited hardware precision. On PC/Console the depth texture Unity renders uses high precision values (0-65.535, 16-bit), whilst on mobile (specifically OpenGLES) it uses linear values (from 0-255, 8-bit). As such, this shader can also be affected by it.

    Water looks different on the device, than it does in the editor (on PC/Consoles)

    The color gradient and intersection effects are both based on the depth texture Unity renders. On mobile platforms, this depth texture is of lower precision, so it’s possible any depth-based effect pans out a little differently.

    To increase the accuracy of the depth texture:

    • Ensure the camera’s far clipping plane value (set on the Camera component) is as small as possible.
      • For orthographic camera’s, move the camera position as close as possible.
    • Increase the near plane value. If no objects come near the camera, you can get away with this.

    Intersection foam starts flickering when running the app on the device

    The intersection foam effect is based on the depth texture Unity renders. On mobile platforms, this depth texture may be of lower precision than on PC/Consoles.

    Jittering may occur when:

    • The camera is very far away from the water surface
    • The water is very shallow

    In these case the depth value (of any given pixel) may be very close to that of the geometry behind it (eg. 0.98553 vs 0.98554). Typically in very shallow water, such as shorelines. Due to floating point rounding errors, these values may appear to jitter back and forth, which translates to a visual artefact. This is comparable to Z-Fighting.

    Solutions:

    • Limit the maximum render range by decreasing the camera’s far clipping plane value (set on the Camera component).
    • Ensure the water is fairly deep (problematic for beaches)
    • Draw the foam/depth effect through Vertex Colors so that it is based on static data (ultimate solution).

    This whole ordeal pertains to the general working of 3D rendering and is not something the water shader can circumvent, nor does it mean it’s broken.

    Textures start to look pixelated, the longer the app runs

    The UV coordinates for the water textures (normal map and foam) are animated. Which means the values are offset every frame by a small increment. Over time, these values run up, to the point where floating point rounding errors start to occur.

    There is already a technique in place, that greatly reduces this artefact on low end hardware. Though, after ~6 hours this starts to become inevitable.

    Solutions:

    • Set the “UV Coordinates” (General tab) to “Mesh UV” preferably
    • Lower the speed of the animations

    When using an orthographic camera, water appears below other objects/terrain and intersection effects aren’t visible

    This issue is caused by transparency sorting, mobile devices are less accurate in this manner, especially with orthographic cameras.

    To rectify this:

    • Reduce the “Far clipping plane” on your camera until it starts to clip your geometry. By default this is set to 1000 units, which is overkill for orthographic scenes.
    • Increasing the “Near” value.
    • Move the camera as close to the environment as possible.

    These steps reduce the rendering range for the camera and therefore increase the accuracy of sorting. After which, the water should render correctly.

    Artefacts

    Light reflections shows noisy artefacts

    This is entirely attributed to the result of texture compression.

    You can disable compression on the normal map that is being used on the material to resolve this, at the cost of more memory (~4x).

    Refraction also distorts objects above the water

    Objects rendered after transparent materials, such as through the Render Objects render feature or Overlay cameras will show these artifacts.

    This is because these objects will render after the water has been. As such, when the water shader renders it’ll have no access to the geometry data, and can’t filter them out.

    If the “Disable Depth Texture” option is enabled (found under the Rendering tab), these artefacts are also visible.

    Water shows noise artifacts when viewed from afar

    This scene uses a 16k terrain, where the scene camera is 20.000 units away. At this point you’re inevitably running into floating point precision issues. On water pixels with the skybox directly behind it, depth values are reaching infinity and causes artifacts to show.

    In any normal situation, this won’t occur. Otherwise, ensure there is some geometry behind/underneath the water.

    Yes No Suggest edit
    Last updated on July 17, 2024
    4 of 4 users found this section helpful
    Suggest Edit