FPS Animation Framework

About FPS Animation Framework – Unity Editor Tool & Plugin

FPS Animation Framework Unity Asset Overview

Building responsive, weight-driven first-person shooter motion inside Unity has traditionally been a huge headache. In my experience, relying solely on clip-based keyframe animations created in external software like Maya or Blender inevitably falls short. You run into rigid transitions, lack of runtime physical feedback, and an awkward disconnect between player camera motion and weapon alignment. The FPS Animation Framework tackles this problem by combining procedural mathematical springs with custom Mecanim animator workflows, providing a hybrid architecture that delivers tactile gunplay felt in modern AAA shooters.

At its core, the architecture acts as an intermediate calculation layer sitting directly between your player input script and the camera/weapon transform hierarchy. Instead of forcing you to bake dozens of subtle animation clips for movement sway, breathing, aiming down sights (ADS), and recoil kick, this tool relies heavily on second-order spring-damper systems. The state machine delegates mechanical state transitions—such as reloading, weapon switching, or melee attacks—to Unity's Animator Controller, while fine-grained motion, rotational sway, camera bob, and procedural recoil are handled at runtime via C# update loops.

Core Technical Features & Highlights

Having integrated numerous procedural gun systems into client projects over the last 8 years, here is a detailed technical breakdown of what makes this specific framework stand out:

1. Spring-Damper Procedural Recoil & Sway

The system utilizes a lightweight Vector3 and Quaternion math engine that calculates translational and rotational spring offsets on every frame. When a shot is fired, the weapon rig doesn't merely play a static animation; it receives directional force impulses. Rotational pitch, yaw, roll, and back-kick decay dynamically using custom damping ratios. This means rapid firing causes continuous, realistic recoil accumulation rather than repetitive, rigid clip loops.

2. Procedural Aim Down Sights (ADS) Alignment

Aligning sights accurately without visual clipping normally requires endless tweaking of weapon offset transforms. This framework calculates sight alignment on the fly. By marking a specific SightTransform node on your weapon prefab, the framework automatically computes the inverse offset needed to align that precise optical center with the main Camera, applying dynamic field of view (FOV) interpolation smoothly.

3. Performance Metrics & Pipeline Compatibility

Because garbage collection spikes will immediately ruin the fluid feel of an action game, the code paths inside this package are designed with clean, zero-allocation paradigms in mind. Here are the key technical specifications:

• Runtime Allocation: Zero GC allocations during continuous update loops (uses cached structs and pre-allocated arrays).
• CPU Overhead: Benchmarked at under 0.04ms per frame for full procedural calculations on modern desktop hardware.
• Render Pipeline Support: Fully pipeline-agnostic. Shaders included for muzzle flashes and scope overlays support the Universal Render Pipeline (URP), High Definition Render Pipeline (HDRP), and the Legacy Built-in Render Pipeline.
• Inverse Kinematics (IK): Built-in support for Unity's Animation Rigging package and Two-Bone IK, ensuring proper left-hand placement on variable weapon foregrips.

Ideal Use Cases & Game Genres

While designed primarily for standard first-person perspectives, the modular physics structure behind this tool makes it flexible across several sub-genres:

• Tactical Hardcore Shooters: Excellent for titles requiring detailed weapon handling, deadzone aiming, procedural inertia based on weapon weight, and realistic sway affected by stamina.
• Fast-Paced Arcade Shooters: The high-frequency spring decay rates can be tightened to produce snappy, responsive recoil feels suited for twitch-based arena combat.
• Survival Horror Prototypes: Easy to adjust spring dampening to induce heavy weapon sway, shaky hands during low health, and exaggerated movement bobbing.
• Extraction Shooters & Looter Shooters: The data-driven weapon component system lets developers easily swapped attachment stats (like scopes or grips) and modify procedural spring variables at runtime without breaking underlying animation states.

Quick-Start Unity Setup & Integration Guide

Integrating the framework into an existing project architecture is straightforward. Follow these steps to attach procedural handling to your player rig.

