Movement

The Movement subsystem handles all unit locomotion. It is mode-driven: a single named mode is active at a time, and only the mover and grounder whose mode name matches will run each tick. This makes locomotion fully composable without any mover combining logic.

The subsystem has four layers:

• Mover Context — Central hub. Transforms raw input into camera-relative and ground-projected vectors, owns mode switching, context states, and profile management.
• Movers — Translate MoverContext input into physics forces on the rigid body. One mover is active at a time per mode.
• Grounders — Detect ground contact, slope, and surface normal. Write results to the MoverContext and trigger mode switches.
• Movement Influence — Spatial zones and global fallbacks that supply the active GS_UnitMovementProfile.

For usage guides and setup examples, see The Basics: GS_Unit.

 

Contents

• Architecture
• Movement Profile
• Movement Influence
• Sub-Sections
• See Also

---

Architecture

Breakdown

Movers and Grounders are multiple components on a Unit that are constantly changing activation based on the units state. When a mover is active, it freely processes the unit’s movement based on it’s functionality. At any moment, through internal or external forces, the Movement, Rotation, or Grounding state can change, which disables the old movers, and activates the new one to continue controlling the Unit.

Input
    ↓  InputDataNotificationBus::InputStateChanged
Input Reactor Components
    ↓  MoverContextRequestBus::SetMoveInputAxis
GS_MoverContextComponent
    ↓  ModifyInputAxis() → camera-relative
    ↓  GroundInputAxis() → ground-projected
    ↓  MoverContextNotificationBus::MovementModeChanged("Free")
GS_3DFreeMoverComponent  [active when mode == "Free"]
    ↓  AccelerationSpringDamper → rigidBody->SetLinearVelocity
GS_PhysicsRayGrounderComponent  [active when grounding mode == "Free"]
    ↓  MoverContextRequestBus::SetGroundNormal / SetContextState("grounding", ...)
    ↓  MoverContextRequestBus::ChangeMovementMode("Slide")  ← when slope too steep
GS_3DSlideMoverComponent  [active when mode == "Slide"]

The Slide mover activates when the Unit is walking on too steep an angle. It takes control over the unit, slides down the hill, then restores the previous movement behaviour.

• The Basics: Mover Context — Movement modes, grounding states, and configuration.
• The Basics: Movement — Mover types, grounder types, and ScriptCanvas usage.
• Framework API: Input Reactor — InputDataComponent schema, reactor base class, and C++ extension.
• Framework API: Mover Context — Context state, mode authority, and C++ extension.
• Framework API: Movers — Mover and grounder components, movement APIs, and C++ extension.

---

Movement Profile

GS_UnitMovementProfile is an asset that holds locomotion parameters. Movers read from the active profile via activeProfile pointer, which the MoverContext updates whenever the profile changes.

Field	Type	Description
LocomotionStyle	enum	Movement style archetype (affects animation matching).
moveSpeed	float	Target movement speed (m/s).
speedChangeSmoothing	float	Lerp factor for speed transitions between profiles.
canSprint	bool	Whether this profile allows sprinting.
canJump	bool	Whether this profile allows jumping.
canRoll	bool	Whether this profile allows rolling.

Create movement profiles as data assets in the Asset Editor. Assign a default profile to the GS_MoverContextComponent in the Inspector. Spatial influence zones can override the active profile at runtime.

Reading Movement Profile Data - ScriptCanvas

---

Movement Influence

The MoverContext selects the active profile by priority:

1. Influence list — MovementInfluenceFieldComponent adds its profile when the unit enters its trigger volume. Multiple fields stack by priority.
2. Global fallback — if the influence list is empty and allowGlobalInfluence is true, falls back to GlobalMovementRequestBus::GetGlobalMovementProfile.
3. Default profile — the defaultMoveProfile assigned directly on the GS_MoverContextComponent.

MovementInfluenceFieldComponent

Inherits PhysicsTriggerComponent. On TriggerEnter, calls MoverContextRequestBus::AddMovementProfile(entityId, profile*) on the entering unit. On TriggerExit, calls RemoveMovementProfile(entityId).

