Skip to content

Buoyancy

Note

Before you start, please read the Water Volume documentation to understand the basics of how the water system works within Oceanology.

Overview of Buoyancy

Oceanology uses the OceanBuoyancyComponent to make actors buoyant in your scene. This component can be added to any actor type, and has been successfully tested with:

  1. AStaticMeshActor (Static Mesh Actors)
  2. ASkeletalMeshActor (Skeletal Mesh Actors)
  3. AActor (Simple generic Actors)

Step-by-Step Buoyancy Setup

  1. Add the OceanBuoyancyComponent to Your Actor

    • Navigate to the actor you want to make buoyant in your scene.
    • Add the OceanBuoyancyComponent to this actor. This will enable the actor to interact with the water surface.

  2. Configure Pontoons

    • Add at least one pontoon (or more) to your OceanBuoyancyComponent. Pontoons are points that help simulate how the object will float and balance on the water.
    • Make sure the pontoon’s mode is set to "Buoyancy".
    • To see where your pontoons are placed relative to the mesh, you can use the "Debug Pontoons" button under the OceanBuoyancyComponent section in the editor. This visualization helps you adjust pontoon positions for proper balance and stability on water.

  3. Add a Static or Skeletal Mesh Component

    • Add a Static Mesh or Skeletal Mesh component to your actor.
    • Remove the DefaultSceneRoot component if it exists, and make the Static or Skeletal Mesh component the root component of your actor. This is essential to ensure the buoyancy calculations work correctly.

  4. Configure Collision Settings

    • Under the Collision section of your actor, enable "Generate Overlap Events". This ensures that the actor can properly interact with the water volume.
    • Also, ensure that the collision settings of your mesh are configured to interact with the water volume. You can use the "PhysicsActor" collision preset as a reference or directly apply it to ensure proper settings.

  5. Enable Physics Simulation and Replication

    • Go to the Physics section and enable "Simulate Physics". This allows the actor to respond to the physics of water, creating realistic movement and flotation.
    • If you want the physics to be replicated across the network (e.g., for multiplayer games), also enable "Replicate Physics to Autonomous Proxy".
    • Note: The mass of your mesh component will impact how the actor behaves in the water. Lighter or heavier masses will alter buoyancy behavior accordingly.

Advanced Buoyancy Settings

  1. Buoyancy Update Interval: Controls how often buoyancy calculations are updated. Setting this to a higher value can improve performance but may reduce accuracy.

  2. Should Check First Init with Fake Collision: Ensures that the first initialization checks collisions in a simplified manner, which can help prevent unwanted interactions during setup.

  3. Default Mesh Density & Water Fluid Density: These values control the density of the object and the water respectively. Adjusting these can directly influence how your object floats or sinks.

  4. Water Fluid Linear and Angular Damping: These settings help control how much the water resists the motion of your actor. Increasing damping will make the object move more slowly and feel "heavier".

  5. Water Velocity Damper: Specifies the effect of water velocity on the actor along different axes. Fine-tuning this can help the actor move more naturally with the current.

  6. Wave XYDirectional Force Enabled: Allows horizontal wave forces to affect the object, adding more realistic wave-driven movement.

  7. Pontoons: Pontoons are key points that determine how the actor interacts with the water. You can add multiple pontoons to simulate a more complex buoyancy behavior, such as balancing large structures.

  8. Debug Options: Enable "Debug Pontoons" to visualize pontoon locations, which is helpful for ensuring correct placement. Note that enabling debug features may impact performance, so use these tools primarily during testing.

  9. Fine-Tuning Buoyancy: There are several options available in the OceanBuoyancyComponent to fine-tune the buoyancy behavior. Most of these options have tooltips that explain their function. Be cautious when changing these settings as radical values can lead to undesired results.

  10. Debugging with Pontoons: You can enable live debug spheres for the pontoons in the Debug section of the OceanBuoyancyComponent. This feature allows you to see how pontoons interact with the water. Keep in mind that enabling debug visualization can impact performance, so use it primarily for testing.

  11. Global Wave Forces: There is an option to allow global wave forces to affect the buoyancy of your actors. This feature is useful if you want your objects to respond to the dynamic movement of waves, adding an extra layer of realism.

  12. Buoyancy Update Interval: You can configure the Buoyancy Update Interval to control how often the buoyancy is recalculated. Lower intervals will provide smoother buoyancy at the cost of performance, while higher intervals can improve performance but may introduce a delay or inaccuracy in buoyancy response.

Example: Adding Buoyancy to a Simple Cube

  1. Create a New Actor

    • In Unreal Engine, create a new Blueprint Actor and name it BP_SimpleBuoyantCube.

  2. Add a Static Mesh Component

    • Inside the newly created Blueprint, add a Static Mesh component.
    • Set the static mesh to a simple cube (you can use the default cube mesh provided by Unreal Engine).
    • Remove the DefaultSceneRoot component and make the Static Mesh the root component.

  3. Add OceanBuoyancyComponent

    • Add the OceanBuoyancyComponent to your BP_SimpleBuoyantCube.
    • This component will allow your cube to interact with the water surface.

  4. Add and Configure Pontoons

    • In the OceanBuoyancyComponent settings, add a pontoon.
    • Set the pontoon’s mode to "Buoyancy".
    • You can use the "Debug Pontoons" button to visualize the pontoon and ensure it is properly positioned for stability.

  5. Enable Physics and Collision Settings

    • Under the Physics section of the Static Mesh, enable "Simulate Physics".
    • Enable "Replicate Physics to Autonomous Proxy" if network replication is required.
    • In the Collision section, enable "Generate Overlap Events" and ensure that the collision settings are configured to interact with the water.
    • Set the collision preset to "PhysicsActor" for best results.

  6. Test Buoyancy in the Scene

    • Drag BP_SimpleBuoyantCube into your scene that contains a water body (e.g., an ocean or lake).
    • Play the scene and observe how the cube floats and reacts to the water. You can use "Debug Pontoons" to see the pontoons in action and adjust their positions if needed.

Summary

By following these steps, you can integrate buoyancy into your actors using Oceanology, ensuring that they interact realistically with the water in your scene. Experiment with pontoon placement, physics settings, and advanced configurations to achieve the desired behavior. If you encounter any issues or need further assistance, please refer to our Discord community, where additional support and updated settings are available.

With the right configuration, your actors will respond naturally to the water dynamics, enhancing the realism and immersion of your project.