Step 1: Hierarchy Preparation

Ensure your local character hierarchy follows a clean structure. You need a root Player Controller transform, a child Camera Holder node, and a Weapon Rig Anchor parented beneath the camera. Place your weapon prefab inside this anchor node and define a child transform named SightTarget directly inline with the iron sights or optic lens.

Step 2: Component Configuration

Attach the central handling controller to your character hierarchy and initialize your input listeners. Below is an practical C# integration script demonstrating how to feed input vectors, toggle procedural ADS, and trigger recoil impulses using the framework's native C# class interfaces:

using UnityEngine;
using System.Collections;

namespace FPSFramework.Integration
{
    [RequireComponent(typeof(Animator))]
    public class PlayerFPSWeaponController : MonoBehaviour
    {
        [Header("Framework References")]
        [SerializeField] private Transform weaponHolderTransform;
        [SerializeField] private Transform cameraTransform;
        [SerializeField] private Transform sightTransform;

        [Header("Spring Physics Profile")]
        [SerializeField] private Vector3 recoilImpulseRotation = new Vector3(-8.0f, 1.5f, 2.0f);
        [SerializeField] private Vector3 recoilImpulseKickback = new Vector3(0.0f, 0.0f, -0.12f);
        [SerializeField] private float springStiffness = 180.0f;
        [SerializeField] private float springDamping = 12.0f;

        private Vector3 currentRotationOffset;
        private Vector3 currentPositionOffset;
        private Vector3 rotationVelocity;
        private Vector3 positionVelocity;

        private bool isAiming;

        private void Update()
        {
            HandleSwayAndBob();
            EvaluateSpringPhysics();
        }

        public void Fire()
        {
            // Apply instant mechanical force vector impulses to spring velocity
            rotationVelocity += recoilImpulseRotation;
            positionVelocity += recoilImpulseKickback;
        }

        public void SetAimState(bool aiming)
        {
            isAiming = aiming;
        }

        private void HandleSwayAndBob()
        {
            float mouseX = Input.GetAxis("Mouse X");
            float mouseY = Input.GetAxis("Mouse Y");

            // Calculate directional sway offset targeting
            Vector3 targetSway = new Vector3(-mouseX, -mouseY, mouseX * 0.5f) * (isAiming ? 0.005f : 0.02f);
            currentPositionOffset = Vector3.Lerp(currentPositionOffset, targetSway, Time.deltaTime * 10f);
        }

        private void EvaluateSpringPhysics()
        {
            // Calculate second-order differential equation for spring-damper motion
            Vector3 targetPosition = isAiming ? (cameraTransform.position - sightTransform.position) : Vector3.zero;
            
            positionVelocity += (targetPosition - currentPositionOffset) * springStiffness * Time.deltaTime;
            positionVelocity -= positionVelocity * springDamping * Time.deltaTime;
            currentPositionOffset += positionVelocity * Time.deltaTime;

            rotationVelocity -= rotationVelocity * springDamping * Time.deltaTime;
            currentRotationOffset += rotationVelocity * Time.deltaTime;

            // Apply transforms locally to weapon holder
            weaponHolderTransform.localPosition = currentPositionOffset;
            weaponHolderTransform.localRotation = Quaternion.Euler(currentRotationOffset);
        }
    }
}

Pros & Cons Assessment

Here is my honest developer evaluation of where this package excels and where you might need to proceed with extra care.

• Pros:
  • Eliminates the need to create hundreds of static keyframe clips for every unique weapon model.
  • Calculates pinpoint procedural ADS sight positioning automatically regardless of FOV changes.
  • Highly optimized C# scripts with negligible CPU performance and memory footprint.
  • Includes flexible shader setups and environment templates for fast greybox prototyping.
• Cons:
  • Requires basic understanding of linear algebra and spring dynamics to fine-tune spring values effectively.
  • Rig setup strictly requires well-aligned transform pivot points on third-party weapon 3D models.

Related Unity Tools Assets