# Animation Integration

> Animation integration keeps combat timing on the animation: a montage window holds a gameplay tag, an item brings its own animation layer, a frame asks for a footstep, and the pose holds on a hit.

Markdown version of https://rigbak.com/docs/universal-player-combat/animation-integration, a page of the Universal Player Combat documentation. Link that page when citing it.

## Set it up (2 minutes)

1. **Put a state tag window on the dodge**

   On the demo player, open `AM_UPC_DodgeBack` (it already carries this window; on a dodge montage of your own, add one). Right-click a notify track, **Add Notify State**, **UPC State Tag Window**. Drag it across the frames the dodge should pass through blows, and put `UPC.State.Intangible` in **Tags**.

   In **AM_UPC_DodgeBack**, under State Tags, set:

   | Property | Value |
   | --- | --- |
   | Tags | UPC.State.Intangible |
2. **Map the tag to a bool**

   The same tag can drive your Animation Blueprint. In `ABP_UPC_MannequinBase` the parent is already **UPC Anim Instance Base**; in your own, open **Class Settings** and set **Parent Class** to it. Add a bool, `IsIntangible`, and in **Class Defaults** add a **Gameplay Tag Property Map** row: the tag in **Tag to Map**, the bool in **Property to Edit**.

   **Details panel: ABP_MyHero** (Blueprint, in Class Defaults)

   **Category: UPC > Gameplay Tags**

   | Property | Value |
   | --- | --- |
   | Gameplay Tag Property Map > Property Mappings | 1 Array element |
   | Gameplay Tag Property Map > Property Mappings > Index [0] > Tag to Map | UPC.State.Intangible |
   | Gameplay Tag Property Map > Property Mappings > Index [0] > Property to Edit | IsIntangible |

   *Each row keeps one bool variable in step with one tag on the character, whatever put the tag there.*
3. **Press Play and dodge through a swing**

   Dodge through an enemy's swing: a melee trace passes through `UPC.State.Intangible`, so a swing crossing those frames lands nothing. Your `IsIntangible` bool is true for the window and false after it, for a pose or an effect to read.

The tags go on the character's ability system; a pawn without one holds nothing.

---

## Tell the plugin which mesh does what

Add these names to a skeletal mesh's **Component Tags** (plain names, separate from gameplay tags). A tag counts when it equals the name or starts with it and a dot: `UPC.Attachment.Body` counts for `UPC.Attachment`.

| Tag | Marks a mesh that |
| --- | --- |
| `UPC.Montage` | Plays the character's montages. The main mesh plays them untagged; tag it so item layers fall back to it, and tag each extra mesh that should follow. |
| `UPC.AnimLayer` | Takes the drawn item's animation layer. With none tagged, the montage meshes take it. |
| `UPC.Attachment` | Holds drawn items. The full tag tells several apart. |

A one-mesh character needs `UPC.Montage` and `UPC.Attachment.Body`; the character base's **UPC Anim Manager** reads them as the character spawns.

**Details panel: AnimManagerComponent** (component, in BP_UPC_Character)

**Category: UPC > Mesh Registry**

| Property | Value |
| --- | --- |
| Montage Mesh Tag Prefix | UPC.Montage |
| Anim Layer Mesh Tag Prefix | UPC.AnimLayer |
| Attachment Mesh Tag Prefix | UPC.Attachment |
| Default Attachment Tag | None |

**Category: UPC > Hit Stop**

| Property | Value |
| --- | --- |
| Hit Stop Enabled | true |

**Category: UPC > Anim > Debug**

| Property | Value |
| --- | --- |
| Debug Overlay Anim | false |

**Category: UPC > Designer Tools**

| Property | Value |
| --- | --- |
|  | buttons: Preview Mesh Discovery |

*Preview Mesh Discovery lists which meshes the tags would register, and in which roles, without registering anything.*

---

## Give an item its own animation layer

Three assets meet. An animation layer interface names each layer (say, a walk cycle). The character's Animation Blueprint has a **Linked Anim Layer** node for that layer, where the walk plays. An item's Animation Blueprint implements the layer with the item's own animation, and the item names it as its **Anim Layer Class** ([Items](https://rigbak.com/docs/universal-player-combat/items)).

In the demo, `ALI_UPC_ItemAnimLayers` (`Core/Animation`) declares the layer, `ABP_UPC_MannequinBase` has the node for it, `ABP_UPC_SwordAnimLayer` implements it with the sword's walk, and `Item_UPC_Sword` names that Blueprint. Drawing the sword links its walk into the node; putting it away unlinks it. A custom character adds the **Linked Anim Layer** nodes to its own Animation Blueprint, and a custom weapon duplicates `ABP_UPC_SwordAnimLayer` (it works on the demo mannequin or a child of `ABP_UPC_MannequinBase`) and sets the copy on its item.

