> For the complete documentation index, see [llms.txt](https://docs.planetaryoceans.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetaryoceans.com/guide-v.-2.1/buoyancy-performance-and-optimization.md).

# Buoyancy Performance & Optimization

The Buoyancy system in Planetary Oceans calculates wave displacement on the CPU to apply physics forces to floating objects. 

{% hint style="success" %}

#### Asynchronous Computation

CPU FFT calculations run on **background worker threads** using ISPC's (Intel SPMD Program Compiler) parallel task system. They do not block the game thread, so the performance cost shows up as increased **overall CPU usage** rather than frame time spikes. This means:

* Your game thread remains responsive even during FFT computation

However, if your CPU cores are already saturated, additional FFT work can still impact frame rate indirectly through resource contention.
{% endhint %}

This page covers performance considerations and the new **per-cascade CPU compute controls** that allow you to fine-tune buoyancy performance based on your specific needs.

#### Understanding FFT Cascades

Planetary Oceans uses **4 FFT cascades** to represent different wave frequencies:

* **Cascade 0**: Shortest waves (ripples) — \~25m tile size by default
* **Cascade 1**: Medium-short waves — \~28m tile size
* **Cascade 2**: Medium-long waves — \~432m tile size
* **Cascade 3**: Longest waves (swell) — \~2000m tile size

All 4 cascades are combined to create the final ocean surface you see. The GPU always renders all cascades regardless of CPU settings.

#### Per-Cascade CPU Compute Toggle

Starting in version 2.1, you can independently **enable or disable each cascade** for CPU buoyancy calculations. This is found in the **Buoyancy** section of `BP_PlanetaryOcean`:

* `Compute Cascade 0 on CPU` (shortest waves)
* `Compute Cascade 1 on CPU`
* `Compute Cascade 2 on CPU`
* `Compute Cascade 3 on CPU` (longest waves / swell)

**Default**: All cascades enabled (preserves behavior from previous versions)

**How It Works**

When you disable a cascade:

* **GPU rendering continues** — the ocean surface visually displays all wave frequencies
* **CPU buoyancy ignores that cascade** — floating objects don't respond to those wave frequencies
* **Performance improves** — each disabled cascade reduces buoyancy computation cost

{% hint style="info" %}
The visual ocean surface and physical buoyancy are intentionally decoupled. If you disable short-wave cascades (0 and 1), you'll still **see** small ripples on the water, but large ships won't **react** to them — which is physically correct, as large vessels don't respond noticeably to small ripples.
{% endhint %}

#### Performance Benchmarks

Performance was measured with a **256×256 FFT grid** and **AVX2 CPU** (AMD Ryzen 9 5950X) on a typical scene:

| Configuration            | CPU Time | Speedup vs All |
| ------------------------ | -------- | -------------- |
| All 4 cascades (default) | 8.0 ms   | 1.0×           |
| Cascades 2 + 3 only      | 4.0 ms   | 2.0×           |
| Cascade 3 only           | 2.0 ms   | **4.0×**       |

{% hint style="warning" %}
The measured milliseconds represent **worker thread time**, not game thread stalls. On multi-core CPUs, this work happens in parallel with gameplay logic.
{% endhint %}

Each disabled cascade saves approximately **2.0 ms** of CPU time per buoyancy update.

#### Recommended Configurations

Choose cascade settings based on **which cascades make the most impact** on the ocean shape (it depends on your per-cascade parameters) and based on the **size of your floating objects**:

**Large Ships (>20 meters):** Cascade 3 (or 2) only

**Medium Boats (5-20 meters):** Cascades 2 + 3 (or 1 + 2)

**Small Boats and characters (<5 meters)**: Cascades 1 + 2 + 3 (or all 4)

#### Performance Debugging

To monitor buoyancy CPU cost in real-time, enable **Show CPU FFT Performance** in the Buoyancy section of the ocean actor:

```
✓ Show CPU FFT Performance
```

{% hint style="warning" %}
Buoyancy calculations run at the rate specified by `Buoyancy Update Tick Rate` (default: 0.15 seconds). If you need more responsive physics, reduce this value — but remember each update costs the full FFT calculation time.
{% endhint %}