Skip to content

Swimming Integration

This guide provides a step-by-step walkthrough to help you integrate the Swimming system in your project using Oceanology. By following these instructions, you will be able to create a buoyant swimming experience for your character, enabling them to swim naturally in defined water areas.

Note

Before diving into the swimming setup, make sure you have read the documentation for Water Volume and Buoyancy Configuration. You will need a Water Volume with swimming enabled to define the areas where the swimming interaction will occur.

The guide assumes that users have intermediate skills in Unreal Engine, including:

  • Setting up Animation Blueprints (AnimBP).
  • Working with actor components.
  • Assigning and using custom blueprint events.
  • Configuring input control through the Enhanced Input system.

Overview of the Swimming System

Oceanology uses buoyant swimming to create a semi-realistic swimming experience. This means the character will float gently to the water surface, and if the character drowns (as seen in BP_ThirdPersonCharacter), it will float using ragdoll physics. This buoyant swimming behavior can be customized using the SwimmingBuoyancyForceMultiplier value.

Quick Start Guide

Here is a quick overview of the steps you need to take to configure swimming for your character:

Add Buoyancy and Swimming Components

  1. Open your character class (e.g., BP_ThirdPersonCharacter).

  2. Add the OceanBuoyancyComponent to your character. Configure two pontoons:

  3. FullBody: Set its mode to "Buoyancy" and place it at the center of your character. This pontoon helps maintain balance and buoyancy across the entire character.

  4. Head: Set its mode to "Water Enter Exit Event Only" and place it at the head of your character. This pontoon is used to detect when the character enters or exits the water, ensuring accurate event triggering.

  5. Turn on "Draw Debug Spheres" to visualize and confirm the location of your pontoons. Ensure that the pontoons are placed symmetrically to maintain proper buoyancy and stability.

  6. Add the OceanSwimmingComponent to your character class.

  7. Ensure the "Buoyancy Pontoon Socket for Enter Water Event" within the OceanSwimmingComponent matches the Head pontoon’s name (by default, it is set to "Head").

  8. If you want the swimming system to replicate in a networked environment, enable the "Component Replicates" flag on both the OceanBuoyancyComponent and OceanSwimmingComponent.

Input Control Configuration

You need to configure input controls for swimming. Refer to BP_ThirdPersonCharacter from the Oceanology demo for inspiration. The input setup is different for each user depending on specific needs and character requirements.

Setting Up the Animation Blueprint

This is the most complex part of the setup, as it involves configuring your AnimBP to include swimming states, ensuring smooth transitions between swimming, walking, and other states.

  1. In the Character/Mannequins/Animations directory, there is an ABP_StateObject class used to store all swimming states. This class helps organize and link the swimming states to your animation blueprints. You can either use this class directly or create your own.

  2. Open ABP_Manny (or your character’s AnimBP). You will find a function called "InitStateObject" and a variable named "StateObject". These elements link the swimming states to the animation.

  3. Create a similar Swimming state graph in your character's AnimBP and link the states through Property Access. It may be helpful to refer to visual guides or external tutorials to understand how to set up these transitions. This ensures your swimming animations are triggered at the right time.

Controls

  • Movement Input: Check the Movement Input section of BP_ThirdPersonCharacter for logic related to water movement (e.g., forward, backward, left, right).
  • Surface Locked Swimming: Review the Surface Locked Swimming section for characters swimming along the surface.
  • Swim Fast: The Swim Fast section allows the character to swim faster under certain conditions.
  • Swim Up / Swim Down: Review the Swim Up / Swim Down logic for controlling vertical movement in the water.

Swimming Settings and Events

  • Settings: Most swimming settings have tooltips to explain their purpose. You can also experiment with these settings to fit your specific requirements. The SwimmingBuoyancyForceMultiplier allows you to control the buoyancy effect, while the Underwater section manages bubble effects and other underwater visuals.

  • Events: Customizable events are provided to allow maximum flexibility when setting up swimming logic. Check the UserExampleGraph in BP_ThirdPersonCharacter to see how different events (e.g., entering water, starting/stopping swimming, drowning) can be triggered.

Example: Adding Swimming to a Character

In this example, we will demonstrate how to add swimming functionality to a character using the OceanSwimmingComponent and the OceanBuoyancyComponent.

  1. Create or Open a Character Blueprint

    • Open your character blueprint (e.g., BP_ThirdPersonCharacter).

  2. Add the OceanBuoyancyComponent to the character and configure pontoons for FullBody and Head as described in the Quick Start Guide.

  3. Add the OceanSwimmingComponent

    • Add the OceanSwimmingComponent to the character.
    • Set the Buoyancy Pontoon Socket for Enter Water Event to Head to ensure the system knows where the character enters or exits water.

  4. Enable Swimming in a Water Volume

    • Make sure you have a Water Volume with swimming enabled in your scene. The character must enter this volume to start swimming.

  5. Configure Input Controls

    • Configure the controls for swimming, such as moving forward, backward, and changing speed. Refer to the BP_ThirdPersonCharacter setup for examples.

  6. Set Up the Animation Blueprint

    • Open your character’s AnimBP and create a Swimming state machine.
    • Link the Swimming states to animations using Property Access from the StateObject. This will allow you to properly trigger swimming animations.

Testing the Setup

  • Place your character in a scene with a Water Volume. Test to ensure the character can enter the water, start swimming, and that animations play smoothly. If animations do not trigger correctly, check the state transitions in the AnimBP and ensure the Property Access references are correctly configured.
  • Use the Debug Enabled option in both the Buoyancy and Swimming components to visualize the state transitions and ensure everything is functioning as expected.

Summary

By following these steps, you can integrate a realistic swimming experience into your project using Oceanology. The setup includes configuring the OceanBuoyancyComponent and OceanSwimmingComponent on your character, setting up input controls, and creating the appropriate AnimBP states for swimming. The UserExampleGraph in the BP_ThirdPersonCharacter serves as a helpful reference for assigning events and customizing behaviors during swimming interactions.

For further help or advanced use cases, consult the demo levels or join our Discord community. There, you can find additional examples, share experiences, and get specific answers to your questions.

With a well-configured Swimming System, your character will swim naturally in the water, adding an engaging layer of interaction and immersion to your project.