# Gravity Field: Usage & Setup Guide >

Note: This Gravity Field system is under active development and may change with upcoming updates.

## Overview `BP_GravityField` is a replicated gravity control volume used to assign gravity behavior to overlapping actors. It supports all field usages: * Directional character gravity * Planetary character gravity * Dynamic character gravity * Zero gravity for characters * Explicit character rotation control * Per-overlap begin and end configuration * Opt-in physics object gravity * Planetary physics object gravity * Directional physics object gravity * Opt-in vehicle gravity * Planetary vehicle gravity * Directional vehicle gravity * Dynamic vehicle gravity * Server-authoritative setup with replicated field settings * Backwards compatibility with existing projects Character gravity is explicit. Your overlap logic chooses which begin or end overlap gravity function to call. Physics object gravity can register overlapping physics bodies automatically when enabled. Vehicle gravity can assign field gravity to overlapping gravity vehicles when enabled. All major systems are opt-in. Existing projects are not changed unless the relevant field feature is enabled or explicitly called. ## Required Setup #### 1. Character Requirements For character gravity, the character must have: * `UGravityMovementComponent` Supported character setups include: * `ATPGravityCharacter` * `AFPGravityCharacter` * Any `ACharacter` using `UGravityMovementComponent` Nothing else is required for basic character gravity setup. #### 2. Physics Object Requirements For simple physics object gravity, the actor needs a simulating `UPrimitiveComponent` that overlaps the field while physics gravity is enabled. For full physics gravity support, the actor should also have: * `UGravityReceiverComponent` `UGravityReceiverComponent` is required or recommended for: * Skeletal meshes * Multi-body actors * Ragdolls * Actors that need authoritative sleep handling * Actors that need optional ragdoll snapshot replication * Actors that may overlap multiple physics gravity fields #### 3. Vehicle Requirements For vehicle gravity, the vehicle should use: * `UGravityVehicleMovementComponent` Vehicle pawns should be based on the gravity vehicle setup so the vehicle movement component can receive gravity from the field instead of relying only on standard Chaos world gravity. For the provided vehicle base setup, use a gravity vehicle pawn such as: * `AGravityVehiclePawn` The vehicle must overlap a field with vehicle gravity enabled. #### 4. Place the Gravity Field Drag `BP_GravityField` into the level. It creates two meshes: * `OverlapMesh` — defines the trigger volume * `SurfaceMesh` — visual and surface reference Set: * `OverlapRadius` * `SurfaceRadius` These replicate automatically. ## Core Concepts #### Begin vs End Overlap Character gravity is split into two independent configurations: * Begin Overlap — what happens when entering the field * End Overlap — what happens when leaving the field Each side has its own gravity mode, direction or center, rotation behavior, dynamic fallback, and tuning values. Physics object gravity and vehicle gravity are field-enabled systems. When enabled, their overlap handling is managed by the field path instead of requiring the same explicit character apply-function routing. ## Character Gravity Modes For both begin and end overlap, set: * `BeginOverlapGravityMode` * `EndOverlapGravityMode` Supported modes are: * `Directional` * `Planetary` * `Dynamic` * `ZeroGravity` * `None` These are replicated enum values. They are not inferred automatically. `None` leaves the current character gravity mode unchanged. ## Directional Character Gravity Use `Directional` when the character should use a fixed world-space gravity direction. Begin overlap uses: * `BGravityDirection` End overlap uses: * `EGravityDirection` These should be normalized direction vectors. Example standard downward gravity: * `(0, 0, -1)` Directional gravity is useful for: * Normal world-down gravity * Sideways gravity zones * Ceiling gravity zones * Wall-walking sections * Fixed-direction gameplay areas ## Planetary Character Gravity Use `Planetary` when the character should be pulled toward a world-space center point. Begin overlap uses: * `BGravityCenter` End overlap uses: * `EGravityCenter` The center is a world-space point that gravity pulls toward. Planetary gravity is useful for: * Planets * Spherical worlds * Asteroids * Gravity wells * Radial walking surfaces ## Dynamic Character Gravity Use `Dynamic` when the character should resolve gravity from nearby surfaces. Dynamic gravity is used for: * Walking around curved surfaces * Wall transitions * Ceiling transitions * Ledges * Loops * Surface-reactive movement Dynamic gravity uses movement component trace and smoothing settings, with field-provided begin and end overlap tunables. ## Zero Gravity Use `ZeroGravity` when the character should enter weightlessness. Call: * `ApplyEnterZeroGravity()` This sets the character to full zero gravity behavior. Zero gravity is replicated and supports local prediction. `ZeroGravityExitGravityScale` controls gravity restoration on exit. Calling any other gravity apply function exits zero gravity automatically, so exit behavior is safe to trigger unconditionally. `bExternalFlyingActive` is respected, so zero gravity does not interfere with custom external flying setups. ## Character Rotation Behavior Rotation behavior is explicit, never inferred. Set: * `BeginOverlapGravityRotationMode` * `EndOverlapGravityRotationMode` Supported rotation modes are: * `Default` * `ForwardBack` * `LeftRight` `Default` uses the normal free geometric rotation behavior. `ForwardBack` limits rotation around the right axis, producing pitch-like gravity transitions. `LeftRight` limits rotation around the forward axis, producing roll-like gravity transitions. Rotation mode applies across gravity modes and is useful for constraining character orientation during specific gravity mechanics. ## Character Field Tunables Each overlap side has independent tuning values. #### High-Precision Math Begin overlap: * `bBUseHighPrecisionMath` End overlap: * `bEUseHighPrecisionMath` High-precision math enables localized `FVector3d` double precision calculations for `Planetary` and `Dynamic` modes. This helps reduce jitter and rounding issues at large world distances by treating the character as a temporary local origin for gravity calculations. ## Directional and Planetary Rotation Tuning Begin overlap: * `BRotationSpeed` * `BRotationStopTolerance` * `BSurfaceLerpSpeed` End overlap: * `ERotationSpeed` * `ERotationStopTolerance` * `ESurfaceLerpSpeed` `BRotationSpeed` and `ERotationSpeed` control how fast gravity rotation smooths toward the new gravity orientation. `BRotationStopTolerance` and `ERotationStopTolerance` control when rotation is considered close enough to stop smoothing. `BSurfaceLerpSpeed` and `ESurfaceLerpSpeed` tune planetary surface smoothing. ## Dynamic Gravity Tuning Begin overlap: * `BDynamicHeadTransitionRotationSpeed` * `BDynamicSurfaceSmoothingSpeed` * `BDynamicEnhancedSmoothingSpeed` * `bBUseEnhancedSmoothing` End overlap: * `EDynamicHeadTransitionRotationSpeed` * `EDynamicSurfaceSmoothingSpeed` * `EDynamicEnhancedSmoothingSpeed` * `bEUseEnhancedSmoothing` These values control dynamic gravity rotation, surface smoothing, and enhanced smoothing behavior. ## Dynamic Predictive Probes Predictive probes are opt-in and off by default. Begin overlap: * `bBUsePredictiveProbes` * `BDynamicWallLerpSpeed` * `BDynamicLedgeLerpSpeed` * `BWallProbeDistance` * `BLedgeProbeDistance` * `BLedgeProbeLength` End overlap: * `bEUsePredictiveProbes` * `EDynamicWallLerpSpeed` * `EDynamicLedgeLerpSpeed` * `EWallProbeDistance` * `ELedgeProbeDistance` * `ELedgeProbeLength` Predictive probes help Dynamic gravity anticipate upcoming walls and ledges for smoother transitions. ## Dynamic Latch and Floor Detection Begin overlap: * `BLatchDistance` * `BFloorDetectionTolerance` End overlap: * `ELatchDistance` * `EFloorDetectionTolerance` Latch distance controls how far the character can remain attached to a detected surface. Floor detection tolerance controls how permissive the system is when validating floor contact under custom gravity. ## Dynamic Character Fallback Dynamic gravity includes a fallback safety net. Begin overlap directional fallback: * `bBUseDirectionalFallback` * `BFallBackDir` End overlap directional fallback: * `bEUseDirectionalFallback` * `EFallBackDir` Begin overlap planetary fallback: * `bBUsePlanetaryFallback` * `BDynamicFallbackCenter` End overlap planetary fallback: * `bEUsePlanetaryFallback` * `EDynamicFallbackCenter` Fallback timers: * `BFallBackTimer` * `EFallBackTimer` If Dynamic gravity cannot maintain or find a valid surface within the fallback timer, gravity falls back to the configured fallback behavior. Directional fallback uses `BFallBackDir` or `EFallBackDir`. Planetary fallback uses `BDynamicFallbackCenter` or `EDynamicFallbackCenter`. Use fallback to prevent floating, invalid surface latching, or permanent wall-cling. ## Applying Character Gravity Character gravity does not auto-route itself. You must call the correct apply function. #### Begin Overlap Apply Functions Use: * `ApplyBeginOverlapGravityDirectional()` * `ApplyBeginOverlapGravityPlanetary()` * `ApplyBeginOverlapGravityDynamic()` * `ApplyEnterZeroGravity()` `ApplyEnterZeroGravity()` is used for zero gravity on either begin or end overlap. #### End Overlap Apply Functions Use: * `ApplyEndOverlapGravityDirectional()` * `ApplyEndOverlapGravityPlanetary()` * `ApplyEndOverlapGravityDynamic()` * `ApplyEnterZeroGravity()` All apply functions: * Run server-authoritative * Resolve the correct `UGravityMovementComponent` * Apply replicated field settings * Return `UGravityMovementComponent` You can chain from the returned movement component or inspect it after applying gravity. ## Character Overlap Routing You control character overlap logic. Required begin overlap pattern: * Cast `OtherActor` to your character * Resolve its `UGravityMovementComponent` * Read `BeginOverlapGravityMode` * Switch on `EEffectiveGravityMode` * Call the matching begin overlap apply function Required end overlap pattern: * Cast `OtherActor` to your character * Resolve its `UGravityMovementComponent` * Read `EndOverlapGravityMode` * Switch on `EEffectiveGravityMode` * Call the matching end overlap apply function Typical routing: * `Directional` → call the directional apply function * `Planetary` → call the planetary apply function * `Dynamic` → call the dynamic apply function * `ZeroGravity` → call `ApplyEnterZeroGravity()` * `None` → do nothing ## Physics Object Gravity Physics object gravity is opt-in and separate from character gravity. Enable it with: * `bApplyPhysicsGravity = true` When enabled, supported overlapping physics bodies are registered automatically. Physics gravity supports: * `Planetary` * `Directional` The physics gravity mode uses: * `BeginOverlapGravityMode` For object physics: * `Planetary` pulls registered physics bodies toward the gravity center. * `Directional` applies gravity along `BGravityDirection`. For directional physics object gravity, configure: * `BGravityDirection` This should be normalized. For standard downward gravity, use: * `(0, 0, -1)` Set physics gravity strength with: * `PhysicsGravityMagnitude` Default Earth-like gravity is approximately: * `980.665` Higher values pull harder. Lower values pull more softly. ## Physics Object Sleep Tuning Physics gravity includes custom sleep handling for supported bodies. Use: * `PhysicsSleepVelocityThreshold` * `PhysicsSleepAccelerationThresholdSq` These control when a body is allowed to sleep under custom gravity. Lower values keep bodies awake longer. Higher values make bodies more prone to sleep. Tune these based on: * Object scale * Gravity strength * Physics gravity mode * Desired settling behavior * Networked physics behavior ## Physics Gravity Capture Use: * `bLatchPhysicsGravityOnExit` When enabled, physics receivers can keep using this field after exiting until they enter another gravity field. This is useful for capture-style gravity behavior where a body should remain under the last assigned physics gravity source instead of immediately restoring engine gravity on exit. ## Physics Receiver Support Simple physics actors can work without a receiver component through generic overlap handling. For full behavior, use: * `UGravityReceiverComponent` Receiver actors get: * Multi-body registration * Active field tracking * Sleep authority * Optional ragdoll snapshot replication * Better multi-field behavior Optional ragdoll correction can be enabled with: * `bEnableRagdollBodySnapshots` Related tunables include: * `RagdollSnapshotInterval` * `RagdollTeleportDistanceThreshold` * `RagdollPositionBlendAlpha` * `RagdollVelocityBlendAlpha` When enabled, the server captures per-body ragdoll transforms and velocities. Clients blend toward the authoritative ragdoll state, and large errors can fall back to teleport-style correction. ## Automatic Physics Registration When a physics body overlaps the field while `bApplyPhysicsGravity` is enabled: * The body is registered * Engine gravity is disabled for that body * The body is added to the active physics gravity set * Custom gravity begins applying automatically When the body leaves: * The body is removed from the active set * Receiver-managed field tracking is updated * Engine gravity is restored when no active physics gravity source remains, unless capture behavior keeps the field active This is automatic for physics object gravity after setup. ## Vehicle Gravity Vehicle gravity is opt-in and separate from character gravity and generic physics object gravity. Enable it with: * `bApplyVehicleGravity = true` Vehicle gravity is applied through: * `UGravityVehicleMovementComponent` Vehicle gravity does not use the generic physics body registration path when field vehicle gravity is enabled. Set vehicle gravity strength with: * `VehicleGravityMagnitude` This is separate from `PhysicsGravityMagnitude` so vehicles and loose physics objects can be tuned independently. ## Vehicle Gravity Modes Vehicle gravity supports: * `Planetary` * `Directional` * `Dynamic` `Planetary` pulls the vehicle toward the active gravity center. `Directional` applies a fixed gravity direction to the vehicle. `Dynamic` resolves gravity from traced surface normals so vehicles can drive across curved surfaces, walls, ceilings, loops, and other non-standard surfaces. ## Dynamic Vehicle Fallback Dynamic vehicle fallback is configured on the field with: * `bUseVehicleDynamicDirectionalFallback` * `bUseVehicleDynamicPlanetaryFallback` * `VehicleDynamicFallbackDirection` * `VehicleDynamicFallbackCenter` Directional fallback uses: * `VehicleDynamicFallbackDirection` Planetary fallback uses: * `VehicleDynamicFallbackCenter` If planetary fallback is enabled, it takes priority over directional fallback. If both fallback modes are disabled, directional fallback is restored for safe behavior. ## Vehicle Movement Component Tuning Vehicle-specific behavior is handled by `UGravityVehicleMovementComponent`. Vehicle tuning can include: * Dynamic vehicle trace channel * Dynamic trace distance * Dynamic trace start offset * Gravity-aware alignment torque * Planetary ground hold * Dynamic ground hold * Gravity-aware sleep * Parked startup behavior Common vehicle movement settings include: * `VehicleDynamicGravityTraceChannel` * `VehicleDynamicGravityTraceDistance` * `VehicleDynamicGravityTraceStartOffset` * `bAlignVehicleUpToGravity` * `GravityAlignmentStiffness` * `GravityAlignmentDamping` * `GravityAlignmentAngleToleranceDegrees` * `MaxGravityAlignmentTorque` * `GroundHoldDownforceCoefficient` * `FrontGroundHoldOffsetCm` * `FrontGroundHoldForceScale` * `VehicleDynamicGroundHoldSpeedCoefficient` * `VehicleDynamicFrontGroundHoldOffsetCm` * `VehicleDynamicFrontGroundHoldForceScale` * `bUseGravityAwareSleep` * `GravityAwareControlInputWakeTolerance` * `GravityAwareSleepSpeedMultiplier` * `GravityAwareHandbrakeSleepSpeedMultiplier` * `bStartParked` * `StartParkedReleaseInputTolerance` Dynamic vehicle driving surfaces must block `VehicleDynamicGravityTraceChannel`, or Dynamic tracing will miss and fallback behavior will be used. ## Automatic Vehicle Assignment When a gravity vehicle overlaps the field while `bApplyVehicleGravity` is enabled: * The field assigns gravity settings to the vehicle movement component * Vehicle gravity magnitude is applied from `VehicleGravityMagnitude` * Vehicle gravity mode, direction, center, or Dynamic trace behavior is updated * Vehicle fallback settings are provided by the field * Alignment, ground hold, sleep, and parking behavior are handled by `UGravityVehicleMovementComponent` When a gravity vehicle leaves the field: * The vehicle movement component is updated from the remaining active field or restored according to fallback behavior * Vehicle gravity remains managed through the gravity vehicle movement component ## Multiple Field Usage Multiple fields can exist in the same level. For characters, your overlap routing decides what happens when entering or leaving each field. For physics objects, `UGravityReceiverComponent` supports active field tracking across multiple overlapping physics gravity fields. Engine gravity is only restored when the final active physics gravity source is exited, unless capture behavior is enabled. For vehicles, overlapping vehicle-enabled fields are handled through `UGravityVehicleMovementComponent`, with field assignment and fallback behavior managed by the vehicle gravity path. Character gravity, physics object gravity, and vehicle gravity can be used in the same field, but they are configured independently. ## Collision and Overlap Requirements The actor must actually overlap the field volume. Required: * Characters must overlap `OverlapMesh` * Physics objects must overlap `OverlapMesh` * Vehicles must overlap `OverlapMesh` * Physics object components must simulate physics * The overlap volume should use simple collision for reliable overlap behavior * Dynamic vehicle driving surfaces must block the configured vehicle trace channel If a character does not overlap correctly, your character overlap logic will not run. If a physics object does not overlap correctly, physics gravity will not register it. If a vehicle does not overlap correctly, vehicle gravity will not be assigned. ## Debugging For physics object debug drawing, use: * `bShowPhysicsDebugs = true` For character visual debugging, enable visual debug support on the gravity movement component: * `bShowVisualDebugs = true` Use debugging to verify: * The actor is overlapping `OverlapMesh` * The correct begin or end overlap path is firing * The expected gravity mode is selected * The correct character apply function is being called * The character has `UGravityMovementComponent` * The physics body is registered * The physics body is awake * The physics component is simulating physics * The physics body is receiving custom acceleration * The vehicle is using `UGravityVehicleMovementComponent` * `bApplyPhysicsGravity` is enabled when testing physics objects * `bApplyVehicleGravity` is enabled when testing vehicles * Dynamic vehicle traces are hitting the intended surfaces * Fallback values are valid * Collision settings are not blocking overlap or trace behavior ## Networking Rules * Gravity changes execute server-authoritatively. * Relevant field properties are replicated. * Character gravity modes, vectors, centers, rotation behavior, and tunables replicate to clients. * Physics gravity settings replicate. * Physics gravity registration is server-authoritative. * Receiver-managed physics sleep state is server-authoritative. * Optional ragdoll snapshot correction is replicated from server to clients. * Vehicle gravity field settings replicate. * Vehicle gravity assignment is server-authoritative where field assignment is involved. * Vehicle gravity movement state is handled through `UGravityVehicleMovementComponent`. * The system works with Iris and legacy replication. ## What This Class Does Not Do * Does NOT decide which character gravity mode to use automatically * Does NOT auto-route character gravity apply functions * Does NOT infer character rotation behavior * Does NOT override custom movement logic * Does NOT enable physics object gravity automatically — `bApplyPhysicsGravity` must be enabled * Does NOT enable vehicle gravity automatically — `bApplyVehicleGravity` must be enabled * Does NOT apply physics gravity to non-simulating components * Does NOT replace correct collision or overlap setup * Does NOT make Dynamic vehicle traces work unless the driven surface blocks the configured trace channel * Does NOT require `UGravityReceiverComponent` for simple single-body physics cases * Does require or recommend `UGravityReceiverComponent` for advanced physics gravity behavior * Does NOT change existing project behavior unless the relevant field feature is enabled or explicitly called ## Intended Design Philosophy * No magic * No hidden state * No hard-coded assumptions * Opt-in by default * Safe for extension * Safe for replication * Safe for custom movement logic * Safe for mixed character, physics object, and vehicle gravity workflows *** --- # 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/gravity-field-usage-and-setup-guide.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.