About 90% of the support questions we receive for Triton Oceans for Unity are answered in our documentation – but not everyone knows where to find it. We’re copying it here so Google will be able to find it, at least!

Thank you for trying out Triton for Unity! Triton brings GPGPU-powered wave simulations to Unity, with fast, realistic waves for any given wind conditions. In addition to 3D surface displacement, refraction, coastal, buoyancy, and reflection effects, Triton also produces foam and particle-based spray effects depending on how violent the seas are. Triton also renders ship wakes with 3D wave displacements and propeller backwash effects, as well as rotor wash and impact effects. Triton also allows decal textures to be applied to the moving water surface. Triton uses a “Pierson-Moskowitz” wave spectrum, making it realistic enough for maritime training purposes, and is capable of representing Beaufort Scale conditions 1-9.
Be sure to read the “Distributing your application with Triton” section below before trying a standalone build of your project.

This trial version will terminate your application after five minutes of runtime, per run, and display a warning dialog stating that Triton is unlicensed at startup. To remove these trial restrictions, per-seat licenses are available through the Unity Asset Store and through our website at http://www.sundog-soft.com.

Getting Started

This distribution installs a Triton.unitypackage file, to “Program Files/Triton for Unity Trial” by default. To get started:

  • From Unity, select Assets / Import Package / Custom Package… and select the Triton.unitypackage file that was installed.
  • Open up the Triton folder in your project view, and find the TritonPrefab. Drag this into your scene.

Now, you can hit “play” and you should have an infinite ocean at sea level in your scene! But to get it looking its best, you’ll want to adjust some settings:

Adjusting the Water

Click on the TritonPrefab in your scene, and you’ll see various properties you may adjust.

To change the level of the water, simply adjust the Y component of the TritonPrefab’s position.

There are several properties in the Triton Unity script component you may adjust:

Wind Speed: The simulated wind speed, in meters per second. The more wind, the higher the waves and the more spray.

Wind Direction: The direction of the wind, in degrees.

Spray: Toggles particle-based spray effects.

Resource Path: A relative path from the project or executable where the TritonResources folder may be found. Triton won’t work without this.

User Name / License Key: If you purchased a license for Triton from http://www.sundog-soft.com/, enter the user name and license key you received here to stop the pop-up dialogs reminding you to register and five minute runtime limit.

Game Camera: Drag the camera object associated with the water here; Triton will use it to obtain the projection and modelview matrix used when rendering the water.

Directional Light: Drag a directional light object here, which will influence the color of the water and specular highlights from the light source. Be sure that the ambient light in your Render Settings is set appropriately, as this too will be used to light the water.

Enable Planar Reflections: Toggles planar reflections of local objects in the water, such as terrain, ships, etc. Planar reflections look great in shallow conditions when the water is very reflective, but in high seas reflections become hard to see, and it might not be worth the performance overhead of the second camera required to generate the reflections. You may use planar reflections together with an environment map, or use either type of reflection independently.

Above Water Visibility: The visibility above water, in meters. This can be used to fog the water in the distance to blend into the sky. Note, this only fogs the water, and not the rest of your scene. Only used if “Use Render Settings Fog” is false.

Water Color: The base color of the water in your scene. Please note that if you adjust this color, you will most likely want to adjust the Above Water Fog Color as well as the Below Water Fog Color to match the new color you have chosen.

Above Water Fog Color: The color the water will blend towards as the Above Water Visibility distance is approached, if “Use Render Settings Fog” is set to false. If your scene has dynamic time of day effects, be sure to update the fog color to make it dark and night and bright during the day.

Use Render Settings Fog: If set to true, the fog color and density above water will be copied from the Render Settings fog values each frame.

Below Water Visibility: The visibility below water, in meters. In addition to fogging the water surface, this will influence the transparency of the water near shorelines if coastal effects are enabled. Note, this only fogs the water, and not the rest of your scene.

Below Water Fog Color: The color the water will blend towards as the Above Water Visibility distance is approached.

Depth: The simulated depth of the water, in meters. At shallow depths, the water will be rendered with some transparency to let the ground underneath it show through. The depth also affects the shapes of the waves. If coastal effects are enabled, an automatically generated height map of your scene will be used to determine the depth and transparency and this setting will be ignored.