Only the item driving combat links a layer, so a shield beside a sword animates through the sword's layer ([Equipment](https://rigbak.com/docs/universal-player-combat/equipment)).

---

## Hold a tag for part of an animation

A **UPC State Tag Window** holds its **Tags** on the character while it runs. An interrupted montage drops its tags, so a canceled dodge loses its i-frames. These tags are ready to hold; a tag of your own works the same way:

| Tag | Hold it over | Read by |
| --- | --- | --- |
| `UPC.State.Intangible` | A dodge's i-frames | A melee trace, which passes through |
| `UPC.State.HyperArmor` | A heavy swing light hits must not stop | A Scale Damage response (lets part of a hit's damage through; [Hit Reactions](https://rigbak.com/docs/universal-player-combat/hit-reactions#hyper-armor)) |
| `UPC.State.Parrying`, `UPC.State.Blocking` | A parry's active frames, a raised guard | A defense rule or a reaction you gate on it |
| `UPC.State.Staggered`, `UPC.State.Recovering` | A stagger, the recovery after an action | Transitions you gate on them |

---

## Fire a one-off signal from a frame

For a moment with no window, such as a prop spawning or an interaction committing, add **Notify**, **UPC Gameplay Event** at the frame and set **Event Tag**. A gameplay ability's **Wait Gameplay Event** task, or a **Wait Gameplay Event to Actor** node in any Blueprint, pointed at the character, hears it once. The character is instigator and target, and the animation is the **Optional Object**.

---

## Hold the pose on a hit

A hit stop holds the picture as a blow lands, while the montage, its windows and the movement run on. Each mesh that holds needs a **UPC Hit Stop** node after the montage slot, followed by an **Inertialization** node:

Blueprint graph, nodes in reading order:

- **Comment box: ABP_MyHero · AnimGraph**

  - **Slot 'DefaultSlot'** (anim; Group 'DefaultGroup'); inputs: Source
  - **UPC Hit Stop** (anim); inputs: Source
  - **Inertialization** (anim); inputs: Source
  - **Output Pose** (anim); inputs: Result

| Setting | Does |
| --- | --- |
| **Release Blend Time** | Seconds the held pose takes to blend back into the live one (0.1); 0 snaps back. A longer hold adds half the hold to the blend, up to this value again (at 0.1, a 0.3 s hold blends back in 0.2 s). **Max Hit Stop Seconds** (0.3 s, **Project Settings > Plugins > Universal Player Combat**) caps the hold and the blend back, each separately. |
| **Hold Placement** | Keeps the held body where it stood while root motion or a glide moves the character; it catches up on release. Turn it off on a mesh attached to the camera, such as first-person arms. |

A damage config's **UPC Hit Stop** hit effect asks for the hold ([Damage and Hit Effects](https://rigbak.com/docs/universal-player-combat/damage-and-hit-effects#hit-stop)).

---

## Ask the character for its own effect

Two notifies ask the character for an effect; each character answers with its own sounds and particles, so a barefoot rogue and a plated knight differ.

| Notify | Use it for |
| --- | --- |
| **UPC Anim Effect** | One frame: a footstep, a landing, a grunt. |
| **UPC Anim Effect Window** | A stretch from its first frame to its last: a weapon trail, a charge glow. |

Set **Effect Tags**, such as `UPC.AnimEffect.Footstep.Left`, and **Socket Name**, where on the body; None plays at the mesh's position.

To answer them, make an **Anim Effect Bank** with a row per **Effect Tag** holding its **Sounds** and **Particles**, and set it as **Bank** on the character's **UPC Anim Effects** component (`AnimEffectComponent` on the character base). A request plays the row whose tag matches it most closely: in a bank with a `Footstep` row and a `Footstep.Left` row, a left step plays `Footstep.Left` and a right step plays `Footstep`.

Create the asset: right-click in the Content Browser, choose **UPC > Presentation > Anim Effect Bank**, and name it **AnimEffectBank_MyHero**.

**Details panel: AnimEffectBank_MyHero** (data asset, in Content Browser)

**Category: Anim Effects**

| Property | Value |
| --- | --- |
| Rows | 1 Array element |
| Rows > UPC.AnimEffect.Footstep > Effect Tag | UPC.AnimEffect.Footstep |
| Rows > UPC.AnimEffect.Footstep > Sounds | 1 Array element |
| Rows > UPC.AnimEffect.Footstep > Sounds > Index [0] | SC_UPC_Footsteps |
| Rows > UPC.AnimEffect.Footstep > Particles | 0 Array elements |
| Rows > UPC.AnimEffect.Footstep > Attach to Socket | true |
| Rows > UPC.AnimEffect.Footstep > Forward Axis | (1, 0, 0) |
| Rows > UPC.AnimEffect.Footstep > Volume Multiplier | 1 |
| Rows > UPC.AnimEffect.Footstep > Pitch Multiplier | 1 |
| Rows > UPC.AnimEffect.Footstep > Particle Scale | 1 |
| Surface Set | None |

*Each row takes its Effect Tag as its title. Surface Set, beside the rows, lets a row answer only on one kind of ground.*

| Row setting | Does |
| --- | --- |
| **Attach to Socket** | Follow the socket. Off leaves the effect where the frame fired, as dust on the ground wants. |
| **Forward Axis** | The socket axis the particles face: X its forward, Y for a bone whose Y points out of the body, such as the mannequin spine. |
| **Volume Multiplier**, **Pitch Multiplier**, **Particle Scale** | Scale the sounds and particles; 1 plays them as authored. |

An item's **Swing Trail** fragment draws its ribbon while a window carrying `UPC.AnimEffect.Weapon.Trail` runs ([Items](https://rigbak.com/docs/universal-player-combat/items#guard-swing-trail-and-camera)).

The animation and montage editors play a clip's effects from **Preview Bank** (**Project Settings > Plugins > Universal Player Combat Editor**, the demo bank to start) and name the bank in the viewport's corner.

---

## One montage on several meshes

An extra mesh tagged `UPC.Montage` (first-person arms next to the body, say) plays the character's montages but only animates; each notify the plugin ships does its work once, on the body. [Equipment](https://rigbak.com/docs/universal-player-combat/equipment) covers which mesh holds the items.

---

## Debug it

```
UPC.Debug.Anim 1          // Each character's montage mesh, layer mesh and hit stop time
UPC.Debug.AnimEffects 1   // Each character's last effect requests and what answered them
Log LogUPCAnim Verbose    // The same answers in the log
ShowDebug AbilitySystem   // The tags each character holds
```

**Debug Overlay Anim** on an Anim Manager shows the first overlay for one character. Test effects on a client or a listen server; a dedicated server plays none.

<details>
<summary>The mesh registry (Advanced)</summary>

- **Register Mesh** adds a mesh during play, such as a mount or an outfit part, with its roles ticked by hand. Its **Attachment Tag** lets items hang on it; None keeps the slot its own `UPC.Attachment` component tag gives. **Include in Hit Stop** off keeps it moving through holds.
- **Release Hit Stop** ends a hold, for a death that plays no montage. **Unregister Mesh** takes a mesh out; **Rediscover Meshes** scans the component tags again and keeps meshes registered by hand.
- With neither `UPC.AnimLayer` nor `UPC.Montage` on any mesh, a layer links nowhere. A character drawing items needs an Anim Manager; without one, a draw warns once.
- When the driving item changes, the new layer links before the old one unlinks, so a layer both share stays on.

</details>

<details>
<summary>Windows, bools and events (Advanced)</summary>

- A window of no length holds nothing, and two windows holding one tag keep it until the second closes. A window restarted without an end, as a jump back a section does, releases its first record; tags come off the ability system they went onto.
- A mapped bool follows a tag from a window and a tag from a gameplay effect alike. **UPC Anim Instance Base** finds the character's ability system itself, one appearing later on a Player State included; **Initialize with Ability System** points it elsewhere. **Get Owned Tags** returns this frame's tags, safe in a thread-safe animation function.
- A listener that starts waiting after a **UPC Gameplay Event** frame hears nothing.
- An animation cut short inside a **UPC Anim Effect Window** can skip its close, so a handler also stops anything costly at teardown.

</details>

<details>
<summary>Effect tags, surfaces, layers and Blueprint answers (Advanced)</summary>

- **Tags.** The plugin's effect tags sit under `UPC.AnimEffect`: Footstep (Left, Right, Land), Land, Jump, Roll, Slide, Foley, Vocal, Whoosh, Weapon (Draw, Sheathe, Hit, Trail, Glow) and Blood.
- **Surfaces.** With a **Surface Set** on the bank, a footstep on a material mapped to `Stone` plays a `Footstep.Stone` row before `Footstep`, while a deeper plain row such as `Footstep.Left` still wins. Add each surface row's tag to the project's tag list. The component traces the ground only for an effect that has surface rows, on its **Surface Trace Channel** (Visibility) up to **Surface Trace Distance** (50 cm) below the socket.
- **Layers.** **Add Bank** layers a bank at a **Priority**, such as wet ground while it rains; the highest wins, the newest on a tie, and a layer needs only the rows it changes. **Remove Bank** takes it off; **Set Bank** replaces the character's own.
- **Blueprint answers.** Implement the **UPC Anim Effect Handler** interface (**Handle Anim Effect**, **Begin** and **End**) on the character or any component. Every handler is asked.
- **Per skeleton.** **Preview Banks By Skeleton** gives one skeleton's clips their own preview bank.

</details>

<details>
<summary>Footsteps on a whole folder of animations (Advanced)</summary>

The **UPC Footsteps** animation modifier, applied from an animation's **Animation Data Modifiers** window, writes a **UPC Anim Effect** where each foot lands: `Footstep.Left` at `foot_l`, `Footstep.Right` at `foot_r`, on a Footsteps track each apply rebuilds. **Ground Tolerance** (3 cm) is how far above its lowest point a foot counts as planted, **Lift Height** (5 cm) how high it rises before the next landing counts, and **Notifies to Remove** clears older footstep notifies.

For a folder, run `UPC.AnimEffects.PlantFootsteps /Game/MyCharacter/Animations save`; without `save` the animations wait for a Save All. A turn in place can miss a step, and a jump or fall clip can gain a false one.

</details>

<details>
<summary>The demo</summary>

- `BP_UPC_Character` tags its mesh `UPC.Montage` and `UPC.Attachment.Body`; its `ABP_UPC_MannequinBase` is a UPC Anim Instance Base.
- The item layers are children of `ABP_UPC_ItemAnimLayersBase`, which maps `UPC.State.Blocking` to a bool: `ABP_UPC_SwordAnimLayer` (sword and shield), `ABP_UPC_TwoHandedAnimLayer`, `ABP_UPC_UnarmedAnimLayers`.
- `AM_UPC_DodgeBack` holds Intangible, `AM_UPC_Sword_Parry` Parrying and `AM_UPC_Unarmed_Combo` HyperArmor. The chest, door and pickup montages send `UPC.Event.Interaction.Commit`.
- The player's bank is `AnimEffectBank_UPC_Default`.

</details>

<details>
<summary>What runs where (Multiplayer)</summary>

- **Windows** add their tags on each machine playing the montage; nothing replicates. The server's damage checks read its own window.
- **On a dedicated server** a window runs only while the mesh ticks its pose, as a character's mesh does by default (**Visibility Based Anim Tick Option** at **Always Tick Pose**). **Only Tick Pose when Rendered** stops it, a root motion montage aside, and the Anim Manager warns once. Keep **Trigger on Dedicated Server** ticked on each notify.
- **Effects and gameplay events** fire on each machine playing the animation (effects never on a dedicated server). **Item layers** link on each machine as the drawn item arrives. Hit stop: [Damage and Hit Effects](https://rigbak.com/docs/universal-player-combat/damage-and-hit-effects#hit-stop).

</details>

<details>
<summary>C++</summary>

- `UUPCAnimManagerComponent` holds the mesh registry, links item layers (`LinkAnimationLayer`, counted per class) and runs hit stop (`HoldPose`); `UUPCAnimInstanceBase` carries the tag to bool map.
- A gameplay notify of your own returns early when `UPCMontageWindow::IsGameplayMesh(MeshComp)` answers false, as the plugin's do: only the mesh the ability system plays montages on counts, or every mesh on a character with no Anim Manager. `MirrorMontagePlayAt` plays a montage on the extra meshes and returns a ticket for `MirrorMontageStopFor`.
- `IUPCAnimEffectHandler` receives every effect request; `UUPCAnimEffectBankStatics` plays a bank row without the component.
- `FUPCAnimNode_HitStop` runs **UPC Hit Stop**; its editor node sits in the uncooked-only `UPCAnimGraph` module, which a packaged game never loads.

</details>

<details>
<summary>Troubleshooting (Advanced)</summary>

| Warning or symptom | Fix |
| --- | --- |
| `UPC.Debug.AnimEffects` lists no request | Put the notify on a montage the character plays. |
| Nothing on this character answers anim effects | Add a **UPC Anim Effects** component or a handler. |
| A request reads nobody answered | Give the bank a row at or above the tag. |
| ...a notify with no Effect Tags | Set its Effect Tags. |
| ...takes anim layers but runs no Animation Blueprint | Give the mesh one, or take `UPC.AnimLayer` off it. |
| ...more than one mesh tagged ... | Give each attachment mesh its own tag. |
| Hit stop on ... shows nothing | Add the UPC Hit Stop and Inertialization nodes, or register a mesh copying another's pose with **Include in Hit Stop** off. |
| ...sending ... but has no Ability System Component | Add one, or take the UPC Gameplay Event off. |
| Montage mesh ... ticks its pose only when rendered | See What runs where. |

</details>

---

Previous page: [Pairing Editor](https://rigbak.com/docs/universal-player-combat/pairing-editor). Next page: [HUD and Input Prompts](https://rigbak.com/docs/universal-player-combat/hud-and-input-prompts)