How to Add a Usable Item

This guide explains how to add a new usable item (consumable) to the RPG Engine v6 inventory system using ItemsAssistant and the BP_UsableClarData_Master clarification asset. Usable items are one‑shot effects that immediately modify player stats (Health, Stamina, Hunger, Thirst), can play sounds and animations, and may cancel specific CharacterStates.

---

Prerequisites

Before you start, make sure that:

• The inventory and equipment system is set up and working in your project (BPEquipmentComponent, DT_ItemData, main inventory UI).
  
• ItemsAssistant is available and configured in the editor.
  
• You have:
  • A name, description, and icon for the new usable item.
    
  • A clear idea of what the item should do (which stat to change and by how much).
    
  • Optionally a static mesh, use sound, and an AnimMontage for the use animation.

---

Step 1 – Create the Usable Item in ItemsAssistant

Usable items are regular inventory items with type World.Items.Types.Usable created through ItemsAssistant.

1. Open ItemsAssistant in the editor.

2. Create a new item:

   • Use your standard flow in ItemsAssistant to add a new item entry.

3. Fill the General Data block:

   • Name – display name of the item, e.g. Water Bottle or Painkillers.
     
   • Short Name – compact name for inventory cells, e.g. Water or Pills.
     
   • Description – short description of what the item does.
     
   • Abbreviation – very short code used in debug and naming, e.g. WTR, PILL.
     
   • Weight – cosmetic/statistical weight.
     
   • Price – price used by the trading system.
     
   • Rarity – rarity tier used for UI and loot balancing.
     
   • Type – set to World.Items.Types.Usable.

4. Fill the Inventory block:

   • Size – grid size in cells, e.g. 1x1.
     
   • MaximumNumberInSlot – max stack size in one cell, e.g. 4, 10, 20.
     
   • InventoryTexture – icon texture (or leave for your icon generator, depending on the pipeline).
     
   • Any other standard inventory parameters you use for items.

5. Click Generate.

After generation, ItemsAssistant will:

• Add a new row for this item to DT_ItemData.
  
• Create a BP_ItemData asset for the item.
  
• Create a Clarification DataAsset of class BP_UsableClarData_Master.
  
• Optionally create or update a world Interact Actor for this item, depending on your project setup.

From this point, all runtime use behavior is configured in the generated BP_UsableClarData_Master asset.

---

Step 2 – Locate the BP_UsableClarData_Master Asset

1. In the Content Browser, navigate to the folder where ItemsAssistant places item clarification assets.
   
2. Find the clarification asset for your new usable item:
   • The name usually follows your project’s naming convention, e.g. DA_Usable_WaterBottle, DA_Usable_Pills.
     
   • The asset class must be BP_UsableClarData_Master.
     
3. Open this asset in the editor.

---

Step 3 – Configure Visuals (Static Mesh)

In BP_UsableClarData_Master, configure the world visual:

• Static Mesh
  • Assign a static mesh used by the world Interact Actor and for any world representation of the usable item.
    
  • This mesh is typically what the player sees when the item is dropped on the ground or spawned as a pickup.

You can leave Static Mesh empty if your project uses a different visual pipeline, but in most cases assigning a mesh is recommended so world pickups look correct.

---

Step 4 – Configure StatAffects (Core Usable Logic)

The StatAffects array is the core of a usable item: it defines what happens to the player’s stats when the item is used.

Each element is an S_StatAffects struct with the following fields:

• Affected Stat – enum E_StatType.
  For usable items, you can only modify these stats:
  • Health
    
  • Stamina
    
  • Hunger
    
  • Thirst
• What to Do – enum E_StatAction:
  • Add – add the specified value to the current stat.
    
  • Multiply – multiply the current stat value by the specified value.
• Value – float value used by the selected action.

At runtime, all entries in StatAffects are applied once when the item is used. There is no duration, stacking, or buff lifetime management for usable items – they are simple one‑shot effects.

Example: Simple Medkit

A medkit that restores 25 Health:

• StatAffects[0]:
  • Affected Stat = Health
    
  • What to Do = Add
    
  • Value = 25.0

When the item is used, the system adds 25 to the player’s Health stat.

Example: Food that Reduces Hunger and Restores Stamina

Food that reduces Hunger by 30 and adds 15 Stamina:

• StatAffects[0]:
  • Affected Stat = Hunger
    
  • What to Do = Add
    
  • Value = -30.0 (negative value reduces hunger)
    
• StatAffects[1]:
  • Affected Stat = Stamina
    
  • What to Do = Add
    
  • Value = 15.0

Example: Multiplicative Stamina Boost

Energy drink that multiplies current Stamina by 1.5:

• StatAffects[0]:
  • Affected Stat = Stamina
    
  • What to Do = Multiply
    
  • Value = 1.5

Use Multiply carefully, because it scales with the current stat value and can grow very strong.

---

Step 5 – Configure Use Sound

The Use Sound parameter controls the audio that plays when the item is used.

1. In BP_UsableClarData_Master, find Use Sound.
   