Choppiness: How sharply-peaked the waves are. A choppiness of 0 will produce rounded waves, and a choppiness of 2.0 will be sharply peaked.

Use Render Settings Fog: If set, the fog color and density specified in your Render Settings will be used instead of the values specified in Above Water Visibility and Above Water Fog Color. This can be useful for consistently fogging the water with the rest of your scene.

World Units: How many meters each unit in your scene represents. This may only be changed at design time, not at run time.

Underwater Fog Effects: If enabled, the RenderSettings fog will be set to match that of the water surface when the camera goes underwater, and any sky boxes will be replaced by the fog color as a background. The original fog and skybox settings are saved and restored once the camera goes back above water.

Geocentric Coordinates: Enable this only in the unlikely scenario that you are using a geocentric coordinates system using a WGS84 ellipsoid Earth model with the origin at the center of the Earth.

Y Is Up: Keep this checked if you are using the default Unity convention of “up” being along the Y axis. Uncheck only if the Z axis is up (or North, in the case of Geocentric coordinates.)

Coastal Effects: (Windows Only) Check this to enable smooth blending of the water with your shorelines. It works by creating a height map of your scene, and increasing the transparency of the water as its depth decreases. Your terrain will need to extend below the water surface (“bathymetry data”) in order for this to work properly. The effect is limited by the resolution of the height map, so it may not produce good results near sheer cliffs or pillars in the water.

Depth Offset: This provides a nudge in the depth buffer on the ocean, allowing you to resolve z-fighting artifacts between the water and sloping terrain underneath it. This is especially useful on MacOS where coastal effects are not available. Reasonable values would be between 0 and 0.002 or so.

Height Map Area: The area (in world units) covered by the height map generated for coastal effects. Increasing this value will result in coastal blending that stretches out further from the camera; decreasing it will increase the resolution of the height data used for blending near the camera. This value is ignored if coastal effects are off.

Breaking Wave Amplitude: If coastal effects are on, the amplitude (in world units) of breaking waves near the shoreline. A value of zero disables breaking waves. Breaking waves will only work well if your terrain includes realistic bathymetry data. If your bathymetry slopes off from the shoreline at more than a few degrees, waves will not break away from the shore – which is realistic behavior.

Breaking Wave Direction: The direction of the breaking waves, which should point toward the shore. This value is ignored unless coastal effects are on and the breaking wave amplitude is greater than zero.

Headless: If you are running Triton on a system intended to be a central server with no graphics, you may enable “headless” mode. This will cause Triton to update all of its waves, physics, and buoyancy models, but it will not spend time actually rendering the water. If you enable this option, the water will disappear – but this is what it’s supposed to do!

Time Scale: Use this to adjust Triton’s sense of time. Increasing this to 2.0 for example will double the wave velocities and motion of spray particles.

VR Support

Triton now supports the native VR integration available in Unity 5.1. To see how integration works, enable the Virtual Reality Supported option in Player Settings. Of special note is that standalone builds current have VR disabled by default, so you must launch the application with the command line argument –vrmode DEVICETYPE, where DEVICETYPE is one of the names supported by Unity.

Distributing your Application with Triton

UNITY 5 ONLY

Unity has implemented a new handle system for plugins, introducing what is known as the Plugin Importer Settings. With this new feature, plugins no longer need to be in specific folders as in previous versions, and instead each plugin has moddable import settings that allow you to change what platforms and CPU architecture the plugin must use. Due to this change, Triton may have errors in regards to plugins colliding due to plugins having the name.

To fix this, Triton now comes with an editor script that adds a new editor option to Unity’s menu bar. Simply select “Triton Editor Tools -> Update Plugin Import Settings” before attempting to build your own standalone executable. This will go through each of Triton’s plugins and label their import settings with the correct CPU architecture, removing the need for you to do so yourself.

Note: If “Triton Editor Tools” does not appear on your menu bar, try these steps to ensure it appears:

  • In your Project View, go to Assets->Editor and right click on TritonEditorTools.cs. Select “Re-Import”. If a message appears telling you that you need to upgrade your script, do so. Afterwards, click on the menu bar to see if it gets updated.
  • If the above doesn’t work, close and reopen your Unity Project. Again, if a message appears telling you that you need to upgrade your script, do so. Once the project opens, you should see “Triton Editor Tools” in the menu bar.

