Swim

Export

The Swim ability provides surface and underwater movement. It normally starts when the character enters a Water-layer trigger, using the inherited Detect Object Ability Base settings to identify the volume.

Swim has two active movement regimes. Surface swimming keeps the character at a target depth below the calculated surface. Underwater swimming allows vertical movement and applies its own buoyancy while optionally activating an underwater state and consuming Breath.

Setup

Position Swim above the Fall ability but below Dive and Climb from Water.
Perform the water setup.
Set the Detect Object Ability Base parameters. In the demo scene Detect Layers is set to the Water layer.
Set the Start Swim Depth, Surface Swim Depth, and the Surface Height Adjustment.
Add the Swim Capsule Collider Positioner preset to the character’s Capsule Collider Positioner component. This component is located on the Character/Colliders/Capsule Collider GameObject. Ensure the Capsule Collider Positioner’s Rotation Bone and Position Bone fields are set to a Transform on the character. This can be set by enabling the Rotate Collider toggle.
Add the Breath attribute and Drown ability if the character can run out of air.
Specify any Water Effects.

API

Use a water trigger for volume detection and select Water Height Detection Mode: Custom before supplying a sampled world-space surface height. The example below keeps that height updated while the trigger owns entry and exit.

using UnityEngine;
using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.AddOns.Swimming;

public class CustomWaterHeight : MonoBehaviour
{
    [SerializeField] private UltimateCharacterLocomotion m_Character;
    [SerializeField] private float m_SurfaceHeight = 5f;
    private Swim m_Swim;

    private void Start()
    {
        m_Swim = m_Character.GetAbility<Swim>();
    }

    private void Update()
    {
        // Replace this value with the water provider's sample near the character.
        m_Swim.SetWaterSurfacePosition(m_SurfaceHeight);
    }
}

TryStartStopSwim(bool) requests entry or exit, but the current source does not calculate depth correctly without a water collider: it returns the supplied height as depth instead of subtracting the character or neck position. A constant world height therefore cannot provide normal triggerless surface swimming. Retain the trigger for this workflow; a triggerless integration needs a corrected depth calculation in project code.

Key settings

Start Swim Depth

The water depth that the character can start to swim at.

Surface Swim Depth

A threshold used for swim-state transitions and shallow-water exit checks. It does not set the surface buoyancy target.

Surface Height Adjustment

Adjusts the surface buoyancy target relative to the neck’s depth, or the character root when no neck is available. Tune it to align the rig’s surface pose with the visible waterline.

Can Swim Underwater

Can the character swim underwater?

Start Underwater Swim Pitch

Specifies the camera pitch that the character will transition from a surface swim to underwater swim.

Min Underwater Swim Depth

The minimum surface depth that the character can swim underwater.

Start Underwater Swim Name

The button mapping to start swimming underwater. An empty value will prevent the mapping from being used.

Surface Buoyancy Amount

The buoyancy applied during Enter Water From Air and Surface Swim.

Underwater Buoyancy Amount

The buoyancy applied during Underwater Swim when the character is not moving.

Retained Gravity Amount

The percentage that the gravity force is retained each frame after the character enters the water.

Water Height Detection Mode

Specifies the method for detecting the water height:

Collider: Detect the water height based on the collider above the character.
Custom: A custom water height can be set with the SetWaterSurfacePosition method.

Breath Modifier

The breath attribute that should be modified when the character is underwater.

Entrance Splash

Effect that should play when the character enters the water from the air.

Surface Swim Splash

Effect that should play when the character is swimming on the surface.

Underwater Swim Movement

Effect that should play when the character is swimming underwater.

Underwater Bubbles

Effect that should play when the character is swimming underwater.

Underwater State Name

The state that should activate when the character is underwater.

Tune the depth thresholds

Treat the three surface values as a sequence:

Start Swim Depth decides when wading becomes swimming.
Surface Swim Depth governs transitions and shallow-water exit checks.
Surface Height Adjustment tunes the surface buoyancy target relative to the neck, or root when no neck is available.

Set the volume or custom surface height first. Then tune the start and transition thresholds from shoreline gameplay and the height adjustment for the visual waterline. Do not compensate for an incorrect world-space surface value with a large height adjustment.

Start Underwater Swim Pitch defines a view-angle route into underwater movement, while Start Underwater Swim Name provides an explicit input route. An empty input name disables that route. Min Underwater Swim Depth should keep the transition out of water that is too shallow for the underwater collider and animation.

Tune buoyancy and carried momentum

Surface Buoyancy Amount controls buoyancy during airborne water entry and surface swimming. Underwater Buoyancy Amount applies in underwater mode only while the character is not moving. Tune them after the surface target is correct, and test idle and moving behavior separately.

Retained Gravity Amount determines how much incoming gravity continues after entry. A high-speed fall should feel different from walking in, but it should still settle into the swim state without crossing the usable volume or immediately leaving it. Test both entries before changing Dive.

Coordinate the collider and camera

The Swim Capsule Collider Positioner preset rotates and positions the collision shape for the swimming posture. Set its rotation and position bones to stable character transforms and test surface and underwater extremes. An incorrect positioner can cause obstruction or grounding behavior that looks like a water-height error.

Use Underwater State Name for camera, audio, rendering, or character component changes that should remain active only below the surface. Test rapid surfacing to ensure those state values restore cleanly.

Integrate breath and effects

Breath Modifier should reference the same attribute consumed by Drown. Confirm the modifier acts only underwater, then test attribute depletion and recovery separately from the Drown animation. Assign Water Effects after the movement transitions work so a missing particle event is not mistaken for a failed entry.

Troubleshooting

Swim starts too close to shore: increase Start Swim Depth or reshape the shallow part of the volume.
The character floats above or below the mesh: correct the surface height and Water Height Detection Mode, then tune Surface Height Adjustment against the neck/root reference. Surface Swim Depth is a transition threshold, not the floating target.
Underwater mode starts in shallow water: increase Min Underwater Swim Depth and verify the calculated surface height.
The character repeatedly enters and exits Swim: inspect trigger seams, depth near the boundary, and external TryStartStopSwim calls.
Movement works but the collider catches: verify the Swim preset and its position and rotation bones.
Breath never changes: confirm the modifier’s attribute name and that the ability is actually in underwater mode.

Verify in Play Mode

Enter the water from the shore and from a fall. Confirm that Swim starts at Start Swim Depth, settles at the neck/root-relative target set by Surface Height Adjustment, transitions underwater only when allowed, and stops after leaving the volume. If a Breath modifier is configured, remain underwater long enough to verify attribute depletion and Drown’s response to the destination event at Min Value.