# Aim Weapon

The **Aim Weapon** node points a weapon muzzle at a target location and then adjusts the supporting arms to follow. It pairs well with [Apply Spray To Target](apply-spray-to-target.md) when you want the weapon to visibly follow a burst pattern.

If your project fires from the animated muzzle, this node helps keep that muzzle lined up. If your project fires from a separate camera or gameplay trace, this node can still keep the weapon pose matching that direction.

![Aim Weapon node](_media/aim-weapon-node.png ':size=1200')

## Usage

1. Add the **Aim Weapon** node to your Control Rig graph
2. Connect a target position in <span class="fr-term" tabindex="0" data-tooltip-key="global-space">global space</span> to **Target**
3. If the detected setup is not right, right-click the node and pick another Quick Setup from the dropdown, or edit [Muzzle Adjustment](#muzzle-adjustment) and [Arm Adjustment](#arm-adjustment) manually

## Quick Setup

When you place the node, FocalRig generates any [Quick Setups](quick-setups.md) it can detect for the current hierarchy and auto-applies the first one. If another one matches your rig better, right-click the node and choose it from the Quick Setup dropdown.

<details>
<summary>How detection works</summary>

Quick Setup builds presets from the hierarchy in a few stages:

- It looks for arm chains named like `upperarm` / `upper_arm` / `shoulder` / `humerus` → `lowerarm` / `lower_arm` / `forearm` / `elbow` / `radius` / `ulna` → `hand` / `wrist`
- It looks for muzzle-like elements named `muzzle`, `barrel`, `gun`, `bow`, `arrow`, `weapon`, or `hand`, checking bones first and then nulls
- For each matching muzzle-like element, it walks up the hierarchy to find which detected arm owns it and offers a one-arm preset for that setup
- If multiple arms are available, it also offers a multi-arm preset that keeps the primary weapon-holding arm first in the pivot list
- For [Aim Down Sights](#aim-down-sights) it tries to find a POV-style bone (`pov`, `camera`, `view`, or `eyes`), otherwise a same-side `eye` bone, and finally falls back to `head`
- If a POV bone exists, Quick Setup also seeds [**Pose Override**](#pose-override) relative to that POV element

</details>

If your hierarchy does not have recognizable arm chains or any muzzle-like element, Quick Setup will not offer a usable preset. In that case, fill [**Muzzle**](#muzzle) manually, then add the supporting arms under [**Arm Settings**](#arm-settings).

## Creating a Muzzle Element

`Aim Weapon` only needs a rig element that matches the muzzle transform. How you provide that element depends on how the weapon is authored.

If the weapon mesh is part of the character mesh, create a bone or null under the weapon's attach bone and place it at the barrel tip. If you want Quick Setup to find it automatically, name it `muzzle`, `barrel`, `gun`, `bow`, `arrow`, `weapon`, or `hand`. `muzzle` is the clearest choice.

Quick Setup searches bones first, then nulls. Once it finds a candidate, it chooses the muzzle's forward axis by snapping to the local ±X/±Y/±Z axis closest to the direction from the pivot shoulder to the muzzle in the preview pose. That is why the preview pose should show the weapon pointing forward.

If the weapon is a separate actor attached to a socket, create a proxy rig element under the attach parent instead, then set its local transform from the weapon's muzzle relative transform before **Aim Weapon** runs. That gives the rig a muzzle proxy even though the actual gun mesh is external.

If Quick Setup still picks the wrong muzzle or wrong arm, right-click the node and choose a different Quick Setup preset from the dropdown. If none of them are right, fill **Muzzle Adjustment > Muzzle** and **Arm Adjustment > Arms** manually.

## Input Pins

| Pin | Type | Description |
|-----|------|-------------|
| Target | Vector | Location to aim at in <span class="fr-term" tabindex="0" data-tooltip-key="global-space">global space</span> |
| Muzzle Adjustment | [Muzzle Adjustment Settings](#muzzle-adjustment) | Settings for weapon muzzle placement and orientation |
| Arm Adjustment | [Arm Adjustment Settings](#arm-adjustment) | Settings for adjusting the arms holding the weapon |
| Debug | [Debug Settings](#debug-draw) | Debug visualization settings |
| Weight | float | The blend weight of this operation (0.0 = no effect, 1.0 = full effect) |

### Muzzle Adjustment

Controls which element represents the muzzle, how it rotates toward the target, how far it can move, and how additional effects such as [Aim Down Sights](#aim-down-sights), [kick](#kick), [weapon bob](#weapon-bob), [idle sway](#idle-sway), [landing dip](#landing-dip), and [aim lock](#aim-lock-weight) are layered on top.

#### Muzzle

Pick the element that represents the muzzle and the axis that should point at the target. Quick Setup usually fills this from the detected muzzle-like element and the current pose.

See [Aim Element](aim-element.md) for the full property breakdown.

#### Pose Override

Overrides the weapon's starting pose before the aiming pipeline. This is mainly useful in first-person rigs where the animation pose does not already place the weapon where you want it.

![Pose override comparison](_media/weapon-pose-override-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

| Property | Type | Description |
|----------|------|-------------|
| Reference Bone | Rig Element Key | The reference element used for the override, typically the POV or camera element. If unset, the offset is treated as <span class="fr-term" tabindex="0" data-tooltip-key="global-space">global space</span> |
| Muzzle Offset From Reference | Transform | Desired muzzle transform relative to **Reference Bone** (or in <span class="fr-term" tabindex="0" data-tooltip-key="global-space">global space</span> if unset) |
| Weight | float | 0 = use the animation pose, 1 = use the override pose |

#### Muzzle Distance

Constrains and smooths muzzle distance relative to the pivot.

This is most visible when you walk into nearby walls or cover. With sensible **Min Distance To Target** and **Min Distance To Pivot** values, the weapon pulls back and the supporting hand follows instead of clipping into the surface.

| Property | Type | Description |
|----------|------|-------------|
| Min Distance To Pivot | float (cm) | Minimum distance from muzzle to pivot to prevent arm collapse |
| Min Distance To Target | float (cm) | Minimum distance from muzzle to target. Targets closer than this are pushed away |
| Smoothing | [Smoothing Settings](smoothing.md) | Spring smoothing for the constrained distance |

#### Pivot Rotation

Rotates around one or more pivot elements to aim the weapon.

| Property | Type | Description |
|----------|------|-------------|
| Pivots | list of Rig Element Keys | The elements to use as the aiming pivot. Their locations are averaged to determine the pivot point. The first pivot's rotation is used as the clamp reference frame |
| Clamp | [Rotation Clamp Settings](rotation-clamping.md) | Settings for clamping pivot rotation |
| Smoothing | [Smoothing Settings](smoothing.md) | Spring smoothing for the pivot rotation |

The clamp and smoothing here affect the single rotation Aim Weapon solves around the combined pivot, not one separate rotation per pivot element. Use the clamp to keep the whole weapon-aim swing inside a believable range, and use smoothing to soften how fast that pivot rotation reacts.

#### Aim Down Sights

When enabled, positions the weapon so the sights align with the line from the eye to the target.

![Aim down sights comparison](_media/weapon-ads-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

| Property | Type | Description |
|----------|------|-------------|
| Weight | float | Blends between regular aiming (0.0) and ADS mode (1.0) |
| Eye Source | [Eye Source](#eye-source) | Where to get the eye position from |
| Eye | Rig Element Key | The eye element to align sights with when **Eye Source** is **Element** |
| Eye Location | Vector | The eye location to use when **Eye Source** is **Transform** |
| Sights Offset From Muzzle | Vector | Offset from the muzzle to the front sights in muzzle space |
| Rear Sights Offset | Vector | Offset from the front sights to the rear sights in muzzle space |
| Rotation Around Sights Smoothing | [Smoothing Settings](smoothing.md) | Spring smoothing for the additional rotation around the sights |

##### Eye Source

| Value | Description |
|-------|-------------|
| **Element** | Use an element from the rig hierarchy as the eye position |
| **Transform** | Use a fixed eye location in <span class="fr-term" tabindex="0" data-tooltip-key="global-space">global space</span> |

#### Straighten

Corrects muzzle roll by aligning the muzzle's up axis with a chosen up vector.

![Weapon straighten comparison](_media/weapon-straighten-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

| Property | Type | Description |
|----------|------|-------------|
| Weight | float | Blend weight for straightening (0.0 = no effect, 1.0 = full effect) |
| Up Vector | Vector | The direction in <span class="fr-term" tabindex="0" data-tooltip-key="global-space">global space</span> to align the muzzle's up axis with |

#### Body Depenetration

Pushes the weapon forward just enough to keep the contact points on the weapon outside the character's physics asset (the same one used for hit detection and ragdolling). [Quick Setup](#quick-setup) fills them in with the spine, neck, head bones it detects based on bone name.

![Weapon body depenetration comparison](_media/weapon-body-depenetration-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

Turn this on if the weapon clips into the character's body when aiming: set **Weight** to 1 and configure one or more **Contact Points** with locations on the gun that tend to clip (e.g., the stock).

Currently supported physics asset body types:

- sphere
- capsule
- box
- convex hull
- tapered capsule (treated as ordinary capsules, this matches engine behavior for ragdoll physics as actual tapered capsules are for clothing only)

| Property | Type | Description |
|----------|------|-------------|
| Contact Points | array of of Vector (cm) | Points on the weapon in muzzle local space to keep outside the body. X points forward along the aim axis. Place them slightly beyond the surface for a small clearance margin |
| Depenetration Bones | list of Rig Element Key | Body bones to test against. These should be bones that actually have physics asset collision shapes |
| Max Forward Push | float (cm) | Safety cap for how far the weapon can be pushed. Keep this just large enough to clear normal clipping. <=0 = no limit |
| Smoothing | [Smoothing Settings](smoothing.md) | Smooths the push in and out. Raise this if the weapon clears correctly but the motion feels too snappy or jittery |
| Weight | float | Effect strength. 0 = disabled (default), 1 = full.

#### Kick

Applies an analytical muzzle kick after a shot.

![Weapon kick comparison](_media/weapon-kick-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

| Property | Type | Description |
|----------|------|-------------|
| Time Of Last Shot | double (s) | The world time when the last shot was fired |
| Offset | Vector (cm) | Positional offset of the kick in muzzle space |
| Kick Duration | float (s) | Duration of the kick phase |
| Kick Ease | Easing | Easing function for the kick phase |
| Recovery Duration | float (s) | Duration of the recovery phase |
| Recovery Ease | Easing | Easing function for the recovery phase |

#### Weapon Bob

Adds a procedural locomotion bob to the weapon.

![Weapon bob comparison](_media/weapon-bob-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

Weapon Bob layers a locomotion-driven bob transform onto the weapon after the main aim solve. That makes the weapon ride with movement without changing what the muzzle is trying to aim at.

See [Bob](bob.md) for the full property breakdown.

#### Idle Sway

Adds subtle multi-axis sway while the character is standing still or moving slowly.

Idle Sway adds subtle breathing and drift to the weapon after aiming so the weapon does not feel perfectly locked while the character is idle.

![Weapon idle sway comparison](_media/weapon-idle-sway-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

See [Idle Sway](idle-sway.md) for the full property breakdown.

#### Landing Dip

Dips the weapon downward on landing.

Landing Dip adds a short downward impact reaction to the weapon without changing the target the muzzle is trying to face.

![Weapon landing dip comparison](_media/weapon-landing-dip-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

See [Landing Dip](landing-dip.md) for the full property breakdown.

#### Aim Lock Weight

Aim Lock freezes the current procedural aim adjustment at the moment the weight becomes nonzero, letting recoil or reload animations play out without the weapon snapping back to the current aim target.

Typical usage: drive **Aim Lock Weight** with a curve that spikes to 1.0 when a shot fires, then decays back to 0.0 as the recoil settles.

| Property | Type | Description |
|----------|------|-------------|
| Aim Lock Weight | float | 0.0 = weapon tracks the target normally. 1.0 = weapon keeps the same procedural aim adjustment it had when the weight first became nonzero. Intermediate values blend between the two. |

![Aim lock comparison](_media/aim-lock-comparison.mp4 ':include :type=video autoplay loop muted playsinline')

### Arm Adjustment

After the muzzle transform is decided the arms holding the weapon are minimally adjusted (via [Adjust Three Bone Chain](adjust-three-bone-chain.md)) to keep the hands fixed relative to the muzzle. This is what creates the actual motion of the weapon, which is assumed to be parented to one of the arms.

> This does not mean that the hands are always snapped to the gun. If in the input pose / animation the hands are on the gun, they will stay on the gun. If a hand is not on the gun (e.g., because it's reaching to reload a magazine), that motion is preserved no matter where the gun is pointing. This makes it safe to do aiming on top of custom animations.

| Property | Type | Description |
|----------|------|-------------|
| Arms | list of [Arm Settings](#arm-settings) | The arms holding the weapon |

#### Arm Settings

Each arm entry uses the following struct:

| Property | Type | Description |
|----------|------|-------------|
| Chain | [Three Bone Chain](three-bone-chain.md?id=three-bone-chain) | The arm chain to adjust |
| Stretch | [Stretch Settings](three-bone-chain.md?id=stretch-settings) | Settings for how the arm handles targets at or beyond reach |
| Twist | [Twist Settings](three-bone-chain.md?id=twist-settings) | Settings for twisting the arm around the root-to-end axis |

### Smoothing In Aim Weapon

Aim Weapon uses [Smoothing Settings](smoothing.md) in several places: muzzle distance, pivot rotation, ADS rotation around sights, weapon bob intensity, and idle sway intensity. In every case, disabling smoothing makes that part of the weapon response follow its current target immediately with no spring lag.

## Debug Draw

| Property | Type | Description |
|----------|------|-------------|
| Enabled | bool | Whether to draw debug visualization |
| Scale | float | Scale factor for debug visualization sizes |

Use this debug view in this order:

1. Check the blue point and green line to confirm the ADS line of sight.
2. Check the sight and muzzle axes to verify the final orientation.
3. Check the yellow arc and clamp overlay if the weapon is not reaching the target.

| Debug item | Meaning |
|------------|---------|
| Yellow/red/green clamp overlay | Pivot rotation limits. See [Rotation Clamping debug draw](rotation-clamping.md?id=debug-draw) |
| Blue point | Safe ADS target position after minimum-distance pushing |
| Green line from eye to target | ADS eye-to-target line of sight |
| Red/green/blue axes at front sights | Final front sights transform axes |
| Blue line from front to rear sights | Sight alignment line |
| Blue point at rear sights | Rear sights position |
| Red/green/blue axis lines from muzzle | Final muzzle forward and side axes |
| Yellow arc | Angle from the final muzzle direction to the target direction |