ALL VERSIONS OF UNITY

When building your standalone executable, Unity will strip out many of Triton’s native resources that it doesn’t recognize, preventing Triton from working. You need to ensure your installer:

  • Installs the TritonDLL.dll file from the Assets/Plugins folder alongside your game’s executable (for 64-bit targets, install the TritonDLL.dll from Asset/Plugins/x64 instead after renaming it.)
  • Installs the TritonResources folder, in its entirety, from the Assets/Triton folder to the path specified in your “Resource Path” property, relative to the executable.
  • Installs the Visual Studio 2010 SP1 runtime libraries from Microsoft.
  • Installs the latest DirectX runtime libraries from Microsoft.

As a reminder, if building on Unity 5, please ensure that your editor script has been updated, as mentioned in the previous Unity 5 section, and ensure that you run “Triton Editor Tools -> Update Plugin Import Settings” before building your standalone executable.

UNITY 4.6 ONLY

When building your standalone executable in Unity 4.6, a precaution needs to be made before the build process if not using the Triton Editor Tools to build your executable.

Go to Edit->Project Settings->Player and go to the Resolution and Presentation section. Uncheck the option “D3D11 Force Exclusive Mode”. Then build your application. Unity 4.6, when using this option, has the application built and run in full screen mode, which conflicts with the license warning dialog box that appears at the start of the application. Unchecking the option will force the build to be in windowed mode so that interaction with the dialog box is possible. This step MUST be completed before every build.

Again, this does not apply to the Triton Editor Tools build process, so this precaution may be ignored if the standalone is built using these tools.

Buoyancy with Triton

Triton exposes several scripting methods for intersection and height tests with the water surface in the TritonUnity.cs (see “Collision Detection” below.) We included an example of using these methods to power the buoyancy of a simple object in the package.

You’ll find a “buoyancy example” object in our demo scene, which is just a scaled cube – but it works just as well with ships and other objects. It uses the public domain Buoyancy.cs script by Alex Zhdankin, slightly modified to retrieve water height values from Triton. We also added a “Sea Level Offset” parameter to it, which can be used to compensate for models that aren’t centered at their center of buoyancy.

For this script to work properly, you will need a collider and a RigidBody attached to your buoyant object, as well as the Buoyancy.cs script. For real models and not just a simple geometric object as in our example, you’ll want to use a mesh collider with the correct mesh object specified within it. It’s important that you have a realistic mass specified in your Rigidbody, and a realistic density in the buoyancy script. If the mass is too small, the object won’t react properly with gravity – and if the density is too small, the object will be too bouncy in the water.
You will also want to make sure that the “slices per axis” and “voxel limit” settings in the Buoyancy script are high enough to represent the complexity of your model. These settings influence how many control points are simulated on your object; too few will result in unrealistic motion. You may visualize the forces coming from these points by enabling Gizmos.

Ship Wakes with Triton

Triton can automatically displace the water surface, render spray effects, and render propeller backwash effects for any object on the water. To do so, simply drag the Triton/TritonWakeGenerator script onto any object in a scene that also contains a TritonPrefab.

At a minimum, you will need to enter the Length and Beam Width properties of the Triton Wake Generator script. The length is the length of the ship or object, and the beam width is the width of the back of the ship or object, in meters.

Propeller backwash effects may be toggled and their origin position tuned as well, using the “Prop Wash” and “Prop Wash Offset” properties. “LOD Distance” sets the distance at which the prop wash effect halves the number of segments in it, allowing you to see more wakes at once from a distance.

“Bow Offset” can be used to generate spray particles in front of the wake generating object. Generally, this will be the distance from the object’s position to the front of the object, to generate spray at the bow of a ship. At higher speeds, a bow wake will also be pushed up at this location. Its effect may be scaled with the “Bow Wave Scale” parameter and capped with “Bow Wave Max.” The bow wake will be influenced by the “Draft”, which is how far below the water surface the hull extends, and by the “Bow Size”, which should be zero for most ships with pointy bows.

