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

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

Build `AG_MyFirstGraph` first, in the [Action Graph](https://rigbak.com/docs/universal-player-combat/action-graph) quick start.

## Set it up (4 minutes)

1. **Create an Item Definition**

   Create the asset: right-click in the Content Browser, choose **UPC > Items > Item Definition**, and name it **Item_MySword**.

   Set its **Slot Tags** to `UPC.Slot.Weapon.Sword`, so the demo's [belt](https://rigbak.com/docs/universal-player-combat/quick-bar), 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.

   In **Item_MySword**, under Fragments, set:

   | Property | Value |
   | --- | --- |
   | Index [ 0 ] | Visuals (replaces None) |
   | Index [ 0 ] > Mesh | SM_MySword |

   *The 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** to `AG_MyFirstGraph`; a weapon with none leaves the character no moves while drawn. Set **Input Mapping Context** to the demo's `IMC_UPC_Sword` and add one **Input Mappings** row, **Input Action** `IA_UPC_LightAttack` and **Input Tag** `UPC.Input.LightAttack`, so the left mouse button reaches the graph ([Input](https://rigbak.com/docs/universal-player-combat/input)).

   In **Item_MySword**, under Fragments, set:

   | Property | Value |
   | --- | --- |
   | Index [ 1 ] | Equippable (replaces None) |
   | Index [ 1 ] > Action Graph | AG_MyFirstGraph |
4. **Give it to the character**

   On `BP_UPC_Character`'s **InventoryComponent**, add `Item_MySword` to **Starting Items** and press Play in `LVL_UPC_Demo`: the belt puts the sword on slot 1 and draws it. A crooked sword needs a Hold Places [Offset](https://rigbak.com/docs/universal-player-combat/equipment#where-an-item-is-held-hold-places).

---

## 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](https://rigbak.com/docs/universal-player-combat/inventory#use-an-item) from the belt, never held.

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

**Category: Item**

| Property | Value |
| --- | --- |
| Max Stack Size | 1 |
| Slot Tags | UPC.Slot.Weapon.Sword |

**Category: Display**

| Property | Value |
| --- | --- |
| Display Name | Short Sword |
| Description |  |
| Icon | T_MySword_Icon |
| Inventory Grab Sound | None |
| Inventory Place Sound | None |

**Category: Fragments**

| Property | Value |
| --- | --- |
| Preset | None |
| Fragments | 3 Array elements |
| Fragments > Index [0] | Equippable |
| Fragments > Index [1] | Visuals |
| Fragments > 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](https://rigbak.com/docs/universal-player-combat/pickups-drops-holders#racks-and-shelves-item-holders) 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](https://rigbak.com/docs/universal-player-combat/items#stowable-hanging-on-the-body) Draw and Put Away Sound. |
| **Preset** | Fragments the item inherits ([Share fragments with a preset](https://rigbak.com/docs/universal-player-combat/items#share-fragments-with-a-preset)). |
| **Fragments** | What the item can do. |

---

## The fragments

Fragment Owned In hand On the body On 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](https://rigbak.com/docs/universal-player-combat/pickups-drops-holders#dropping) |
| **Worn Mesh** | [Equipment](https://rigbak.com/docs/universal-player-combat/equipment#worn-gear) |
| **Weight**, **Grid Footprint**, **Capacity Bonus** | [Containers and Rules](https://rigbak.com/docs/universal-player-combat/inventory-containers) |
| **Container** | [Bags and Banks](https://rigbak.com/docs/universal-player-combat/inventory-bags) |
| **Belt Limit** | [Quick Bar](https://rigbak.com/docs/universal-player-combat/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 panel: Equippable** (instanced object, in Item_MySword)

**Category: Equippable**

| Property | Value |
| --- | --- |
| Item Actor Class | None |
| Instance Type | None |
| Action Graph | AG_MySword |
| Ability Sets to Grant | 0 Array elements |
| Hold Places | 2 Array elements |
| Hold Places > UPC.Place.Main > Place | UPC.Place.Main (folded until clicked) |
| 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 (folded until clicked) |
| Hold Places > UPC.Place.Main > Move To Earlier Place When Free | false (folded until clicked) |
| Hold Places > UPC.Place.Off > Place | UPC.Place.Off (folded until clicked) |
| 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 (folded until clicked) |
| Hold Places > UPC.Place.Off > Move To Earlier Place When Free | true (folded until clicked) |
| Places Required | 1 |
| Main Weapon | true |
| Equipment Tags | no 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 > Seconds | 0.2 (folded until clicked, greyed out) |
| Draw Timing > Start Sound | None (folded until clicked, greyed out) |
| Draw Timing > Commit Sound | None (folded until clicked, greyed out) |
| Draw Timing > Cancel on Move | false (folded until clicked, greyed out) |
| Stow Timing > Seconds | 0.2 (folded until clicked, greyed out) |
| Stow Timing > Start Sound | None (folded until clicked, greyed out) |
| Stow Timing > Commit Sound | None (folded until clicked, greyed out) |
| Stow Timing > Cancel on Move | false (folded until clicked, greyed out) |

*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](https://rigbak.com/docs/universal-player-combat/equipment)). |
| **Action Graph** | The item's moves; the one drawn item that **drives combat** supplies the character's ([Equipment](https://rigbak.com/docs/universal-player-combat/equipment#which-item-gives-the-moves)). |
| **Ability Sets to Grant** | **Ability Sets** (abilities with an optional key, effects such as a stat bonus) granted while drawn ([Input](https://rigbak.com/docs/universal-player-combat/input#abilities-that-answer-a-key)). |
| **Hold Places**, **Places Required**, **Main Weapon** | Where it is held, in how many places, and whether its moves take over ([Equipment](https://rigbak.com/docs/universal-player-combat/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](https://rigbak.com/docs/universal-player-combat/input#inputs-an-item-brings)). |
| **Trace Sockets** | Where swings sweep from ([Melee Trace](https://rigbak.com/docs/universal-player-combat/melee-trace#hit-volumes-from-items)). |
| **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](https://rigbak.com/docs/universal-player-combat/attack-steering#where-the-stop-distance-comes-from)). |
| **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](https://rigbak.com/docs/universal-player-combat/inventory-containers#combine-sets-and-timing)). |

### 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 panel: Visuals** (instanced object, in Item_MySword)

**Category: Visuals**

| Property | Value |
| --- | --- |
| Mesh | SM_MySword |
| Override Per State | true |
| 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](https://rigbak.com/docs/universal-player-combat/equipment#show-carried-items-on-the-body)). Without it, the item vanishes while put away.

**Details panel: Stowable** (instanced object, in Item_MySword)

**Category: Stowable**

| Property | Value |
| --- | --- |
| Stow Actor Class | None |
| Stow Places | 1 Array element |
| Stow Places > UPC.Place.Back.Left > Place | UPC.Place.Back.Left |
| Stow Places > UPC.Place.Back.Left > Offset > Location | (0, 0, 0) |
| Stow Places > UPC.Place.Back.Left > Offset > Rotation | (0, 0, 0) |
| Stow Places > UPC.Place.Back.Left > Offset > Scale | (1, 1, 1) |
| Stow Places > UPC.Place.Back.Left > Draw Montage | AM_MySword_Draw |
| Stow Places > UPC.Place.Back.Left > Stow Montage | AM_MySword_Stow |
| Stow Places > UPC.Place.Back.Left > 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](https://rigbak.com/docs/universal-player-combat/defense)). **Camera Rig** changes the camera while the item drives combat, on a character with the camera rig ([Camera](https://rigbak.com/docs/universal-player-combat/camera#set-the-cameras-distance-and-framing)).

**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 panel: Swing Trail** (instanced object, in Item_MySword)

**Category: Swing Trail**

| Property | Value |
| --- | --- |
| Trail System | NS_MySwordTrail |
| Start Socket | TraceStart |
| End Socket | TraceEnd |
| Trail Seconds | 0.18 |
| Tint | R 1, G 1, B 1, A 1 (linear) |
| Trail Tags | no 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).

1. Right-click in the Content Browser, **UPC**, **Items**, **Item Preset**, and add the shared fragments.
2. On each item, set **Preset** to it.

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

**Category: Fragments**

| Property | Value |
| --- | --- |
| Fragments | 1 Array element |
| Fragments > 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.

> **Warning**
>
> 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 panel: Item_MySword** (data asset, in Content Browser)

**Category: Inherited from Preset**

| Property | Value |
| --- | --- |
| ItemPreset_MyWeapons | buttons: Open Preset |
| World Item | buttons: Override Locally |

**Category: Fragments**

| Property | Value |
| --- | --- |
| 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.

<details>
<summary>What validation checks (Advanced)</summary>

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

</details>

<details>
<summary>Which fragment answers (Advanced)</summary>

The Details panel's read-only **Combines With** lists each Combine Set recipe that uses or makes the item ([Combines](https://rigbak.com/docs/universal-player-combat/inventory-combines#recipes-the-rows-you-fill)).

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.

</details>

<details>
<summary>What loads when (Advanced)</summary>

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.

</details>

<details>
<summary>A fragment of your own in Blueprint (Advanced)</summary>

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](https://rigbak.com/docs/universal-player-combat/inventory#per-item-state-stat-tags). A variable in category `Hide` stays out of the Details panel.

</details>

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

- `ItemPreset_UPC_Default` gives the sword, the shield and the baton their World Item fragment. `Item_UPC_Potion` has no Equippable; its **BP_UPC_ItemFragment_UseEffect** heals 40.

</details>

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

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.

</details>

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

- `UUPCItemDefinition` is a `UPrimaryDataAsset` (primary asset type `UPCItemDefinition`). `FindFragmentByClass<T>()` is the typed lookup; `GetEffectiveFragments` lists 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 `UUPCItemFragment` for a new kind (or an existing fragment to count as that kind), with `UCLASS(meta = (DisplayName = "..."))` for the dropdown. Override `OnInstanceCreated(UUPCInventoryItemInstance*)` to seed stat tags, `CollectPreloadAssets` for soft references, `ValidateForItem(const UUPCItemDefinition&, FDataValidationContext&)` for checks needing the item.
- `UUPCItemDefinition::IsDataValid` refuses duplicate kinds and runs `ValidateForItem` on every fragment the item uses.

</details>

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

**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](https://rigbak.com/docs/universal-player-combat/equipment#troubleshooting).

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

</details>

---

Previous page: [Input](https://rigbak.com/docs/universal-player-combat/input). Next page: [Equipment](https://rigbak.com/docs/universal-player-combat/equipment)