TODO reference this conversation to account for the details

Overview

Water is made up of 3 parts:

1. The volume. Has all the components that react to colliding with the water. This includes the fluid volume (for making it act like water), audio volume (for underwater ambience), and effect ruleset (for the visual underwater effect of distorting the screen)
2. The water surface. For most water this will be a plane or quad (plane has more vertices, which is good for showing waves)
3. The stencil renderer. This is a volume that roughly matches the shape of the space you put the water in. It allows the distortion effect to function.

Setup

If you want materials and shaders to steal from, scroll to the Stencil Mechanics section

The volume

The effect ruleset should have type Underwater

[!NOTE] NH does the effect ruleset setup for you using the GD distortion underwater material. Only make your own if you want something different. Make sure you have surfaceSize or soiOverride set. Code is here

The water surface

The stencil render

The stencil volume should match up closely with the water surface so that the underwater effect matches with the surface

You can test that the stencil works in editor by making a sphere underwater with the effect ruleset material and moving your camera inside of it.

[!WARNING] If you have any holes in your stencil mesh, the underwater effect with "leak" through it! This actually happens in base game in some places on Timber Hearth

TODO show pictures of the setup here

TODO make sure to include specific setup details like the priority and uh render queue

TODO maybe put the note about the buoyancy here? otherwise put it in the fluid volume page

How it works

The volume

This uses the standard effect volume system for the fluid and audio.

See also the NH Docs and the wiki page

The effect ruleset assigns a material to a small inverted sphere renderer surrounding the camera (code path is EffectRuleset > RulesetDetector > UnderwaterEffectBubbleController). This sphere reads from the stencil to know whether to draw.

The water surface

This is a normal renderer with a normal material/shader. It also reads the stencil for some reason that I do not understand.

The stencil renderer

Writes to stencil

TODO show shaders and materials in editor

Stencil mechanics

The stencil buffer is a screen-sized image that stores bits instead of colors for each pixel. Shaders can write to it and read from it to determine whether to draw.

• Shader "Outer Wilds/Utility/Water Stencil"
  Shader "Outer Wilds/Utility/Underwater Stencil"
  • the stencil renderer
  • inverts bit 5
  • no ztest, no zwrite, no backface culling. so always draws even with things in front of it
• Shader "Outer Wilds/Environment/Water"
  Material Terrain_TH_Water_v2_mat
  • the water surface renderer
  • reads bits 5 and 6 and draws if only bit 5 is set
  • i think this is for the underside of the water, but idk
• Shader "Outer Wilds/Effects/Effect Bubble/Distort"
  Material VFX_UnderwaterEffectBubble_mat
  Shader "Outer Wilds/Effects/Effect Bubble/Distort and Fog (Ringworld)"
  Material Effects_IP_UnderwaterFogEffectBubble
  Shader "Outer Wilds/Environment/Giant's Deep/Ocean Fog"
  • the sphere around the player camera
  • reads bits 5 and 6 and draws if only bit 5 is set
  • no ztest, no zwrite, no backface culling. so always draws even with things in front of it
• BONUS:
  Shader "Outer Wilds/Utility/Ship Interior Stencil"
  Shader "Outer Wilds/Utility/Ship Viewport Stencil"
  • this makes you not see underwater when you're inside the ship. also used for the sunken probe module
  • inverts bit 6
  • no ztest, no zwrite, no backface culling. so always draws even with things in front of it

Since the bits are inverted, being outside of the mesh means it inverts twice (one for front face and one for backface), the bit stays 0. being inside the shape only inverts once, so you see the distortion effect or whatever else

Special water

Giant's Deep

TODO someone look into this. should be fairly similar mechanics, with a water surface shader, a stencil writing shader, and a stencil reading shader

Ring World

TODO someone look into this. should be fairly similar mechanics, with a water surface shader, a stencil writing shader, and a stencil reading shader