> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinemation.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Procedural Recoil Animation System in CAS FPS Add-on

> Set up procedural weapon recoil in CAS: create RecoilAnimData assets, tune pitch, roll, yaw, noise, pushback layers, and call Play/Stop/Init.

The **Recoil Animation** component generates smooth, layered firing animation at runtime without requiring hand-keyed recoil clips. It combines randomised pitch, roll, and yaw impulses with a continuous noise layer and a first-shot pushback effect, all shaped by normalised animation curves and smoothed with configurable spring parameters. Each weapon carries its own **RecoilAnimData** ScriptableObject so you can tune recoil feel independently without changing any code.

## The Recoil Animation component

Add a **Recoil Animation** component to your character's prefab. The component exposes no configuration of its own in the Inspector — all parameters live in the `RecoilAnimData` asset you pass to it at runtime. The component exposes three methods that your shooting code must call:

```csharp theme={null}
// Call every time the weapon fires a single shot.
public void Play();

// Call when the player releases the fire input.
public void Stop();

// Call once when a weapon is equipped, passing the weapon's recoil data,
// the weapon's fire rate in rounds-per-minute, and the fire mode.
public void Init(RecoilAnimData data, float fireRate, FireMode newFireMode);
```

Call `Init` whenever the player equips a new weapon or switches fire mode, `Play` on every shot, and `Stop` when the trigger is released. CAS handles the curve sampling, smoothing, and layer blending internally between those calls.

## Creating a RecoilAnimData asset

Right-click anywhere in the Project window and go to **Create → KINEMATION → Procedural Recoil → Recoil Data** to create a new `RecoilAnimData` ScriptableObject. Give it a descriptive name tied to the weapon it will be used with, for example `RD_SMG_Default`. Create one asset per weapon type — or per fire mode if you want semi and auto to feel different.

## Recoil Targets

These properties define the maximum and minimum angular and translational impulses applied on each shot.

<ParamField body="Pitch" type="Vector2">
  Minimum and maximum values for the upward (pitch) rotation applied per shot. The system picks a random value between X (min) and Y (max) each time `Play` is called.
</ParamField>

<ParamField body="Roll" type="Vector4">
  Random roll rotation per shot. Because roll naturally alternates direction, the value is a Vector4: X–Y defines the range for the minimum value and Z–W defines the range for the maximum value. A random number is drawn from \[X;Y] for the negative direction and from \[Z;W] for the positive direction.
</ParamField>

<ParamField body="Yaw" type="Vector4">
  Random horizontal (yaw) rotation per shot, defined the same way as Roll — two separate ranges for the min and max random draws.
</ParamField>

<ParamField body="Aim Rot / Aim Loc" type="Vector3 multiplier">
  Multipliers applied to all rotation and translation values when the player is aiming down sights. Set values below 1 to reduce recoil while aiming — a common feel-design technique where ADS tightens the weapon.
</ParamField>

## Smoothing

<ParamField body="Smooth Rot" type="float">
  Interpolation speed for the rotation component. When greater than zero, the rotation impulse is smoothed over time rather than applied instantly. Higher values snap more aggressively toward the target.
</ParamField>

<ParamField body="Smooth Loc" type="float">
  Interpolation speed for the translation (pushback) component. Set to zero to disable translation smoothing.
</ParamField>

<ParamField body="Extra Rot" type="float">
  Rotation multiplier applied only in auto or burst fire mode. Use this to increase felt recoil accumulation during sustained fire without changing single-shot behaviour.
</ParamField>

<ParamField body="Extra Loc" type="float">
  Translation multiplier applied only in auto or burst fire mode. Mirrors Extra Rot for the pushback axis.
</ParamField>

## Layers

### Noise layer

The noise layer adds a continuous 2D position offset that simulates inaccuracy and organic movement during sustained fire. It runs independently of the per-shot impulse.

<ParamField body="Noise X / Noise Y" type="Vector2">
  Minimum and maximum values for the lateral (X) and vertical (Y) noise displacement. The noise drifts randomly within these bounds.
</ParamField>

<ParamField body="Noise Accel" type="float">
  How quickly the noise offset accelerates toward a new random target position.
</ParamField>

