Redirect to the Docs main page.Docs

Holders NEW

Applying Character Effects When Equipping Items

Learn how to apply buffs or debuffs to your character when items are equipped in a holder.

You can apply buffs or debuffs—such as increased defense, health regeneration, or weight adjustments—when a character equips or unequips an item in a specific holder (e.g., helmet slot).

Prebuilt Support

You don’t need to modify the core logic!

Simply hook into the equip/unequip events using a custom script. The system already provides structure to check what is equipped in each holder. You only need to add your logic for effect application.

Example: Adding Weight on Equip

The script below demonstrates how to monitor a specific holder and apply an effect (e.g., increasing character weight) when an item is equipped.

using Inventory.Scripts.Core.Controllers;
using Inventory.Scripts.Core.Holders;
using Inventory.Scripts.Core.Items;
using UnityEngine;
 
namespace Inventory.Samples
{
    public class OnEquipPlayerApplyEffect : MonoBehaviour
    {
        [SerializeField] private string holderIdToListen; // Get the holder id you want to listen to
        
        private HolderData _holderData;
        private bool _isEquipped;
        private ItemTable _itemEquipped;
 
        private void Start()
        {
            _holderData = GetHolder(holderIdToListen);
        }
 
        private static HolderData GetHolder(string id)
        {
            return StaticInventoryContext.GetPlayerInventory()
                .Holders.Find(data => id.Equals(data.id));
        }
 
        private void Update()
        {
            var itemEquipped = _holderData?.GetItemEquipped();
 
            if (itemEquipped == null && _isEquipped)
            {
                _isEquipped = false;
                UnEquipItem(_itemEquipped);
                _itemEquipped = null;
                return;
            }
 
            if (_isEquipped || itemEquipped == null) return;
 
            _isEquipped = true;
            _itemEquipped = itemEquipped;
            EquipItem(_itemEquipped);
        }
 
 
        /// <summary>
        /// Sample variable used to demonstrate state change when the player equips an item (e.g., from 1 to 0).
        /// You can remove this example and replace the logic in <see cref="Update"/> with your own effect application
        /// directly on the player character and using the item to get the values.
        /// </summary>
        [Header("Sample Player Data")]
        [SerializeReference] private double sampleCharacterWeight;
 
        /// <summary>
        /// Apply the player's effect here (e.g., defense boost, speed increase, health regen, etc.).
        /// Ensure the effect application is idempotent—safe to call multiple times without causing unintended side effects.
        /// </summary>
        /// <param name="itemEquipped"></param>
        private void EquipItem(ItemTable itemEquipped)
        {
            // You can get data from the item, such as:
            // var inventoryMetadata = itemEquipped.GetMetadata<InventoryMetadata>();
            // 
            // Or for container data:
            // var containerMetadata = itemEquipped.GetMetadata<ContainerMetadata>();
            //
            // Or directly from the ItemDataSo
            var itemWeight = itemEquipped.ItemDataSo.Weight; // You can customize the properties in the ItemDataSo,
            // in order to give more power to the asset.
 
            sampleCharacterWeight += itemWeight;
        }
 
        /// <summary>
        /// Remove or revert the player's effect here (e.g., undo stat changes or buffs).
        /// </summary>
        /// <param name="itemEquipped">The item that was equipped.</param>
        private void UnEquipItem(ItemTable itemEquipped)
        {
            var itemWeight = itemEquipped.ItemDataSo.Weight;
 
            sampleCharacterWeight -= itemWeight;
        }
    }
}

🧠 Customizing the Logic

You can access metadata stored inside the ItemTable:

var inventoryMetadata = itemEquipped.GetMetadata<InventoryMetadata>();

Or read custom stats from the ItemDataSo (ScriptableObject):

var defense = itemEquipped.ItemDataSo.Defense; // You can add Defense to the ItemDataSo (so you can customize your items)

This gives you full flexibility to implement effects like:

  • Defense += X
  • MaxHealth += Y
  • Speed -= Z
  • And more...

🎯 Targeting a Specific Holder

Pass the holderId of the slot you want to monitor (e.g., "HelmetSlot") via the Inspector:

Holder ID ExampleLoading image

You can find the holderId either directly in the UI or through the PlayerInventory ScriptableObject:

Holder ID on Item Holder MonoBehaviourLoading image

Idempotency Reminder

Ensure your effect logic is idempotent—it should be safe to call multiple times without unintentionally stacking or repeating effects. While the sample script only applies effects during actual equip or unequip actions, it’s still good practice to write your logic defensively in case the method is triggered more than once under specific conditions (e.g., reinitialization, holder reloads, or manual re-equips).

Previous

Equipping Items in Player Inventory NEW

Next

Learning the Grids NEW

On this page

Prebuilt SupportExample: Adding Weight on Equip🧠 Customizing the Logic🎯 Targeting a Specific Holder