1. Getting Started¶
This section has steps for importing the Crest content into a project, and for adding a new ocean surface to a scene.
Warning
When changing Unity versions, setting up a render pipeline or making changes to packages, the project can appear to break. This may manifest as spurious errors in the log, no ocean rendering, magenta materials, scripts unassigned in example scenes, etcetera. Often, restarting the Editor fixes it. Clearing out the Library folder can also help to reset the project and clear temporary errors. These issues are not specific to Crest, but we note them anyway as we find our users regularly encounter them.
To augment / complement this written documentation we published a video available here:
Fig. 1.1 Getting Start with Crest for BIRP¶
Fig. 1.2 Getting Start with Crest for HDRP¶
Fig. 1.3 Getting Start with Crest for URP¶
1.1. Requirements¶
Unity Version: 2020.3.10
Shader compilation target 4.5 or above
Crest does not support OpenGL or WebGL backends
The Crest example content uses the post-processing package (for aesthetic reasons). If this is not present in your project, you will see an unassigned script warning which you can fix by removing the offending script.
The minimum HDRP package version is 10.5
The minimum URP package version is 10.5
1.2. Importing Crest files into project¶
The steps to set up Crest in a new or existing project are as follows:
1.2.1. Pipeline Setup¶
Ensure that BIRP is setup and functioning, either by setting up a new project using the BIRP template or by configuring your current project. This is beyond the scope of this documentation so please see the Unity documentation for more information.
Switch to Linear space rendering under . If your platform(s) require Gamma space, the material settings will need to be adjusted to compensate. Please see the Unity documentation for more information.
Ensure that HDRP is setup and functioning, either by setting up a new project using the HDRP template or by configuring your current project. This is beyond the scope of this documentation so please see the Unity documentation for more information.
Ensure that URP is setup and functioning, either by setting up a new project using the URP template or by configuring your current project. This is beyond the scope of this documentation so please see the Unity documentation for more information.
Switch to Linear space rendering under . If your platform(s) require Gamma space, the material settings will need to be adjusted to compensate. Please see the Unity documentation for more information.
1.2.2. Importing Crest¶
Import the Crest package into project using the Asset Store window in the Unity Editor.
Note
The files under Crest-Examples are not required by our core functionality, but are provided for illustrative purposes. We recommend first time users import them as they may provide useful guidance.
Import Crest assets by either:
Currently we do not prepare release packages. However, we do tag each asset store version, so the zip corresponding to each version can be downloaded by clicking the desired version on the Releases page.
Getting latest by either cloning this repository or downloading it as a zip, and copying the Crest/Assets/Crest/Crest folder into your project. Be sure to always copy the .meta files.
Note
The Crest/Assets/Crest/Development folder is only used to develop Crest and should be skipped.
HDRP defaults to using TAA which currently does not work well with the water material and makes it look blurry under motion. We recommend switching to a different anti-aliasing method such as SMAA using the Anti-aliasing option on the camera component.
Transparency
To enable the water surface to be transparent, two options must be enabled in the URP configuration. To find the configuration, open Edit/Project Settings/Graphics and double click the Scriptable Render Pipeline Settings field to open the render pipeline settings. This field will be populated if URP was successfully installed.
After double clicking the graphics settings should appear in the Inspector. Transparency requires the following two options to be enabled, Depth Texture and Opaque Texture:
Note
If you are using the underwater effect, it is recommended to set Opaque Downsampling to None. Opaque Downsampling will make everything appear at a lower resolution when underwater. Be sure to test to see if recommendation is suitable for your project.
Read Unity’s documentation on the URP Asset for more information on these options.
Tip
If you are starting from scratch we recommend creating a project using a template in the Unity Hub.
1.3. Adding Crest to a Scene¶
The steps to add an ocean to an existing scene are as follows:
Create a new GameObject for the ocean, give it a descriptive name such as Ocean.
Assign the OceanRenderer component to it. This component will generate the ocean geometry and do all required initialisation.
Assign the desired ocean material to the OceanRenderer script - this is a material using the Crest/Ocean shader.
Set the Y coordinate of the position to the desired sea level.
Tag a primary camera as MainCamera if one is not tagged already, or provide the Camera to the View Camera property on the OceanRenderer script. If you need to switch between multiple cameras, update the ViewCamera field to ensure the ocean follows the correct view.
Be sure to generate lighting if necessary. The ocean lighting takes the ambient intensity from the baked spherical harmonics. It can be found at the following:
Tip
You can check Auto Generate to ensure lighting is always generated.
To add waves, create a new GameObject and add the Shape FFT component. See Wave Conditions section for customisation.
Any ocean seabed geometry needs set up to register it with Crest. See section Shorelines and Shallows.
If the camera needs to go underwater, the underwater effect must be configured. See section Underwater for instructions.
1.4. Frequent Setup Issues¶
The following are kinks or bugs with the install process which come up frequently.
1.4.1. Errors present, or visual issues¶
Try restarting Unity as a first step.
1.4.2. Compile errors in the log, not possible to enter play mode, visual issues in the scene¶
Verify that render pipeline is installed and enabled in the settings. See the follow for documentation:
1.4.3. Possible to enter play mode, but errors appear in the log at runtime that mention missing ‘kernels’¶
Recent versions of Unity have a bug that makes shader import unreliable. Please try reimporting the Crest/Shaders folder using the right click menu in the project view. Or simply close Unity, delete the Library folder and restart which will trigger everything to reimport.
1.4.4. Ocean framerate low in edit mode¶
By default, the update speed is intentionally throttled by Unity to save power when in edit mode. To enable real-time update, enable Animated Materials in the Scene View toggles:
See the Unity Documentation for more information.
1.4.5. Ocean surface appears blurred under motion HDRP¶
HDRP defaults to using TAA which currently does not work well with the water material and makes it look blurry under motion. We recommend switching to a different anti-aliasing method such as SMAA using the Anti-aliasing option on the camera component.
1.4.6. Ocean reflections/lighting/fog looks wrong HDRP¶
If reflections appear wrong, it can be useful to make a simple test shadergraph with our water normal map applied to it, to compare results. We provide a simple test shadergraph for debugging purposes - enable the Apply test material debug option on the OceanRenderer component to apply it. If you find you are getting good results with a test shadergraph but not with our ocean shader, please report this to us.