Request Bus: MovementInfluenceRequestBus

ById bus — addressed by the influence field’s entity ID.

Method	Parameters	Returns	Description
GetPriority	—	int	Returns this field’s priority. Higher values take precedence when multiple fields overlap.

GlobalMovementRequestBus

Broadcast bus — single global instance.

Method	Parameters	Returns	Description
GetGlobalMovementProfile	—	GS_UnitMovementProfile*	Returns the global fallback movement profile. Used by the MoverContext when no influence fields are active.

---

Sub-Sections

• Mover Context — Input transformation, mode switching, context states, profile management
• Movers — Mover base class and concrete movers (GS_3DFreeMoverComponent, GS_3DSlideMoverComponent)
• Grounders — Grounder base class and concrete grounders (GS_PhysicsRayGrounderComponent)

---

See Also

• Units — Unit entity setup and GS_UnitComponent
• Unit Controllers — Controllers that manage possession and drive input routing
• Input Data — The input pipeline that feeds movement reactors
• Stage Data — Handler for current stage functionality and global effects
• Springs Utility — Spring-damper functions used by movers and grounders
• Physics Trigger Volume — Physics overlap that triggers functionality.

---

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

1 - Mover Context

GS_MoverContextComponent is the central state store for all movement on a unit. It sits between the input layer and the mover/grounder layer, holds all shared movement data, owns the mode-switching logic, and manages the active movement profile.

Movers and Grounders never communicate directly — they all read from and write to the MoverContext.

For usage guides and setup examples, see The Basics: GS_Unit.

Contents

• Input Transformation Pipeline
• Mode Switching
• Context States
• Movement Profile Management
• Editor-Exposed Fields
• API Reference
• See Also

Input Transformation Pipeline

Raw input from reactor components arrives as a Vector2 (rawMoveInput). The MoverContext applies two sequential transformations each time input changes.

Step 1 — ModifyInputAxis() — Camera-Relative

For a player unit (detected by “Player” tag): fetches the active camera’s world transform, flattens its forward and right vectors to the XY plane, then computes:

modifiedMoveInput = camForward * rawInput.Y + camRight * rawInput.X

For AI units (or when inputOverride = true): uses world cardinal axes (Y=forward, X=right).

Step 2 — GroundInputAxis() — Ground-Projected

Projects modifiedMoveInput onto the ground plane using the current groundNormal:

groundedMoveInput = modifiedMoveInput - groundNormal * dot(modifiedMoveInput, groundNormal)

Direction is then normalized and the original magnitude is restored. Movers use groundedMoveInput so movement always follows the surface contour, even on slopes.

Both steps run automatically whenever SetMoveInputAxis is called and again whenever SetGroundNormal is called (ground changed under a moving unit).

Mode Switching

The MoverContext maintains three independent mode strings, each with a current and last value:

ChangeMovementMode("Free") updates the string and broadcasts MoverContextNotificationBus::MovementModeChanged("Free"). Each Mover and Grounder component checks whether its own named mode matches the broadcast and activates or deactivates itself accordingly.

RevertToLastMovementMode() swaps current and last — enabling one-step undo (e.g., return from “Slide” to whatever was active before).

Context States

A generic key-value store for runtime state flags used by movers and grounders:

AZStd::unordered_map<AZStd::string, AZ::u32> contextStates

SetContextState(name, value) writes and broadcasts MoverContextNotificationBus::ContextStateChanged.

Known state keys:

Movement Profile Management

The MoverContext selects the active GS_UnitMovementProfile* by priority:

1. Influence list — AddMovementProfile(influencer, profile*) is called by MovementInfluenceFieldComponent when the unit enters a trigger volume. Multiple fields stack additively by priority via MovementInfluenceRequestBus::GetPriority.
2. Global fallback — if influenceList is empty and allowGlobalInfluence is true, checks GlobalMovementRequestBus::GetGlobalMovementProfile.
3. Default profile — the asset-configured defaultMoveProfile on the component.

When the profile changes, MoverContextNotificationBus::MovementProfileChanged(profile*) is broadcast. Movers update their cached activeProfile pointer.

