Items
Documentation Unreal Engine Player Combat Items
An item is one asset: its name and icon, how many stack together, and a list of fragments, each adding one thing the item can do, such as be drawn into the hand, hang on the back or lie on the ground.
Build
AG_MyFirstGraph first, in the Action Graph quick start.Set it up
4 minutes- 1
Create an Item Definition
Content Browser▸ ContentSet its Slot Tags toUPC.Slot.Weapon.Sword, so the demo's belt, its row of item keys, takes it on key 1. - 2
Give it a look
Under Fragments, press +, pick Visuals and set its Mesh to your sword's static mesh.Item_MySword▾FragmentsIndex [ 0 ]NoneThe mesh shows in the hand, on the body and on the ground. - 3
Make it drawable
Add an Equippable fragment. Its Hold Places already list the right hand. Set Action Graph toAG_MyFirstGraph; a weapon with none leaves the character no moves while drawn. Set Input Mapping Context to the demo'sIMC_UPC_Swordand add one Input Mappings row, Input ActionIA_UPC_LightAttackand Input TagUPC.Input.LightAttack, so the left mouse button reaches the graph (Input).Item_MySword▾FragmentsIndex [ 1 ]None - 4
Give it to the character
OnBP_UPC_Character's InventoryComponent, addItem_MySwordto Starting Items and press Play inLVL_UPC_Demo: the belt puts the sword on slot 1 and draws it. A crooked sword needs a Hold Places Offset.
What an item is
An Item Definition describes one kind of item and never changes in play: three potions are three units of one definition. There is no category to pick; an item without Equippable (a potion) is owned, stacked and used from the belt, never held.
Details
Item_MySword
Item
Max Stack Size
1
Slot Tags
1 Gameplay Tag
UPC.Slot.Weapon.Sword
Display
Display Name
Short Sword
Description
Icon
T_MySword_Icon
Inventory Grab Sound
None
Inventory Place Sound
None
Fragments
Preset
None
Fragments3 Array elements
Fragments
3 Array elements
Index [ 0 ]Equippable
Index [ 0 ]
Equippable
Index [ 1 ]Visuals
Index [ 1 ]
Visuals
Index [ 2 ]Stowable
Index [ 2 ]
Stowable
An item is its identity plus the fragments it lists. This one is drawn into the hand, shown with a mesh and hung on the back when put away.
| Setting | Does |
|---|---|
| Max Stack Size | Most units in one stack; 1 keeps units apart. A bag always holds 1. |
| Slot Tags | The item's kind (UPC.Slot.Weapon.Sword). A belt slot or holder peg with Filter UPC.Slot.Weapon takes it, children included; inventory rules also admit by kind. Empty fits unfiltered slots only. |
| Display Name, Description, Icon | Text and texture for your UI and the pickup prompt. |
| Inventory Grab Sound, Inventory Place Sound | Played by a screen as the player picks up or puts down the item (Get Inventory Grab Sound, Get Inventory Place Sound); empty uses its Stowable Draw and Put Away Sound. |
| Preset | Fragments the item inherits (Share fragments with a preset). |
| Fragments | What the item can do. |
The fragments
FragmentOwnedIn handOn the bodyOn the ground
Equippable
Makes the item drawable: where it is held, its moves, its keys, what it grants, where it cuts.
Visuals
The item's mesh, with its own look on the body or on the ground if you want one.
Stowable
Where it hangs while carried, the animation of reaching for it, and its draw and put-away sounds.
Worn Mesh
Skinned meshes worn on the body while it is equipped, such as a cape or gloves.
World Item
Lets it leave the hand and lie in the world, and the sound it makes landing.
Guard
The block or parry it lends whoever holds it.
Swing Trail
A ribbon behind it while it swings.
Camera Rig
Camera settings while the character fights with its moves.
Weight
A weight per unit, for a weight limit.
Grid Footprint
The cells it covers in a grid container.
Capacity Bonus
More slots, grid rows, weight or units while it is owned.
Container
Makes it a bag with a container of its own, open while the bag sits in a container that opens bags.
Belt Limit
How many copies the belt may hold.
| Fragment | Covered on |
|---|---|
| World Item | Pickups, Drops and Holders |
| Worn Mesh | Equipment |
| Weight, Grid Footprint, Capacity Bonus | Containers and Rules |
| Container | Bags and Banks |
| Belt Limit | Quick Bar |
Equippable: drawing it
A sword needs Hold Places (right hand by default), an Action Graph, and the keys that reach it: an Input Mapping Context and Input Mappings row, as the quick start sets. The rest is optional.
Details
Equippable
Equippable
Item Actor Class
None
Instance Type
None
Action Graph
AG_MySword
Ability Sets to Grant
0 Array elements
Hold Places2 Array elements
Hold Places
2 Array elements
UPC.Place.Main
UPC.Place.Main
Place
UPC.Place.Main
Offset
Offset
Location
0.0
0.0
0.0
Rotation
0.0
0.0
0.0
Scale
1.0
1.0
1.0
Place Tags
0 Gameplay Tags
Move To Earlier Place When Free
UPC.Place.Off
UPC.Place.Off
Place
UPC.Place.Off
Offset
Offset
Location
0.0
0.0
0.0
Rotation
0.0
0.0
0.0
Scale
1.0
1.0
1.0
Place Tags
1 Gameplay Tag
MyGame.Equipment.OffHandBlade
Move To Earlier Place When Free
Places Required
1
Main Weapon
Equipment Tags
0 Gameplay Tags
Anim Layer Class
ABP_MySwordLayers
Input Mapping Context
IMC_MySword
Input Mapping Priority
0
Input Mappings
2 Array elements
Input Chords
0 Array elements
Trace Sockets
1 Array element
Attack Stop Distance
-1
Draw Timing
Draw Timing
Seconds
0.2
Start Sound
None
Commit Sound
None
Cancel on Move
Stow Timing
Stow Timing
Seconds
0.2
Start Sound
None
Commit Sound
None
Cancel on Move
The sword: held in the right hand, or the left when the right is taken, with its own moves, keys, animation layer and hit volume.
| Setting | Does |
|---|---|
| Item Actor Class | Blueprint child of UPCEquippableItem shown in hand instead of the Visuals Mesh. |
| Instance Type | Blueprint child of UPCEquipmentInstance for your own draw and put-away logic (Equipment). |
| Action Graph | The item's moves; the one drawn item that drives combat supplies the character's (Equipment). |
| Ability Sets to Grant | Ability Sets (abilities with an optional key, effects such as a stat bonus) granted while drawn (Input). |
| Hold Places, Places Required, Main Weapon | Where it is held, in how many places, and whether its moves take over (Equipment). A row's Move To Earlier Place When Free moves the item to an earlier place as that place frees, as the demo sword's off-hand row does. |
| Equipment Tags | Tags on the character while drawn. |
| Anim Layer Class | Animation layer linked while it drives combat (the weapon's idles and locomotion). |
| Input Mapping Context, Input Mapping Priority, Input Mappings, Input Chords | Keys added while drawn (Input). |
| Trace Sockets | Where swings sweep from (Melee Trace). |
| Attack Stop Distance | How close attacks stop to a target, in cm; -1 defers to the combat style. A move's own Stop Distance and a window's override win over it (Attack Steering). |
| Draw Timing, Stow Timing | Tick one for the item's own wait and sounds, replacing the inventory config's, when a screen draws or puts it away and it has no draw or stow animation (Containers and Rules). |
Visuals: what it looks like
Mesh serves every state. Override Per State adds a Stow Mesh (a scabbard) and a Drop Mesh, each falling back to Mesh. An Equippable Item Actor Class beats Mesh in hand; with neither, the character holds nothing visible (as fists want).
Details
Visuals
Visuals
Mesh
SM_MySword
Override Per State
Stow Mesh
SM_MySword_Sheathed
Drop Mesh
None
The sword shows a sheathed mesh on the body and its plain Mesh on the ground, since Drop Mesh is empty.
Stowable: hanging on the body
Stowable lists the places the item hangs while carried but not in hand, and the reach to each (Equipment). Without it, the item vanishes while put away.
Details
Stowable
Stowable
Stow Actor Class
None
Stow Places1 Array element
Stow Places
1 Array element
UPC.Place.Back.Left
UPC.Place.Back.Left
Place
UPC.Place.Back.Left
Offset
Offset
Location
0.0
0.0
0.0
Rotation
0.0
0.0
0.0
Scale
1.0
1.0
1.0
Draw Montage
AM_MySword_Draw
Stow Montage
AM_MySword_Stow
Reach Overrides
0 Array elements
Draw Sound
SC_MySword_Draw
Put Away Sound
SC_MySword_PutAway
The places the item may hang while it is carried but not in hand, and the animation of reaching to each one.
Its Sounds belong to the item, so items sharing one reach still sound like themselves. Draw Sound plays as the item arrives in the hand and Put Away Sound as it arrives at its place on the body, at the reach's commit frame or as the item appears there. Neither plays for an item with no earlier look to move from, such as a starting item.
Guard, Swing Trail and Camera
Guard lends a Defense Rule Set (block, parry) to whoever holds the item (Defense). Camera Rig changes the camera while the item drives combat, on a character with the camera rig (Camera).
Swing Trail leaves a ribbon behind the swinging item. Set Trail System, then put a UPC Anim Effect Window carrying
UPC.AnimEffect.Weapon.Trail over each swing. The ribbon runs between Start Socket and End Socket on the item's mesh (TraceStart and TraceEnd by default).Details
Swing Trail
Swing Trail
Trail System
NS_MySwordTrail
Start Socket
TraceStart
End Socket
TraceEnd
Trail Seconds
0.18
Tint
Trail Tags
0 Gameplay Tags
A ribbon behind the blade while a trail window on the swing runs. Max Seconds sits under the advanced arrow.
| Setting | Does |
|---|---|
| Trail System | Niagara system, handed SweepAxis, SweepLength, TrailDuration and TrailTint when it declares them, so one ribbon fits any blade. |
| Trail Seconds | Life of each trail piece (default 0.18). |
| Tint | Color; alpha scales strength. |
| Trail Tags | Anim effect windows that run it; empty answers UPC.AnimEffect.Weapon.Trail. |
Share fragments with a preset
An Item Preset holds the fragments a family of items shares (swords that drop and hang alike).
- Right-click in the Content Browser, UPC, Items, Item Preset, and add the shared fragments.
- On each item, set Preset to it.
Details
ItemPreset_MyWeapons
Fragments
Fragments1 Array element
Fragments
1 Array element
Index [ 0 ]World Item
Index [ 0 ]
World Item
Every item pointing here inherits these fragments unless it carries one of the same kind itself.
An item uses each preset fragment of a kind it lacks, so a sword keeps its Equippable and inherits World Item.
An item's own fragment replaces the preset's of the same kind whole. A sword adding its own World Item to change the Impact Sound loses the preset's Drop Montage until it sets that too.
The item's Details panel lists what it inherits under Inherited from Preset, with Open Preset and Override Locally (copies one fragment onto the item).
Details
Item_MySword
Inherited from Preset
ItemPreset_MyWeapons
Open Preset
World Item
Override Locally
Fragments
Preset
ItemPreset_MyWeapons
Fragments
3 Array elements
Override Locally copies the preset's fragment onto the item, where it is edited on its own from then on.
Debug it
Saving an item validates it (or right-click, Asset Actions, Validate Assets); problems appear in the Message Log.
AdvancedWhat validation checks
- Two fragments of one kind on an item or preset fail (a lookup finds the first); an empty preset entry warns.
- Equippable warns on Main Weapon with no Action Graph (drawing it leaves no moves).
- Stowable warns on a mesh with no Stow Places, a Stow Actor Class that fails to load or ignores the mesh, and a Reach Overrides destination outside Hold Places.
- Swing Trail warns on no Trail System, unset or equal sockets, no Equippable, a mesh-only item missing a named socket, and no graph montage carrying a window it answers.
- Worn Mesh warns on no mesh or no Equippable.
- Container fails on a Max Stack Size above 1, no Container Tag, or a Definition that opens bags.
- An inherited Stowable or Swing Trail is checked against the item's own fragments.
AdvancedWhich fragment answers
The Details panel's read-only Combines With lists each Combine Set recipe that uses or makes the item (Combines).
A fragment's kind is its class one step below the fragment base, so a Blueprint child of Equippable counts as Equippable. Find Fragment by Class, on an Item Definition or owned item, returns the first fragment of that class or a child, the item's own before the preset's. The Equipment Manager's Find Drawn Fragment by Class asks every drawn item.
AdvancedWhat loads when
Costly references are soft: Icon, Equippable's Item Actor Class and Anim Layer Class, Visuals meshes, Stowable's stow actor, reaches and sounds, World Item's drop animation, world item class and Impact Sound, Worn Mesh's meshes, Swing Trail's system, plus whatever the Action Graph plays. They load in the background while the item sits on the belt (server and player's machine), and on every machine while it hangs on the body, is drawn or is the Default Item. A draw that comes sooner loads what it needs on the spot (
LogUPCEquipment Verbose reports it). The Drop Mesh loads when the item drops.An item only in the inventory loads nothing ahead, so a menu showing its icon loads it itself; Collect Preload Assets returns the whole list. The Inventory Grab and Place Sounds load only on the machine of the player whose inventory holds the item. Preset, Action Graph, Ability Sets to Grant, Input Mapping Context and Guard's Defense Set load with the item.
AdvancedA fragment of your own in Blueprint
Create a Blueprint child of
UPCItemFragment with variables for your data; it joins every item's Fragments dropdown and Find Fragment by Class reads it back. Characters share the fragment, so tick Blueprint Read Only on each variable (validation warns about writable ones). State for one owned item (durability) goes on the instance as stat tags. A variable in category Hide stays out of the Details panel.The demo
ItemPreset_UPC_Defaultgives the sword, the shield and the baton their World Item fragment.Item_UPC_Potionhas no Equippable; its BP_UPC_ItemFragment_UseEffect heals 40.
MultiplayerWhat runs where
Definitions and presets are assets every machine loads; nothing on them replicates. An owned item reaches only its owning player; other machines learn what a character holds through its equipment.
C++C++
UUPCItemDefinitionis aUPrimaryDataAsset(primary asset typeUPCItemDefinition).FindFragmentByClass<T>()is the typed lookup;GetEffectiveFragmentslists the item's own fragments then each preset fragment of a kind none has, the list lookup, preloading, seeding and validation walk.- A fragment subclasses
UUPCItemFragmentfor a new kind (or an existing fragment to count as that kind), withUCLASS(meta = (DisplayName = "..."))for the dropdown. OverrideOnInstanceCreated(UUPCInventoryItemInstance*)to seed stat tags,CollectPreloadAssetsfor soft references,ValidateForItem(const UUPCItemDefinition&, FDataValidationContext&)for checks needing the item. UUPCItemDefinition::IsDataValidrefuses duplicate kinds and runsValidateForItemon every fragment the item uses.
AdvancedTroubleshooting
The item shows nothing in the hand
- No Mesh and no Item Actor Class: the item is held with nothing shown.
- The Item Actor Class failed to load: it shows nothing, never the Mesh.
- The Mesh failed to load: the Output Log names the item.
- The character cannot hold it: see Equipment.
The swing trail stops early
- The window outlasts Max Seconds (Swing Trail's advanced arrow): one trail runs at most 2 seconds, so a cut-off swing still ends its trail.