if “Auto Update” is on, the velocity will be computed automatically based on the object’s motion. If it’s off, you’ll need to keep the Velocity property updated on your own. The velocity influences the height of the wake waves and the amount of foam on them.

Finally, the “Test Motion” checkbox will cause the object to rotate around the camera position. It’s handy for seeing the wake effects when you don’t have the motion of the object rigged up yet.

Collision Detection

The TritonUnity script exposes two public methods you may use for collision detection with the water surface:

public UnityEngine.Vector3 ClosestPointOnBounds(UnityEngine.Vector3 position)
public bool Raycast (Ray ray, out RaycastHit hitInfo, float distance)

These are identical method signatures to Unity’s own Collider interface. They will return accurate collision points and surface normals for the ocean surface taking all of the waves and wakes into account. Triton does not include a buyoancy model for positioning your ships, but these methods will give you the data you need to power one.

In addition, we expose:

public float GetHeight(float x, float z)

which retrieves the wave height at the given x,z position, assuming that negative Y is “down”.

Rotor Wash Effects

The included RotorWash.cs script may be attached to any object to generate rotor wash effects from its position. Both particle effects and 3D wave displacements result from the rotor wash.
Set the wind velocity in meters per second coming off the rotors, the direction the rotors are pointing (usually down, or 0, -1, 0), the diameter of the rotor in meters, and Triton will do the rest.

The test scene included with the package includes an initially disabled Sphere-RotorWash object that illustrates usage.

Please note that until Unity upgrades the editor to 64-bit (Unity 5), enabling rotor wash can cause the editor to lock up, as there isn’t enough memory available for everything. If you encounter this problem, try running your project outside of the editor, and it will eliminate this issue.

Impact Effects

The included Impact.cs script may be used to simulate objects hitting the water, kicking up spray and waves depending on the mass and velocity of the object. Set the diameter of the object in meters, its velocity in meters per second, its mass in kilograms, and its direction from its starting position (pointing toward the water surface.) When you’re ready to trigger the effect, set the “trigger” property to true. On the next frame, the effect will be triggered, and the trigger property will be cleared to you may re-use the Impact object.

The test scene included with the package includes an initially disabled Sphere-Impact object that illustrates usage.

Decal Textures

Triton allows you to apply arbitrary textures on top of the water surface. This can be useful for effects like floating kelp, oil slicks, or whatever else you can dream up. Our package comes with a “Decal Example” game object that illustrates how to set up a decal.

Basically, create a game object and attach the TritonDecal script to it. Assign a texture and a decal size to the script properties, and set the game object’s position to where you want the decal located. Note, it’s important that the Y position you specify is at sea level.

At runtime, you may adjust the opacity of the decal texture and adjust the scale on the decal’s game object without incurring a performance penalty. You can use this to provide simple animation of your decals by adjusting their opacity and size over time.

Changing the base size, texture, or position will result in the underlying decal being re-created.

Decals are rendered using a deferred volumetric rendering technique, in order to conform the decal to the moving water surface.

Triton and Transparent Effects

Unity’s architecture only allows native plugins such as ours to render at the end of a Camera’s rendering. This can lead to sorting issues with transparent objects, such as particle effects, since transparent objects should always be rendered last in the scene.

The way around this limitation is to create a separate camera for transparent objects. If you assign your transparent objects to the “transparent FX” layer, you can then use culling masks and the camera depth order to keep transparent objects out of the main camera, which Triton draws over, and into another camera that draws after Triton. You’ll need to ensure the “transparent camera” is kept in sync with the main camera’s orientation by using the same camera controller, and that this transparency camera does not clear the color or depth buffers.

As of Unity 5.1, cameras with deferred shading no longer honor the “don’t clear” flag. This means using a second camera for transparency effects is a little more involved. If you main camera is set to deferred, the transparent camera must be set to legacy deferred for it to work properly. Another alternative is to set both cameras to forward rendering.

An example project illustrating this technique may be found at http://media.sundog-soft.com/TritonRTTProblemTrans.zip

Coastal Effects and Ponds

Triton can produce shorelines and smaller bodies of water as well as open oceans. To take advantage of this, produce your terrain such that it extends below the water surface with realistic “bathymetry” data – that is, your terrain should include the seafloor or the bottoms of the ponds in your scene.

