Movement and Traversal System

This document describes the on-foot movement and traversal layer in RPG Engine v6.
It covers ground locomotion, sprinting, crouching, GASP-based parkour, dashes, ladders, and swimming, and explains how these mechanics integrate with the global State System, stats, and animation data.

Core Components

• BP_MovementComponent — main runtime component that controls on-foot movement and traversal.
  
• CharacterMovement — standard Unreal movement component referenced and driven by BP_MovementComponent.
  
• BP_ModulesMediator — routes movement-related state activation requests and coordinates movement states with other systems.
  
• DT_CharacterStates — defines movement and traversal states, their required/forbidden tags, and activation rules.
  
• BP_DA_Move_Container (movement container data asset) — configures speed presets for different movement modes.
  
• BP_MS_GASP_Movement and BP_MS_MovementBase — movement settings assets for ground, swimming, and flying movement.

Movement logic is fully integrated into the shared state system: all major movement actions are represented by CharacterStates and validated through BP_ModulesMediator on the server.

Movement Architecture

Movement input is handled through the input component and converted into state activation requests such as run, sprint, crouch, jump, parkour, dashes, ladder, and swim.
BP_ModulesMediator forwards these requests into the state system, which checks DT_CharacterStates rules (necessary and forbidden tags, additional component checks) and, if allowed, activates the corresponding movement state tags.

BP_MovementComponent reads movement-related states and parameters and drives CharacterMovement accordingly (movement mode, speed, gravity, etc.).
Animation selection for movement and traversal is driven by locomotion data assets and Chooser tables that map current state, weapon type, and traversal context into specific montages and poses.

Speed Configuration

Movement container data asset

Character movement speeds are configured through the DA_Movements_Container variable in BP_MovementComponent.
This variable references a data asset of type BP_DA_Move_Container, which holds separate movement settings for different movement contexts:

• OnNavMesh — ground movement settings using a BP_MS_GASP_Movement data asset.
  
• Swim — swimming movement settings using a BP_MS_MovementBase-derived data asset.
  
• Fly — flying movement settings using a BP_MS_MovementBase-derived data asset (reserved for future use).

OnNavMesh (ground) settings include:

• CrouchSpeeds
  
• WalkSpeeds (not used in the current build)
  
• RunSpeeds
  
• SprintSpeeds

In the current version the character always jogs by default (using RunSpeeds) and can transition to sprint (using SprintSpeeds) while holding the sprint key.
Dedicated “slow walk” is not exposed as a player-facing mode yet, even though the parameter exists in the data asset.

Ground movement modes

On NavMesh the project uses two practical ground speeds:

• Jog (default) — normal movement speed, based on RunSpeeds in BP_MS_GASP_Movement.
  
• Sprint — faster movement when the sprint key is held, based on SprintSpeeds.

Crouch uses its own speed values from CrouchSpeeds, making the character move slower while crouched.
Because speeds are fully data-driven, designers can tweak movement balance per project without modifying BP_MovementComponent graphs.

Movement States Overview

The following movement-related CharacterStates are used in the project:

• CharacterStates.Movement.Run
  
• CharacterStates.Movement.Crouch
  
• CharacterStates.Movement.Jump
  
• CharacterStates.Movement.Parkour
  
• CharacterStates.Movement.Swim
  
• CharacterStates.UnusualSkills.SimpleDash
  
• CharacterStates.UnusualSkills.JumpDash
  
• CharacterStates.UnusualSkills.StepDodge
  
• CharacterStates.UnusualSkills.OnLadder
  
• CharacterStates.UnusualSkills.LadderSpeed
  
• CharacterStates.UnusualSkills.LadderForceDown

Each of these states is defined in DT_CharacterStates with its own activation rules, required tags, forbidden tags, and follow-up tag transitions.
The state system ensures that movement actions can enforce conditions (for example, sufficient Energy) and cleanly block incompatible states such as some combat or UI states.

Crouch

Crouch behavior

Crouch is implemented as a dedicated movement state:

• CharacterStates.Movement.Crouch — makes the character crouch and move slower in a lower stance.

While crouched:

• Movement uses crouch-specific speeds from CrouchSpeeds in the ground movement data asset.
  
• Crouching does not consume Energy.

Crouch is configured in DT_CharacterStates so it can:

• Be activated via input only when allowed by other states.
  
• Block or be blocked by certain actions (for example, some traversal or combat states) depending on the project’s rules.