Standby behavior:

• UnitEnteringStandby → clears the influence list, broadcasts empty mode names (disables all movers/grounders)
• UnitExitingStandby → re-evaluates profile priority, re-broadcasts current mode names to re-enable the correct movers

Editor-Exposed Fields

API Reference

Request Bus: MoverContextRequestBus

Commands sent to a specific unit’s MoverContext. ById bus — addressed by unit entity ID.

Input Axis:

Ground State:

Context States:

Mode Switching:

Profile Management:

Notification Bus: MoverContextNotificationBus

Events broadcast by the MoverContext. ById bus — addressed by unit entity ID. Movers and Grounders subscribe to this.

Virtual Methods

Override these when extending the MoverContext.

Script Canvas Examples

Changing movement mode:

Reverting to the previous movement mode:

Setting a context state flag:

See Also

• Movers — Mover components that read from the MoverContext
• Grounders — Grounder components that write ground state to the MoverContext
• Movement — Movement system overview
• Input Data — The input pipeline that feeds SetMoveInputAxis

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

2 - Movers

Movers translate the processed movement input from the MoverContext into physics forces on the unit’s rigid body. Each mover activates for a specific named mode — when the MoverContext broadcasts MovementModeChanged("Free"), only the mover whose m_moveModeName matches "Free" activates. All others deactivate. This makes the locomotion system fully mode-driven and composable.

For usage guides and setup examples, see The Basics: GS_Unit.

Contents

• Class Hierarchy
• GS_MoverComponent (Base)
• GS_PhysicsMoverComponent
• Concrete Movers
• API Reference
• Extension Guide
• See Also

Class Hierarchy

GS_MoverComponent (base — mode-aware activation, tick management)
  └── GS_PhysicsMoverComponent (adds RigidBody cache + validity check)
        ├── GS_3DFreeMoverComponent    (mode: "Free")
        └── GS_3DSlideMoverComponent   (mode: "Slide")

GS_MoverComponent (Base)

Tick: AzPhysics::SystemEvents::OnPostSimulateEvent (after the physics step). Optional debugForceTick uses AZ::TickBus for debugging without physics.

Mode-Aware Activation

Listens to MoverContextNotificationBus::MovementModeChanged and RotationModeChanged. Compares the broadcast mode name against its own m_moveModeName and m_rotateModeName. Calls ToggleMovement(true/false) and ToggleRotation(true/false) accordingly. The physics post-simulate handler is only registered when the mover is active, saving ticks when inactive.

Per-Tick Processing

Each tick:

1. CheckCanOperate() — validates that the required pointers and state are valid
2. HandleMovement() — calculates and applies movement (no-op in base)
3. HandleRotation() — calculates and applies rotation (no-op in base)

Key Fields

GS_PhysicsMoverComponent

Extends GS_MoverComponent. On activate, fetches AzPhysics::RigidBody* from the entity. CheckCanOperate() verifies the rigid body pointer is valid before allowing tick processing.

Concrete Movers

API Reference

Movers consume two buses and produce one:

Consumed

Virtual Methods

Override these when extending any mover:

Extension Guide

Use the Mover ClassWizard template to generate a new mover with boilerplate already in place — see GS_Unit Templates. The template offers two base class options: Physics Mover (default) for rigid-body locomotion, and Base Mover for transform-only movement.

Extend GS_PhysicsMoverComponent to create a custom physics-driven mover.

#pragma once
#include <Source/Unit/Mover/GS_PhysicsMoverComponent.h>

namespace MyProject
{
    class MyCustomMover : public GS_Unit::GS_PhysicsMoverComponent
    {
    public:
        AZ_COMPONENT_DECL(MyCustomMover);
        static void Reflect(AZ::ReflectContext* context);

    protected:
        void Activate() override;

        void HandleMovement() override;
        void HandleRotation() override;

    private:
        // Mode name must be set in Activate():
        // m_moveModeName = "MyMode";
        // m_rotateModeName = "MyMode";
    };
}