2. Assign a SoundBase asset appropriate for the item:
   • Drink: water/juice sip sound.
     
   • Pills: pill bottle or swallow sound.
     
   • Food: eating/bite sound.

If you leave Use Sound empty, the item will work without a dedicated use sound. This can be acceptable for placeholder or very simple items, but final designs should usually have some feedback.

---

Step 6 – Configure AnimMontage (Optional)

The AnimMontage parameter defines an animation montage that plays when the item is used.

1. In BP_UsableClarData_Master, find AnimMontage.
   
2. Assign an AnimMontage that is valid for the player character, for example:
   • AM_Use_WaterBottle – drinking animation.
     
   • AM_Use_Pills – pills/medicine animation.

If AnimMontage is not set:

• The item will still apply its StatAffects and play the Use Sound (if configured).
  
• No dedicated use animation will be triggered.

This field is optional but recommended for polished items.

---

Step 7 – Configure DeactivateStates (Optional)

The DeactivateStates parameter allows a usable item to cancel specific CharacterStates when it is used. This is useful for items that cure negative effects.

1. In BP_UsableClarData_Master, locate DeactivateStates (Gameplay Tag or array of tags, depending on your project setup).
   
2. Add one or more CharacterState Gameplay Tags that should be deactivated when the item is used.

Example: Pills that Cure Water Poisoning

For a pill item that removes water poisoning:

• Set DeactivateStates to include:
  • CharacterStates.Effects.PoisonByWater

When the player uses these pills:

• StatAffects are applied (e.g. health restoration).
  
• The CharacterStates.Effects.PoisonByWater state is deactivated, removing the poison effect.

If you do not need to cancel any states (e.g. pure food or water), you can leave DeactivateStates empty.

---

Step 8 – Verify ItemData and Interact Actor

Before testing in game, quickly verify the data connections in your item setup.

1. BP_ItemData:
   • Open the BP_ItemData asset for your usable item.
     
   • Confirm that:
     • The Type is World.Items.Types.Usable.
       
     • The Clarification / Additional Info field references your BP_UsableClarData_Master asset.
2. DT_ItemData row:
   • Open DT_ItemData and locate the row for your item.
     
   • Confirm that:
     • GeneralData (Name, Short Name, Description, Abbreviation, Type, Rarity, Price, Weight) matches your configuration.
       
     • The row points to the correct BP_ItemData asset.
3. World Interact Actor (if used in your project):
   • Open the Interact Actor class used for this usable item.
     
   • Make sure that:
     • Its ItemData / General Data points to your BP_ItemData.
       
     • The visual mesh matches the Static Mesh you expect.

This ensures that the item can exist in the world, be picked up, and show correct metadata in the inventory.

---

Step 9 – Test the Usable Item In‑Game

1. Launch a test session (PIE or Standalone).
   
2. Give the item to the player:
   • Via debug command, a test vendor, starting inventory, or a placed world pickup.
     
3. Open the inventory UI and locate your usable item.
   
4. Use the item:
   • Trigger the Use action (e.g. right‑click → Use or equivalent input).
5. Verify behavior:
   • Stat changes:
     • Health, Stamina, Hunger, Thirst change according to StatAffects.
       
   • Sound:
     • The Use Sound plays when the item is used (if configured).
       
   • Animation:
     • The AnimMontage runs on the character, if set and compatible.
       
   • State cancellation:
     • Any CharacterStates listed in DeactivateStates are deactivated.
       
   • Inventory:
     • The item’s stack is reduced or removed according to your stack logic (MaximumNumberInSlot and general item use rules).

If the item does not behave as expected:

• Recheck BP_UsableClarData_Master (StatAffects, Use Sound, AnimMontage, DeactivateStates).
  
• Confirm that:
  • The DT_ItemData row uses Type = World.Items.Types.Usable.
    
  • BP_ItemData correctly references the clarification asset.
    
  • StatAffects only use Health, Stamina, Hunger, or Thirst as Affected Stat.

---

Summary Checklist

Use this checklist to verify that your usable item is fully configured:

• ItemsAssistant:
  • New item created with Type = World.Items.Types.Usable.
    
  • General Data and Inventory blocks filled.
    
  • Generate pressed; DT_ItemData row and BP_ItemData created.
• Clarification (BP_UsableClarData_Master):
  • Static Mesh assigned (or intentionally left empty).
    
  • StatAffects contains one or more entries:
    • Affected Stat is Health, Stamina, Hunger, or Thirst.
      
    • What to Do is Add or Multiply.
      
    • Value is a reasonable float.
      
  • Use Sound assigned (optional, but recommended).
    
  • AnimMontage assigned (optional) and valid for the player character.
    
  • DeactivateStates contains any CharacterStates to cancel on use (optional).
• Integration:
  • BP_ItemData references BP_UsableClarData_Master.
    
  • DT_ItemData row is correct and uses World.Items.Types.Usable.
    
  • World Interact Actor (if used) references the BP_ItemData and displays the correct mesh.
• Runtime:
  • Item appears in inventory and can be used.
    
  • Stat changes are applied correctly.
    
  • Sound and animation play when configured.
    
  • CharacterStates from DeactivateStates are removed on use.