<ParamField body="Noise Damp" type="float">
  How quickly the noise settles or decelerates when the target changes. Balance Accel and Damp to control how erratic or sluggish the noise feels.
</ParamField>

<ParamField body="Noise Scalar" type="float">
  A multiplier applied to all noise values when the player is aiming. Set below 1 to tighten the weapon while in ADS.
</ParamField>

### Pushback layer

The pushback layer applies a one-shot translational impulse on the first shot of an auto or burst sequence, simulating the initial physical kick of the weapon.

<ParamField body="Push Amount" type="float">
  The maximum backward translation applied on the first auto shot.
</ParamField>

<ParamField body="Push Accel" type="float">
  How quickly the pushback reaches its maximum value.
</ParamField>

<ParamField body="Push Damp" type="float">
  How quickly the pushback decays back to zero.
</ParamField>

## Misc properties

<ParamField body="Hip Pivot Offset" type="Vector3">
  Offsets the rotation pivot point of the weapon during hip-fire. Adjust this to control which part of the weapon appears to kick when not aiming.
</ParamField>

<ParamField body="Aim Pivot Offset" type="Vector3">
  Offsets the rotation pivot point during ADS. Typically set closer to the optic or iron sight so the view stays centred through the sight during recoil.
</ParamField>

<ParamField body="Smooth Roll" type="bool">
  When enabled, the sign of the random roll value alternates with each shot — positive one shot, negative the next. This produces a natural left-right rocking motion during sustained fire rather than random directional bouncing.
</ParamField>

<ParamField body="Play Rate" type="float">
  Scales the playback speed of the recoil animation curves. Increase to make recoil snappier; decrease for a heavier, slower kick.
</ParamField>

<ParamField body="Recoil Curves" type="VectorCurve × 4">
  Four normalised animation curves that shape how the rotation and translation values are applied over time. See the section below for authoring rules.
</ParamField>

## Recoil Curves

The four Vector curves in the asset animate rotation and translation over a single fire cycle. Two curves are for semi-auto fire (rotation and translation) and two are for auto fire (rotation and translation).

<Warning>
  All curves must start **and** end at zero. If a curve does not return to zero, the recoil value will accumulate across shots and quickly produce extreme, uncontrollable motion.
</Warning>

### Semi vs. auto curves

The key difference between semi and auto curves is that the **auto curve** must pass through or very near zero at the point in time equal to the delay between shots. For example, at 600 RPM the delay between shots is 0.1 seconds, so the auto curve must approach zero around the 0.1 second mark.

When CAS runs in auto or burst mode it crops the auto curve length to the fire delay (0.1 s in the example). This cropping is how the system chains successive shots together smoothly — each new shot restarts the curve from where the previous one reached zero. If the auto curve is not near zero at the crop point, shots will not chain cleanly and the animation will jump or stutter.

Semi curves have no such constraint — they simply play out fully between trigger presses and return to zero at their natural end time.

<Tip>
  A reliable starting point is to author your semi curve first, then duplicate it and drag the peak slightly earlier so the value is close to zero around the intended fire delay interval. Fine-tune from there with the Play Rate property.
</Tip>

## Connecting recoil to the Procedural Animation Settings

The Recoil Animation component produces two output properties — `OutRot` (rotation) and `OutLoc` (translation) — that you bind into the procedural modifier stack.

<Steps>
  <Step title="Add the component">
    Add a **Recoil Animation** component to your character's Skeleton\_ prefab and apply the prefab change.
  </Step>

  <Step title="Add a Modify Bone modifier">
    Open the PA\_ asset and add a **Modify Bone** modifier. Place it in Stage 2 of the modifier stack — after the ADS Modifier and before the IK solvers.
  </Step>

  <Step title="Bind the output properties">
    In the Modify Bone modifier's **Property Bindings** section, bind `OutRot` to the bone rotation input and `OutLoc` to the bone translation input. Select the **Recoil Animation** component on the character as the binding source.
  </Step>

  <Step title="Call Init from your weapon code">
    When the player equips a weapon, call `recoilAnimation.Init(weaponData.RecoilData, weaponData.FireRate, weaponData.FireMode)`. Then call `Play()` on every shot and `Stop()` on trigger release.
  </Step>
</Steps>