# Vehicle Gravity: Usage & Setup Guide ## Overview This guide covers custom gravity setup and usage for Chaos vehicles using `UGravityVehicleMovementComponent`. Vehicle Gravity is intended only for gravity-aware Chaos vehicles. It does not explain character gravity, generic physics-object gravity, or the full gravity field system. Vehicle Gravity supports: * Directional vehicle gravity * Planetary vehicle gravity * Dynamic surface-normal vehicle gravity * Field-driven vehicle gravity assignment * Custom vehicle gravity magnitude * Dynamic fallback behavior * Gravity-aware vehicle alignment * Planetary and Dynamic ground-hold tuning * Gravity-aware vehicle sleep * Optional parked startup behavior * Server-authoritative gravity state replication * Compatibility with Iris and legacy replication Vehicle Gravity is opt-in. It only runs when the vehicle uses `UGravityVehicleMovementComponent` and the relevant gravity state is assigned by a field, startup setup, or API call. ## Required Vehicle Setup Vehicles should use: * `UGravityVehicleMovementComponent` Vehicle pawns should be based on the gravity vehicle setup so the movement component can receive and apply custom gravity 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 be a Chaos vehicle. This system does not apply to non-Chaos vehicle movement components. ## Field-Driven Vehicle Setup To let a gravity field assign vehicle gravity automatically, the field must have: * `bApplyVehicleGravity = true` When a vehicle using `UGravityVehicleMovementComponent` overlaps a vehicle-enabled gravity field, the field applies vehicle gravity settings through the vehicle movement component. Vehicle gravity is separate from character gravity and generic physics-object gravity. Enabling physics-object gravity does not enable vehicle gravity. Vehicle gravity uses: * `bApplyVehicleGravity` Generic physics-object gravity uses: * `bApplyPhysicsGravity` These are independent systems. ## Vehicle Gravity Strength Use: * `VehicleGravityMagnitude` This controls the acceleration magnitude applied to gravity vehicles. It is intentionally separate from `PhysicsGravityMagnitude` so vehicles and loose physics objects can be tuned independently. Higher values pull the vehicle harder. Lower values pull the vehicle more softly. ## Vehicle Gravity Modes Vehicle Gravity supports: * `Planetary` * `Directional` * `Dynamic` ## Planetary Vehicle Gravity Use `Planetary` when the vehicle should be pulled toward an active gravity center. This is useful for: * Planets * Spherical worlds * Asteroids * Curved tracks * Radial driving surfaces * Large gravity wells In Planetary mode, the vehicle gravity direction is calculated from the vehicle position toward the active gravity center. ## Directional Vehicle Gravity Use `Directional` when the vehicle should receive gravity in a fixed direction. This is useful for: * Standard world-down driving * Flat directional gravity zones * Wall-driving areas * Ceiling-driving areas * Moving gravity zones * Linear artificial-gravity setups Directional vehicle gravity applies a consistent gravity vector rather than calculating gravity from a center point. ## Dynamic Vehicle Gravity Use `Dynamic` when the vehicle should resolve gravity from traced surface normals. Dynamic vehicle gravity is useful for: * Curved roads * Loops * Walls * Ceilings * Spherical tracks * Non-standard driving surfaces * Fast-changing surface transitions Dynamic mode traces along the vehicle's down axis to find the active driving surface. The hit surface normal becomes the basis for the vehicle gravity direction. For Dynamic vehicle gravity, tune: * `VehicleDynamicGravityTraceChannel` * `VehicleDynamicGravityTraceDistance` * `VehicleDynamicGravityTraceStartOffset` The driven surface must block: * `VehicleDynamicGravityTraceChannel` If the surface does not block the configured trace channel, the Dynamic trace can miss and fallback behavior will be used. ## Dynamic Vehicle Trace Tuning Use: * `VehicleDynamicGravityTraceDistance` This controls how far the vehicle traces along its down axis to find the active driving surface. Use: * `VehicleDynamicGravityTraceStartOffset` This offsets the trace start above the vehicle along its up axis. This helps prevent traces from starting inside the surface. Use: * `VehicleDynamicGravityTraceChannel` This selects the collision channel used by Dynamic vehicle gravity traces. Make sure the surfaces the vehicle should drive on block this channel. ## Dynamic Vehicle Fallback Dynamic vehicle fallback is used when the Dynamic trace misses. Configure fallback 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. Use fallback to prevent the vehicle from losing a valid gravity direction when it temporarily leaves a surface, jumps, crosses gaps, or misses a trace. ## Vehicle Alignment Vehicle alignment can rotate the vehicle's up direction toward the active gravity up direction. Use: * `bAlignVehicleUpToGravity` * `GravityAlignmentStiffness` * `GravityAlignmentDamping` * `GravityAlignmentAngleToleranceDegrees` * `MaxGravityAlignmentTorque` When enabled, the movement component applies smooth torque to align the vehicle with the current gravity orientation. * Increase stiffness for stronger alignment. * Increase damping to reduce oscillation. * Use `MaxGravityAlignmentTorque` to cap the torque applied. * Disable `bAlignVehicleUpToGravity` if the vehicle should rely only on suspension, wheel contact, and physical body motion after gravity is assigned. ## Vehicle Ground Hold Ground hold helps keep the vehicle seated on curved, inverted, or fast-changing surfaces. For planetary ground hold, tune: * `GroundHoldDownforceCoefficient` * `FrontGroundHoldOffsetCm` * `FrontGroundHoldForceScale` For Dynamic vehicle ground hold, tune: * `VehicleDynamicGroundHoldSpeedCoefficient` * `VehicleDynamicFrontGroundHoldOffsetCm` * `VehicleDynamicFrontGroundHoldForceScale` Higher values hold the vehicle harder to the surface. Lower values reduce forced grip, suspension compression, and nose-down behavior. If the vehicle launches off curved surfaces too easily, increase ground hold carefully. If the vehicle feels glued to the surface or suspension is over-compressed, reduce ground hold. ## Gravity-Aware Sleep Vehicle Gravity includes gravity-aware sleep behavior so vehicles can settle correctly on arbitrary gravity directions instead of relying only on world `Z`. Use: * `bUseGravityAwareSleep` * `GravityAwareControlInputWakeTolerance` * `GravityAwareSleepSpeedMultiplier` * `GravityAwareHandbrakeSleepSpeedMultiplier` Gravity-aware sleep can consider vehicle speed, grounded wheels, control input, handbrake state, and alignment relative to the current gravity up vector. This helps vehicles remain parked on planets, walls, ceilings, curved tracks, and other non-standard surfaces without sliding, jittering, or waking from tiny input noise. If a vehicle will not stay parked, review: * `bUseGravityAwareSleep` * `GravityAwareSleepSpeedMultiplier` * `GravityAwareHandbrakeSleepSpeedMultiplier` * `GravityAwareControlInputWakeTolerance` * Whether the handbrake is engaged * Whether throttle or brake input is being applied * Whether control input has small stick drift * Whether the vehicle is actually grounded * Whether alignment torque or ground hold is too aggressive ## Parked Startup Optional parked startup uses: * `bStartParked` * `StartParkedReleaseInputTolerance` When enabled, the vehicle starts in a parked state until throttle or brake input releases it. Steering alone does not release parked mode. Use parked startup for vehicles placed on unusual gravity surfaces where they should remain stable until the player intentionally drives. ## How Field-Driven Vehicle Gravity Works When a gravity vehicle overlaps a field with `bApplyVehicleGravity` enabled: * The field detects the vehicle through overlap * The field resolves the vehicle's `UGravityVehicleMovementComponent` * The field assigns the active vehicle gravity mode * The field applies `VehicleGravityMagnitude` * The field provides the needed direction, center, Dynamic behavior, or fallback settings * The movement component applies custom gravity through the vehicle simulation path * Vehicle alignment, ground hold, sleep, and parking behavior are handled by `UGravityVehicleMovementComponent` Vehicle gravity is applied through the vehicle movement component, not through the generic physics body registration path. ## Engine Gravity Suppression Use: * `bDisableWorldGravityWhenCustomGravityActive` When enabled, the vehicle movement component manages the engine's default gravity flag while custom vehicle gravity is active. This helps prevent force doubling, where standard Chaos world gravity and custom vehicle gravity both affect the vehicle at the same time. Use this when the vehicle should be driven entirely by the custom gravity state. ## Leaving A Vehicle Gravity Field When the vehicle leaves a vehicle-enabled field: * The vehicle movement component is updated from the remaining active field, if one is available * The vehicle gravity state may be restored or changed according to configured fallback behavior * Vehicle gravity remains managed through `UGravityVehicleMovementComponent` The vehicle does not switch to generic physics-object gravity when field vehicle gravity is enabled. ## Multiple Vehicle Gravity Fields Vehicles can move through overlapping vehicle-enabled gravity fields. The vehicle movement component maintains the active gravity state, and the latest valid applied field state can override the previous state. This allows transitions across: * Planetary systems * Space stations * Gravity tunnels * Wall-driving sections * Dynamic surface tracks * Overlapping artificial-gravity volumes For predictable results, avoid ambiguous overlaps where multiple fields continuously fight to assign different gravity states unless that behavior is intentional. ## API-Driven Vehicle Gravity Vehicle gravity can also be controlled directly through the vehicle movement component instead of only through fields. Use API-driven assignment when gravity should be controlled by gameplay code, scripted events, abilities, vehicles entering special states, or custom systems. Field-driven, startup-overridden, and API-set gravity should be treated as explicit sources of vehicle gravity. The system does not guess which source should win unless your setup applies or clears a state. ## Debugging Use Chaos vehicle and physics debug tools to inspect behavior. Standard Chaos vehicle debug commands remain compatible, such as: * `p.Vehicle.ShowDebug` Use debugging to verify: * The vehicle uses `UGravityVehicleMovementComponent` * The vehicle overlaps the intended vehicle gravity field * The field has `bApplyVehicleGravity` enabled * `VehicleGravityMagnitude` is set correctly * The expected vehicle gravity mode is active * The vehicle's up direction aligns with the gravity up direction * Dynamic vehicle traces hit the intended surface * The driven surface blocks `VehicleDynamicGravityTraceChannel` * Fallback settings are valid when Dynamic traces miss * Ground hold is not too weak or too strong * Alignment torque is not too weak or too strong * The vehicle is not being affected by both world gravity and custom gravity unintentionally * Gravity-aware sleep settings are not preventing wake or causing unwanted wake If Dynamic vehicle gravity is not working, check: * `VehicleDynamicGravityTraceChannel` * `VehicleDynamicGravityTraceDistance` * `VehicleDynamicGravityTraceStartOffset` * Surface collision response * Fallback settings * Whether the vehicle is close enough to the intended driving surface ## Networking Rules * Vehicle gravity assignment is server-authoritative where field assignment is involved. * Vehicle gravity state is handled through `UGravityVehicleMovementComponent`. * Relevant vehicle gravity field settings are replicated. * Vehicle movement state updates from the replicated gravity state. * The server remains the source of truth for gravity transitions. * Vehicle gravity works with Iris and legacy replication. ## What Vehicle Gravity Does Not Do * Does NOT apply to non-Chaos vehicles * Does NOT work without `UGravityVehicleMovementComponent` * Does NOT require user-authored Blueprint Tick logic for gravity * Does NOT require manual field handling when using vehicle-enabled gravity fields * Does NOT enable itself automatically — `bApplyVehicleGravity` must be enabled for field-driven vehicle gravity * Does NOT use generic physics-object gravity when field vehicle gravity is enabled * Does NOT make Dynamic vehicle traces work unless the driven surface blocks the configured trace channel * Does NOT replace correct vehicle collision, wheel, suspension, or surface setup * Does NOT prevent bad tuning from causing sliding, over-compression, flipping, or jitter * Does NOT change existing vehicle behavior unless custom vehicle gravity is explicitly assigned or enabled ## Intended Design Philosophy * Drop-in Chaos compatibility * Explicit gravity control * No hidden gravity source guessing * Opt-in by default * Network-first vehicle gravity state * Physics-correct chassis and suspension behavior * Safe for planetary, directional, and Dynamic vehicle gravity workflows * Safe for mixed character, physics object, and vehicle gravity projects --- # 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/vehicle-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.