In HandleMovement(), read from the MoverContext and write to the rigid body:

void MyCustomMover::HandleMovement()
{
    AZ::Vector3* groundedInput = nullptr;
    GS_Unit::MoverContextRequestBus::EventResult(
        groundedInput, GetEntityId(),
        &GS_Unit::MoverContextRequestBus::Events::GetGroundMoveInputAxis
    );

    if (!groundedInput || groundedInput->IsZero()) return;

    AZ::Vector3 targetVelocity = *groundedInput * activeProfile->moveSpeed;
    m_rigidBody->SetLinearVelocity(targetVelocity);
}

See Also

• Mover Context — Provides all input data movers read from
• GS_3DFreeMoverComponent — The standard free-locomotion mover
• GS_3DSlideMoverComponent — The slope-slide mover
• Grounders — Provide ground state and trigger mode switches
• Movement Profile — Asset defining speed and locomotion parameters

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

2.1 - 3D Free Mover

GS_3DFreeMoverComponent is the standard mover for walking characters. It reads the ground-projected input vector from the MoverContext, applies optional slope attenuation, computes a destination velocity, and drives the rigid body via AccelerationSpringDamper. Rotation is handled separately using QuaternionSpringDamper to face the last non-zero movement direction.

Mode names: "Free" (both movement and rotation)

For usage guides and setup examples, see The Basics: GS_Unit.

Contents

• How It Works
• Slope Slowdown
• Speed Calculation
• Editor-Exposed Settings
• Extension Guide
• See Also

How It Works

HandleMovement()

Called each post-physics tick while movement mode is "Free":

1. Reads groundedMoveInput pointer from MoverContextRequestBus::GetGroundMoveInputAxis.
2. If EnableSlopeSlowdown is true, attenuates the input vector on steep slopes (see Slope Slowdown).
3. Multiplies the attenuated direction by CalculateSpeed() to get destinationVelocity.
4. Fetches rigidBody->GetLinearVelocity() as the current velocity.
5. Calls GS_Core::Springs::AccelerationSpringDamper(position, velocity, cachedAcceleration, destinationVelocity, moveHalflife, delta).
6. Applies the result: rigidBody->SetLinearVelocity(velocity).

The cachedAcceleration is a member field that persists between frames to produce smooth acceleration response even on sudden direction changes.

HandleRotation()

1. Reads groundedMoveInput from the MoverContext.
2. Updates lastDirection only when groundedMoveInput is non-zero — so the unit keeps facing the last direction when stopped.
3. Computes target yaw from lastDirection using atan2f.
4. Calls GS_Core::Springs::QuaternionSpringDamper(currentRotation, cachedAngularVelocity, targetRotation, rotateHalflife, delta).
5. Applies cachedAngularVelocity.Z to rigidBody->SetAngularVelocity().

StopMovement State

When ContextStateChanged("StopMovement", 1) fires, the mover zeros both velocity and cached acceleration, then clears the state back to 0. This allows other systems (e.g. landing from a jump, ability wind-up) to cleanly halt the unit.

Slope Slowdown

When EnableSlopeSlowdown is true, the mover reduces movement speed as the slope angle increases toward maxWalkAngle. The attenuation curve uses an exponent applied to the dot product of the movement direction against the uphill slope direction:

attenuation = 1.0 - uphillSlowStrength * pow(dot(moveDir, slopeDir), uphillSlowExponent)
              × remap(slopeAngle, startSlowAngle, maxWalkAngle, 0, 1)

The slowdown begins at startSlowAngle degrees and reaches maximum reduction at maxWalkAngle. At or beyond maxWalkAngle, the grounder will switch the unit to "Slide" mode regardless.

Speed Calculation

CalculateSpeed() lerps curSpeed toward activeProfile->moveSpeed each frame:

curSpeed = AZ::Lerp(curSpeed, activeProfile->moveSpeed, expf(-speedChangeSmoothing * delta));

speedChangeSmoothing is read from activeProfile. This produces a smooth speed transition when the movement profile changes (e.g. entering a slow zone).

Editor-Exposed Settings

Extension Guide