Enable the “Coastal Effects” option in the Triton Prefab object, and Triton will automatically generate a height map from your scene used to determine the water depth at each point. When shallow water is detected, the water’s transparency will be increased and wave displacements will be decreased, leading to smooth water / land transitions and preventing z-fighting artifacts.
The amount of transparency can be adjusted with the “below water visibility” setting. Take care not to set this too high when the camera is above water, as it may result in the water being unrealistically clear. Values of 10-20 meters generally produce good results.

If your shore includes a smoothly sloping seafloor dropping off at a slope of a few degrees, try setting the “breaking wave amplitude” to a realistic wave height and the “breaking wave direction” to point toward the coast. This will result in a breaking wave effect with waves that grow, slow down, and finally spread out as the depth decreases.

Using Multiple Cameras

If your scene contains multiple cameras, associate your primary camera with the TritonPrefab’s “game camera” property. Then, pass any additional cameras to the TritonUnity.AddCamera() method. Each camera will have water rendered relative to its location, but Triton’s physics update will only run once per frame.

If you have multiple cameras, but only one is active at a time, you may use TritonUnity.SwitchCamera() to switch between them at runtime.

Using Triton with Linear Color Space and HDR

Some popular shader packages require your project to be set to linear color space instead of gamma. However, Unity has no visibility into Triton’s shaders and so this will result in Triton’s water being too bright if your camera has HDR enabled as well.

As a workaround, you can modify Triton’s shaders to remove the effect of gamma correction. You will need to edit both the TritonResources/flat-fft-patch.fx and TritonResources/flat-fft.fx files in a text editor.

At the bottom of the PS() function in these shaders, you’ll see the following lines:

#ifndef HDR
finalColor = clamp(finalColor, 0.0f, 1.0f);
#endif
return finalColor;

Replace this code with:

return float4(pow(finalColor.xyz, 2.2), 1.0);

And, that should provide correct results with linear color space.

Troubleshooting

If your application doesn’t work when built into a standalone executable, be sure you read the section above about distributing your application with Triton.

If the orientation of the water seems flipped, you may be using an image effect that causes Unity to render the scene upside down internally without telling Triton about it. However there is a workaround. Inside the TritonUnity.cs file in the UpdateMatrices method, you’ll see this block of code:

if (camera.actualRenderingPath == RenderingPath.DeferredLighting || camera.targetTexture != null)
{
Matrix4x4 pflip = Matrix4x4.Scale (new UnityEngine.Vector3(1.0f, -1.0f, 1.0f));
P = pflip * P;
}

