Stylized Water 3

Version: 3.0.1

3.1.Update guide #

Before updating, make obsolutely sure that the project is free of any compile errors. Automatic update processes will otherwise not run. You’d be left to figure out why things went broken.

⚠️ Use of a version control system is rightly assumed, and otherwise strongly advisable for any Unity project. No project is alike, you’d want to ability to observe what’s changing and undo any unwanted changes.

If not, backup your project before updating!

From Stylized Water 2 (v1.6.9+ only)

Using both assets simultaneously is not possible. However, there is a window of opportunity to upgrade a project’s water materials using SW2 to use SW3.

This guide is written for projects that have SW2’s shader and scripts in use. Deleting SW2 will cause these aspects to break, as the shader and scripts will go missing. This is unavoidable, but damage can be mitigated.

The easiest course of action is of course to delete SW2, then import SW3, and set up water again in your project as a clean break.

Functionality	Auto-upgradable
Materials*	✅
Meshes	✅
Scene components	✅
Fog integrations	✅
Render features	❌
Wave animations	❌
API changes	❌
Prefab components	❌
DWP2 integration	❌

*Intersection foam settings (eg. enabled state) may appeared changed

1. Import Stylized Water 3

From the Package Manager.

Stylized Water 3 uses completely new files and folders, so importing it will never overwrite anything in the StylizedWater2 folder. Otherwise SW3 content would import and merge with the SW2 folder, leaving you to guess what needs to be deleted afterwards.

Console messages

Multiple warnings along the lines of “Cannot add menu item <…> because a menu item with the same name already exists.”. Which are safe to ignore for now.

Error: Multiple scripted importers are targeting the extension ‘watermesh’ and have all been rejected.

This will break any water mesh asset, potentially turning some water bodies invisible. That’ll get fixed automatically by the end of this guide 😉

2. Update custom scripts using an API

Code namespace have simply changed from sc.stylizedwater2.runtime to sc.stylizedwater3.runtime. Search for any references in your codebase and change them. Observe any errors that follow and correct them.

The Buoyancy API has changed drastically, in order to facilitate the modernized GPU-readback functionality. See the Height Query System page. The new “Align Transform to Water” component also serves as a fully commented scripting example for how to use this.

3. Install the upgrade helper

Before deleting SW2, you need to make sure that any materials using its shaders will now use the SW3 shader. Additionally, components need to be converted to their SW3 version, otherwise they’ll go missing.

An editor utility is available to help achieve this

DOWNLOAD

Once imported into your project, options will appear under a new “Stylized Water 3 upgrader” menu.

4. Remove old render features

On any of your renderers, check for any Stylized Water 2 render features and remove them.

Go to the Stylized Water 3 upgrader/Add Render Feature menu option, to set up the new one.

5. Update water materials

Go to the Stylized Water 3 upgrader/Upgrade project materials menu option.

It finds any materials in the project using the SW2 shader and switches it to the SW3 shader (most material parameters are transferable)

For custom materials, you may have to make small adjustments. For example, materials that had Intersection Foam enabled will not appear to have it enabled anymore.

Waves have been completely revised, so will have to be finetuned to your liking. A default Wave Profile will be assigned

6. Update old components

Before deleting SW2, you need to make sure that any components aren’t going to go missing. These need to be converted to their SW3 version.

Open all relevant scenes that contain water-related things…

Go to
• Stylized Water 3 upgrader/Upgrade scene Water Objects
• Stylized Water 3 upgrader/Upgrade scene Water Grids
• Stylized Water 3 upgrader/Upgrade scene Planar Reflection Renderers
• Stylized Water 3 upgrader/Upgrade scene Align To Waves components

(Options will be grayed out if nothing can be done in the current scene)

The tool looks for certain components in the scene, and swaps them out.

Not all parameters and values can be retained unfortunately! For example, water object references on a Planar Reflections component

Components added to prefabs must be converted manually.

The Stylized Water Data Provider component for the Dynamic Water Physics 2 asset is not upgradable. At this time, DWP2 does not contain an integration for SW3.

7. Update scene prefabs

If you are actively using any of the included prefabs, such as water objects or particle effects. These are soon going to be deleted.

You can use the free Replace Selected tool to swap these prefabs out with their SW3 equivalent. You’d also find these in the Stylized Water 3/Prefabs/… folder