Equipment

Documentation Unreal Engine Player Combat 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.

Set it up

5 minutes

1
Start from the sword
Follow the 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.
Item_MySword
▾Stowable
Stow Places0 Array elements
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.
Item_MySword
▾Stow Places [ 0 ]
Draw Montage
None▾
Stow Montage
None▾
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

EquipmentManagerComponent

UPC

Equipment

Equipment Action Class

UPCEquipmentActionAbility

Default Item

Item_UPC_Unarmed

Places

Body Places

5 Array elements

UPC.Place.Main

Place

UPC.Place.Main

Body Socket

hand_r

UPC.Place.Off

Place

UPC.Place.Off

Body Socket

hand_l

UPC.Place.Back.Right

Place

UPC.Place.Back.Right

Body Socket

stow_back_r

UPC.Place.Back.Left

Place

UPC.Place.Back.Left

Body Socket

stow_back_l

UPC.Place.Back

Place

UPC.Place.Back

Body Socket

back_center_heavy

Hand Places

2 Gameplay Tags

UPC.Place.Main

UPC.Place.Off

Debug

Debug Overlay Equipment

The demo character. The two hand rows are there out of the box; the three back rows are added for its sheaths.

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.

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

Equippable

Hold Places

2 Array elements

UPC.Place.Main

Place

UPC.Place.Main

Offset

Location

0.0

Rotation

0.0

Scale

1.0

Place Tags

0 Gameplay Tags

Move To Earlier Place When Free

UPC.Place.Off

Place

UPC.Place.Off

Offset

Location

0.0

Rotation

0.0

Scale

1.0

Place Tags

1 Gameplay Tag

MyGame.Equipment.OffHandBlade

Move To Earlier Place When Free

Places Required

Main Weapon

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
1Sword Main, Off; takes 1	Sword	empty	nothing
Moves: Sword. Alone, an item takes the first place it lists.
2A 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.
3Two-hander Main, Off; takes 2	Two-hander	Two-hander	SwordSword 2
Moves: Two-hander. It needs both places, so whatever holds them is put away first.
4Sword 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.
5Shield 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).

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). 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).

Details

Worn Mesh

Meshes

1 Array element

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 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

UPC Stow Visual

UPC

Stow Visual

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.

AM_MySword_Draw

0.0

0.2

0.4

0.6

0.8

1.0

1.2

Notifies

glide

Equipment Commit

The sword sits in the sheath until the commit frame and in the hand after it; Blend Seconds glides only the look.

Details

UPC Equipment Commit

Equipment

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 topEach step lands at its own commit frame

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.

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.

Play each reach

the equipment action, an ability the plugin grants

Each montage plays in turn.

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.

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

GA_MyEquipmentAction

UPC

Equipment

Block Actions While Running

Allow During Actions

Cancel Tags

0 Gameplay 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 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).
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.

AdvancedChange what a press does

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.

AdvancedBlueprints of your own for an item

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.

AdvancedFirst-person and third-person meshes

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.

MultiplayerWhat runs where

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). 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++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<FUPCEquipStep>, TOptional<bool>). 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.

AdvancedTroubleshooting

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.