How-To: Make an Item Usable

Goal: give an item a Use action that applies gameplay effects, spends the item and starts a cooldown - from the context menu, a double-click, or an action bar slot, all through one ability you grant once.

1. Register the tags

Two project tags: one gameplay event that reaches the ability, and one cooldown identity per item (or per family of items that should share a cooldown). Add them in Project Settings -> GameplayTags, or in an ini:

[/Script/GameplayTags.GameplayTagsList]
GameplayTagList=(Tag="Ability.Event.UseItem",DevComment="Activates the shared use-item ability.")
GameplayTagList=(Tag="Ability.Cooldown.Item.HealthPotion",DevComment="Cooldown identity for the health potion.")

2. Author the effect the item applies

A plain UGameplayEffect Blueprint. Leave the NUMBER off it: set the modifier's Magnitude Calculation Type to Set by Caller and give it a Data Tag, and the item supplies the value at use time. One authored heal then serves the minor, greater and supreme potions instead of three near-identical assets that drift apart the first time the heal formula changes.

3. Create the use-ability

One ability, granted to the player like any other, answers the event for every consumable in the game. Set its Ability Triggers to a Gameplay Event on Ability.Event.UseItem, its Instancing Policy to Instanced Per Execution (the ability carries which object this activation is for, so a shared instance would let two uses in the same frame overwrite each other), and its Net Execution Policy to Local Predicted. Leave the ability's own Cooldown Gameplay Effect Class unset unless you want a shared lockout across every consumable - the per-item cooldown comes from the item, not from here.

4. Add the Consumable fragment to the item

Open the item definition and add UCrimsonInventoryItemFragment_Consumable to Fragments. This is the whole integration - the item now answers ICrimsonUsableObject, and every path that offers a Use finds it.

Set the definition's ItemType too (for example Item.Type.Consumable) - the type action set in the next step is keyed on it.

5. Offer Use in the context menu

From your UI, call UCrimsonUsableStatics::SendUseEvent for the item (or your own menu's Use action). (CrimsonCore - requires all Crimson plugins) ships UCrimsonInventoryContextAction_Use as the default action of its item context menu.

The entry hides itself on items with no Consumable fragment, and on vendor stock, loot and container contents. It grays out with a reason when the player has none left or the item is still on cooldown.

Use is an OwningClient action (ExecutionPolicy on UCrimsonContextAction): picking it runs on the player's own machine and sends the item's use event there, the same path as an action bar press. That is not optional - the use ability is locally predicted, and GAS only triggers a locally predicted ability from a gameplay event where the ability system is locally controlled, so an event sent by the server for a remote client is dropped silently. The ability still re-checks CanBeUsedBy and spends through ConsumeUse under authority, so nothing is trusted client-side.

6. Put it on an action bar (optional)

An action bar resolves the bound item by identity and presses it through the same use event. (CrimsonCore - requires all Crimson plugins) supplies the action-bar resolver and presentable for inventory items. The slot draws its cooldown sweep from the effect the ability applied - the same place an ability's sweep comes from.

7. Make the cooldown respond to stats

The authored CooldownSeconds is a starting point, not the final number. What the item hands over is an FCrimsonUseCooldown (Usable/ICrimsonUsableObject.h), and its BaseSeconds is explicitly pre-modifier: the ability that answers folds in the owner's cooldown modifiers and cooldown recovery rate before it applies anything. Ask the ability for the effective number when you put one in a tooltip - never show CooldownSeconds raw.

The item also reports the tags a cooldown modifier may be keyed to, in ModifierTags, widest to narrowest:

So one modifier can shorten health potions specifically and another every consumable, with identical authoring, and the ability never has to know which item it is holding. An ability system that does not read ModifierTags simply ignores them; nothing else changes.

Where each piece runs

The item is spent before its effects are applied. If the stack emptied between activation and that moment - a second press in the same frame, another player's transfer - nothing has been handed out and the use simply does not happen.

Validation

Every way this can be misconfigured fails silently at runtime - the item applies cleanly and changes nothing - so the fragment checks itself when the item definition is saved or validated. UCrimsonInventoryItemDefinition walks its fragments to make that happen; UObject::IsDataValid does not descend into instanced subobjects on its own.

See also

• How-To: Author an Item Definition
• How-To: Add Context Actions
• API Reference
• API Reference