# Buoyancy

<figure><img src="/files/en4SZYWBqPlOSWYYWlST" alt=""><figcaption></figcaption></figure>

## How it works

The buoyancy system calculates the entire FFT grid on the CPU, mirroring the GPU implementation. For performance reasons, these calculations are triggered every `BuoyancyUpdateTickRate` (0.2 seconds by default). This should be sufficient for most use cases, such as vessel buoyancy and character swimming. However, if you need updates to occur more frequently, this parameter is exposed in `BP_PlanetaryOcean`.

These CPU calculations run in parallel using the ISPC task system and do not block the game thread. The ready-to-use data can then be sampled by the buoyancy component (for vessels) or the swimming component (for characters) to apply forces. Reading these values is virtually free, because the computed data covers every possible location across all wave cascades. Since the cascades are tiled indefinitely, data is available for the entire ocean sphere.

{% hint style="success" %}
For visualizing Buoyancy Points check `bShowBuoyancyPoints` in the `PlanetaryBounancy` component.
{% endhint %}

`PlanetaryBuoyancy` component must be attached to an Actor to enable floating. This component reads the depth below (or above) water for a specified array of `BuoyancyPoints`. Using this data, it applies forces to the BuoyancyPoints. It also includes built-in gravity.

{% hint style="success" %}
Buoyancy system reacts to the movement of the ocean actor at runtime.
{% endhint %}

## Setting up buoyancy

To set up buoyancy on your Actor, follow these steps:

* Add `PlanetaryBuoyancy` component to your Actor blueprint.
* In the component settings fill the `Buoyancy Points` array. Vector locations it is asking for are in local space (relative to the root). It is recommended to have more than 4 Buoyancy Points for smoother buoyancy simulation. System will sample the water height and apply buoyancy forces at these locations.

<div align="left"><figure><img src="/files/KdHU613vZCu3enfSzks9" alt=""><figcaption></figcaption></figure></div>

* Make the Static Mesh Component you want to float as root component. Static Mesh can have any other components attached to it (meshes, cameras, particles etc.)

{% hint style="warning" %}

* Root component of the vessel should be a static mesh with `Simulate Physics` enabled.
* `Enable Gravity` should be disabled as the plugin applies custom gravity (with gravity direction pointing to the ocean sphere center with the ocean location taken into account)
  {% endhint %}

{% hint style="warning" %}
Static Mesh has to have simple collision added. Polygon count doesn't matter, but the complexity of the collision may affect performance. Make sure, you don't have excessive amount of collision primitives with complex geometry.
{% endhint %}

* If your Actor is added to the level, you can navigate to the Primary Ocean category in the component settings and set the existing in the level `BP_PlanetaryOcean` to the ocean you'd like this Actor to float on. If not set, the Buoyancy Component will assign the first found in the level object of class `APlanetaryOcean` on BeginPlay and use it.

<div align="left"><figure><img src="/files/xFifzGNt06izIWgOkZyW" alt=""><figcaption></figcaption></figure></div>

{% hint style="success" %}
To change the primary ocean at runtime, use `SetPrimaryOcean` function that is exposed to blueprint.
{% endhint %}

* Now you can press Play and tweak the buoyancy settings.

{% hint style="warning" %}
Currently buoyancy does not take into account waves attenuation feature since distance field is only accessible on GPU. That means a boat will float near the shoreline assuming waves have full strength there, although they are faded out using distance field. This might be fixed in the future by introdusing a distance field approximation on CPU using line or sphere traces.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.planetaryoceans.com/guide-v.-2.1/buoyancy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.