Understanding Holders in UGI

Holders are a fundamental component in Ultimate Grid Inventory that manage the equipping, displaying, and interaction with items. They serve as the bridge between your game's items and their visual representation in the UI or game world.

Why Use Holders?

Holders serve several important purposes in your inventory system:

• Equipment Management: Display equipped items (weapons, armor, accessories)
• Container Access: Provide access to container items like backpacks or chests
• Item Filtering: Restrict slots to only accept specific item types
• Visual Customization: Show equipped items with custom visuals
• Gameplay Integration: Connect inventory items to character stats and abilities
• World Interaction: Allow players to interact with items in the game environment

Holder Hierarchy

Ultimate Grid Inventory provides a flexible hierarchy of holder types to handle different scenarios:

1. Holder (Base Class): Provides core functionality for equipping and unequipping items
   • ItemHolder: UI-based holder for displaying equipped items with visual representation
     • ContainerHolder: Specialized holder for container items that can display their contents
     • ReplicatorItemHolder: Mirrors items from another holder for display in multiple UI locations
   • EnvironmentItemHolder: Represents items in the game world that can be picked up
   • EnvironmentContainerHolder: Interactive containers in the game world (chests, lockers, etc.)

The Holder Base Class

All holder types in UGI inherit from the Holder base class, which provides the core functionality for managing equipped items. Understanding this base class is essential for working with any holder type.

Key Methods in the Holder Base Class

• TryEquipItem: Attempts to equip an item, checking if the holder is already equipped
• Equip: Directly equips an item or a HolderData object
• UnEquip: Unequips the current item
• PickUp: Picks up the current item without triggering the OnUnEquip event
• IsEquipped: Checks if the holder has an equipped item
• GetItemEquipped: Returns the currently equipped item
• GetHolderData: Returns the holder's data object

Holder Events

The Holder class provides two key events that you can use to respond to item changes:

• OnEquipItem: Called when an item is equipped in the holder
• OnUnEquipItem: Called when an item is unequipped from the holder

These events are virtual methods that derived classes can override to add custom behavior.

UI Holders

UI Holders are used to display items in your game's user interface, such as equipment slots, inventory slots, and hotbars.

Creating Item Holders

Let's start by creating basic item holders for equipment like helmets or weapons.

Step 1: Create an Item Holder

1. In your UI scene, navigate to Ultimate Grid Inventory > Item Holder in the menu

Item Holder Menu OptionLoading image

2. This creates a new Item Holder GameObject in your scene hierarchy

Step 2: Position and Style the Holder

1. Move the Item Holder to your desired position in the UI
2. Adjust the size and appearance of the holder:
   • Modify the RectTransform component for size and position
   • Customize the Image component to change the holder's appearance
   • Add visual elements like borders or labels to indicate the holder's purpose

Step 3: Configure the Item Holder Component

The most important step is configuring what type of items this holder can accept:

1. Select your Item Holder GameObject
2. In the Inspector, find the Item Holder component
3. Set the Item Data Type SO field to the appropriate item type:
   • Create a new Item Data Type SO if needed via Create > Inventory > Items > New Item Data Type
   • For example, create a "Helmet" type for a helmet slot or "Weapon" type for a weapon slot

Helmet Item Holder ConfigurationLoading image

4. Configure additional settings:
   • On Item Equipped: Event triggered when an item is placed in this holder
   • On Item Unequipped: Event triggered when an item is removed
   • Can Drop Item: Whether players can drag items out of this holder

Step 4: Create Additional Item Holders

Repeat the process to create all the equipment slots your game needs:

1. Helmet/Head slot
2. Armor/Chest slot
3. Weapon slots
4. Accessory slots
5. Consumable quick-access slots

Each holder should have its own Item Data Type SO to ensure only appropriate items can be equipped.

Creating Container Holders

Container Holders are special slots that can hold items like backpacks, chests, or pouches. When a container item is equipped in these holders, the container's contents become accessible.

Step 1: Create a Container Holder

1. Navigate to Ultimate Grid Inventory > Container Holder in the menu
2. This creates a new Container Holder GameObject in your scene

Step 2: Position and Style the Container Holder

Follow the same positioning and styling steps as with regular Item Holders.

Step 3: Configure the Container Holder Component

1. Select your Container Holder GameObject
2. In the Inspector, find the Container Holder component
3. Set the Item Data Type SO to a container type (e.g., "Backpack")
4. Configure the Container Holder Settings:

Container Holder ConfigurationLoading image

The key settings include:

• Container Display Anchor SO: Links this holder to a Container Display where contents will be shown
• Auto Open When Equipped: Automatically opens the container when an item is equipped
• Auto Close When Unequipped: Automatically closes the container when the item is removed

Step 4: Link to a Container Display

For the Container Holder to work properly, you need to connect it to a Container Display:

1. Create a Container Display as described in Creating Container Displays
2. Create a Container Display Anchor SO
3. Assign this anchor to both:
   • The Container Display component
   • The Container Holder's "Container Display Anchor SO" field

This connection ensures that when a container item (like a backpack) is equipped in the Container Holder, its contents will appear in the linked Container Display.