Extend GS_3DFreeMoverComponent to override movement or rotation behavior while keeping the base spring physics.

#pragma once
#include <Source/Unit/Mover/GS_3DFreeMoverComponent.h>

namespace MyProject
{
    class MyFreeMove : public GS_Unit::GS_3DFreeMoverComponent
    {
    public:
        AZ_COMPONENT_DECL(MyFreeMove);
        static void Reflect(AZ::ReflectContext* context);

    protected:
        void HandleMovement() override;
    };
}

void MyFreeMove::HandleMovement()
{
    // Call base for standard spring movement
    GS_3DFreeMoverComponent::HandleMovement();

    // Add custom post-processing (e.g. strafe penalty, footstep IK correction)
}

See Also

• Movers — Mover base class and class hierarchy
• GS_3DSlideMoverComponent — Activated automatically when slope exceeds max walk angle
• Mover Context — Provides groundedMoveInput and activeProfile
• Springs Utility — AccelerationSpringDamper and QuaternionSpringDamper used internally

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

2.2 - Slide Mover

GS_3DSlideMoverComponent handles slope-sliding locomotion. It activates automatically when the grounder detects a slope angle exceeding maxWalkAngle, and deactivates when the slope eases or the unit slows enough to recover.

Mode names: "Slide" (both movement and rotation)

For usage guides and setup examples, see The Basics: GS_Unit.

Contents

• How It Works
• Finish Sliding
• Editor-Exposed Settings
• Extension Guide
• See Also

How It Works

HandleMovement()

Called each post-physics tick while movement mode is "Slide":

1. Reads slopeDir from MoverContextRequestBus::GetSlopeDirection.
2. Computes destinationVelocity = slopeDir * baseSlideSpeed.
3. If EnableInputSlideResistance is true, reads groundedMoveInput and applies an opposing influence:

   destinationVelocity += groundedMoveInput * InputResistanceInfluence
   

   This allows the player to push slightly against or across the slide direction.
4. Fetches rigidBody->GetLinearVelocity() as the current velocity.
5. Calls GS_Core::Springs::AccelerationSpringDamper(position, velocity, cachedAcceleration, destinationVelocity, moveHalflife, delta).
6. Applies the result: rigidBody->SetLinearVelocity(velocity).
7. Calls FinishSliding() to check whether the slide should end.

HandleRotation()

1. Reads slopeDir from the MoverContext.
2. Computes target yaw from slope direction using atan2f — unit faces down the slope.
3. Calls GS_Core::Springs::QuaternionSpringDamper(currentRotation, cachedAngularVelocity, targetRotation, rotateHalflife, delta).
4. Applies cachedAngularVelocity.Z to rigidBody->SetAngularVelocity().

Finish Sliding

FinishSliding() is called every movement tick. It returns true and triggers recovery when both conditions are met:

• The current slope angle is below minSlideAngle
• The unit’s current speed is below minSpeedToStop

On recovery:

MoverContextRequestBus::ChangeMovementMode(recoveryMoveMode);
MoverContextRequestBus::ChangeRotationMode(recoveryRotateMode);

Both modes default to "Free", returning the unit to standard locomotion.

Editor-Exposed Settings

Extension Guide

Extend GS_3DSlideMoverComponent to override slide behavior while keeping the base spring physics and recovery logic.

#pragma once
#include <Source/Unit/Mover/GS_3DSlideMoverComponent.h>

namespace MyProject
{
    class MySlide : public GS_Unit::GS_3DSlideMoverComponent
    {
    public:
        AZ_COMPONENT_DECL(MySlide);
        static void Reflect(AZ::ReflectContext* context);

    protected:
        void HandleMovement() override;
    };
}

void MySlide::HandleMovement()
{
    // Call base for standard slope physics
    GS_3DSlideMoverComponent::HandleMovement();

    // Add custom post-processing (e.g. audio trigger, particle effect on slide)
}

See Also

• Movers — Mover base class and class hierarchy
• GS_3DFreeMoverComponent — Standard free-locomotion mover
• Mover Context — Provides slopeDir, groundedMoveInput, and mode switching
• Grounders — Detect slope angle and trigger the switch to Slide mode
• Springs Utility — AccelerationSpringDamper and QuaternionSpringDamper used internally

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

