MotionCrouchingComponent

Manages crouch state using Unreal's native crouch system with GAS integration, speed modifiers, and ceiling collision detection. The component wraps Character->Crouch()/UnCrouch() functions with additional features like speed effects and tag management.

Requirements

• Character with standard UCharacterMovementComponent and UCapsuleComponent
• MotionPlayerState configured in GameMode
• Gameplay Ability System (GAS) initialized
• Enhanced Input System configured
• Gameplay Effects:
  • GE_Motion_CrouchSpeed - Modifies walk speed while crouching
  • GE_Motion_WantsToCrouch - Grants wants to crouch tag
  • GE_Motion_Crouching - Grants crouching state tag
• Gameplay Tags:
  • Motion.State.WantsToCrouch - Player input to crouch
  • Motion.State.Crouching - Active crouching state
  • Attribute.Movement.WalkSpeed - Movement speed attribute

Installation

1. Add UMotionCrouchingComponent to your Character Blueprint or C++ class
2. Configure the component properties in the Details panel
3. Set the CrouchingTagEffect to GE_Motion_Crouching
4. Set the WantsToCrouchTagEffect to GE_Motion_WantsToCrouch
5. Configure CapsuleHalfHeightWhenCrouching (default: 48.0)
6. Set CrouchSpeedEffect to GE_Motion_CrouchSpeed for GAS-based speed modification
7. Bind crouch input action in Enhanced Input or through component

Functionality

The component uses Unreal's built-in Character crouch system with automatic server replication, while the camera component handles its own height interpolation separately.

Crouch State Machine

Update Flow

Expandability

The MotionCrouchingComponent provides virtual functions for customization:

Core Crouch Functions

Function	Parameters	Returns	Use Case Examples
SetWantsToCrouch()	bool bWantsToCrouch	void	• Add cooldown timer • Check prerequisites
GetWantsToCrouch()	None	bool	• Query crouch intent • UI state display
IsCurrentlyCrouching()	None	bool	• Check active crouch • Animation triggers
IsFullyCrouched()	None	bool	• Verify crouch active • Enable abilities
IsUncrouchBlocked()	None	bool	• Check ceiling collision • Show UI warning
GetCurrentCapsuleHalfHeight()	None	float	• Query capsule height • Calculate positions

State Management Functions

Function	Parameters	Returns	Use Case Examples
UpdateCrouchingState()	float DeltaTime	void	• Custom state logic • Monitor changes
InitializeComponent()	None	void	• Additional setup • Cache references
HandleCrouchInputStateChange()	bool bPressed	void	• Process input • Toggle mode

Collision Detection Functions

Function	Parameters	Returns	Use Case Examples
GetCapsuleOverlapResult()	const FVector& TestLocation, float TestHeight	bool	• Test collisions • Validate space

GAS Integration Functions

Function	Returns	Use Case Examples
ApplyCrouchSpeedModification()	void	• Apply speed effect • Stack with abilities
RemoveCrouchSpeedModification()	void	• Remove speed effect • Clear modifiers
GenerateCurveIdentifier()	FString	• Unique IDs • Multi-component

Input System Functions

Function	Parameters	Returns	Use Case Examples
OnInputStarted()	const FInputActionValue& Value	void	• Handle press • Start crouch
OnInputCompleted()	const FInputActionValue& Value	void	• Handle release • Stop crouch
BindCrouchInput()	UInputAction* CrouchAction	bool	• Bind action • Setup input
BindCrouchInputWithComponent()	UInputAction* CrouchAction, UEnhancedInputComponent* InputComponent	bool	• Explicit binding • Custom component

Debug Functions

Function	Parameters	Returns	Use Case Examples
PrintDebugInformation()	None	void	• Debug display • State logging

Blueprint Events

Event	Parameters	Use Case Examples
OnCrouchStateChanged	bool bIsCrouching	• Animation triggers • Sound effects
OnCrouchBlocked	None	• UI notification • Warning sound
OnCrouchTransitionCompleted	bool bIsNowCrouched	• State confirmation • Enable abilities

Network Functions

Function	Parameters	Returns	Use Case Examples
ServerRequestCrouch()	bool bWantsToCrouch	void (RPC)	• Server validation • Authority check

Configuration

Crouch Settings

Property	Type	Default	Description	Range
CapsuleHalfHeightWhenCrouching	float	48.0	Target capsule half height when fully crouched	10.0 - 200.0
CrouchWalkSpeedModifier	float	-200.0	Absolute walk speed value to add when crouching (negative to slow)	-

GAS Integration

Property	Type	Description
CrouchSpeedEffect	TSubclassOf<UGameplayEffect>	Effect for crouch speed modification (GAS-only)
MovementSpeedAttributeTag	FGameplayTag	Tag for movement speed attribute (e.g., "Attribute.Movement.WalkSpeed")
WantsToCrouchTagEffect	TSubclassOf<UGameplayEffect>	Grants wants to crouch tag
CrouchingTagEffect	TSubclassOf<UGameplayEffect>	Grants crouching state tag

Internal State (Read-Only)

Property	Type	Description
ActiveCrouchSpeedEffectHandle	FActiveGameplayEffectHandle	Handle to active speed modifier effect
WantsToCrouchTagHandle	FActiveGameplayEffectHandle	Handle to wants to crouch tag effect
CrouchingTagHandle	FActiveGameplayEffectHandle	Handle to crouching state tag effect

State Tracking (Read-Only)

Property	Type	Description
OriginalCapsuleHalfHeight	float	Original capsule half height cached at BeginPlay
CachedCapsuleComponent	UCapsuleComponent*	Cached reference to capsule component
CachedCameraComponent	UMotionCameraComponent*	Cached reference to camera component (for notifications)
bWasCrouchedLastFrame	bool	Previous frame's bIsCrouched state for change detection
bWasCrouchingLastFrame	bool	Previous frame's crouching tag state
LastCrouchRPCTime	float	Server RPC rate limiting (for custom ServerRequestCrouch)

Debug

Property	Type	Description
bShowDebugInformation	bool	Debug information display

Input Binding

The component provides multiple ways to bind crouch input:

// Blueprint binding
BindCrouchInput(CrouchInputAction);

// C++ with explicit component
BindCrouchInputWithComponent(CrouchAction, EnhancedInputComponent);

State Access

Query crouch state for gameplay logic:

• GetWantsToCrouch() - Check if player wants to crouch (input held)
• IsCurrentlyCrouching() - Returns Character->bIsCrouched
• IsFullyCrouched() - Same as IsCurrentlyCrouching() (instant transition)
• IsUncrouchBlocked() - Check if ceiling blocks standing via Character->CanCrouch()
• GetCurrentCapsuleHalfHeight() - Get current capsule half height

Architecture Summary

MotionCrouchingComponent acts as a wrapper and coordinator for Unreal's native crouch system:

• Does NOT handle capsule resizing - CharacterMovementComponent does this
• Does NOT interpolate heights - Camera component handles its own interpolation
• DOES manage - Input, GAS effects, tags, and coordination between systems
• DOES provide - Blueprint events, state queries, and debugging

Local Prediction

Leverages native prediction system:

• Character->Crouch() - Automatically handles prediction and server RPC
• CharacterMovementComponent - Built-in rollback support
• bIsCrouched - Authoritative state from server
• No custom prediction tracking - Uses UE5's native system

Networking

The component handles multiplayer through:

• Native crouch RPCs - Character->Crouch() includes built-in server RPC
• CharacterMovementComponent replication - Automatic bIsCrouched sync
• GAS effect synchronization - Speed and tag effects replicate
• Camera independence - Each client interpolates camera locally