# Physics Gravity: Usage & Setup Guide >

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

#### Overview Physics Gravity is an opt-in system for applying custom gravity to physics-simulated objects. It is intended for physics bodies only, not for explaining the full gravity field system, character gravity, or vehicle gravity. Physics Gravity supports: * Custom planetary gravity for physics-simulated objects * Custom directional gravity for physics-simulated objects * Server-authoritative physics body registration * Multi-body support through `UGravityReceiverComponent` * Custom sleep handling for supported bodies * Optional ragdoll snapshot replication * Automatic overlap-based registration * Full backwards compatibility with existing projects Physics Gravity is off by default. It only runs when explicitly enabled. #### Basic Setup 1. Enable Physics Gravity Use: * `bApplyPhysicsGravity = true` This enables custom gravity for overlapping physics-simulated bodies. When enabled, supported physics bodies that overlap the physics gravity volume are registered automatically and begin receiving custom gravity. 2. Choose Physics Gravity Mode Use: * `BeginOverlapGravityMode` Supported physics gravity modes are: * `Planetary` * `Directional` `Planetary` pulls registered physics bodies toward the gravity center. `Directional` applies gravity in a fixed world-space direction instead of pulling toward a center. Use `Directional` for: * Flat gravity zones * World-down gravity replacement areas * Wall gravity areas * Ceiling gravity areas * Moving directional gravity volumes * Any setup where all physics objects should fall in the same direction For directional physics gravity, configure: * `BGravityDirection` `BGravityDirection` should be normalized. For standard downward gravity, use approximately: * `(0, 0, -1)` 3. Set Gravity Strength Use: * `PhysicsGravityMagnitude` This controls the magnitude of the custom gravity force applied to registered physics bodies. Default Earth-like gravity is approximately: * `980.665` Higher values pull harder. Lower values pull more softly. #### Physics Actor Requirements For a simple physics object, the actor only needs a simulating `UPrimitiveComponent` that overlaps the physics gravity area while `bApplyPhysicsGravity` is enabled. For full 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 areas #### Collision and Overlap Requirements The physics object must actually overlap the physics gravity area. Required: * The object must overlap `OverlapMesh` * The relevant `UPrimitiveComponent` must simulate physics * The overlap volume should use simple collision for reliable overlap behavior If the object does not overlap correctly, Physics Gravity will not register the body. If the component is not simulating physics, custom physics gravity will not be applied. #### How Physics Gravity Works When a supported physics body overlaps while Physics Gravity 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 This registration behavior is automatic after setup. #### Planetary Physics Gravity Use `Planetary` when physics objects should fall toward a center point. In `Planetary` mode, the gravity direction is calculated from the body position toward the active gravity center. This is useful for: * Planets * Spherical worlds * Asteroids * Localized gravity wells * Radial pull zones #### Directional Physics Gravity Use `Directional` when physics objects should fall in one consistent direction. Set: * `BeginOverlapGravityMode = Directional` Then configure: * `BGravityDirection` Examples: Standard downward gravity: * `(0, 0, -1)` Upward gravity: * `(0, 0, 1)` Sideways gravity: * `(1, 0, 0)` `BGravityDirection` should be normalized. If directional gravity behaves incorrectly, verify that the direction is valid and not zero-length. #### Sleep Tuning Physics Gravity includes custom sleep handling for supported bodies. Use: * `PhysicsSleepVelocityThreshold` * `PhysicsSleepAccelerationThresholdSq` These control when a physics body is allowed to sleep while under custom gravity. Lower values make bodies stay awake longer under strong gravity. Higher values make bodies more permissive to sleep. Tune these based on: * Object scale * Gravity strength * Physics gravity mode * Desired settling behavior * Networked physics behavior If an object appears stuck asleep or fails to respond correctly, review these sleep settings. #### Optional Ragdoll Snapshot Replication If using `UGravityReceiverComponent`, 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. This is optional and intended for advanced ragdoll use cases. #### Multiple Physics Gravity Areas `UGravityReceiverComponent` supports active field tracking across multiple overlapping physics gravity areas. This allows bodies to remain valid while overlapping more than one active gravity source. Engine gravity is only restored when the final active physics gravity source is exited. Use `UGravityReceiverComponent` for reliable multi-body and multi-overlap behavior. #### Debugging Enable physics debug drawing with: * `bShowPhysicsDebugs = true` Use debugging to verify: * The body is overlapping correctly * The body is registered * The body is awake * The component is simulating physics * The body is receiving custom acceleration * The expected physics gravity mode is being used * The directional gravity vector is valid * Collision setup is not blocking registration If a physics object is not reacting, check: * `bApplyPhysicsGravity` is enabled * The component is simulating physics * The object overlaps `OverlapMesh` * The object is not asleep incorrectly * `PhysicsGravityMagnitude` is high enough * `BeginOverlapGravityMode` is set as intended * `BGravityDirection` is valid when using `Directional` #### Networking Rules * Physics Gravity registration is server-authoritative. * Relevant physics gravity settings are replicated. * Receiver-managed sleep state is server-authoritative. * Optional ragdoll snapshot correction is replicated from server to clients. * Physics Gravity works with Iris and legacy replication. #### What Physics Gravity Does Not Do * Does NOT enable itself automatically — `bApplyPhysicsGravity` must be turned on * Does NOT apply to non-simulating components * Does NOT replace correct collision and overlap setup * Does NOT require `UGravityReceiverComponent` for simple single-body cases * Does require or recommend `UGravityReceiverComponent` for multi-body, skeletal, ragdoll, sleep-authoritative, and multi-overlap use cases * Does NOT infer whether a body should use `Planetary` or `Directional` gravity unless the mode is configured * Does NOT infer whether a body should use ragdoll snapshot replication unless configured * Does NOT change existing project behavior unless Physics Gravity is explicitly enabled #### Intended Design Philosophy * No magic * No hidden state * Opt-in by default * Safe for extension * Safe for replication * Safe for mixed character and physics-object 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/physics-gravity-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.