2.3 - 3D Strafe Mover

The 3D Strafe Mover provides aim-relative movement where the unit strafes relative to its facing direction. This is the standard movement model for first-person and third-person shooters where the camera or aim direction determines the movement frame.

This component is not yet implemented. This page will be updated with full API reference and usage documentation when the component is available.

For usage guides and setup examples, see The Basics: GS_Unit.

See Also

• Movement – Movement subsystem overview
• 3D Free Mover – Free three-dimensional movement
• Slide Mover – Surface-sliding movement

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

2.4 - Side Scroller Mover

The Side Scroller Mover provides two-dimensional movement constrained to a horizontal plane with vertical jump support. This is the standard movement model for side-scrolling platformers, beat-em-ups, and other 2D gameplay projected in a 3D environment.

This component is not yet implemented. This page will be updated with full API reference and usage documentation when the component is available.

For usage guides and setup examples, see The Basics: GS_Unit.

See Also

• Movement – Movement subsystem overview
• Movers – All available mover components

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

2.5 - Grid Step Mover

The Grid Step Mover provides discrete, tile-based movement for units that move in fixed steps along a grid. This is the standard movement model for turn-based RPGs, tactics games, puzzle games, and any project that uses grid-locked locomotion.

This component is not yet implemented. This page will be updated with full API reference and usage documentation when the component is available.

For usage guides and setup examples, see The Basics: GS_Unit.

See Also

• Movement – Movement subsystem overview
• Movers – All available mover components

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

3 - Grounders

Grounders run each physics tick to determine whether the unit is in contact with the ground, what the slope looks like, and whether the surface is walkable. They write their findings to the MoverContext and switch movement modes when the ground state changes.

For usage guides and setup examples, see The Basics: GS_Unit.

Contents

• Class Hierarchy
• GS_GrounderComponent (Base)
• Concrete Grounders
• API Reference
• Extension Guide
• See Also

Class Hierarchy

GS_GrounderComponent (base — mode-aware activation, tick management)
  └── GS_PhysicsRayGrounderComponent  (grounding mode: "Free")

GS_GrounderComponent (Base)

Tick: AzPhysics::SystemEvents::OnPostSimulateEvent (after the physics step).

Mode-Aware Activation

Listens to MoverContextNotificationBus::GroundingModeChanged. Compares the broadcast mode name against its own m_groundModeName. Calls ToggleGrounder(true/false) accordingly. The physics post-simulate handler is only registered when the grounder is active.

Per-Tick Processing

Each tick:

1. CheckCanOperate() — validates required pointers and state
2. HandleGrounding() — performs ground detection and updates MoverContext (no-op in base)

Key Fields

Concrete Grounders

API Reference

Virtual Methods

Override these when extending any grounder:

Consumed Buses

Produced Calls

Extension Guide

Use the Grounder ClassWizard template to generate a new grounder with boilerplate already in place — see GS_Unit Templates. The template offers two base class options: Physics Ray Grounder (default, includes raycast, coyote time, and gravity) or Base Grounder for fully custom detection.

Extend GS_GrounderComponent to implement custom ground detection.

#pragma once
#include <Source/Unit/Grounder/GS_GrounderComponent.h>

namespace MyProject
{
    class MyGrounder : public GS_Unit::GS_GrounderComponent
    {
    public:
        AZ_COMPONENT_DECL(MyGrounder);
        static void Reflect(AZ::ReflectContext* context);

    protected:
        void Activate() override;

        void HandleGrounding() override;
        void GroundingStateChange(AZ::u32 newState) override;

    private:
        // Set in Activate():
        // m_groundModeName = "Free";
    };
}

In HandleGrounding(), run your detection and write results to the MoverContext:

