Physics quality modes
The BuoyancyComponent exposes a PhysicsQuality enum with three values: Async, Mixed, and Runtime. They trade smoothness, latency, and responsiveness against each other. This page is the decision guide.
At a glance
Section titled “At a glance”| Mode | Latency | Smoothness | Best for |
|---|---|---|---|
| Async | 1 frame behind | Highest | Networked play, large vessels, most production cases |
| Mixed | Mostly current | Mid | Single-player with high responsiveness needs |
| Runtime | Current | Lowest | Player-character buoyancy, gameplay reads |
Async (default)
Section titled “Async (default)”Buoyancy is sampled non-blocking from the GPU. The result lands one frame after the sample is queued, which means the physics tick uses heights that are very slightly stale. In return: zero main-thread stall and consistent CPU cost regardless of how many buoyant actors you have.
Pick Async when:
- You’re shipping multiplayer or expect to.
- You have large numbers of buoyant actors (10+).
- You’re on a content-driven schedule and just want it to work: this is the recommended default.
The one-frame latency is invisible at typical wave speeds and never desyncs replicated state.
A blend: the buoyancy tick uses a same-frame estimate where possible, falling back to async sampling otherwise. Smoother than Runtime but spikier than Async: good when you specifically want a single hero vessel to feel ultra-responsive without paying for it everywhere.
Pick Mixed when:
- You have a small number of player-driven vessels (1–4).
- The single-player feel matters more than worst-case CPU consistency.
Runtime
Section titled “Runtime”The buoyancy tick samples heights synchronously each frame. Fully current, but the cost lives on the main thread.
Pick Runtime when:
- A player character needs swim-state to be exactly current (e.g. for a tight underwater traversal).
- You have very few buoyant actors and want zero perceptible latency.
Switching at runtime
Section titled “Switching at runtime”PhysicsQuality is editable on the BuoyancyComponent and can be changed in Blueprint, but in practice, set it on the actor and leave it. Mid-gameplay swaps cause one tick of jumpiness as the sampling pipeline re-warms.