Testing Your Holders

To test your holders:

1. Enter Play mode
2. Create test items with the appropriate Item Data Types
3. Try dragging items to their corresponding holders
4. Verify that:
   • Items can only be placed in holders of the correct type
   • Container items open their inventory when equipped
   • Any OnEquipped/OnUnequipped events fire correctly

Creating Replicator Item Holders

The ReplicatorItemHolder is a specialized UI holder that mirrors items from another holder. This is useful for displaying the same item in multiple UI locations, such as showing equipped weapons in both an equipment panel and a character preview.

Step 1: Create a Replicator Item Holder

1. Create a regular Item Holder as described above
2. Replace the ItemHolder component with a ReplicatorItemHolder component:
   • Remove the ItemHolder component
   • Add Component > Inventory > Holders > Replicator Item Holder

Step 2: Configure the Replication

1. Set the Item Data Type SO to match the type of items you want to replicate
2. Configure the Replication Uid:
   • This should match the UniqueUid of the holder you want to replicate
   • When an item is equipped in the original holder, it will automatically appear in the replicator

Environment Holders

Environment Holders are used to represent items and containers in your game world, allowing players to interact with them.

Creating Environment Item Holders

The EnvironmentItemHolder represents items in the game world that players can pick up.

Step 1: Create an Environment Item Holder

1. Add the EnvironmentItemHolder component to any GameObject in your scene:
   • Select the GameObject
   • Add Component > Inventory > Environment > Environment Item Holder

Step 2: Configure the Environment Item Holder

1. Set the Unique Uid to a unique identifier for this holder
2. To set the item programmatically:

   // Get a reference to the holder
   var environmentItemHolder = GetComponent<EnvironmentItemHolder>();
    
   // Create an item table from an item data scriptable object
   var itemTable = StaticInventoryContext.CreateItemTable(itemDataSo);
    
   // Equip the item in the holder
   environmentItemHolder.Equip(itemTable);

Creating Environment Container Holders

The EnvironmentContainerHolder represents interactive containers in the game world (like chests, barrels, or lockers) that players can open to access their contents.

Step 1: Create an Environment Container Holder

1. Add the EnvironmentContainerHolder component to any GameObject in your scene:
   • Select the GameObject
   • Add Component > Inventory > Environment > Environment Container Holder

Step 2: Configure the Environment Container Holder

1. Set the Unique Uid to a unique identifier for this container
2. Set the Item Container Data SO to the container item you want to use
3. Set the Inventory Display Anchor SO to the anchor that will display the container's contents
4. Optionally, set the Attached Inventory SO to save the container's contents

Step 3: Implement Interaction

To allow players to interact with the container:

// Get a reference to the container holder
var containerHolder = GetComponent<EnvironmentContainerHolder>();
 
// Open the container when the player interacts with it
public void OnPlayerInteract()
{
    containerHolder.ToggleEnvironmentContainer();
}

Programmatic Interaction with Holders

You can interact with holders programmatically using the InventorySupplierSo:

// Reference to the inventory supplier
[SerializeField] private InventorySupplierSo inventorySupplierSo;
 
// Reference to a holder
[SerializeField] private Holder holder;
 
// Equip an item in a holder
public void EquipItemInHolder(ItemDataSo itemDataSo)
{
    inventorySupplierSo.EquipItem(itemDataSo, holder);
}
 
// Unequip an item from a holder
public void UnequipItemFromHolder()
{
    var itemTable = holder.UnEquip();
 
    // Do something with the unequipped item
    if (itemTable != null)
    {
        Debug.Log($"Unequipped {itemTable.ItemDataSo.DisplayName}");
    }
}

Saving and Loading Holder States

To save and load the state of holders (what items are equipped), you can use the InventorySo class. For a comprehensive guide to the save system, see the Save System documentation:

// Reference to the inventory
[SerializeField] private InventorySo inventorySo;
 
// Save the inventory state
public void SaveInventory()
{
    inventorySo.Save();
}
 
// Load the inventory state
public void LoadInventory()
{
    inventorySo.Load();
}

For environment containers, you can attach them to an InventorySo to automatically save and load their contents:

// Reference to the inventory
[SerializeField] private InventorySo environmentContainersSo;
 
// Reference to the environment container holder
[SerializeField] private EnvironmentContainerHolder containerHolder;
 
// Add the container to the inventory for saving/loading
private void Start()
{
    environmentContainersSo.AddHolder(containerHolder.GetHolderData());
}
 
// Remove the container when destroyed
private void OnDestroy()
{
    environmentContainersSo.RemoveHolder(containerHolder.GetHolderData());
}

Next Steps

After setting up your holders, you can:

• Create items with the appropriate Item Data Types
• Set up container items to use with your Container Holders
• Configure Container Displays to show container contents
• Add visual feedback when items are dragged over holders
• Implement scripting hooks to connect equipped items to gameplay systems
• Create environment containers for interactive world objects
• Set up a save system to persist inventory state between game sessions

With properly configured holders, your inventory system will provide players with an intuitive way to manage their equipment and access container items, both in the UI and in the game world.