void MyGrounder::HandleGrounding()
{
    AZ::Vector3 groundNormal = AZ::Vector3::CreateAxisZ();
    bool isGrounded = false;

    // ... custom detection logic ...

    GS_Unit::MoverContextRequestBus::Event(
        GetEntityId(),
        &GS_Unit::MoverContextRequestBus::Events::SetGroundNormal,
        groundNormal
    );

    AZ::u32 state = isGrounded ? 1 : 0;
    GS_Unit::MoverContextRequestBus::Event(
        GetEntityId(),
        &GS_Unit::MoverContextRequestBus::Events::SetContextState,
        "grounding", state
    );
}

See Also

• GS_PhysicsRayGrounderComponent — The standard raycast grounder
• Mover Context — Receives ground state and normal from grounders
• Movers — Consume ground state to drive physics
• Movement — Movement system overview

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.

3.1 - 3D Free Grounder

GS_PhysicsRayGrounderComponent is the standard grounder for walking characters. Each physics tick it casts a ray downward from the unit’s capsule base, evaluates the slope, applies gravity when airborne, and updates the MoverContext with ground normal and grounding state.

Grounding mode name: "Free"

For usage guides and setup examples, see The Basics: GS_Unit.

Contents

• How It Works
• Ground Check
• Grounding Move
• Grounding State Changes
• Editor-Exposed Settings
• Extension Guide
• See Also

How It Works

Each post-physics tick, the grounder runs two operations in order:

1. GroundCheck() — determines contact, slope, and normal
2. GroundingMove() — applies gravity or snap force based on contact result

Ground Check

GroundCheck() casts a sphere (matching the capsule base radius) downward from the unit’s feet:

1. If the ray hits geometry within groundCheckDistance:
   • Computes slope angle from the hit normal vs. world up.
   • Updates MoverContextRequestBus::SetGroundNormal(hitNormal).
   • If slope angle ≤ maxWalkAngle (from the MoverContext): reports Grounded.
   • If slope angle > maxWalkAngle: reports Sliding.
   • Resets coyote timer.
2. If no hit:
   • Increments coyoteTimer.
   • If coyoteTimer < coyoteTime: still reports Grounded (coyote grace period).
   • If coyoteTimer ≥ coyoteTime: reports Falling.

Grounding Move

GroundingMove() applies vertical forces based on the current state:

Grounded: Applies a downward TimedSpringDamper to keep the unit snapped to the surface without bouncing.

Falling: Applies manual gravity — adds gravityScale * AZ::Physics::DefaultGravity to the rigid body’s linear velocity each frame:

AZ::Vector3 velocity = rigidBody->GetLinearVelocity();
velocity.SetZ(velocity.GetZ() + gravity * delta);
rigidBody->SetLinearVelocity(velocity);

Sliding: Does not override vertical velocity — the Free Mover’s AccelerationSpringDamper handles the slide direction entirely.

Grounding State Changes

GroundingStateChange(newState) is called whenever the ground state changes:

When returning to Grounded from Sliding, the grounder calls ChangeMovementMode("Free") to restore locomotion.

Editor-Exposed Settings

Extension Guide

Extend GS_PhysicsRayGrounderComponent to add custom ground detection or state reactions.

#pragma once
#include <Source/Unit/Grounder/GS_PhysicsRayGrounderComponent.h>

namespace MyProject
{
    class MyGrounder : public GS_Unit::GS_PhysicsRayGrounderComponent
    {
    public:
        AZ_COMPONENT_DECL(MyGrounder);
        static void Reflect(AZ::ReflectContext* context);

    protected:
        void GroundingStateChange(AZ::u32 newState) override;
    };
}

void MyGrounder::GroundingStateChange(AZ::u32 newState)
{
    // Call base to handle mode switching
    GS_PhysicsRayGrounderComponent::GroundingStateChange(newState);

    if (newState == 0)
    {
        // Unit became airborne — trigger jump animation, etc.
    }
}

See Also

• Grounders — Grounder base class and class hierarchy
• Slide Mover — Activated when this grounder reports Sliding state
• Mover Context — Receives ground normal and state from this grounder
• Springs Utility — TimedSpringDamper used for ground snap

Get GS_Unit

GS_Unit — Explore this gem on the product page and add it to your project.