Add aimpunch camera recoil system (issue #153)

- Implements Source engine-style aimpunch with automatic recovery
- Camera kicks when shooting, smoothly recovers when stopped
- Per-weapon configuration via UseAimPunch and AimPunchRecoverySpeed
- Resets on weapon switch to prevent carry-over
- Backward compatible (defaults to legacy instant recoil)

Author: misterbubb

code/swb_base/Weapon.Shoot.cs

@@ -101,8 +101,18 @@ public virtual void Shoot( ShootInfo shootInfo, bool isPrimary )
 		// Barrel smoke
 		barrelHeat += 1;
 
-		// Recoil
-		Owner.ApplyEyeAnglesOffset( GetRecoilAngles( shootInfo ) );
+		// Recoil / AimPunch
+		var recoilAngles = GetRecoilAngles( shootInfo );
+		if ( shootInfo.UseAimPunch )
+		{
+			// Apply aimpunch (camera recoil with recovery)
+			Owner.ApplyAimPunch( recoilAngles, shootInfo.AimPunchRecoverySpeed );
+		}
+		else
+		{
+			// Apply instant recoil (legacy behavior)
+			Owner.ApplyEyeAnglesOffset( recoilAngles );
+		}
 
 		// Screenshake
 		if ( shootInfo.ScreenShake is not null )

code/swb_base/structures/ShootInfo.cs

@@ -67,6 +67,12 @@ public class ShootInfo : Component
 	/// <summary>Weapon recoil</summary>
 	[Property, Group( "Bullets" )] public float Recoil { get; set; } = 0.1f;
 
+	/// <summary>Enable aimpunch (camera recoil with recovery)</summary>
+	[Property, Group( "Bullets" )] public bool UseAimPunch { get; set; } = false;
+
+	/// <summary>Aimpunch recovery speed (higher = faster recovery)</summary>
+	[Property, Group( "Bullets" )] public float AimPunchRecoverySpeed { get; set; } = 5f;
+
 	/// <summary>Rate Per Minute, firing speed (higher is faster)</summary>
 	[Property, Group( "Bullets" )] public int RPM { get; set; } = 200;
 

code/swb_player/Inventory.cs

@@ -56,6 +56,9 @@ public void SetActive( GameObject gameObject )
 			oldActive.OnCarryStop();
 		}
 
+		// Reset aimpunch when switching weapons
+		player?.ResetAimPunch();
+
 		if ( gameObject.Components.TryGet<IInventoryItem>( out var newActive, FindMode.EverythingInSelf ) )
 		{
 			newActive.OnCarryStart();

code/swb_player/PlayerBase.AimPunch.cs

@@ -0,0 +1,80 @@
+namespace SWB.Player;
+
+public partial class PlayerBase
+{
+	Angles aimPunchAngle;
+	float aimPunchRecoverySpeed = 5f;
+	RealTimeSince timeSinceLastPunch;
+
+	/// <summary>
+	/// Apply aimpunch recoil to the camera
+	/// </summary>
+	/// <param name="punchAmount">The angular offset to apply</param>
+	/// <param name="recoverySpeed">How fast the camera recovers (higher = faster)</param>
+	public virtual void ApplyAimPunch( Angles punchAmount, float recoverySpeed = 5f )
+	{
+		// Accumulate the punch angle
+		aimPunchAngle += punchAmount;
+		aimPunchRecoverySpeed = recoverySpeed;
+		timeSinceLastPunch = 0;
+		
+		// Apply the kick to the camera immediately
+		ApplyEyeAnglesOffset( punchAmount );
+	}
+
+	/// <summary>
+	/// Reset aimpunch angle (called on weapon switch, death, etc.)
+	/// </summary>
+	public virtual void ResetAimPunch()
+	{
+		aimPunchAngle = Angles.Zero;
+	}
+
+	/// <summary>
+	/// Handle aimpunch recovery over time
+	/// </summary>
+	public virtual void HandleAimPunch()
+	{
+		if ( !IsAlive )
+		{
+			aimPunchAngle = Angles.Zero;
+			return;
+		}
+
+		// Get the active weapon to check if player is shooting
+		var activeWeapon = Inventory?.Active?.GetComponent<SWB.Base.Weapon>();
+		bool isShooting = activeWeapon?.IsShooting() ?? false;
+
+		// Only recover when NOT shooting (with small delay after last shot)
+		if ( isShooting || timeSinceLastPunch < 0.1f )
+			return;
+
+		// Recover the punch angle back toward zero
+		if ( aimPunchAngle.pitch != 0 || aimPunchAngle.yaw != 0 || aimPunchAngle.roll != 0 )
+		{
+			var decayAmount = aimPunchRecoverySpeed * Time.Delta;
+			
+			// Store old angle to calculate what changed
+			var oldPitch = aimPunchAngle.pitch;
+			var oldYaw = aimPunchAngle.yaw;
+			var oldRoll = aimPunchAngle.roll;
+			
+			// Decay toward zero
+			aimPunchAngle = new Angles(
+				aimPunchAngle.pitch.Approach( 0, decayAmount ),
+				aimPunchAngle.yaw.Approach( 0, decayAmount ),
+				aimPunchAngle.roll.Approach( 0, decayAmount )
+			);
+			
+			// Calculate the change (this will be negative, pulling camera back)
+			var deltaAngle = new Angles(
+				aimPunchAngle.pitch - oldPitch,
+				aimPunchAngle.yaw - oldYaw,
+				aimPunchAngle.roll - oldRoll
+			);
+			
+			// Apply the recovery movement
+			ApplyEyeAnglesOffset( deltaAngle );
+		}
+	}
+}

code/swb_player/PlayerBase.cs

@@ -224,6 +224,7 @@ protected override void OnUpdate()
 			ViewModelCamera.Enabled = IsFirstPerson && IsAlive;
 			HandleFlinch();
 			HandleScreenShake();
+			HandleAimPunch();
 		}
 
 		if ( IsAlive )
@@ -259,7 +260,7 @@ public void TriggerAnimation( Animations animation )
 
 	public void ApplyEyeAnglesOffset( Angles offset )
 	{
-		CameraMovement?.EyeAnglesOffset += offset;
+		CameraMovement.EyeAnglesOffset += offset;
 	}
 
 	public void ParentToBone( GameObject weaponObject, string boneName )

code/swb_shared/IPlayerBase.cs

@@ -115,6 +115,14 @@ public interface IPlayerBase : IValid, Sandbox.Component.IDamageable
 	/// <param name="offset">The suggested angular offset to apply</param>
 	public void ApplyEyeAnglesOffset( Angles offset );
 
+	/// <summary>
+	/// Apply aimpunch (camera recoil with recovery) to the player's view.
+	/// Unlike ApplyEyeAnglesOffset, this will smoothly recover over time.
+	/// </summary>
+	/// <param name="punchAmount">The angular offset to apply</param>
+	/// <param name="recoverySpeed">How fast the camera recovers (higher = faster)</param>
+	public void ApplyAimPunch( Angles punchAmount, float recoverySpeed = 5f );
+
 	/// <summary>
 	/// Called when the weapon object should be attached/parented to the player's body
 	/// </summary>