**Overview**
**Gravity Transform – Custom Gravity Zones** is a lightweight C++ plugin that adds **local gravity fields** to Unreal Engine, without modifying engine source.
It is built on:
* **UWorldSubsystem** – to manage gravity zones globally;
* **Actor Components** – `CustomGravityComponent` to apply forces per actor;
* **Blueprint Function Library** – easy access to current gravity direction, acceleration and zone info.
With a few clicks you can drop **box or sphere zones** into your level, choose a gravity mode, and let physics bodies or characters be pulled towards your custom gravity instead of the default world gravity.
> Focus: **environment & physics gravity**\
> Not a full “walk-on-planets” character controller.
***
#### ✨ Key Features
**1. Local Gravity Zones**
* Box (`GravityZone_Box`) and Sphere (`GravityZone_Sphere`) shapes
* Each zone has its own:
* Gravity **mode**
* Strength
* Priority
* Filters (what objects it affects)
* Works alongside Unreal’s default world gravity – outside all zones you fall normally.
***
**2. Two Gravity Modes**
* **Fixed Vector**
* Gravity always points in a fixed direction (like wind tunnels or a sideways gravity room).
* In the editor, an arrow gizmo shows the direction; drag it to aim.
* **Toward Point**
* Objects are attracted toward a point (like a planet, black hole or gravity sphere).
* A small sphere gizmo represents the attractor; drag it to move the gravity center.
* Uses a configurable **MinDistance** to avoid extreme acceleration very close to the point.
***
**3. Per-Actor Gravity Component**
Attach **`CustomGravityComponent`** to any actor you want to be affected:
* Works for:
* Physics bodies (`Simulate Physics` enabled)
* Characters / Pawns (uses their existing movement)
* Per-actor **`GravityMultiplier`**:
* Scale zone strength per object (e.g. heavy stone feels 0.5×, light box 2×)
* Simple on/off control:
* Toggle gravity logic per actor from Blueprint or C++
***
**4. Zone Priority & Overlap Handling**
* Each zone has a **Priority** value.
* When multiple zones overlap:
* The **highest-priority** zone wins for that location.
* This makes it easy to:
* Define a large “global” zone with low priority
* Override small local areas with higher-priority zones (e.g. a strong gravity pit inside a weaker global field).
***
**5. Blueprint Utility Library**
The plugin includes a **Blueprint function library** (no engine code modifications required) with helpers such as:
* Get current gravity for an actor:
* **GetActorGravityDirection**
* **GetActorGravityAcceleration**
* Query zones:
* Check whether a point is inside any zone
* Get the active zone affecting an actor (if any)
* Project vectors onto gravity “up” / “down” for your own logic:
* Great for custom VFX, UI arrows, or gameplay checks (“Is the player moving against gravity?”).
These functions are designed to be future-proof so you can later plug in a custom character movement system or a separate “gravity character” plugin reusing the same API.
***
**6. Debug Visualization & Editor Workflow**
* Optional **debug arrows** inside zones:
* Visualize gravity direction field, with adjustable density and length;
* Can be turned off at runtime for performance / cleanliness.
* Simple gizmos for:
* Zone bounds (box / sphere)
* Fixed Vector direction arrow
* Toward Point attractor sphere
* Clean separation:
* No engine source edits
* No changes to global project settings required
***
#### 🎮 Typical Use Cases
* Floating islands with local “down” direction
* Gravity wells that pull physics debris or pickups toward a point
* Sideways or upside-down gravity rooms for puzzle stages
* Magnetic or tractor-beam style effects
* Boss skills that temporarily change gravity direction or strength in an area (via Blueprint)
***
#### ⚠️ Important Notes & Limitations (Character Movement)
This plugin focuses on **computing and applying gravity**, not on replacing Unreal’s **CharacterMovementComponent**.
**What it does for characters:**
* Changes the gravity **vector** and **acceleration** that characters experience in the air;
* Characters will fall, hover or be pulled toward the zone’s gravity direction when not grounded;
* You can query gravity direction in Blueprint and use it to drive your own movement logic, animations or camera.
**What it does *****not***** do:**
* Does **not** implement a full “walk on any surface / planet” controller;
* Does **not** automatically rotate the capsule and feet to align with curved surfaces;
* Grounded walking still uses your project’s existing character movement logic.
* For example, walking into gravity “headwind” will mostly feel like normal movement unless you add your own speed scaling or input logic.
If you need:
* Complex 360° planet walking
* Wall-running, ceiling walking
* Fully custom movement animations aligned to arbitrary surfaces
…you will still need a custom movement system (Blueprint or C++) or a separate dedicated character-movement plugin.\
**Gravity Transform** is designed to be the **gravity backend** you can build those systems on
*
---
# 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/readme.md?ask=
```
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.