Basically this tries to guess when Unity is rendering upside down, but it misses the case of image effects. Just comment out the if(.. line (put a // before the if statement) to force the flip to happen and it should clear things up.

If there is a gap between your objects and their reflections, try adjusting the value of clipPlaneOffset at the top of TritonReflection.cs.

If the color of the water looks wrong, check a few things:

  • Is the ambient light in the Render Settings set too low?
  • Did you forget to associate a Directional Light with Triton? If not, is that light pointing in the wrong direction?
  • Is something wrong with the cube map you’re passing in? Try removing it, and activate the Auto Generate Cube Map property to see.
  • Did you turn on Use Render Settings Fog, and have too low of a fog density set in the Render Settings? Is the fog color consistent with the time of day?

If you’re not happy with Triton’s performance, check the following:

  • Do you have the latest graphics drivers installed from your video card manufacturer? If Triton can’t take advantage of GPGPU technologies such as CUDA and OpenCL due to outdated drivers, performance will suffer.
  • Is the reflection pass eating up too many resources? Try disabling planar reflections and see if that helps – you may need to customize the TritonReflection class to render only a subset of the scene to the reflection texture. If you’re calling GenerateCubeMap() every frame, ask yourself if you really need to.

If you are seeing jitter or other anomalies near the horizon, check the following:

  • Is your far clipping on your camera too close? It should be at least 50 km for the horizon to look correct.
  • Do you have a sky box or sky dome that is too close to the camera? This could mess up distant reflections on the water. Make sure your sky is out just inside your far clip plane.
  • If all else fails, the setting grid-horizon-offset in the TritonResources/Triton.config file may be used to influence the alignment of Triton’s projected grid with the horizon line. Valid values would be between +- 0.002.

If Unity scripts appear to be missing on game objects and have warnings with compile errors, particularly with Unity 5, try the following:

  • Reimport the offending script in the Project View. The scripts may have outdated API calls from an older version of Unity and needs to be upgraded. Reimporting should force the upgrade, and may update all other offending scripts.
  • Close/reopen your Unity project. This will ensure that all scripts are forced to update and recompile, if all else fails.

If “Triton Editor Tools” is not shown on the menu bar, try the following:

  • Click on the menu bar. This will have Unity update any changes that were to be made to the menu bar, as long as there were no errors in the compilation.
  • Reimport the TritonEditorTools.cs script in Assets/Editor. The script may need to be updated when using it in Unity 5. After doing so, click on the menu bar again to see if the option appeared.
  • Close/reopen your Unity project. This is an end all to force Unity to upgrade any scripts that may need to be upgraded. After the project opens, the “Triton Editor Tools” option should show on your menu bar.

If building a standalone application in Unity 4.6 causes the build to run in full screen mode and it is not possible to exit the license warning dialog box (except using Alt-Tab to focus on the box), force quit the application and rebuild.

If running an Oculus supported application causes visual misrepresentations of the running scene, close the application and re-run. The connection with the Oculus hardware may not have connected properly.

If running Triton in Unity 5 editor causes errors to occur involving the use of SetDirectoryDll, this is a known issue that started to appear in later Unity 5 beta versions. These should have no impact on the running state of Triton in editor nor should it have an impact on standalone builds from Unity 5.

Using Triton with SilverLining

Sundog Software also offers the SilverLining Sky, 3D Clouds, and Weather asset for Unity (available via the Unity Asset Store.) SilverLining and Triton can work together seamlessly by using the following settings:

  • Use the TritonUnity.GenerateCubeMap() script function from a LateUpdate call, to dynamically create a cube map from SilverLining’s skies whenever the skies change.
  • Associate SilverLining’s SilverLiningSunLight (or SilverLiningMoonLight, depending on the time of day) light source as Triton’s directional light.
  • If you’re using fog with Triton, be sure the fog color is updated to be consistent with the time of day.
  • Ensure the scale on the _SilverLiningSky prefab is increased to at least 50km to ensure proper reflections on Triton’s water. Make sure your camera’s far clip distance is set to at least this amount as well.

More to Explore

At a scripting level, much more is possible with Triton – the entire C++ API is available via the TritonClassLibrary C# DLL. Refer to the documentation at http://www.sundog-soft.com/docs/triton/index.html to learn more about what’s available.

Notes for running on OS X

Running Triton on OS X has a few differences from the Windows version. This is due to the nature of the operating system itself. Check the following items to ensure the best possible experience when running on a Mac.

If you have an NVIDIA video card, Triton provides support for CUDA acceleration. To enable this, you must download version 5.5.47 or later of the CUDA driver. Access the latest driver through System Preferences > Other > CUDA. Click ‘Install CUDA Update.’ This driver is required for support on Mac OS X 10.9 Mavericks.

The Intel IPP libraries must be placed along the app when running. There is code in TritonUnity.cs to automatically do this, but if you move the Resources folder and it is not picked up, you may need to manually move them. They are located at Assets > Triton > TritonResources > linux and are all of the *.dylib files in this folder.

There are a few Mac specific items in Triton.config, namely default-grid-resolution-mac and spray-force-point-sprites-mac. These items have been tuned for OS X specific performance, but you may adjust them as your application requires. Please note that the default settings result in large increases in performance (~8 fps per setting).

When building a standalone executable, ensure that you copy Assets/Triton/TritonResources and paste next to the built executable to ensure that Triton runs correctly.

As is with the Windows build, using Triton on Unity 5 on OS X may require you to update the including Triton scripts. Please refer to the “Troubleshooting” section if you see compile warnings and missing Monobehaviour scripts on Triton game objects.

Triton on Unity 5 on OS X gives the same editor option for updating plugin import settings as the Windows version of Triton. Please refer to the “Distributing your Application with Triton – Unity 5” section for more details on how to run this option. Please run this option before you attempt to build a standalone executable.

Getting Support

Feel free to contact us at support@sundog-soft.com if you run into trouble.