# Public API ## UGravityVehicleMovementComponent – Public API (v2.6.0) #### Setters (Blueprint / C++) * **SetEffectiveGravityDirectional(FVector WorldDirection, double Magnitude = 980.665)** — Sets a normalized world-space direction and magnitude for Directional mode. Replicated through the authoritative GravityVehicleState. Call from the server or an owning client. * **SetEffectiveGravityPlanetary(FVector WorldCenter, double Magnitude = 980.665)** — Sets a world-space attraction point and magnitude for Planetary mode. * **SetEffectiveZeroGravity()** — Disables gravity forces on the vehicle. * **ClearCustomGravity()** — Restores the default world gravity behavior and re-enables engine gravity if `bDisableWorldGravityWhenCustomGravityActive` is true. #### Getters (Blueprint / C++) * **GetEffectiveGravityDirection()** — Returns the current normalized world-space gravity vector. * **GetEffectiveGravityUpDirection()** — Returns the current "Up" vector (negative gravity direction) used for vehicle alignment. * **GetGravityMagnitude()** — Returns the current gravity acceleration magnitude (cm/s²). #### Configuration / Blueprint Properties #### **Gravity Vehicle | Startup** * **bUseStartupGravityOverride** — If enabled, the vehicle ignores world gravity on spawn and immediately applies the configured startup state. * **StartupGravityMode** — Initial mode: `Directional`, `Planetary`, or `Zero Gravity`. * **StartupGravityDirection** — Initial direction for `Directional` mode. * **StartupGravityCenter** — Initial center point for `Planetary` mode. * **StartupGravityMagnitude** — Initial gravity force (default: 980.665). #### **Gravity Vehicle | Ground Hold** * **GroundHoldDownforceCoefficient** — Scales the extra inward acceleration used to keep the vehicle seated on curved surfaces (planets, loops) at high speeds. * **FrontGroundHoldOffsetCm** — Forward offset for hold torque calculation. Positive values bias the hold toward the front tires; lower values reduce nose-down behavior. * **FrontGroundHoldForceScale** — Independent scale for the front-biased hold torque. #### **Gravity Vehicle | Alignment** * **bAlignVehicleUpToGravity** — Toggles the smooth torque-based alignment system that rotates the vehicle to match the gravity vector. * **GravityAlignmentStiffness** — Controls the strength of the alignment torque. Higher = snappier; Lower = smoother. * **GravityAlignmentDamping** — Reduces overshoot and wobbling during transitions. * **GravityAlignmentAngleToleranceDegrees** — Angle error allowed before alignment torque is applied. * **MaxGravityAlignmentTorque** — Caps the maximum torque the alignment system can apply. #### **Gravity Vehicle | Sleep** * **bUseGravityAwareSleep** — Enables custom sleep logic that works on arbitrary gravity directions (walls, planets) instead of world-Z. * **GravityAwareControlInputWakeTolerance** — Input threshold required to wake the vehicle (prevents minor stick drift from waking parked cars). * **GravityAwareSleepSpeedMultiplier** — Multiplier for the Chaos sleep speed threshold. * **GravityAwareHandbrakeSleepSpeedMultiplier** — Independent sleep threshold multiplier used when the handbrake is engaged. #### **General** * **bDisableWorldGravityWhenCustomGravityActive** — Automatically toggles Unreal's internal `bEnableGravity` flag to prevent "double gravity" when a custom mode is active. #### Key Notes * **Inheritance**: Inherits from `UChaosWheeledVehicleMovementComponent`, making it a drop-in replacement for standard Chaos vehicles. * **Networking**: Uses `FGravityVehicleState` for replicated gravity data and server-reliable RPCs for authoritative state changes. * **Iris Ready**: Includes Iris replication support via `RegisterReplicationFragments`. * **Simulation**: Uses a custom Chaos vehicle simulation and overrides vehicle simulation/sleep behavior so physics respects the local gravity vector. *** ## AGravityField – Public API (v2.6.0) #### Gravity Mode / Rotation Settings (Blueprint / C++) * **BeginOverlapGravityMode** — Gravity mode applied on begin overlap (`Planetary`, `Directional`, `Dynamic`, `ZeroGravity`). * **EndOverlapGravityMode** — Gravity mode applied on end overlap. * **BeginOverlapGravityRotationMode** — Rotation behavior applied on begin overlap (`Default`, `ForwardBack`, `LeftRight`). * **EndOverlapGravityRotationMode** — Rotation behavior applied on end overlap. #### Directional / Planetary Settings * **BGravityDirection / EGravityDirection** — Normalized world-space directional vector for Begin/End overlap. * **BGravityCenter / EGravityCenter** — World-space center for Planetary mode for Begin/End overlap. #### High-Precision Math * **bBUseHighPrecisionMath / bEUseHighPrecisionMath** — Enables `FVector3d` double precision localized math for Planetary and Dynamic modes per overlap. Eliminates jitter and rounding errors at large world distances by treating the character as a temporary origin for calculations. #### Zero Gravity Settings * **ZeroGravityExitGravityScale** — `GravityScale` restored when exiting zero gravity (default: 1.0). #### Dynamic Gravity Settings * **BFallBackDir / EFallBackDir** — Default fallback direction when a Dynamic latch fails. * **BFallBackTimer / EFallBackTimer** — Duration for gravity transition trial before falling back. * **BLatchDistance / ELatchDistance** — Maximum feet latch distance for Begin/End overlap. #### Dynamic Predictive Probe Settings * **bBUsePredictiveProbes / bEUsePredictiveProbes** — Enables Surface Forward Probe system per overlap — opt-in, off by default. * **BWallProbeDistance / EWallProbeDistance** — Forward reach of wall detection probes — requires `bUsePredictiveProbes`. * **BLedgeProbeDistance / ELedgeProbeDistance** — Forward reach of ledge drop probe — requires `bUsePredictiveProbes`. * **BLedgeProbeLength / ELedgeProbeLength** — Downward reach of ledge drop probe — requires `bUsePredictiveProbes`. * **BDynamicWallLerpSpeed / EDynamicWallLerpSpeed** — Lerp speed for wall transitions — requires `bUsePredictiveProbes`. * **BDynamicLedgeLerpSpeed / EDynamicLedgeLerpSpeed** — Lerp speed for ledge transitions — requires `bUsePredictiveProbes`. #### Tunables / Smoothing * **BRotationSpeed / ERotationSpeed** — Degrees per second for rotation smoothing. * **BSurfaceLerpSpeed / ESurfaceLerpSpeed** — Speed for surface alignment smoothing in Planetary mode. * **BRotationStopTolerance / ERotationStopTolerance** — Angle threshold (normalized 0..1) for snapping rotation to target. * **BFloorDetectionTolerance / EFloorDetectionTolerance** — Extra distance for supplemental ground detection. * **BDynamicHeadTransitionRotationSpeed / EDynamicHeadTransitionRotationSpeed** — Quat step speed for head-probe transitions. * **BDynamicSurfaceSmoothingSpeed / EDynamicSurfaceSmoothingSpeed** — Lerp speed for Dynamic surface following. * **BDynamicEnhancedSmoothingSpeed / EDynamicEnhancedSmoothingSpeed** — First-stage lerp speed for enhanced smoothing. * **bBUseEnhancedSmoothing / bEUseEnhancedSmoothing** — Enables two-stage surface smoothing. #### Vehicle Gravity Settings (v2.6.0) * **bApplyVehicleGravity** — Enables field-driven gravity for overlapping actors using `GravityVehicleMovementComponent` (default: true). * **VehicleGravityMagnitude** — Acceleration magnitude applied to `GravityVehicleMovementComponent` vehicles (default Earth gravity: 980.665). #### Physics Gravity Settings * **bApplyPhysicsGravity** — Enables opt-in planetary gravity for overlapping physics-simulated objects (default: false). * **PhysicsGravityMagnitude** — Acceleration magnitude applied to registered physics bodies (default Earth gravity: 980.665). * **PhysicsSleepAccelerationThresholdSq** — Maximum gravity acceleration squared allowed for custom sleep. Lower values prevent bodies from sleeping while still under strong gravity. * **bShowPhysicsDebugs** — Enables physics-object debug drawing for this field. * **GT\_OverlapCount** — Game-thread overlap count for debug / replication. * **PT\_RegisteredCount** — Physics-thread total registered body count. * **PT\_AwakeCount** — Physics-thread awake body count. * **PT\_SleepingCount** — Physics-thread sleeping body count. #### Overlap / Surface Meshes * **OverlapMesh** — Mesh used to detect field overlaps. Also drives automatic physics overlap registration when physics gravity is enabled. * **SurfaceMesh** — Mesh used for surface radius / alignment. * **OverlapRadius / SurfaceRadius** — Radius for overlap and surface detection (replicated, editable). #### Overlap Gravity Functions (BlueprintNativeEvents / C++) All functions return the resolved `UGravityMovementComponent*` for the affected character: * `ApplyBeginOverlapGravityDirectional(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyBeginOverlapGravityPlanetary(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyBeginOverlapGravityDynamic(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityDirectional(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityPlanetary(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityDynamic(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEnterZeroGravity(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` — Enters zero gravity. Can be called from Begin or End Overlap. All other Apply functions automatically exit zero gravity before applying their mode. #### Vehicle Gravity Functions (Blueprint / C++) * *ApplyBeginOverlapGravityToVehicle(AActor)*\* — Applies `BeginOverlapGravityMode` to an actor using `GravityVehicleMovementComponent`. * *ApplyEndOverlapGravityToVehicle(AActor)*\* — Applies `EndOverlapGravityMode` to an actor using `GravityVehicleMovementComponent`. * *ResolveVehicleMovementComponent(AActor)*\* — Finds and returns the actor’s `GravityVehicleMovementComponent`. #### Physics Overlap / Runtime Functions * **OnOverlapBegin(...)** — Automatic overlap entry handler for vehicle gravity and physics gravity. * **OnOverlapEnd(...)** — Automatic overlap exit handler for vehicle gravity and physics gravity. * *BeginOverlap(AActor, UPrimitiveComponent*)\*\* — Internal physics registration path for overlapping physics bodies. * *EndOverlap(AActor, UPrimitiveComponent*)\*\* — Internal physics unregistration path for overlapping physics bodies. * *OnPhysicsScenePreTick(FPhysScene\_Chaos, float)*\* — Chaos pre-tick callback that applies custom planetary acceleration to registered awake physics bodies. * **SyncPhysicsThreadData()** — Pushes current physics gravity settings into the physics-thread cache. * **ProcessPendingSleepNotifications()** — Processes queued authoritative sleep notifications for receiver-managed bodies. * **QueueSleepNotificationDispatch()** — Schedules deferred game-thread sleep notification handling. #### Utility Functions * **ResolveMovementComponent(...)** — Internal helper to resolve which movement component to apply gravity to. * **OnRep\_OverlapRadius() / OnRep\_SurfaceRadius()** — Replication handlers for radius changes. * **OnRep\_BGravityCenter()** — Replication hook for Planetary center changes. * **OnRep\_PhysicsGravityMagnitude()** — Replication hook for physics gravity magnitude updates. #### Editor / Replication Hooks * **PreReplication(IRepChangedPropertyTracker&)** — Custom replication logic including direction sanitization. * **PostEditChangeProperty(FPropertyChangedEvent&)** — Editor hooks for property updates, direction normalization, mesh radius updates, and physics-thread sync. * **BeginPlay()** — Initializes field, applies initial mesh scaling, binds overlap handlers, syncs physics settings, and registers the Chaos pre-tick callback. * **EndPlay(const EEndPlayReason::Type)** — Removes the Chaos pre-tick callback. #### Key Notes * **Single unified Gravity Field**: `AGravityField` handles all four character gravity modes, opt-in physics gravity, and field-driven vehicle gravity. * **Data-driven & replicated**: Gravity, rotation, tunable, physics, and vehicle gravity settings are per-instance and replicated. * **High-Precision Support**: `bBUseHighPrecisionMath` and `bEUseHighPrecisionMath` ensure stability at extreme world distances. * **Zero Gravity**: Full weightlessness mode with idempotent exit — safe to call unconditionally. `ExitZeroGravity` is called automatically inside every other character Apply function. * **Dynamic support**: Surface Forward Probe system is opt-in via `bUsePredictiveProbes`. When enabled it drives wall and ledge transitions automatically with full hysteresis. * **Character gravity remains explicit**: You still choose and call the appropriate `Apply*` function. * **Vehicle gravity is field-driven**: When `bApplyVehicleGravity` is enabled and the actor has a `GravityVehicleMovementComponent`. * **Physics gravity registration is automatic**: Overlap registration is handled automatically when `bApplyPhysicsGravity` is enabled. * **Mesh-based detection**: Overlap and surface radius remain adjustable per instance via the `OverlapMesh` and `SurfaceMesh` components. *** ## **UGravityMovementComponent – Public API (v2.6.0)** #### ***Setters (Blueprint / C++)*** * `SetGravityMode(EEffectiveGravityMode NewMode)` — Switch between Planetary, Directional, Dynamic, and Zero Gravity modes. * `SetEffectiveGravityPlanetary(const FVector& Center)` — Sets world-space center for Planetary mode. * `SetEffectiveGravityDirectional(const FVector& WorldDir)` — Sets normalized world-space direction for Directional mode. * `SetGravityRotationMode(EGravityRotationMode NewMode)` — Sets rotation constraints for gravity transitions (Default, ForwardBack, LeftRight). * `EnterZeroGravity()` — Enters Zero Gravity mode. Sets movement mode to `MOVE_Flying` and `GravityScale` to 0. Fully replicated with local prediction. * `ExitZeroGravity(float ExitGravityScale)` — Exits Zero Gravity mode and restores `GravityScale`. Idempotent — safe to call unconditionally from any overlap. #### ***Getters (Blueprint / C++)*** * `GetGravityMode()` — Returns current `EEffectiveGravityMode`. * `GetGravityRotationMode()` — Returns current `EGravityRotationMode`. * `GetGravityCenter()` — Returns world-space Planetary center. * `GetGravityDirectionVector()` — Returns raw directional gravity vector. * `GetEffectiveGravityDirection()` — Returns smoothed applied direction (`GravityDirCached`). * `GetSurfaceGravityDirection()` — Returns target direction used for surface alignment smoothing. * `GetIsFalling()` — Returns predicted falling state for local owner or replicated state for remotes. #### ***Events (Blueprint)*** * `BP_OnFallingStateChanged(bool bIsFalling)` — Fires on falling state changes (owner prediction or replicated). * `BP_OnEffectiveGravityDirectionChanged(const FVector& NewEffectiveDir)` — Fires when a meaningful change in applied gravity occurs. #### ***Controller / Utility Helpers (BlueprintPure)*** * `GetGravityRelativeRotation(FRotator Rotation, FVector GravityDirection)` — Converts a world-space rotation to gravity-relative space. * `GetGravityWorldRotation(FRotator Rotation, FVector GravityDirection)` — Converts a gravity-relative rotation back to world space. #### ***Key Enumerations*** * `EEffectiveGravityMode` — Planetary, Directional, Dynamic, ZeroGravity. * `EGravityRotationMode` — Default, ForwardBack, LeftRight. #### ***Configuration / Blueprint Properties*** #### ***General*** * `bApplyReplicatedRotationOnMovingBases` — Enforce visual rotation replication on moving platforms. * `bApplyGravityRotationWhileFlying` — Apply gravity-aligned rotation during flying mode. On exit, cached direction resyncs from actual rotation to prevent snapping. * `bShowVisualDebugs` — Toggle debug visuals (development builds only). #### ***Zero Gravity*** * `bZeroGravityActive` — Read-only runtime state, true when in zero gravity. * `bExternalFlyingActive` — Set true to prevent zero gravity from overriding your custom flying mode. * `ZeroGravityExitGravityScale` — GravityScale restored on exit (default: 1.0). #### ***Dynamic — Probe Behavior*** * `DynamicGravityTraceChannel` — Trace channel used for all Dynamic gravity probes. * `LatchDistance` — Maximum distance the feet latch will remain attached to a detected surface (default: `UE_LARGE_WORLD_MAX`). * `FallBackDir` — Default fallback gravity direction for Dynamic mode. * `FallBackTimer` — Time before fallback triggers in Dynamic mode. * `bUsePredictiveProbes` — Enables the Surface Forward Probe system. When disabled (default) the reactive system is used. When enabled adds dual wall probes, ledge detection, and hysteresis for smooth wall and ledge gravity transitions (default: false). * `WallProbeDistance` — Forward reach of wall detection probes (default: 75.0) — requires `bUsePredictiveProbes`. * `LedgeProbeDistance` — Forward reach of ledge drop probe (default: 75.0) — requires `bUsePredictiveProbes`. * `LedgeProbeLength` — Downward reach of ledge drop probe (default: 55.0) — requires `bUsePredictiveProbes`. #### ***Dynamic — Rotation Speeds*** * `DynamicHeadTransitionRotationSpeed` — Quat step speed for head-probe gravity transitions (default: 270.0). * `DynamicSurfaceLerpSpeed` — Lerp speed for surface following (default: 20.0). * `DynamicEnhancedSurfaceSmoothingSpeed` — First-stage lerp speed for enhanced smoothing (default: 10.0). * `bUseEnhancedSmoothing` — Enables two-stage surface smoothing for curved geometry (default: false). * `DynamicWallLerpSpeed` — Lerp speed for wall transitions (default: 10.0) — requires `bUsePredictiveProbes`. * `DynamicLedgeLerpSpeed` — Lerp speed for ledge transitions (default: 20.0) — requires `bUsePredictiveProbes`. #### ***Directional / Planetary — Rotation*** * `RotationSpeed` — Max rotation speed for smoothing in Directional and Planetary modes (deg/sec). * `SurfaceLerpSpeed` — Speed for surface alignment smoothing in Planetary mode. * `RotationStopTolerance` — Angle threshold for snapping rotation to target. #### ***Precision (v2.4.3 New Feature)*** * `bUseHighPrecisionMath` — Enables localized double-precision (`FVector3d`) math for gravity calculations. Specifically addresses "splitting" jitter and coordinate collapse when the character is at large world distances from the origin. #### ***General*** * `FloorDetectionTolerance` — Extra distance for supplemental ground detection. #### ***Key Notes*** * `UGravityMovementComponent` remains the core runtime component for all character gravity behavior in v2.5.0. * All character gravity modes remain fully supported: Directional, Planetary, Dynamic, and ZeroGravity. Dynamic Predictive Probes remain opt-in and are still the wall / ledge transition system. * v2.5.0 adds opt-in physics gravity alongside the existing character gravity workflow — it does not replace the movement component workflow. *** ## **UGravityReceiverComponent – Public API (v2.6.0)** #### ***Sleep / Snapshot Structures*** *FReplicatedGravitySleepState* — Replicated authoritative sleep state for a specific primitive component / bone pair. * `PrimitiveComponent` — Target primitive component. * `BoneName` — Target bone name for skeletal bodies. * `bSleeping` — Authoritative sleeping state. * `Sequence` — Sequence counter used to order sleep-state updates. #### ***FReplicatedGravityRagdollBodySnapshot*** Replicated authoritative ragdoll body snapshot for a specific primitive component / bone pair. * `PrimitiveComponent` — Target primitive component. * `BoneName` — Target bone name for skeletal bodies. * `WorldTransform` — Authoritative world transform. * `LinearVelocity` — Authoritative linear velocity. * `AngularVelocity` — Authoritative angular velocity. * `bSleeping` — Sleeping state at snapshot time. #### ***Active Field State*** * `ActiveFields` — Runtime list of gravity fields currently affecting this actor. * `ReplicatedActiveFields` — Replicated authoritative field list used to keep clients in sync. * `CachedPrimitives` — Cached primitive components used by receiver-managed registration. * `AuthoritativeSleepStates` — Replicated authoritative sleep state list for receiver-managed bodies. * `ReplicatedRagdollBodySnapshots` — Replicated ragdoll body snapshots. #### ***Ragdoll Snapshot Settings*** * `bEnableRagdollBodySnapshots` — Enables optional ragdoll snapshot replication / correction. * `RagdollSnapshotInterval` — Interval used for authoritative ragdoll snapshot capture. * `RagdollTeleportDistanceThreshold` — Distance threshold before large error correction snaps instead of blending. * `RagdollPositionBlendAlpha` — Blend alpha used for ragdoll transform correction. * `RagdollVelocityBlendAlpha` — Blend alpha used for ragdoll velocity correction. * `RagdollOverlapRadius` — Radius used by the ragdoll overlap proxy sphere. #### ***Blueprint / Public Functions*** * `RefreshGravityFieldRegistration()` — Blueprint-callable re-scan / re-register helper for overlapping fields. * `OnRep_ActiveFields()` — Replication handler for active field changes. * `OnRep_AuthoritativeSleepStates()` — Replication handler for authoritative sleep state changes. * `OnRep_RagdollBodySnapshots()` — Replication handler for ragdoll snapshot updates. * `RegisterWithField(AGravityField* Field)` — Registers this actor with a specific field. * `OnSimulationStateChanged()` — Re-evaluates gravity registration when simulation state changes. * `OnAddedToField(AGravityField* Field)` — Adds a field to the active set and updates receiver-managed state. * `HandleComponentWake(UPrimitiveComponent* WakingComponent, FName BoneName)` — Wake callback for receiver-managed bodies. * `HandleComponentSleep(UPrimitiveComponent* SleepingComponent, FName BoneName)` — Sleep callback for receiver-managed bodies. * `HandleComponentHit(UPrimitiveComponent* HitComponent, AActor* OtherActor, UPrimitiveComponent* OtherComp, FVector NormalImpulse, const FHitResult& Hit)` — Hit callback used by wake-on-hit logic. * `BindPhysicsEvents()` — Binds wake / sleep / hit delegates on owned simulating primitives. * `SetAuthoritativeBodySleepState(UPrimitiveComponent* PrimitiveComponent, FName BoneName, bool bSleeping)` — Updates the authoritative sleep state for a specific body / bone. #### ***Networking / Lifecycle*** * `RegisterReplicationFragments(...)` — Iris replication registration when enabled. * `GetLifetimeReplicatedProps(...)` — Traditional replication registration. * `BeginPlay()` — Initializes cached primitives, ragdoll support, bindings, and bootstrap registration. * `EndPlay(const EEndPlayReason::Type)` — Cleans up receiver-managed state on shutdown. #### ***Key Notes*** * `UGravityReceiverComponent` is optional for simple single-body physics cases. * `UGravityReceiverComponent` is required for multi-body support and recommended for full receiver-managed behavior. * Receiver-managed behavior includes active field tracking, authoritative sleep replication, wake-on-hit handling, and optional ragdoll snapshot correction. *** ## **UGravityReplicationSubsystem – Public API (v2.6.0)** #### ***Registration Functions*** * `RegisterPhysicsBody(AGravityField* Field, AActor* OwnerActor, UPrimitiveComponent* PrimitiveComponent, FName BoneName)` — Registers a field/body relationship. * `UnregisterPhysicsBody(AGravityField* Field, UPrimitiveComponent* PrimitiveComponent, FName BoneName)` — Removes a field/body relationship. #### ***Query Functions*** * `GetRegisteredPhysicsBodyCount(const AGravityField* Field) const` — Returns total registered body count for a field. * `GetRegisteredActorCount(const AGravityField* Field) const` — Returns unique registered actor count for a field. * `GetRegisteredSkeletalBodyCount(const AGravityField* Field) const` — Returns skeletal body count for a field. * `GetSleepingPhysicsBodyCount(const AGravityField* Field) const` — Returns sleeping body count for a field. * `GetAwakePhysicsBodyCount(const AGravityField* Field) const` — Returns awake body count for a field. #### ***Sleep State Functions*** * `UpdateBodySleepState(AActor* OwnerActor, UPrimitiveComponent* PrimitiveComponent, FName BoneName, bool bSleeping)` — Updates sleep state for all matching owner/body registrations. * `UpdateFieldBodySleepState(AGravityField* Field, UPrimitiveComponent* PrimitiveComponent, FName BoneName, bool bSleeping)` — Updates sleep state for a specific field/body registration. #### ***Cached Registration Structures*** *FGravityRegisteredPhysicsBody* — Stored registration record for a field/body pair. * `Field` — Weak field reference. * `OwnerActor` — Weak owner actor reference. * `PrimitiveComponent` — Weak primitive component reference. * `BoneName` — Bone name for skeletal body registrations. * `bSleeping` — Cached sleeping state. #### ***FGravityFieldCachedCounts*** Per-field cached counts for registered, sleeping, awake, and skeletal bodies. * `RegisteredBodies` — Total registered bodies for the field. * `SleepingBodies` — Sleeping body count for the field. * `AwakeBodies` — Awake body count for the field. * `SkeletalBodies` — Skeletal body count for the field. #### ***Key Notes*** * `UGravityReplicationSubsystem` is the world-level bookkeeping layer for physics gravity registration and sleep accounting. * Register, unregister, and sleep-state updates use cached keyed lookups — no per-frame linear scans. * Full cache rebuilds are deferred to cleanup / invalid-entry maintenance rather than the hot runtime path. *** ## **UGravityMovementComponent – Public API (v2.5.0)** #### ***Setters (Blueprint / C++)*** * `SetGravityMode(EEffectiveGravityMode NewMode)` — Switch between Planetary, Directional, Dynamic, and Zero Gravity modes. * `SetEffectiveGravityPlanetary(const FVector& Center)` — Sets world-space center for Planetary mode. * `SetEffectiveGravityDirectional(const FVector& WorldDir)` — Sets normalized world-space direction for Directional mode. * `SetGravityRotationMode(EGravityRotationMode NewMode)` — Sets rotation constraints for gravity transitions (Default, ForwardBack, LeftRight). * `EnterZeroGravity()` — Enters Zero Gravity mode. Sets movement mode to `MOVE_Flying` and `GravityScale` to 0. Fully replicated with local prediction. * `ExitZeroGravity(float ExitGravityScale)` — Exits Zero Gravity mode and restores `GravityScale`. Idempotent — safe to call unconditionally from any overlap. #### ***Getters (Blueprint / C++)*** * `GetGravityMode()` — Returns current `EEffectiveGravityMode`. * `GetGravityRotationMode()` — Returns current `EGravityRotationMode`. * `GetGravityCenter()` — Returns world-space Planetary center. * `GetGravityDirectionVector()` — Returns raw directional gravity vector. * `GetEffectiveGravityDirection()` — Returns smoothed applied direction (`GravityDirCached`). * `GetSurfaceGravityDirection()` — Returns target direction used for surface alignment smoothing. * `GetIsFalling()` — Returns predicted falling state for local owner or replicated state for remotes. #### ***Events (Blueprint)*** * `BP_OnFallingStateChanged(bool bIsFalling)` — Fires on falling state changes (owner prediction or replicated). * `BP_OnEffectiveGravityDirectionChanged(const FVector& NewEffectiveDir)` — Fires when a meaningful change in applied gravity occurs. #### ***Controller / Utility Helpers (BlueprintPure)*** * `GetGravityRelativeRotation(FRotator Rotation, FVector GravityDirection)` — Converts a world-space rotation to gravity-relative space. * `GetGravityWorldRotation(FRotator Rotation, FVector GravityDirection)` — Converts a gravity-relative rotation back to world space. #### ***Key Enumerations*** * `EEffectiveGravityMode` — Planetary, Directional, Dynamic, ZeroGravity. * `EGravityRotationMode` — Default, ForwardBack, LeftRight. #### ***Configuration / Blueprint Properties*** #### ***General*** * `bApplyReplicatedRotationOnMovingBases` — Enforce visual rotation replication on moving platforms. * `bApplyGravityRotationWhileFlying` — Apply gravity-aligned rotation during flying mode. On exit, cached direction resyncs from actual rotation to prevent snapping. * `bShowVisualDebugs` — Toggle debug visuals (development builds only). #### ***Zero Gravity*** * `bZeroGravityActive` — Read-only runtime state, true when in zero gravity. * `bExternalFlyingActive` — Set true to prevent zero gravity from overriding your custom flying mode. * `ZeroGravityExitGravityScale` — GravityScale restored on exit (default: 1.0). #### ***Dynamic — Probe Behavior*** * `DynamicGravityTraceChannel` — Trace channel used for all Dynamic gravity probes. * `LatchDistance` — Maximum distance the feet latch will remain attached to a detected surface (default: `UE_LARGE_WORLD_MAX`). * `FallBackDir` — Default fallback gravity direction for Dynamic mode. * `FallBackTimer` — Time before fallback triggers in Dynamic mode. * `bUsePredictiveProbes` — Enables the Surface Forward Probe system. When disabled (default) the reactive system is used. When enabled adds dual wall probes, ledge detection, and hysteresis for smooth wall and ledge gravity transitions (default: false). * `WallProbeDistance` — Forward reach of wall detection probes (default: 75.0) — requires `bUsePredictiveProbes`. * `LedgeProbeDistance` — Forward reach of ledge drop probe (default: 75.0) — requires `bUsePredictiveProbes`. * `LedgeProbeLength` — Downward reach of ledge drop probe (default: 55.0) — requires `bUsePredictiveProbes`. #### ***Dynamic — Rotation Speeds*** * `DynamicHeadTransitionRotationSpeed` — Quat step speed for head-probe gravity transitions (default: 270.0). * `DynamicSurfaceLerpSpeed` — Lerp speed for surface following (default: 20.0). * `DynamicEnhancedSurfaceSmoothingSpeed` — First-stage lerp speed for enhanced smoothing (default: 10.0). * `bUseEnhancedSmoothing` — Enables two-stage surface smoothing for curved geometry (default: false). * `DynamicWallLerpSpeed` — Lerp speed for wall transitions (default: 10.0) — requires `bUsePredictiveProbes`. * `DynamicLedgeLerpSpeed` — Lerp speed for ledge transitions (default: 20.0) — requires `bUsePredictiveProbes`. #### ***Directional / Planetary — Rotation*** * `RotationSpeed` — Max rotation speed for smoothing in Directional and Planetary modes (deg/sec). * `SurfaceLerpSpeed` — Speed for surface alignment smoothing in Planetary mode. * `RotationStopTolerance` — Angle threshold for snapping rotation to target. #### ***Precision (v2.4.3 New Feature)*** * `bUseHighPrecisionMath` — Enables localized double-precision (`FVector3d`) math for gravity calculations. Specifically addresses "splitting" jitter and coordinate collapse when the character is at large world distances from the origin. #### ***General*** * `FloorDetectionTolerance` — Extra distance for supplemental ground detection. #### ***Key Notes*** * `UGravityMovementComponent` remains the core runtime component for all character gravity behavior in v2.5.0. * All character gravity modes remain fully supported: Directional, Planetary, Dynamic, and ZeroGravity. Dynamic Predictive Probes remain opt-in and are still the wall / ledge transition system. * v2.5.0 adds opt-in physics gravity alongside the existing character gravity workflow — it does not replace the movement component workflow. *** ## **AGravityField – Public API (v2.5.0)** #### ***Gravity Mode / Rotation Settings (Blueprint / C++)*** * `BeginOverlapGravityMode` — Gravity mode applied on begin overlap (Planetary, Directional, Dynamic, ZeroGravity). * `EndOverlapGravityMode` — Gravity mode applied on end overlap. * `BeginOverlapGravityRotationMode` — Rotation behavior applied on begin overlap (Default, ForwardBack, LeftRight). * `EndOverlapGravityRotationMode` — Rotation behavior applied on end overlap. #### ***Directional / Planetary Settings*** * `BGravityDirection` / `EGravityDirection` — Normalized world-space directional vector for Begin/End overlap. * `BGravityCenter` / `EGravityCenter` — World-space center for Planetary mode for Begin/End overlap. #### ***High-Precision Math*** * `bBUseHighPrecisionMath` / `bEUseHighPrecisionMath` — Enables `FVector3d` double precision localized math for Planetary and Dynamic modes per overlap. Eliminates jitter and rounding errors at large world distances by treating the character as a temporary origin for calculations. #### ***Zero Gravity Settings*** * `ZeroGravityExitGravityScale` — GravityScale restored when exiting zero gravity (default: 1.0). #### ***Dynamic Gravity Settings*** * `BFallBackDir` / `EFallBackDir` — Default fallback direction when a Dynamic latch fails. * `BFallBackTimer` / `EFallBackTimer` — Duration for gravity transition trial before falling back. * `BLatchDistance` / `ELatchDistance` — Maximum feet latch distance for Begin/End overlap. #### ***Dynamic Predictive Probe Settings*** * `bBUsePredictiveProbes` / `bEUsePredictiveProbes` — Enables Surface Forward Probe system per overlap — opt-in, off by default. * `BWallProbeDistance` / `EWallProbeDistance` — Forward reach of wall detection probes — requires bUsePredictiveProbes. * `BLedgeProbeDistance` / `ELedgeProbeDistance` — Forward reach of ledge drop probe — requires bUsePredictiveProbes. * `BLedgeProbeLength` / `ELedgeProbeLength` — Downward reach of ledge drop probe — requires bUsePredictiveProbes. * `BDynamicWallLerpSpeed` / `EDynamicWallLerpSpeed` — Lerp speed for wall transitions — requires bUsePredictiveProbes. * `BDynamicLedgeLerpSpeed` / `EDynamicLedgeLerpSpeed` — Lerp speed for ledge transitions — requires bUsePredictiveProbes. #### ***Tunables / Smoothing*** * `BRotationSpeed` / `ERotationSpeed` — Degrees per second for rotation smoothing. * `BSurfaceLerpSpeed` / `ESurfaceLerpSpeed` — Speed for surface alignment smoothing in Planetary mode. * `BRotationStopTolerance` / `ERotationStopTolerance` — Angle threshold (normalized 0..1) for snapping rotation to target. * `BFloorDetectionTolerance` / `EFloorDetectionTolerance` — Extra distance for supplemental ground detection. * `BDynamicHeadTransitionRotationSpeed` / `EDynamicHeadTransitionRotationSpeed` — Quat step speed for head-probe transitions. * `BDynamicSurfaceSmoothingSpeed` / `EDynamicSurfaceSmoothingSpeed` — Lerp speed for Dynamic surface following. * `BDynamicEnhancedSmoothingSpeed` / `EDynamicEnhancedSmoothingSpeed` — First-stage lerp speed for enhanced smoothing. * `bBUseEnhancedSmoothing` / `bEUseEnhancedSmoothing` — Enables two-stage surface smoothing. #### ***Physics Gravity Settings (v2.5.0)*** * `bApplyPhysicsGravity` — Enables opt-in planetary gravity for overlapping physics-simulated objects (default: false). * `PhysicsGravityMagnitude` — Acceleration magnitude applied to registered physics bodies (default Earth gravity: 980.665). * `PhysicsSleepVelocityThreshold` — Velocity threshold used by the custom physics sleep gate. * `PhysicsSleepAccelerationThresholdSq` — Maximum gravity acceleration squared allowed for custom sleep. Lower values prevent bodies from sleeping while still under strong gravity. * `bShowPhysicsDebugs` — Enables physics-object debug drawing for this field. * `GT_OverlapCount` — Game-thread overlap count for debug / replication. * `PT_RegisteredCount` — Physics-thread total registered body count. * `PT_AwakeCount` — Physics-thread awake body count. * `PT_SleepingCount` — Physics-thread sleeping body count. #### ***Overlap / Surface Meshes*** * `OverlapMesh` — Mesh used to detect field overlaps. Also drives automatic physics overlap registration when physics gravity is enabled. * `SurfaceMesh` — Mesh used for surface radius / alignment. * `OverlapRadius` / `SurfaceRadius` — Radius for overlap and surface detection (replicated, editable). #### ***Overlap Gravity Functions (BlueprintNativeEvents / C++)*** All functions return the resolved `UGravityMovementComponent*` for the affected character: * `ApplyBeginOverlapGravityDirectional(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyBeginOverlapGravityPlanetary(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyBeginOverlapGravityDynamic(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityDirectional(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityPlanetary(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityDynamic(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEnterZeroGravity(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` — Enters zero gravity. Can be called from Begin or End Overlap. All other Apply functions automatically exit zero gravity before applying their mode. #### ***Physics Overlap / Runtime Functions*** * `OnOverlapBegin(...)` — Automatic overlap entry handler for physics gravity. * `OnOverlapEnd(...)` — Automatic overlap exit handler for physics gravity. * `BeginOverlap(AActor*, UPrimitiveComponent*)` — Internal physics registration path for overlapping physics bodies. * `EndOverlap(AActor*, UPrimitiveComponent*)` — Internal physics unregistration path for overlapping physics bodies. * `OnPhysicsScenePreTick(FPhysScene_Chaos*, float)` — Chaos pre-tick callback that applies custom planetary acceleration to registered awake physics bodies. * `SyncPhysicsThreadData()` — Pushes current physics gravity settings into the physics-thread cache. * `ProcessPendingSleepNotifications()` — Processes queued authoritative sleep notifications for receiver-managed bodies. * `QueueSleepNotificationDispatch()` — Schedules deferred game-thread sleep notification handling. #### ***Utility Functions*** * `ResolveMovementComponent(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` — Internal helper to resolve which movement component to apply gravity to. * `OnRep_OverlapRadius()` / `OnRep_SurfaceRadius()` — Replication handlers for radius changes. * `OnRep_BGravityCenter()` — Replication hook for Planetary center changes. * `OnRep_PhysicsGravityMagnitude()` — Replication hook for physics gravity magnitude updates. #### ***Editor / Replication Hooks*** * `PreReplication(IRepChangedPropertyTracker&)` — Custom replication logic including direction sanitization. * `PostEditChangeProperty(FPropertyChangedEvent&)` — Editor hooks for property updates, direction normalization, and physics-thread sync. * `BeginPlay()` — Initializes field, applies initial mesh scaling, binds overlap handlers, syncs physics settings, and registers the Chaos pre-tick callback. * `EndPlay(const EEndPlayReason::Type)` — Removes the Chaos pre-tick callback. #### ***Key Notes*** * Single unified Gravity Field: AGravityField handles all four character gravity modes and now also supports opt-in physics gravity. * Data-driven & replicated: All gravity, rotation, tunable, and physics settings are per-instance and replicated. * High-Precision Support: `bBUseHighPrecisionMath` and `bEUseHighPrecisionMath` ensure stability at extreme world distances. * Zero Gravity: Full weightlessness mode with idempotent exit — safe to call unconditionally. ExitZeroGravity is called automatically inside every other Apply function. * Dynamic support: Surface Forward Probe system is opt-in via `bUsePredictiveProbes`. When enabled it drives wall and ledge transitions automatically with full hysteresis. * Character gravity remains explicit — you still choose and call the appropriate Apply\* function. * Physics gravity overlap registration is automatic when `bApplyPhysicsGravity` is enabled. * Mesh-based detection: Overlap and surface radius remain adjustable per instance. *** ## **UGravityReceiverComponent – Public API (v2.5.0)** #### ***Sleep / Snapshot Structures*** *FReplicatedGravitySleepState* — Replicated authoritative sleep state for a specific primitive component / bone pair. * `PrimitiveComponent` — Target primitive component. * `BoneName` — Target bone name for skeletal bodies. * `bSleeping` — Authoritative sleeping state. * `Sequence` — Sequence counter used to order sleep-state updates. #### ***FReplicatedGravityRagdollBodySnapshot*** Replicated authoritative ragdoll body snapshot for a specific primitive component / bone pair. * `PrimitiveComponent` — Target primitive component. * `BoneName` — Target bone name for skeletal bodies. * `WorldTransform` — Authoritative world transform. * `LinearVelocity` — Authoritative linear velocity. * `AngularVelocity` — Authoritative angular velocity. * `bSleeping` — Sleeping state at snapshot time. #### ***Active Field State*** * `ActiveFields` — Runtime list of gravity fields currently affecting this actor. * `ReplicatedActiveFields` — Replicated authoritative field list used to keep clients in sync. * `CachedPrimitives` — Cached primitive components used by receiver-managed registration. * `AuthoritativeSleepStates` — Replicated authoritative sleep state list for receiver-managed bodies. * `ReplicatedRagdollBodySnapshots` — Replicated ragdoll body snapshots. #### ***Ragdoll Snapshot Settings*** * `bEnableRagdollBodySnapshots` — Enables optional ragdoll snapshot replication / correction. * `RagdollSnapshotInterval` — Interval used for authoritative ragdoll snapshot capture. * `RagdollTeleportDistanceThreshold` — Distance threshold before large error correction snaps instead of blending. * `RagdollPositionBlendAlpha` — Blend alpha used for ragdoll transform correction. * `RagdollVelocityBlendAlpha` — Blend alpha used for ragdoll velocity correction. * `RagdollOverlapRadius` — Radius used by the ragdoll overlap proxy sphere. #### ***Blueprint / Public Functions*** * `RefreshGravityFieldRegistration()` — Blueprint-callable re-scan / re-register helper for overlapping fields. * `OnRep_ActiveFields()` — Replication handler for active field changes. * `OnRep_AuthoritativeSleepStates()` — Replication handler for authoritative sleep state changes. * `OnRep_RagdollBodySnapshots()` — Replication handler for ragdoll snapshot updates. * `RegisterWithField(AGravityField* Field)` — Registers this actor with a specific field. * `OnSimulationStateChanged()` — Re-evaluates gravity registration when simulation state changes. * `OnAddedToField(AGravityField* Field)` — Adds a field to the active set and updates receiver-managed state. * `HandleComponentWake(UPrimitiveComponent* WakingComponent, FName BoneName)` — Wake callback for receiver-managed bodies. * `HandleComponentSleep(UPrimitiveComponent* SleepingComponent, FName BoneName)` — Sleep callback for receiver-managed bodies. * `HandleComponentHit(UPrimitiveComponent* HitComponent, AActor* OtherActor, UPrimitiveComponent* OtherComp, FVector NormalImpulse, const FHitResult& Hit)` — Hit callback used by wake-on-hit logic. * `BindPhysicsEvents()` — Binds wake / sleep / hit delegates on owned simulating primitives. * `SetAuthoritativeBodySleepState(UPrimitiveComponent* PrimitiveComponent, FName BoneName, bool bSleeping)` — Updates the authoritative sleep state for a specific body / bone. #### ***Networking / Lifecycle*** * `RegisterReplicationFragments(...)` — Iris replication registration when enabled. * `GetLifetimeReplicatedProps(...)` — Traditional replication registration. * `BeginPlay()` — Initializes cached primitives, ragdoll support, bindings, and bootstrap registration. * `EndPlay(const EEndPlayReason::Type)` — Cleans up receiver-managed state on shutdown. #### ***Key Notes*** * `UGravityReceiverComponent` is optional for simple single-body physics cases. * `UGravityReceiverComponent` is required for multi-body support and recommended for full receiver-managed behavior. * Receiver-managed behavior includes active field tracking, authoritative sleep replication, wake-on-hit handling, and optional ragdoll snapshot correction. *** ## **UGravityReplicationSubsystem – Public API (v2.5.0)** #### ***Registration Functions*** * `RegisterPhysicsBody(AGravityField* Field, AActor* OwnerActor, UPrimitiveComponent* PrimitiveComponent, FName BoneName)` — Registers a field/body relationship. * `UnregisterPhysicsBody(AGravityField* Field, UPrimitiveComponent* PrimitiveComponent, FName BoneName)` — Removes a field/body relationship. #### ***Query Functions*** * `GetRegisteredPhysicsBodyCount(const AGravityField* Field) const` — Returns total registered body count for a field. * `GetRegisteredActorCount(const AGravityField* Field) const` — Returns unique registered actor count for a field. * `GetRegisteredSkeletalBodyCount(const AGravityField* Field) const` — Returns skeletal body count for a field. * `GetSleepingPhysicsBodyCount(const AGravityField* Field) const` — Returns sleeping body count for a field. * `GetAwakePhysicsBodyCount(const AGravityField* Field) const` — Returns awake body count for a field. #### ***Sleep State Functions*** * `UpdateBodySleepState(AActor* OwnerActor, UPrimitiveComponent* PrimitiveComponent, FName BoneName, bool bSleeping)` — Updates sleep state for all matching owner/body registrations. * `UpdateFieldBodySleepState(AGravityField* Field, UPrimitiveComponent* PrimitiveComponent, FName BoneName, bool bSleeping)` — Updates sleep state for a specific field/body registration. #### ***Cached Registration Structures*** *FGravityRegisteredPhysicsBody* — Stored registration record for a field/body pair. * `Field` — Weak field reference. * `OwnerActor` — Weak owner actor reference. * `PrimitiveComponent` — Weak primitive component reference. * `BoneName` — Bone name for skeletal body registrations. * `bSleeping` — Cached sleeping state. #### ***FGravityFieldCachedCounts*** Per-field cached counts for registered, sleeping, awake, and skeletal bodies. * `RegisteredBodies` — Total registered bodies for the field. * `SleepingBodies` — Sleeping body count for the field. * `AwakeBodies` — Awake body count for the field. * `SkeletalBodies` — Skeletal body count for the field. #### ***Key Notes*** * `UGravityReplicationSubsystem` is the world-level bookkeeping layer for physics gravity registration and sleep accounting. * Register, unregister, and sleep-state updates use cached keyed lookups — no per-frame linear scans. * Full cache rebuilds are deferred to cleanup / invalid-entry maintenance rather than the hot runtime path. *** ## ***Replicated Gravity – Key Notes (v2.5.0)*** * v2.5.0 keeps the full character gravity API intact and adds an opt-in physics gravity system alongside it. Character gravity is still driven through `UGravityMovementComponent` and `AGravityField` overlap Apply\* functions. * Physics gravity is field-driven, overlap-driven, and off by default. Simple single-body physics actors can work without `UGravityReceiverComponent`. * Multi-body physics actors require `UGravityReceiverComponent`. * `UGravityReplicationSubsystem` provides the registration and authoritative sleep-state bookkeeping for the physics gravity path. *** ## **UGravityMovementComponent – Public API (v2.4.0)** #### **Setters (Blueprint / C++)** * `SetGravityMode(EEffectiveGravityMode NewMode)` — Switch between Planetary, Directional, Dynamic, and Zero Gravity modes. * `SetEffectiveGravityPlanetary(const FVector& Center)` — Sets world-space center for Planetary mode. * `SetEffectiveGravityDirectional(const FVector& WorldDir)` — Sets normalized world-space direction for Directional mode. * `SetGravityRotationMode(EGravityRotationMode NewMode)` — Sets rotation constraints for gravity transitions (Default, ForwardBack, LeftRight). * `EnterZeroGravity()` — Enters Zero Gravity mode. Sets movement mode to `MOVE_Flying` and `GravityScale` to 0. Fully replicated with local prediction. * `ExitZeroGravity(float ExitGravityScale)` — Exits Zero Gravity mode and restores `GravityScale`. Idempotent — safe to call unconditionally from any overlap. #### **Getters (Blueprint / C++)** * `GetGravityMode()` — Returns current `EEffectiveGravityMode`. * `GetGravityRotationMode()` — Returns current `EGravityRotationMode`. * `GetGravityCenter()` — Returns world-space Planetary center. * `GetGravityDirectionVector()` — Returns raw directional gravity vector. * `GetEffectiveGravityDirection()` — Returns smoothed applied direction (`GravityDirCached`). * `GetSurfaceGravityDirection()` — Returns target direction used for surface alignment smoothing. * `GetIsFalling()` — Returns predicted falling state for local owner or replicated state for remotes. #### **Events (Blueprint)** * `BP_OnFallingStateChanged(bool bIsFalling)` — Fires on falling state changes (owner prediction or replicated). * `BP_OnEffectiveGravityDirectionChanged(const FVector& NewEffectiveDir)` — Fires when a meaningful change in applied gravity occurs. #### **Controller / Utility Helpers (BlueprintPure)** * `GetGravityRelativeRotation(FRotator Rotation, FVector GravityDirection)` — Converts a world-space rotation to gravity-relative space. * `GetGravityWorldRotation(FRotator Rotation, FVector GravityDirection)` — Converts a gravity-relative rotation back to world space. #### **Key Enumerations** * `EEffectiveGravityMode` — Planetary, Directional, Dynamic, ZeroGravity. * `EGravityRotationMode` — Default, ForwardBack, LeftRight. #### **Configuration / Blueprint Properties** #### *General* * `bApplyReplicatedRotationOnMovingBases` — Enforce visual rotation replication on moving platforms. * `bApplyGravityRotationWhileFlying` — Apply gravity-aligned rotation during flying mode. On exit, cached direction resyncs from actual rotation to prevent snapping. * `bShowVisualDebugs` — Toggle debug visuals (development builds only). #### *Zero Gravity* * `bZeroGravityActive` — Read-only runtime state, true when in zero gravity. * `bExternalFlyingActive` — Set true to prevent zero gravity from overriding your custom flying mode. * `ZeroGravityExitGravityScale` — GravityScale restored on exit (default: 1.0). #### *Dynamic — Probe Behavior* * `DynamicGravityTraceChannel` — Trace channel used for all Dynamic gravity probes. * `LatchDistance` — Maximum distance the feet latch will remain attached to a detected surface (default: `UE_LARGE_WORLD_MAX`). * `FallBackDir` — Default fallback gravity direction for Dynamic mode. * `FallBackTimer` — Time before fallback triggers in Dynamic mode. * `bUsePredictiveProbes` — Enables the Surface Forward Probe system. When disabled (default) the reactive system is used. When enabled adds dual wall probes, ledge detection, and hysteresis for smooth wall and ledge gravity transitions (default: false). * `WallProbeDistance` — Forward reach of wall detection probes (default: 75.0) — requires `bUsePredictiveProbes`. * `LedgeProbeDistance` — Forward reach of ledge drop probe (default: 75.0) — requires `bUsePredictiveProbes`. * `LedgeProbeLength` — Downward reach of ledge drop probe (default: 55.0) — requires `bUsePredictiveProbes`. #### *Dynamic — Rotation Speeds* * `DynamicHeadTransitionRotationSpeed` — Quat step speed for head-probe gravity transitions (default: 270.0). * `DynamicSurfaceLerpSpeed` — Lerp speed for surface following (default: 20.0). * `DynamicEnhancedSurfaceSmoothingSpeed` — First-stage lerp speed for enhanced smoothing (default: 10.0). * `bUseEnhancedSmoothing` — Enables two-stage surface smoothing for curved geometry (default: false). * `DynamicWallLerpSpeed` — Lerp speed for wall transitions (default: 10.0) — requires `bUsePredictiveProbes`. * `DynamicLedgeLerpSpeed` — Lerp speed for ledge transitions (default: 20.0) — requires `bUsePredictiveProbes`. #### *Directional / Planetary — Rotation* * `RotationSpeed` — Max rotation speed for smoothing in Directional and Planetary modes (deg/sec). * `SurfaceLerpSpeed` — Speed for surface alignment smoothing in Planetary mode. * `RotationStopTolerance` — Angle threshold for snapping rotation to target. #### **Precision (v2.4.3 New Feature)** * `bUseHighPrecisionMath` — Enables localized double-precision (`FVector3d`) math for gravity calculations. Specifically addresses "splitting" jitter and coordinate collapse when the character is at large world distances from the origin. #### *General* * `FloorDetectionTolerance` — Extra distance for supplemental ground detection. *** ## **AGravityField – Public API (v2.4.0)** #### **Gravity Mode / Rotation Settings (Blueprint / C++)** * `BeginOverlapGravityMode` — Gravity mode applied on begin overlap (Planetary, Directional, Dynamic, ZeroGravity). * `EndOverlapGravityMode` — Gravity mode applied on end overlap. * `BeginOverlapGravityRotationMode` — Rotation behavior applied on begin overlap (Default, ForwardBack, LeftRight). * `EndOverlapGravityRotationMode` — Rotation behavior applied on end overlap. #### **Directional / Planetary Settings** * `BGravityDirection` / `EGravityDirection` — Normalized world-space directional vector for Begin/End overlap. * `BGravityCenter` / `EGravityCenter` — World-space center for Planetary mode for Begin/End overlap. #### **High-Precision Math (v2.4.3 New Feature)** * `bBUseHighPrecisionMath` / `bEUseHighPrecisionMath` — Enables `FVector3d` (double precision) localized math for Planetary and Dynamic modes per overlap. This eliminates jitter and rounding errors at large world distances by treating the character as a temporary origin for calculations. #### **Zero Gravity Settings** * `ZeroGravityExitGravityScale` — `GravityScale` restored when exiting zero gravity (default: 1.0). #### **Dynamic Gravity Settings** * `BFallBackDir` / `EFallBackDir` — Default fallback direction when a Dynamic latch fails. * `BFallBackTimer` / `EFallBackTimer` — Duration for gravity transition trial before falling back. * `BLatchDistance` / `ELatchDistance` — Maximum feet latch distance for Begin/End overlap. #### **Dynamic Predictive Probe Settings** * `bBUsePredictiveProbes` / `bEUsePredictiveProbes` — Enables Surface Forward Probe system per overlap — opt-in, off by default. * `BWallProbeDistance` / `EWallProbeDistance` — Forward reach of wall detection probes — requires `bUsePredictiveProbes`. * `BLedgeProbeDistance` / `ELedgeProbeDistance` — Forward reach of ledge drop probe — requires `bUsePredictiveProbes`. * `BLedgeProbeLength` / `ELedgeProbeLength` — Downward reach of ledge drop probe — requires `bUsePredictiveProbes`. * `BDynamicWallLerpSpeed` / `EDynamicWallLerpSpeed` — Lerp speed for wall transitions — requires `bUsePredictiveProbes`. * `BDynamicLedgeLerpSpeed` / `EDynamicLedgeLerpSpeed` — Lerp speed for ledge transitions — requires `bUsePredictiveProbes`. #### **Tunables / Smoothing** * `BRotationSpeed` / `ERotationSpeed` — Degrees per second for rotation smoothing. * `BSurfaceLerpSpeed` / `ESurfaceLerpSpeed` — Speed for surface alignment smoothing in Planetary mode. * `BRotationStopTolerance` / `ERotationStopTolerance` — Angle threshold (normalized 0..1) for snapping rotation to target. * `BFloorDetectionTolerance` / `EFloorDetectionTolerance` — Extra distance for supplemental ground detection. * `BDynamicHeadTransitionRotationSpeed` / `EDynamicHeadTransitionRotationSpeed` — Quat step speed for head-probe transitions. * `BDynamicSurfaceSmoothingSpeed` / `EDynamicSurfaceSmoothingSpeed` — Lerp speed for Dynamic surface following. * `BDynamicEnhancedSmoothingSpeed` / `EDynamicEnhancedSmoothingSpeed` — First-stage lerp speed for enhanced smoothing. * `bBUseEnhancedSmoothing` / `bEUseEnhancedSmoothing` — Enables two-stage surface smoothing. #### **Overlap / Surface Meshes** * `OverlapMesh` — Mesh used to detect character overlaps. * `SurfaceMesh` — Mesh used for surface radius / alignment. * `OverlapRadius` / `SurfaceRadius` — Radius for overlap and surface detection (replicated, editable). #### **Overlap Gravity Functions (BlueprintNativeEvents / C++)** All functions return the resolved `UGravityMovementComponent*` for the affected character: * `ApplyBeginOverlapGravityDirectional(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyBeginOverlapGravityPlanetary(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyBeginOverlapGravityDynamic(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityDirectional(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityPlanetary(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEndOverlapGravityDynamic(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` * `ApplyEnterZeroGravity(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` — Enters zero gravity. Can be called from Begin or End Overlap. All other Apply functions automatically exit zero gravity before applying their mode. #### **Utility Functions** * `ResolveMovementComponent(ATPGravityCharacter*, AFPGravityCharacter*, ACharacter*)` — Internal helper to resolve which movement component to apply gravity to. * `OnRep_OverlapRadius()` / `OnRep_SurfaceRadius()` — Replication handlers for radius changes. #### **Editor / Replication Hooks** * `PreReplication(IRepChangedPropertyTracker&)` — Custom replication logic including direction sanitization. * `PostEditChangeProperty(FPropertyChangedEvent&)` — Editor hooks for property updates and direction normalization. * `BeginPlay()` — Initializes field and applies initial mesh scaling. *** #### **Key Notes** * Single unified Gravity Field: `AGravityField` handles all four gravity modes. * Data-driven & replicated: All gravity, rotation, and tunable settings are per-overlap and fully replicated. * High-Precision Support (v2.4.3): New `bBUseHighPrecisionMath` and `bEUseHighPrecisionMath` flags ensure stability at extreme world distances. * Zero Gravity: Full weightlessness mode with idempotent exit — safe to call unconditionally. `ExitZeroGravity` is called automatically inside every other Apply function. * Dynamic support: Surface Forward Probe system is opt-in via `bUsePredictiveProbes` — off by default, restoring v2.3.3 behavior as the default. When enabled drives wall and ledge transitions automatically with full hysteresis. * Optional / explicit: Nothing happens automatically — you must bind overlaps and call the appropriate Apply\* functions. * Mesh-based detection: Overlap and surface radius adjustable per instance. *** ## **UGravityMovementComponent – Public API (v2.3.0)** #### **Setters (Blueprint / C++)** * `SetGravityMode(EEffectiveGravityMode NewMode)` — Switch between `Planetary`, `Directional`, and `Dynamic` modes. * `SetEffectiveGravityPlanetary(const FVector& Center)` — Sets world-space center for Planetary mode. * `SetEffectiveGravityDirectional(const FVector& WorldDir)` — Sets normalized world-space direction for Directional mode. * `SetGravityRotationMode(EGravityRotationMode NewMode)` — Sets rotation constraints for gravity transitions (`Default`, `ForwardBack`, `LeftRight`). #### **Getters (Blueprint / C++)** * `GetGravityMode()` — Returns current `EEffectiveGravityMode`. * `GetGravityRotationMode()` — Returns current `EGravityRotationMode`. * `GetGravityCenter()` — Returns world-space Planetary center. * `GetGravityDirectionVector()` — Returns raw directional gravity vector. * `GetEffectiveGravityDirection()` — Returns smoothed applied direction (`GravityDirCached`). * `GetSurfaceGravityDirection()` — Returns target direction used for surface alignment smoothing. * `GetIsFalling()` — Returns predicted falling state for local owner or replicated state for remotes. #### **Events (Blueprint)** * `BP_OnFallingStateChanged(bool bIsFalling)` — Fires on falling state changes (owner prediction or replicated). * `BP_OnEffectiveGravityDirectionChanged(const FVector& NewEffectiveDir)` — Fires when a meaningful change in applied gravity occurs. #### **Controller / Utility Helpers (BlueprintPure)** * `GetGravityRelativeRotation(FRotator Rotation, FVector GravityDirection)` — Converts a world-space rotation to gravity-relative space. * `GetGravityWorldRotation(FRotator Rotation, FVector GravityDirection)` — Converts a gravity-relative rotation back to world space. #### **Key Enumerations** * `EEffectiveGravityMode` — `Planetary`, `Directional`, `Dynamic`. * `EGravityRotationMode` — `Default`, `ForwardBack`, `LeftRight`. #### **Configuration / Blueprint Properties** * `bApplyReplicatedRotationOnMovingBases` — Enforce visual rotation replication on moving platforms. * `bApplyGravityRotationWhileFlying` — Apply gravity-aligned rotation during flying mode. Note: rotating base support while flying is still in development. * `DynamicGravityTraceChannel` — Trace channel used for Dynamic gravity. * `LatchDistance` — Maximum distance the feet latch will remain attached to a detected surface. Default: `UE_LARGE_WORLD_MAX` (effectively unlimited). * `FallBackDir` — Default fallback gravity direction for Dynamic mode. * `FallBackTimer` — Time before fallback triggers in Dynamic mode. * `RotationSpeed` — Max rotation speed for smoothing (deg/sec). * `SurfaceLerpSpeed` — Speed for surface alignment smoothing. * `RotationStopTolerance` — Angle threshold for snapping rotation to target. * `FloorDetectionTolerance` — Extra distance for supplemental ground detection. * `bShowVisualDebugs` — Toggle debug visuals. ## **AGravityField – Public API (v2.3.0)** #### **Gravity Mode / Rotation Settings (Blueprint / C++)** * `BeginOverlapGravityMode` — Gravity mode applied when a character begins overlapping the field (`Planetary`, `Directional`, `Dynamic`). * `EndOverlapGravityMode` — Gravity mode applied when a character ends overlapping the field. * `BeginOverlapGravityRotationMode` — Rotation behavior applied when a character begins overlap (`Default`, `ForwardBack`, `LeftRight`). * `EndOverlapGravityRotationMode` — Rotation behavior applied when a character ends overlap. #### **Directional / Planetary Settings** * `BGravityDirection` — Normalized world-space directional vector used for BeginOverlap. * `BGravityCenter` — World-space center for Planetary mode used on BeginOverlap. * `EGravityDirection` — Directional vector for EndOverlap. * `EGravityCenter` — Planetary center for EndOverlap. #### **Dynamic Gravity Settings** * `BFallBackDir` / `EFallBackDir` — Default fallback direction when a Dynamic latch fails. * `BFallBackTimer` / `EFallBackTimer` — Duration for gravity transition trial before falling back. #### **Tunables / Smoothing** * `BRotationSpeed` / `ERotationSpeed` — Degrees per second for rotation smoothing. * `BSurfaceLerpSpeed` / `ESurfaceLerpSpeed` — Speed for surface alignment smoothing. * `BRotationStopTolerance` / `ERotationStopTolerance` — Angle threshold (normalized 0..1) for snapping rotation to target. * `BFloorDetectionTolerance` / `EFloorDetectionTolerance` — Extra distance for supplemental ground detection. #### **Overlap / Surface Meshes** * `OverlapMesh` — Mesh used to detect character overlaps. * `SurfaceMesh` — Mesh used for surface radius / alignment. * `OverlapRadius` — Radius for overlap detection (replicated, editable). * `SurfaceRadius` — Radius for surface alignment detection (replicated, editable). #### **Overlap Gravity Functions (BlueprintNativeEvents / C++)** All functions return the resolved `UGravityMovementComponent*` for the affected character(s): * `ApplyBeginOverlapGravityDirectional(ATPGravityCharacter* TPChar, AFPGravityCharacter* FPChar, ACharacter* Char)` * `ApplyBeginOverlapGravityPlanetary(ATPGravityCharacter* TPChar, AFPGravityCharacter* FPChar, ACharacter* Char)` * `ApplyBeginOverlapGravityDynamic(ATPGravityCharacter* TPChar, AFPGravityCharacter* FPChar, ACharacter* Char)` * `ApplyEndOverlapGravityDirectional(ATPGravityCharacter* TPChar, AFPGravityCharacter* FPChar, ACharacter* Char)` * `ApplyEndOverlapGravityPlanetary(ATPGravityCharacter* TPChar, AFPGravityCharacter* FPChar, ACharacter* Char)` * `ApplyEndOverlapGravityDynamic(ATPGravityCharacter* TPChar, AFPGravityCharacter* FPChar, ACharacter* Char)` > **Usage:** Call the appropriate function when handling `BeginOverlap` or `EndOverlap` events on the field. Each function resolves the correct movement component and applies gravity + rotation according to the selected mode. #### **Utility Functions** * `ResolveMovementComponent(ATPGravityCharacter* TPChar, AFPGravityCharacter* FPChar, ACharacter* Char)` — Internal helper to resolve which movement component to apply gravity to. * `OnRep_OverlapRadius()` / `OnRep_SurfaceRadius()` — Replication handlers for radius changes. #### **Editor / Replication Hooks** * `PreReplication(IRepChangedPropertyTracker&)` — Custom replication logic. * `PostEditChangeProperty(FPropertyChangedEvent&)` — Editor hooks for property updates. * `BeginPlay()` — Initializes field and caches references to overlapping characters and components. *** #### **Key Notes** * **Single unified Gravity Field:** `AGravityField` replaces separate FP/TP field blueprints. * **Data-driven & replicated:** All gravity and rotation settings are per-overlap, fully replicated. * **Dynamic support:** Applies fallbacks and timers for Dynamic gravity latches. * **Optional / explicit:** Nothing happens automatically; you must bind overlaps and call the appropriate `Apply*` functions (basic example setup included). * **Mesh-based detection:** Overlap and surface radius adjustable per instance. --- # 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/public-api.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.