Run and Sprint

Jog (run) and sprint model

The project uses two main upright movement intensities:

• Default run/jog — the standard forward movement when no sprint key is held.
  
• Sprint — higher speed when the sprint key is held.

Internally, the state CharacterStates.Movement.Run represents active running movement.
The speed used depends on whether the sprint-modifier key is pressed:

• Without sprint key — speeds from RunSpeeds.
  
• With sprint key — speeds from SprintSpeeds.

Energy consumption

Sprint and other high-intensity movement states consume Energy through the stats system.
Energy-consuming movement-related states include:

• CharacterStates.Movement.Run (sprinting phase).
  
• CharacterStates.Movement.Jump.
  
• CharacterStates.Movement.Parkour.
  
• CharacterStates.UnusualSkills.SimpleDash.
  
• CharacterStates.UnusualSkills.JumpDash.
  
• CharacterStates.UnusualSkills.StepDodge.

If Energy is depleted, the state system can prevent re-activation of these expensive movement states through an additional check such as AC Energy Is Not Empty configured in DT_CharacterStates.
Energy consumption and regeneration frequencies and deltas are configured in BP_StatsComponent, as described in the stats and survival documentation.

Jump and Parkour (GASP)

Jump vs Parkour activation

When the player triggers a jump, the movement system first attempts to perform a parkour action rather than a simple vertical jump.
The high-level flow is:

1. Jump input triggers a request to activate CharacterStates.Movement.Parkour.
   
2. In the Parkour activation logic (AC Parkour function on the client), the system runs forward-facing traces to detect potential traversal obstacles.
   
3. Based on trace results, parkour data is passed into the Chooser table CHT_TraversalAnims to select the appropriate parkour type and animation.
   
4. If a valid parkour option is found, the Parkour state proceeds using that traversal type.
   
5. If no suitable obstacle is found, the system falls back to a standard jump by activating CharacterStates.Movement.Jump.

This makes jump input context-sensitive: near obstacles it triggers parkour moves, while in open space it behaves like a normal jump.

Parkour configuration

Parkour uses a single movement state:

• CharacterStates.Movement.Parkour — covers all GASP-based traversal moves.

The AC Parkour function determines the actual traversal type by:

• Performing traces in front of the character to collect environment data (height, distance, ledge position).
  
• Passing these parameters into the Chooser table CHT_TraversalAnims.
  
• Receiving traversal output describing which animation/montage to play and which traversal configuration to use.

GASP integration is implemented through BP_MS_GASP_Movement and locomotion data:

• BP_MS_GASP_Movement controls ground speeds and some parkour-related settings.
  
• Locomotion and traversal animation mapping is handled by BP_Locomotion data assets per weapon and a shared common animation data asset.

Rotation and speed ban tags

Global settings also include GameplayTag containers that affect movement and traversal while certain states are active:

• RotationRefreshBanTags — list of tags under which rotation refresh logic is disabled or limited.
  
• CalculateSpeedBanTags — list of tags under which movement speed calculation is suspended.

These containers allow traversal states like parkour, dashes, or cinematic actions to temporarily override regular rotation and speed updates.

Dashes and Dodges

Dash-related states

Three UnusualSkills are tightly connected to movement:

• CharacterStates.UnusualSkills.SimpleDash
  
• CharacterStates.UnusualSkills.JumpDash
  
• CharacterStates.UnusualSkills.StepDodge

All three are implemented as movement-like actions driven by root motion animations.
They are high-intensity states and therefore consume Energy when used.

Animation and data assets

Dash and dodge animations are root-motion-based and configured in:

• DA_CommonAnims — shared common animation data asset that contains root motion dash/dodge/jump dash montages.
  
• BP_Locomotion data assets per weapon — define how these common dashes are blended with weapon-specific locomotion and overlay poses.

When a dash state is activated:

• The state system validates conditions in DT_CharacterStates (for example, required modifier keys, forbidden states like OnLadder).
  
• BP_MovementComponent triggers the configured root motion montage through locomotion data.
  
• The montage itself drives character displacement; CharacterMovement follows root motion rather than regular input while the dash plays.

These actions are pure movement bursts; by default they do not provide invulnerability frames and are not treated as damage-avoidance skills on the damage pipeline level.

Ladders

Ladder states

Ladder traversal is implemented through the following states:

• CharacterStates.UnusualSkills.OnLadder — active while the character is attached to a ladder.
  
