# Equipment
> Equipment holds a drawn item in a place on the body, such as the right hand, and hangs it in another, such as a back sheath, when put away. The drawn item driving combat gives the character its moves.
Markdown version of https://rigbak.com/docs/universal-player-combat/equipment, a page of the Universal Player Combat documentation. Link that page when citing it.
## Set it up (5 minutes)
1. **Start from the sword**
Follow the [Items](https://rigbak.com/docs/universal-player-combat/items) quick start, so `Item_MySword` sits on belt slot 1 and in the right hand.
2. **Hang it on the back**
Add a **Stowable** fragment to `Item_MySword`, with one **Stow Places** row whose **Place** is `UPC.Place.Back.Left`.
In **Item_MySword**, under Stowable, set:
| Property | Value |
| --- | --- |
| Stow Places | 1 Array element (replaces 0 Array elements) |
| Stow Places > Place | UPC.Place.Back.Left |
*The demo character's Body Places put this place on its left shoulder blade, and its UPC Stow Visual shows the sword there.*
3. **Make the character reach for it**
Make two montages, drawing the sword from the back and putting it back, each with a **UPC Equipment Commit** notify at the frame the hand closes on or lets go of the grip. Set them as the row's **Draw Montage** and **Stow Montage**.
In **Item_MySword**, under Stow Places [ 0 ], set:
| Property | Value |
| --- | --- |
| Draw Montage | AM_MySword_Draw |
| Stow Montage | AM_MySword_Stow |
*The sword changes hands at the notify. With no montage, it changes hands at once.*
4. **Press Play, then 1**
Press 1: the character reaches over its shoulder and hangs the sword on its back at the notify's frame. Press 1 again to draw it.
---
## Where items go: Body Places
The **UPC Equipment Manager** (made by the character base) lists the body's **Body Places**, one place tag and socket per row. The hands ship as `UPC.Place.Main` at `hand_r` and `UPC.Place.Off` at `hand_l`; add a row per sheath, hook or worn-gear place. Items name places, never sockets, so a new skeleton is one edit here. A parent tag is its own place: `UPC.Place.Back` does not cover `UPC.Place.Back.Left`.
**Hand Places** names the hands (`UPC.Place.Main` and `UPC.Place.Off` by default). An item held in one is in hand: the belt lights its slot, the drop key can drop it, a full pickup can swap it. Worn gear is never in hand.
**Details panel: EquipmentManagerComponent** (component, in BP_UPC_Character)
**Category: UPC > Equipment**
| Property | Value |
| --- | --- |
| Equipment Action Class | UPCEquipmentActionAbility |
| Default Item | Item_UPC_Unarmed |
**Category: UPC > Equipment > Places**
| Property | Value |
| --- | --- |
| Body Places | 5 Array elements |
| Body Places > UPC.Place.Main > Place | UPC.Place.Main |
| Body Places > UPC.Place.Main > Body Socket | hand_r |
| Body Places > UPC.Place.Off > Place | UPC.Place.Off |
| Body Places > UPC.Place.Off > Body Socket | hand_l |
| Body Places > UPC.Place.Back.Right > Place | UPC.Place.Back.Right |
| Body Places > UPC.Place.Back.Right > Body Socket | stow_back_r |
| Body Places > UPC.Place.Back.Left > Place | UPC.Place.Back.Left |
| Body Places > UPC.Place.Back.Left > Body Socket | stow_back_l |
| Body Places > UPC.Place.Back > Place | UPC.Place.Back |
| Body Places > UPC.Place.Back > Body Socket | back_center_heavy |
| Hand Places | UPC.Place.Main, UPC.Place.Off |
**Category: UPC > Equipment > Debug (collapsed until clicked)**
| Property | Value |
| --- | --- |
| Debug Overlay Equipment | false |
*The demo character. The two hand rows are there out of the box; the three back rows are added for its sheaths.*
> **Warning**
>
> Items hang only on a skeletal mesh tagged `UPC.Attachment` or a child (`BP_UPC_Character` uses `UPC.Attachment.Body`), and only on a character with a **UPC Anim Manager** (the character base has one). See [Animation Integration](https://rigbak.com/docs/universal-player-combat/animation-integration).
---
## Where an item is held: Hold Places
The Equippable's **Hold Places** list where the item can be held, in order of preference (`UPC.Place.Main` by default); **Places Required** is how many it takes (2 for a two-hander listing both hands). A row's **Offset** sets the item's seat on the socket: preview the mesh on a temporary socket under the hand bone in the skeleton editor, move it until it sits right, and copy its relative transform (an off-hand row usually mirrors the main-hand one). A row's **Place Tags** go on the character while the item sits there.
**Details panel: Equippable** (instanced object, in Item_MySword)
**Category: Equippable**
| Property | Value |
| --- | --- |
| Hold Places | 2 Array elements |
| Hold Places > UPC.Place.Main > Place | UPC.Place.Main |
| Hold Places > UPC.Place.Main > Offset > Location | (0, 0, 0) (folded until clicked) |
| Hold Places > UPC.Place.Main > Offset > Rotation | (0, 0, 0) (folded until clicked) |
| Hold Places > UPC.Place.Main > Offset > Scale | (1, 1, 1) (folded until clicked) |
| Hold Places > UPC.Place.Main > Place Tags | no tags |
| Hold Places > UPC.Place.Main > Move To Earlier Place When Free | false |
| Hold Places > UPC.Place.Off > Place | UPC.Place.Off |
| Hold Places > UPC.Place.Off > Offset > Location | (0, 0, 0) (folded until clicked) |
| Hold Places > UPC.Place.Off > Offset > Rotation | (0, 0, 0) (folded until clicked) |
| Hold Places > UPC.Place.Off > Offset > Scale | (1, 1, 1) (folded until clicked) |
| Hold Places > UPC.Place.Off > Place Tags | MyGame.Equipment.OffHandBlade |
| Hold Places > UPC.Place.Off > Move To Earlier Place When Free | true |
| Places Required | 1 |
| Main Weapon | true |
*Listed in preference order. Alone, the sword always takes the first row; a second sword drawn beside it finds that place taken and takes the off hand, with the off-hand row's tag, and moves to the main hand once it frees, since that row has Move To Earlier Place When Free on.*
### What drawing takes
A draw takes free places first, in the item's order, then occupied ones, putting their items away; a sword listing main then off hand, drawn twice, fills both hands. A Hold Places row with **Move To Earlier Place When Free** on moves its item to the first earlier place in the list as soon as that place frees, at once and with no animation: the demo sword turns it on for its off-hand row, so putting away the main-hand sword of a pair moves the other into the main hand. Off, the default, an item stays where it was drawn, such as a dagger kept in the off hand.
| Draw | UPC.Place.Main hand_r | UPC.Place.Off hand_l | Put away |
| --- | --- | --- | --- |
| 1 Sword Main, Off; takes 1 | Sword | empty | nothing |
| Moves: Sword. Alone, an item takes the first place it lists. | | | |
| 2 A second sword Main, Off; takes 1 | Sword | Sword 2 | nothing |
| Moves: Sword. Main is taken, so it takes the next place it lists and adds that row's Place Tags. The first one drawn keeps the moves. | | | |
| 3 Two-hander Main, Off; takes 2 | Two-hander | Two-hander | ~~Sword~~ ~~Sword 2~~ |
| Moves: Two-hander. It needs both places, so whatever holds them is put away first. | | | |
| 4 Sword Main, Off; takes 1 | Sword | empty | ~~Two-hander~~ |
| Moves: Sword. No listed place is free, so it takes the first one and the two-hander goes away whole. | | | |
| 5 Shield Off; Main Weapon off | Sword | Shield | nothing |
| Moves: Sword. The off hand is free. Not a main weapon, so the sword keeps the moves. | | | |
A held item puts its **Equipment Tags** and its places' Place Tags on the character. A lone item takes its first row, so a tag on the off-hand row (`MyGame.Equipment.OffHandBlade`) gates a transition or sub graph on a second sword. Hit volumes take the place's name the same way ([Melee Trace](https://rigbak.com/docs/universal-player-combat/melee-trace#hit-volumes-from-items)).
---
## Which item gives the moves
One drawn item **drives combat**: its Action Graph and Anim Layer Class become the character's. **Main Weapon** on the Equippable decides which:
- **On** (default): a weapon, driving in place of fists or a shield. With two weapons in hand the first drawn drives until **Set Combat Driver** hands the moves over.
- **Off, with an Action Graph**: an off-hand item such as a shield, driving with its own graph while no weapon is drawn.
- **Off, no Action Graph**: supportive, like worn gear; it lends tags, Guard and fragments and never drives.
An item that does not drive keeps its tags, so a shield's moves can sit in the sword's graph as a sub graph gated on its Equipment Tag ([Action Graph Editor](https://rigbak.com/docs/universal-player-combat/action-graph-editor#fold-one-graph-into-another)). The Equipment Manager's **Default Item** (fists, say) drives while nothing else does; it must carry Equippable and never holds a place against another item.
---
## Worn gear
A helmet, cape, ring or necklace is an equippable item with **Main Weapon** off and no Action Graph. Add a Body Places row for its place (`UPC.Place.Head`), with a socket only where a look sits, and list the place in the item's **Hold Places**. Its look:
| Look | How |
| --- | --- |
| One bone (helmet, ring) | **Visuals** fragment **Mesh**, placed by the Hold Places Offset. |
| Skinned (cape, gloves, armor) | **Worn Mesh** fragment skeletal meshes rigged to the character's skeleton, following its pose and visibility. |
| None (a stat necklace) | No look fragment. |
On a belt, a piece of worn gear goes on and off with its key ([Quick Bar](https://rigbak.com/docs/universal-player-combat/quick-bar#lay-out-the-slots)).
**Details panel: Worn Mesh** (instanced object, in Item_UPC_ShoulderCape)
**Category: Worn Mesh**
| Property | Value |
| --- | --- |
| Meshes | 1 Array element |
| Meshes > Index [0] | SKM_UPC_ShoulderCape |
*The demo shoulder cape: a skeletal mesh rigged to the character's skeleton, worn while the item is equipped.*
The demo ring lists `UPC.Place.Ring.Left`, then `UPC.Place.Ring.Right`: a first ring goes left, a second right, a third replaces the left. **Can Draw** names what a draw would replace. A stat comes from an **Equipment Tag** something reads (the UPC Speed Modifier turns the demo ring's `UPC.State.Swift` into 5% more walk speed) or from an effect in an Ability Set the item grants, lasting while it is worn.
Give gear **Slot Tags** the belt's Filters refuse, or a self-filling belt draws it; [Inventory Screens](https://rigbak.com/docs/universal-player-combat/inventory-screens#equip-from-the-inventory) put gear on. To give a character gear from Blueprint, on the server, call the inventory's **Add Item Definition**, then **Equip Item If Free** on the Equipment Manager with the item it returns. A null answer means a place is taken, such as by another cape; **Request Equip Item** puts that one away first. **Remove Item Instance** takes the gear off as it leaves the inventory.
---
## Show carried items on the body
A belt item not in hand can hang on the body, such as a sword on the back. Add a **UPC Stow Visual** component to the character (the character base has none), give the item a **Stowable** fragment listing its **Stow Places** in order of preference, each with an Offset, and give the body a Body Places row for each.
**Details panel: UPC Stow Visual** (component, in AUPCCharacterBase)
**Category: UPC > Stow Visual**
| Property | Value |
| --- | --- |
| Attachment Tag Override | None |
| Default Stow Visual Actor Class | UPCStowVisualActor |
*Add it to the character. With the defaults it hangs each item on the body on the mesh its drawn items use.*
Each hanging item takes the first of its places no other hanging item holds, or shows nothing until one frees, so two swords listing both shoulder blades hang one on each. The look is the Visuals fragment's **Mesh**, or its **Stow Mesh** when **Override Per State** sets one.
Only the belt's items hang by default; a character with no belt, such as an enemy, shows nothing. Tick **Show Carried Items On Body** on the inventory config to hang every carried item with a Stowable fragment, as in a survival game where no weapon can be hidden. An item inside a bag stays hidden unless the belt holds it. An item that does not hang plays no reach to the body.
---
## Animate the draw and the stow
The **UPC Equipment Commit** notify on a Draw or Stow Montage marks the frame the item changes hands; its **Blend Seconds** glides the look there.
**Timeline: AM_MySword_Draw** (1.2 s long). Tracks:
- **Notifies**: glide (0.45 s to 0.6 s); Equipment Commit (at 0.45 s)
*The sword sits in the sheath until the commit frame and in the hand after it; Blend Seconds glides only the look.*
**Details panel: UPC Equipment Commit** (anim notify, in AM_MySword_Draw)
**Category: Equipment**
| Property | Value |
| --- | --- |
| Blend Seconds | 0.15 |
*One notify for every direction: drawing, putting away and dropping. Blend Seconds glides the item's look from the sheath to the hand.*
A row's **Reach Overrides** play another clip for one hand, its **Held Destination**: a row with Held Destination `UPC.Place.Off` and its own Draw Montage plays that clip when the sword goes to the off hand; the main hand uses the place's clip. One press can play several reaches (a two-hander drawn over two swords puts each away first).
A belt press, or Draw With Reach (below), enters at the top. Each step lands at its own commit frame.
1. **May the character change what it holds?** (Can Change Equipment): No while it carries UPC.State.EquipmentBlocked, by default no while a move is running, and no while another sequence of reaches is playing. The section below changes these rules.
2. **Plan the steps** (Plan Draw): One step puts away each item holding a place the new one needs, then one step draws it. Each step picks its reach: the Stowable fragment's Draw or Stow Montage for that sheath, or a Reach Override for that hand.
3. **Play each reach** (the equipment action, an ability the plugin grants): Each montage plays in turn.
4. **Swap at the commit frame** (UPC Equipment Commit notify): Up to the notify the old item is still in hand. At the notify the item changes hands: the outgoing one goes back to its sheath and the incoming one arrives in the hand. A montage with no notify swaps as it ends, and logs a warning.
5. **Hand over the moves** (the drawn item that drives combat): As each step lands, the item that drives combat hands its Action Graph and anim layer to the character; the fists wait for the last step.
---
## When the character may change what it holds
A press mid-attack is refused and forgotten. To change that, make a Blueprint child of `UPCEquipmentActionAbility`, set it as the Equipment Manager's **Equipment Action Class**, and set its Class Defaults:
| Setting | Does |
| --- | --- |
| **Allow During Actions** | A change may start mid-move. Off by default. |
| **Cancel Tags** | Tags that stop a running change and refuse new ones while held (a hit reaction's state). |
| **Block Actions While Running** | On by default: the action graph refuses moves during a reach, until the last step's commit frame. Off lets attacks run through. |
| **Can Run Equipment Action** | Override for conditions of your own, such as an open menu. |
**Details panel: GA_MyEquipmentAction** (Blueprint, in Class Defaults)
**Category: UPC > Equipment**
| Property | Value |
| --- | --- |
| Block Actions While Running | true |
| Allow During Actions | false |
| Cancel Tags | no tags |
*A Blueprint child of the plugin's equipment ability, named in the Equipment Manager's Equipment Action Class. Shown with the shipped defaults.*
`UPC.State.EquipmentBlocked` refuses every draw, put-away and drop whatever these say; a [paired action](https://rigbak.com/docs/universal-player-combat/paired-actions) participant holds it, and a stagger can add it. **Can Change Equipment**, on the Equipment Manager, applies these rules for a button that grays out.
---
## Starting items without a belt
With no belt, or a belt leaving **Auto Populate from Inventory** off (an AI, a placed character, a player on the plugin's **UPC Player Controller**), the character draws its starting items itself. **Draw Starting Items** (character base, on by default) draws the carried equippable items in order, each while its places are free: a helmet, sword and shield put on the helmet and draw both weapons. With Auto Populate on the belt draws instead, so an item no slot takes stays undrawn, as does everything under a config with **Has Belt** off. An already armed character (a non-Default Item drives combat) skips the pass; a bank's items stay put.
---
## Draw and put away from Blueprint
The belt draws for players. Elsewhere call these on the Equipment Manager, on the server unless noted:
| Node | Does |
| --- | --- |
| **Draw With Reach**, **Stow With Reach** | Change what is held, with reaches. Answers **Started**, **Completed Instantly** or **Refused** (a refusal is not kept for later). |
| **Equip Item**, **Unequip Item** | Change it at once whatever the character is doing (script, death, disarm). |
| **Request Equip Item**, **Request Unequip Item** | A screen's equip and put-away, called on the player's machine; the first takes an optional **Place** ([Inventory Screens](https://rigbak.com/docs/universal-player-combat/inventory-screens#equip-from-the-inventory)). |
| **Set Combat Driver**, **Set Default Item** | Hand the moves to another drawn item, or none to restore the ordinary rule; change the fallback. |
| Node | Answers, on any machine |
| --- | --- |
| **Get Combat Driver Instance** | The drawn item driving combat. |
| **Get Drawn Instances**, **Get Drawn Instances Except Default** | Every drawn item, with or without the fists (the second answers "is the character armed"). |
| **Get Instance by Tag**, **Get Instance in Place** | The drawn item with an Equipment Tag, or in a place. |
| **Find Drawn Fragment by Class** | A drawn item's fragment of a class, non-drivers first (a raised shield answers before the sword). |
| **Can Draw** | Whether an item fits now, and what it would put away. |
| **Get Carried Items** | What hangs on the body, and where. |
| **Hangs On Body** | Whether an item hangs while out of hand. |
**On Item Equipped**, **On Item Unequipped**, **On Combat Driver Changed** and **On Drawn State Changed** (once a change has settled) report changes.
---
## Debug it
Tick **Debug Overlay Equipment** on an Equipment Manager, or type `UPC.Debug.Equipment 1` for every character, to see what each holds, which item drives and what hangs on its body. `Log LogUPCEquipment Verbose` logs each reach step, each trace socket as it registers, and every refusal.
Change what a press does (Advanced)
The equipment action's **Plan Draw** lists a draw's steps: each item holding a place the new one needs goes away, then the new one comes out, each with its reach. Its **Place** input is the place a paper doll asked for, empty for a belt press or Equip button. **Plan Stow** does the same for a put-away.
**Can Equip Item** asks Plan Draw too, so a Plan Draw that refuses grays an Equip button, and **Request Equip Item** then takes nothing out of storage.
Override either in your Blueprint child, calling the parent for the default steps; set **Outgoing** on the drawing step to put the shield away as the two-hander comes out. Read the character from the **Equipment** input, not the ability's variables, since the player's machine also asks the plan outside any activation. Draw With Reach and a belt press refuse a change while another sequence plays.
Blueprints of your own for an item (Advanced)
- **Held look.** A Visuals **Mesh** with no **Item Actor Class** spawns the plugin's held actor, its mesh tagged `UPC.ItemMesh` for a Trace Sockets row. For parts of your own, set a Blueprint child of `UPCEquippableItem` as Item Actor Class (a `UPCStaticMeshEquippableItem` child shows its own Mesh component's mesh); it spawns on draw, goes on stow, and fires **On Drawn** and **On Stowed**.
- **Release Visual Actor**, on the equipment instance, hands the actor to your game (a thrown sword): it stays alive on stow and gets no On Stowed.
- **Stowed look.** Stowable's **Stow Actor Class** shows an actor of your own (a `UPCStowVisualActor` child also receives the Stow Mesh); the UPC Stow Visual's **Default Stow Visual Actor Class** restyles every mesh-only holster.
- **Logic.** A Blueprint child of `UPCEquipmentInstance`, set as the Equippable's **Instance Type**, runs **On Equipped** once in hand and **On Unequipped** once gone; **Get Spawned Actor**, **Get Held Tags** and **Is Combat Driver** read it.
First-person and third-person meshes (Advanced)
Tag each mesh (`UPC.Attachment.Body`, `UPC.Attachment.FirstPerson`). The UPC Anim Manager's **Default Attachment Tag** picks one at the start; **Set Active Attachment Tag** switches at runtime, moving what is drawn (each machine picks for itself). The UPC Stow Visual's **Attachment Tag Override** pins stowed looks to one mesh.
The demo
- `BP_UPC_Character`: Body Places for the hands, three back sheaths (`UPC.Place.Back`, `.Left`, `.Right`) and each demo worn-gear piece; Default Item `Item_UPC_Unarmed`.
- `Demo/Items/WornGear`: helmet, shoulder cape, ring and necklace (the last two hold `UPC.State.Swift`).
- `LVL_UPC_Wardrobe`: a pad per demo weapon and worn item; walk on to equip, again to put away.
What runs where (Multiplayer)
The server decides what is drawn, which item drives, what hangs and where, and replicates it to every machine (an item that does not hang reaches no other machine). Each machine spawns its own held and stowed looks and runs its own Blend Seconds glide.
- Nothing is predicted. A belt press plays the reach at once and asks the server; the item arrives about a round trip later, with the server's sequence confirming the reach or replacing it when its steps differ.
- A refusal blends the player's reach out; it names no press, so a second press within that round trip plays its reach again.
- The equipment action runs on the server only; the plugin grants it once the ability system is ready ([Character Setup](https://rigbak.com/docs/universal-player-combat/character-setup)). Without it a reach-authored item changes hands at once, with a warning.
- **On Equipped** and **On Unequipped** run on every machine, so gate gameplay on authority. Item input binds only on the controlling player's machine; **Try Get Held Velocity** answers on the server only.
C++
- `UUPCEquipmentManagerComponent::EquipItem` and `UnequipItem` are instant. `DrawWithReach` and `StowWithReach` plan through `UUPCEquipmentActionAbility::PlanDraw` / `PlanStow` (Blueprint native events taking the manager as `Equipment`; the granted action's, else the Equipment Action Class's defaults) and run `RunEquipSequence(TArray, TOptional)`. A step's C++-only `Commit` delegate runs on the server after its change.
- `ResolvePlaceAssignment` is the one place rule, for hands and sheaths alike.
- `IsChangeBlocked(const AActor*, bool bAllowDuringActions)` is Can Change Equipment's static half; `CanRunEquipmentAction_Implementation` the project half.
- `GatherDrawnFragmentsByClass` returns every drawn item's fragment of a class, supportive items first.
- `FUPCEquipStep` and `EUPCEquipSequenceOutcome` live in `UPCEquipStep.h`; `IsEquipSequenceRunning` is true on the server while a change runs.
- The server keeps the hanging items from the inventory (`RefreshCarriedItems`, on the inventory's `OnCarryChanged` and as each equipment change settles): one unit per out-of-hand item `HangsOnBody` answers yes for, each with a server-assigned id and place, read through `GetCarriedItems`. A unit keeps its id and place while its item keeps hanging.
Troubleshooting (Advanced)
**An item does not show where it should**
Each warns once in the Output Log:
- **No mesh carries the attachment tag, or there is no UPC Anim Manager.** Nothing attaches.
- **The body has no row for a place the item needs.** The draw fails: a body without the off-hand row refuses a two-hander.
- **The row names no socket.** The item hangs off the mesh root. Set Body Socket, or the Hold Places row's **Body Socket Override** (under its advanced arrow), a socket of the item's own.
- **The socket is not on the mesh.** The item hides until it is. A Body Socket Override the mesh lacks falls back to Body Places.
- **Body Places is empty.** The body takes any item and hangs it off the mesh root.
- **A carried item shows nothing.** No UPC Stow Visual or Anim Manager, no Stow Places, no Body Places row for them, a missing socket, or the item is off the belt and **Show Carried Items On Body** is off. Only the missing rows warn.
- **A reach plays nothing.** The montage did not load or does not suit the skeleton, so the change happened at once. One with no commit notify swaps as it ends.
---
Previous page: [Items](https://rigbak.com/docs/universal-player-combat/items). Next page: [Quick Bar](https://rigbak.com/docs/universal-player-combat/quick-bar)