Crystal Recoil

CrystalRecoil is an Unreal Engine plugin that provides a pattern-based recoil system for shooter games. Define per-weapon recoil patterns visually using the built-in Recoil Pattern Editor, then drive them at runtime through a Blueprint and C++ API.

Features

• Pattern-Based Recoil System
• Custom Recoil Pattern Editor
• Blueprint Exposed API
• Recoil Recovery and Compensation
• Spread Recoil Component

Installation

1. Get CrystalRecoil.zip from the releases
2. Extract it into your project's Plugins folder.
3. Enjoy!

Usage

1. Add CRRecoilComponent to your Actor (Pawn, Weapon, etc.)
2. In the Content Browser, create a new CRRecoilPattern asset: Add → Gameplay → Recoil Pattern
3. Set CRRecoilPattern in the CRRecoilComponent defaults
   • Or call UCRRecoilComponent::SetRecoilPattern to assign the pattern at runtime
4. On BeginPlay, optionally call UCRRecoilComponent::SetTargetController to specify which controller receives recoil
   • If not called, defaults to GetFirstPlayerController automatically
   • Changing the target clears pending recoil and recovery for the previous controller
5. On fire start: call UCRRecoilComponent::StartShooting
6. On each shot: call UCRRecoilComponent::ApplyShot

Recoil Pattern Behavior

When the player shoots beyond the defined pattern length, ERecoilBehaviorOnShotLimitReached controls what happens:

• RepeatLast - Repeats the last shot's delta indefinitely (AK-47 style infinite climb)
• Stop - Recoil stops, gun stabilizes at the last position (laser rifles, low-recoil weapons)
• RestartFromCustomIndex - Loops back to a specific shot index. Use 0 to restart the full pattern, or a higher index to loop only the sustained fire phase
• Random - Switches to procedural random recoil defined by RandomizedRecoil min/max ranges (LMGs, chaotic spray)

Recoil Implementation Details

Uplift
Delta rotation is calculated from the recoil pattern coordinates. Using kinematic equations (v₀ = 2d/T, a = 2d/T²), an initial speed and deceleration are derived that guarantee the camera travels exactly that distance in exactly the configured uplift duration. The deceleration is applied each tick until the full recoil is consumed.

Compensation
Player input that opposes accumulated recoil (e.g., pulling down while gun kicks up) reduces the recovery debt in real-time, allowing players to manually control recoil.

Recovery
Once recoil uplift is complete and RecoveryDelay has elapsed since the last shot, the camera automatically returns toward the pre-shot position at a configurable speed and acceleration. Recovery can be canceled if the player makes large aiming movements (controlled by RecoveryCancelThreshold), including while recoil is still rising, allowing natural aim adjustments without fighting the system.

Recoil Pattern Editor Shortcuts

• Shift+Click: Add Unit
• Shift+S: Toggle Snapping
• S: Scale (select at least two units)
• R: Auto Rearrange
• F: Zoom View to Fit
• H: Toggle Shortcuts

Activating Scale opens and focuses the Graph tab. Move the mouse to scale the selected units, then press S again or click to finish. Right-click panning or moving focus to another panel also finishes scaling.

Auto Rearrange applies the graph's rearrange policy when units are edited, including through Graph Settings. Disable it to preserve manual shot order. Copying selected units preserves their shot order, regardless of selection order.

Recoil Spread Component

The plugin comes with a UCRRecoilSpreadComponent, which extends UCRRecoilComponent with a heat-based spread system. Since it inherits all base recoil functionality, you only need one component - use UCRRecoilSpreadComponent instead of UCRRecoilComponent if you want spread.

The spread effect is driven by three curves configured in the editor:

• ShotToHeatCurve - heat added per shot based on current heat
• HeatToSpreadAngleCurve - spread angle corresponding to the current heat
• HeatToCooldownPerSecondCurve - heat lost per second based on current heat

Call UCRRecoilSpreadComponent::GetCurrentSpreadAngle() before each shot to get the current spread angle for projectile direction calculation.

Reducing the heat cap with SetMaxRecoilHeat() immediately clamps existing heat and notifies OnHeatChanged when heat changes. Assigning MaxRecoilHeat in Blueprint uses the same setter.

External Rotation Integration

External aim assist or scripted camera adjustments can call UCRRecoilComponent::NotifyExternalControlRotationDelta after applying automatic control rotation. Pass the matching controller and the measured (RotationAfter - RotationBefore).GetNormalized() delta so recoil does not treat that movement as manual compensation or recovery cancellation. Report only automatic movement, excluding player input and this component's own recoil.

Tests

Run the CrystalRecoil tests in Unreal Editor's Session Frontend Automation tab to check recoil and compensation, controller changes, spread heat and cooldown, Blueprint heat-cap assignments, graph ordering, undo/redo, selection, scaling gestures, and external rotation integration.

Acknowledgements

Huge thanks to Solessfir for the massive overhaul in v2.0! His contributions significantly improved the architecture, physics model, and editor UX.

License

This plugin is licensed under the MIT License