# Public API

## 📚 **GravityTransform Plugin – API Reference Documentation**

*Version 1.0.0 — Runtime Module*

GravityTransform provides localized custom-gravity zones (box & sphere) and a character-friendly gravity component.\
It enables directional gravity, point gravity, floating islands, spherical-world walking, and physics attraction.

This document lists **all public classes, components, Blueprint functions, and C++ APIs**.

***

## =====================================================================

## **1. Gravity Zones (AGravityZoneBase)**

Base class for all custom gravity areas.

```
AGravityZoneBase
 ├─ AGravityZoneBox
 └─ AGravityZoneSphere
```

***

### 🔶 **1.1 Public Properties**

#### **Gravity Mode**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
EGravityMode GravityMode;   // FixedVector or TowardPoint
```

#### **Gravity Strength**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
float GravityStrength = 980.f;
```

#### **Falloff**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
EGravityFalloff FalloffMode; // NoFalloff / Linear
```

#### **Override World Gravity**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
bool bOverrideWorldGravity = true;
```

#### **Affect Characters**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
bool bAffectCharacters = true;
```

#### **Affect Physics Objects**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
bool bAffectPhysicsObjects = true;
```

***

### 🔶 **1.2 Public Methods**

#### **ComputeGravityAt()**

```cpp
virtual FVector ComputeGravityAt(const FVector& Position) const;
```

Returns the final gravity vector applied at the given world position.

***

#### **IsPointInside()**

```cpp
virtual bool IsPointInside(const FVector& Position) const;
```

***

### 🔶 **1.3 Box Zone (AGravityZoneBox) Additional Properties**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Zone")
FVector BoxExtent;
```

***

### 🔶 **1.4 Sphere Zone (AGravityZoneSphere) Additional Properties**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Zone")
float Radius;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Zone")
bool bUseCustomCenter;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Zone")
FVector CustomCenter;
```

***

## =====================================================================

## **2. CustomGravityComponent (UCustomGravityComponent)**

Component attached to characters or actors that want to receive custom gravity.

***

### 🔷 **2.1 Public Properties**

#### **Enable/Disable Custom Gravity**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
bool bEnableCustomGravity = true;
```

***

#### **Gravity Multiplier**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Gravity")
float GravityMultiplier = 1.f;
```

***

#### **Debug Options**

```cpp
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Debug")
bool bDrawDebugArrow;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Debug")
FLinearColor DebugArrowColor;
```

***

### 🔷 **2.2 Public Methods**

#### **GetGravityDirection()**

```cpp
FVector GetGravityDirection() const;
```

#### **GetGravityStrength()**

```cpp
float GetGravityStrength() const;
```

#### **GetCurrentZone()**

```cpp
AGravityZoneBase* GetCurrentZone() const;
```

#### **HasValidGravity()**

```cpp
bool HasValidGravity() const;
```

***

### 🔷 **2.3 Blueprint Events**

| Event                  | Trigger                            |
| ---------------------- | ---------------------------------- |
| **OnEnterGravityZone** | Character enters a Gravity Zone    |
| **OnExitGravityZone**  | Character leaves a Gravity Zone    |
| **OnGravityUpdated**   | Gravity direction/strength changed |

***

## =====================================================================

## **3. GravityWorldSubsystem (UGravityWorldSubsystem)**

Global gravity manager used to track and query all active zones.

***

### 🔷 **3.1 Public Methods**

#### **RegisterZone()**

```cpp
void RegisterZone(AGravityZoneBase* Zone);
```

#### **UnregisterZone()**

```cpp
void UnregisterZone(AGravityZoneBase* Zone);
```

#### **FindNearestZone()**

```cpp
AGravityZoneBase* FindNearestZone(const FVector& Position) const;
```

#### **GetAllZones()**

```cpp
const TArray<AGravityZoneBase*>& GetAllZones() const;
```

***

## =====================================================================

## **4. Blueprint Function Library (UGravityBlueprintLibrary)**

These functions can be used anywhere in Blueprint.

***

### 🔷 **4.1 GetActorGravityDirection**

```
(Get Actor Gravity Direction)
FVector UGravityBlueprintLibrary::GetActorGravityDirection(AActor* Actor)
```

Returns the gravity direction affecting the Actor.

***

### 🔷 **4.2 GetActorGravityStrength**

```
(Get Actor Gravity Strength)
float UGravityBlueprintLibrary::GetActorGravityStrength(AActor* Actor)
```

Returns computed gravity acceleration in cm/s².

***

### 🔷 **4.3 GetClosestGravityZone**

```
(Get Closest Gravity Zone)
AGravityZoneBase* GetClosestGravityZone(AActor* Actor)
```

***

### 🔷 **4.4 IsActorInsideZone**

```
(Is Actor Inside Zone)
bool IsActorInsideZone(AActor* Actor, AGravityZoneBase* Zone)
```

***

## =====================================================================

## **5. Internal Workflow (for developers)**

```
Every Tick:
    UCustomGravityComponent 
        → queries GravityWorldSubsystem 
        → finds nearest valid GravityZone 
        → calls GravityZoneBase::ComputeGravityAt()
        → outputs GravityDirection + Strength
```

Character Movement / Physics bodies consume this gravity instead of world gravity.

***

## =====================================================================

## **6. Compatibility Notes**

| System                  | Status                                                   |
| ----------------------- | -------------------------------------------------------- |
| Physics Bodies          | ✔ Fully supported                                        |
| Character Movement      | ✔ Supported（uses AddForce or override gravity）           |
| Custom movement systems | ✔ Works with API access                                  |
| Network replication     | ✔ Gravity is deterministic, per-client local calculation |
| Third-party animations  | ✔ No dependency                                          |

***

## =====================================================================

## **7. Summary Table – Public API**

#### **Blueprint API**

| Function                 | Description                      |
| ------------------------ | -------------------------------- |
| GetActorGravityDirection | Get normalized gravity direction |
| GetActorGravityStrength  | Get gravity magnitude            |
| GetClosestGravityZone    | Query nearest zone               |
| IsActorInsideZone        | Check overlap                    |

***

#### **C++ API**

| Class                   | Key Functions                                                 |
| ----------------------- | ------------------------------------------------------------- |
| UCustomGravityComponent | GetGravityDirection(), GetGravityStrength(), GetCurrentZone() |
| AGravityZoneBase        | ComputeGravityAt(), IsPointInside()                           |
| UGravityWorldSubsystem  | RegisterZone(), FindNearestZone()                             |


---

# 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://realms-roar.gitbook.io/gravity-transform-custom-gravity-system/getting-started/publish-your-docs.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.