• CharacterStates.UnusualSkills.LadderSpeed — state that represents accelerated ladder climbing (for example, when holding sprint).
  
• CharacterStates.UnusualSkills.LadderForceDown — state for fast sliding down the outside of a ladder when pressing the forced descent key.

The state system ensures that while OnLadder is active, incompatible movement and combat states (such as some melee attacks or certain parkour actions) are blocked.

Ladder parameters and behavior

Key ladder parameters are configured in movement settings and states:

• LadderSpeed — base speed for moving on the ladder.
  
• Ladder Accelerated Speed — increased climb speed when the acceleration condition is met (for example, sprint key held).
  
• LadderForceDown and Ladder Force Down Speed — control fast sliding down the ladder when the player holds the designated key (Left Ctrl).

Force down does not detach from the ladder abruptly: when the player presses the force down key, the character grabs the outer side of the ladder and quickly slides down while remaining on the ladder.

Ladder-specific AnimNotifies manage details such as:

• Which hand is currently leading on the ladder (for animation logic).
  
• When ladder variables are reset after leaving the ladder.
  
• When to update ladder transition states.

Swimming and Underwater Detection

Swimming movement

Swimming is implemented as a full movement mode using CharacterMovement and the movement state system:

• CharacterStates.Movement.Swim — indicates that the character is in swimming mode.
  
• Swimming speeds and acceleration are configured via a BP_MS_MovementBase-derived data asset referenced as Swim inside BP_DA_Move_Container.

When the character enters an Unreal PhysicsVolume configured for water, CharacterMovement automatically switches to the swimming mode.
BP_MovementComponent and states coordinate the rest of the traversal behavior (animations, transitions, and interaction with stats).

Head-under-water detection

Underwater breath logic uses a dedicated periodic check:

• A timer calls the CheckHeadUnderWater function at a frequency defined by CheckHeadUnderWaterFrequency.
  
• CheckHeadUnderWater performs a line trace:
  • Start: head socket location + Vector(0, 0, 40.f).
    
  • End: head socket location − Vector(0, 0, 100.f).
    
• If the trace hits water, the character’s head is considered to be under water.

When the head is detected underwater:

• The state CharacterStates.Effects.HeadUnderWater is activated.
  
• This state triggers air (breath) consumption in the stats system, which may later lead to suffocation damage if breath is depleted.

Exiting the underwater condition deactivates HeadUnderWater, stopping further air consumption and suffocation damage (details in the stats and survival documentation).

Integration with Stats (Energy and Breath)

Movement and survival are tightly connected through Energy and Breath:

• Sprint, jump, parkour, SimpleDash, JumpDash, and StepDodge consume Energy while active, using parameters defined in BP_StatsComponent.
  
• CharacterStates.Effects.HeadUnderWater activates breath loss, and once breath runs out, suffocation damage is applied to Health over time.

DT_CharacterStates can require Energy-related checks (for example, additional checks ensuring sufficient Energy) before activating expensive movement states.
The stats and survival system remains the authority for numeric changes, while the movement system decides when survival conditions such as underwater or sprint are active.

Multiplayer Behavior

The movement and traversal system relies on standard CharacterMovement replication for physical movement while treating CharacterStates as the authoritative gameplay truth.
Clients send input that requests activation of movement states; the server validates these requests via BP_ModulesMediator and DT_CharacterStates, then applies and replicates the resulting states back to clients.

Because movement and traversal are state-driven:

• The same state model is used for on-foot movement, parkour, dashes, ladders, and swimming.
  
• Movement-related restrictions (for example, blocking dash during certain abilities) remain consistent across singleplayer and multiplayer.

Related Docs

The movement and traversal system is closely connected with:

• docs/systems/state/state-system.md — global state machine that controls movement states and transitions.
  
• docs/systems/stats/stats-and-survival-system.md — Energy and Breath stats that interact with sprinting, parkour, dashes, and underwater behavior.
  
• docs/systems/firearms/firearms-system.md — aiming and ADS behavior that affects character rotation and camera.
  
• docs/systems/melee/melee-system.md — melee attacks that can block or override movement states during combat.
  
• docs/systems/interaction/interaction-and-items.md — interaction states (doors, stations, ladders entry) that temporarily modify movement.
  
• docs/systems/vehicles/vehicles-system.md — transitions between on-foot movement and driving or passenger modes.
  
• docs/reference/reference-data-tables.md — DT_CharacterStates and global settings related to movement and traversal.