Item Stack

The item stack is the runtime object that represents item(s). Each stack may contain multiple items, hence its name.

Definitions

Each item stack has an item definition, which represents the type of item stored in the stack.

Capacity

Item stacks can hold item counts up to their capacity. An item stack's capacity is determined by the slot containing it. Slots may define capacity as a multiplier of default capacity (e.g., a default capacity of 100 and a multiplier of 2 yields a slot capacity of 200), or a constant value. Item stacks are also capped by their item definition's Max Capacity, which takes precedence over slots:

Slot Capacity	Max Capacity	Final Capacity
100	200	100
200	100	100

Interfaces

Equippable

Items implementing IBLEquippable can be deposited into Equipment Inventories. They will be asked whether they can be Equipped or Unequipped, and will receive notifies when those occur.

Equip and Unequip will only be received on servers.

Socketable

Items implementing IBLSocketable can be deposited into Socket Inventories. They will be asked whether they can be Socketed or Unsocketed, and will receive notifies when those occur.

Socket and Unsocket will only be received on servers.

Usable

Items implementing IBLUsable can be used. What this means depends on the item, but the most common usage is to activate an ability on the inventory's owner. Inventories have an Use Item In Slot function for using items directly inside inventories.

Runtime Data

Item stacks can store runtime data for items.

Splitting and Merging

When not all items are withdrawn from an item stack, it must be split into two item stack objects. Conversely, when items are deposited from one stack into another existing stack, one of the two objects must be destroyed because it was emptied; this is called merging. Bolt provides the PostStackSplit and PreStackMerge functions to update data whenever item stacks are split or merged.

For example, suppose you have a food item that decays over time - you store its decay amount with a DecayPercent variable. When you split or merge items of this type, you want the highest DecayPercent to be kept - after all, a few bad apples spoil the bunch.

Blueprint

C++

void UDecayableItem::PostStackSplit(UBLItemStack& FromStack)
{
    // FromStack is guaranteed to be the same class so we may use 'CastChecked'.
    UDecayableItem* FromDecayableItem = CastChecked<UDecayableItem>(&FromStack);
    SetDecayPercent(FromDecayableItem->GetDecayPercent());
    // Alternatively, if DecayPercent is a UPROPERTY, it will automatically be copied during duplication.

    // ...
}

void UDecayableItem::PreStackMerge(const UBLItemStack& FromStack, int32 CountToDeposit)
{
    const UDecayableItem* FromDecayableItem = CastChecked<UDecayableItem>(&FromStack);
    SetDecayPercent(FMath::Max(DecayPercent, FromDecayableItem->GetDecayPercent()));

    // ...
}

Extensions

Extensions are functions that you may override to extend the item stack's behavior. These functions have no functionality by default, so you may freely override them without side-effects.

Can Destroy

Check whether items can be destroyed.

Can Combine

Check whether two item stacks can be combined.

Can Drop Items

Check whether items can be dropped (as an actor) from this item stack.

Post Spawn

Called after items are spawned for the first time (from SpawnItemStack).

Post Gameplay Load

Called after items are loaded from a save file.

Post Item Duplicate

Called after items are duplicated from DuplicateItemStack, including when the item stack is split.

Post Stack Split

Called after an item stack is split into two objects. Useful for fixing up item stack data.

Pre Stack Merge

Called before two item stacks are merged into one object. Useful for fixing up item stack data.

Pre Item Destroy

Called before the item stack is destroyed.

caution

This will only be called when the item stack is explicitly destroyed. It won't be called if you spawn an item stack but don't keep a reference to it, causing it to be garbage collected.

Post Withdraw From Inventory

Called after an item stack is withdrawn from an inventory.

Post Deposit To Inventory

Called after an item stack is deposited into an inventory.

Pre Destroy In Inventory

Called before an item stack is destroyed while inside an inventory.