# Analyze Weapon

The **Analyze Weapon** Blueprint function automatically finds a weapon's muzzle, sights, and stock from sockets on its skeletal mesh, and figures out how to hold the weapon in front of the first-person camera. It returns the result as a **Weapon Analysis** struct, which can override various settings on [Aim Weapon](aim-weapon.md) so you don't have to configure them manually for each weapon. See [Weapon Analysis](aim-weapon.md?id=weapon-analysis) for an example setup.

In C++, this function is `UFocalRigWeaponAnalysisLibrary::AnalyzeWeapon`. You can also call `FFocalRigWeaponAnalysisSettings::Analyze`, which returns an empty `TOptional` on failure.

## Usage

For example, a weapon Blueprint can call **Analyze Weapon** in its construction script, with its skeletal mesh component as **Weapon Mesh**, and store the result in a variable:

![Analyze Weapon in a weapon's construction script](_media/analyze-weapon-construction-script.png ':size=1000')

Then connect the equipped weapon's analysis to Aim Weapon's **Weapon Analysis** pin and enable **Override With Weapon Analysis**. See [Weapon Analysis](aim-weapon.md?id=example-setup) for the whole example setup.

The analysis is relative to the actor that owns the mesh component (the weapon actor). It assumes that the actor's origin is where the hand holds the weapon. This is true when the weapon actor is attached to a hand socket, such as `HandGrip_R`, with no offset. Aim Weapon's **Muzzle > Element** must then be that socket. The Quick Setup for the socket sets this for you, e.g., `Quick Setup: Aim HandGrip_R, first person, two-handed`.

If the analysis fails, the **Failure** pin runs instead of **Success**, and **Weapon Analysis** has the default values. The output log says why, e.g., the component has no skeletal mesh or owning actor, it isn't registered yet, or the mesh has no socket or bone with the **Muzzle** name.

The analysis is a normal struct. If a weapon needs special handling, you can change single fields after the analysis, or give that weapon its own [settings](#settings).

## Sockets

Analyze Weapon looks for these sockets (or bones) on the weapon mesh. You can change the names in the [settings](#settings).

| Socket | Required | Where to put it |
|--------|----------|-----------------|
| `Muzzle` | Yes | At the end of the barrel. **Muzzle Forward Axis** is the socket's local axis that points along the barrel, X by default |
| `FrontSights` | No | On the front sights, such as the front post of iron sights or the front lens of a scope |
| `RearSights` | No | On the rear sights, such as the rear notch of iron sights or the eyepiece of a scope. Leave it out for sights where only one point matters, such as a red dot |
| `Stock` | No | At the back of the stock, where it touches the shoulder |

If the weapon has only one sights socket, [Aim Down Sights](aim-weapon.md?id=aim-down-sights) lines up that one point with the eye. If it has none, Aim Down Sights is turned off for that weapon.

A weapon can have more than one `Stock` socket. When you duplicate a socket in the Skeleton editor, the copies are named `Stock_1`, `Stock_2`, and so on. All of them are used, e.g., for the top and bottom of the butt plate. They become [body depenetration](aim-weapon.md?id=body-depenetration) contact points, and the rearmost one decides how the weapon is held in first person. If there is no `Stock` socket, the rear of the mesh's bounds is used.

## First Person Hold

In first person, the analysis decides where to hold each weapon in front of the camera, so you don't need to set this for each weapon. It puts either the stock or the grip at a fixed offset from the camera:

- Weapons with a stock, such as rifles, are held against the shoulder. The stock goes to **Stock Offset From Camera**.
- Weapons without a stock, such as pistols, are held out in the hand. The grip goes to **Grip Offset From Camera**.

The grip is the weapon actor's origin, where the hand holds the weapon. Everything behind the grip counts as the stock. A weapon has a stock if it reaches at least **Min Stock Length** behind the grip.

Both offsets are relative to the first-person camera, i.e. Pose Override's **Reference Bone** (usually the POV bone). X is forward, Y is right, and Z is up. Rotating an offset tilts the weapon around the stock or the grip. You set the offsets once in the [settings](#settings), and they apply to all weapons.

The result goes to Aim Weapon's [Pose Override](aim-weapon.md?id=pose-override), so it only has an effect while Pose Override's **Weight** is above 0, as in the first-person Quick Setups.

## Settings

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| Muzzle | Name | `Muzzle` | The name of the socket or bone at the end of the barrel |
| Front Sights | Name | `FrontSights` | The name of the socket or bone at the front sights |
| Rear Sights | Name | `RearSights` | The name of the socket or bone at the rear sights. Clear it for single-point sights such as a red dot |
| Stock | Name | `Stock` | The name of the socket or bone at the back of the stock. Numbered copies such as `Stock_1` are used too |
| Muzzle Forward Axis | Vector | X | Which local axis of the muzzle is the "forward" one, the one that projectiles come out of |
| Min Stock Length | float (cm) | 15 | How far behind the grip the stock must reach for the weapon to be held against the shoulder. See [First Person Hold](#first-person-hold) |
| Stock Offset From Camera | Transform | (-10, 10, -20) | Where to put the stock of weapons held against the shoulder, relative to the first-person camera |
| Grip Offset From Camera | Transform | (30, 10, -20) | Where to put the grip of weapons held in the hand, relative to the first-person camera |
| Depenetration Clearance | float (cm) | 1 | How far behind the stock to place the contact points. Increase it to leave more space between the stock and the body |

## Weapon Analysis

Each field of the analysis overrides a setting on Aim Weapon while **Override With Weapon Analysis** is enabled.

| Field | Type | Overrides |
|-------|------|-----------|
| Muzzle Relative To Weapon Actor | Transform | **Muzzle > Offset**, and sets **Muzzle > Local Axis** to X |
| Muzzle Offset From Camera | Transform | **Pose Override > Muzzle Offset From Reference** |
| Has Sights | bool | If false, sets **Aim Down Sights > Weight** to 0 |
| Sights Offset From Muzzle | Vector | **Aim Down Sights > Sights Offset From Muzzle** |
| Rear Sights Offset From Front Sights | Vector | **Aim Down Sights > Rear Sights Offset** |
| Depenetration Contact Points | array of Vector | **Body Depenetration > Contact Points** |