# Directional Gravity: Usage & Setup Guide

### What Directional Gravity Does

Directional gravity forces the character's gravity down vector to a fixed world-space direction.

* No traces are used to determine gravity direction
* Rotation is driven entirely by `GravityDirectionVector`
* Updates during movement via `SetGravityDirFromState()`
* Fully replicated and authority-safe
* Supports optional constrained rotation and moving bases

***

### Required Setup

#### 1. Character Setup

Your character **must** use `UGravityMovementComponent`.

* Replace `CharacterMovementComponent` with `GravityMovementComponent`
* Replication must be enabled (default in constructor)
* Works with standard `ACharacter`

***

#### 2. Enable Directional Gravity

Directional gravity is enabled by setting the **effective gravity mode**:

```cpp
GravityMovementComponent->SetEffectiveGravityDirectional(WorldDirection);
```

This **must** be called from a **server-replicated function**.

* Client calls are ignored
* Server computes gravity direction
* Resulting direction and rotation replicate to clients

***

### Setting the Gravity Direction

#### Gravity Direction Rules

* Direction must be world-space
* Direction represents DOWN
* Automatically normalized and sanitized
* Zero or invalid vectors fall back to (0,0,-1)

#### Example Directions

```cpp
// Standard downward gravity
FVector(0, 0, -1);

// Gravity pulling toward +X
FVector(1, 0, 0);

// Gravity pulling toward ceiling
FVector(0, 0, 1);
```

### Rotation Behavior

#### Default Rotation

Character smoothly rotates so its down axis aligns with gravity.

* Rotation uses quaternion stepping when angle is large
* Uses lerp when rotation change is negligible (instant snap)
* Max rotation per frame clamped by `RotationSpeed` \* `DeltaTime` (max 90°)
* Prevents sudden flips during large transitions

#### Rotation Methods

Directional mode uses quaternion rotation for non-trivial changes:

**Quaternion Rotation** (when angle change is significant):

* Angular stepping around computed axis
* Respects `GravityRotationMode` constraints
* Speed controlled by `RotationSpeed`

**Instant Snap** (when close to target):

* Direct assignment to target direction
* No lerp smoothing in directional mode
* Happens when within `RotationStopTolerance`

#### Rotation Constraints (Optional)

You can limit how gravity rotation is applied using:

```cpp
SetGravityRotationMode(EGravityRotationMode::Default);      // Free rotation
SetGravityRotationMode(EGravityRotationMode::ForwardBack);  // Pitch-only (around right vector)
SetGravityRotationMode(EGravityRotationMode::LeftRight);    // Roll-only (around forward vector)
```

#### Modes Explained

* **Default**: Free rotation using the geometric axis between gravity vectors
* **ForwardBack**: Rotation constrained to the character's right axis (pitch-style)
* **LeftRight**: Rotation constrained to the character's forward axis (roll-style)

This is useful for gameplay-driven gravity transitions.

### Moving Platforms (Important)

#### Important Limitation

Unreal does **not** replicate arbitrary base rotation for non-Z gravity.

This can cause:

* Client visual drift
* Z-down fallback on listen servers

#### Solution

Enable:

```cpp
bApplyReplicatedRotationOnMovingBases = true;
```

What this does:

* Tracks base quaternion changes in `UpdateBasedRotation()`
* Applies gravity-aligned yaw compensation
* Fixes client-side visual desync only
* Does not affect physics or collision

If you do not want base rotation at all:

```cpp
bIgnoreBaseRotation = true;  // Default in constructor
```

### Flying Mode Interaction

#### Default Behavior

Directional gravity does not rotate the character while flying.

* Early-out in `RotateCharacter()` when `MOVE_Flying` and `!bApplyGravityRotationWhileFlying`
* `GravityDirCached` is still updated (for other systems)
* No rotation applied

#### Optional

To force gravity-aligned rotation while flying:

```cpp
bApplyGravityRotationWhileFlying = true;
```

Notes:

* Handled in `UpdateCharacterStateBeforeMovement()`
* Rotation is interpolated
* Forward direction is preserved

### Networking & Replication

* Gravity mode is replicated
* Gravity direction is replicated using `FVector_NetQuantizeNormal`
* Direction is set server-side through `SetNewGravityDirection()`
* Rotation smoothing is client-predicted through `RotateCharacter()`
* Authority is enforced inside RPCs (`ServerSetNewGravityDirection`)
* Simulated proxies receive rotation fixes via `ReplicatedComponentRotation`
* Update throttling via `Gravity_ShouldUpdateDirection()` (0.5° threshold)

No manual replication setup is required.

***

### Blueprint Usage (Server-Authoritative)

#### Minimal Blueprint Flow

1. **From the Gravity Field or Gameplay Logic**
   * Detect overlap or trigger condition
2. **Call a *****Server-Replicated***** Function**
   * This function **must run on the server**
   * Gravity changes issued on clients are ignored
3. **Inside the Server Function**
   * Get: `GravityMovementComponent`
   * Call: `SetEffectiveGravityDirectional(Direction)`
4. **Optional (Server Only)**
   * Set gravity rotation mode
   * Enable moving-base replication fixes

***

### Configuration Properties

#### Gravity Direction

```cpp
GravityDirectionVector  // World-space down vector (replicated as FVector_NetQuantizeNormal)
```

#### Rotation Settings

```cpp
RotationSpeed           // Angular step speed for quaternion rotation
RotationStopTolerance  // Snap threshold angle
```

#### Flying

```
bApplyGravityRotationWhileFlying  // Whether to align rotation to gravity while flying (default: false)
```

#### Moving Base

```
bApplyReplicatedRotationOnMovingBases  // Sync simulated proxy rotation on movable bases (default: false)
```

### Summary

* Directional gravity is explicit, deterministic, and trace-free
* Gravity direction = authoritative world-space down vector
* Direction updates during movement from replicated `GravityDirectionVector`
* Rotation uses quaternion stepping for significant changes
* Rotation is smooth, clamped, and optionally constrained
* Moving platforms require opt-in replication fix
* Flying mode support is optional (disabled by default)
* Fully compatible with replication and prediction


---

# 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://replicated-gravity.gitbook.io/replicated-gravity-docs/getting-started/setup-guides-and-tutorials/directional-gravity-usage-and-setup-guide.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.