Upgrades System

For that one user that asked!

With Inventool v2, it's possible to create your own item-related systems aside from the existing ones (inventory, crafting, enchanting, shop, and storage).

In this section, we’ll walk through how to create a custom item upgrade system. The system is built around item sockets—slots embedded within items that allow other items to be inserted to enhance their power. We'll also cover how the socket data can be used to dynamically change the display name of the item.

System Analysis

Since the purpose of this tutorial is for learning, this will be a rather simple system for the sake of time. Here are the requirements for the system:

1. Items that support sockets and items that can be socketed

2. A UI window that allows the player to edit the socketed items (max 2 sockets for simplicity)

3. Applying the socket data to the item (enhancing its power & updating the name)

The name will be updated based on the prefix and suffix data taken from the socketed items.

Feasibility

There are two notable features that make developing this system possible:

1. Custom Fields: Custom fields are data you can add to items without code, are editable at runtime, and are saved along with the item itself.

2. Blocks: Blocks is the core of Inventool's UI. It's a modular system that allows you to create your own UI that works with Inventool's objects. Blocks can be something small, like a text block, or large, like an inventory block, and each block is customizable and optional.

These two features will the main focus points in this tutorial.

Prerequisites

You should have some items, item types (required by items), and stats already created if you're planning on following along in this tutorial.

Developing the System

Step 1: Socket Data

This part is pretty simple; we just need to add sockets to items. We can do this through the items tab in the Object Manager by selecting an item and adding an Item Stack field under Custom Fields.

Since sockets are essentially empty slots, we don't need to set an item reference on the fields, but you can if you want to. Setting an item reference would make the item a "default" socketed item.

This step needs to be repeated for each item that should support sockets.

Step 2: Prefix/Suffix Data

Since we want the socketed data to change the name of the item, we can add custom string fields for items that can be socketed. For example, the "Electric Gem" was given a string field called "Suffix" with the value set to " of Electricity." So, when set on an item called "Sword," combining them would give us "Sword of Electricity."

This step needs to be repeated for each item that can be socketed.

Step 3: Stats

Our socketable items need to enhance the item they're applied to. So, we need to give them stats through the Stats Manager.

This step needs to be repeated for each item that can be socketed.

Step 4: Custom Window

We need to create a custom window that can display the item and sockets. This is where the Blocks system comes in.

All blocks are available through the GameObject menu (right-click in the hierarchy, navigate to Inventool > Blocks).

Here are the steps to create this window:

1. Add a Draggable Window Block.

2. Rename the title to Upgrade.

3. Add a Text Block and Image Block as a child of the window's container object (look for a child object named Container).

4. Position the text block at the top and the image at the left-hand side.

5. Add 2 Item Slot Blocks and position them in the right-hand side (one above the other). These slots represent the sockets.

6. Optional: edit the default look of the slots (a basic circle PNG was applied for this example).

7. For each socket, add item type restrictions from the inspector (Accepted Item Types list). It's recommended to create an item type for socketable items and set the restriction to only that type.

Step 5: Coding the System

This step is the most complex, as it requires scripting. We'll be creating a script that handles both the data and UI logic of our upgrades system.

The script needs to:

• Target a specific item

• Display socketed items of the target item

• Update the socket data of the target item whenever socketed items are removed/added

• Update the name displayed based on the socketed items

Section 1: Namespaces

Start off by adding the required namespaces we will be using.

using Esper.Inventool.Blocks;
using Esper.Inventool.Blocks.UGUI;
using Esper.Inventool.Items;
using UnityEngine;

Section 2: Inherit From Draggable Window

Most blocks generally support inheritance, and is usually recommended for customization purposes.

Create a new class and inherit from the generic DraggableWindowBlock class.

✅ Inheriting from the generic windows (instead of non-generic) makes the window singleton. This is great for us because we only need one instance of it in the scene.

public class UpgradeWindow : DraggableWindowBlock<UpgradeWindow>

❌ For example, the code below would create a window that's not singleton.

public class UpgradeWindow : DraggableWindowBlock

The benefit of singleton windows is ease of access and to forcefully prevent duplicates.

✅ Singleton windows can be accessed like this:

var window = UpgradeWindow.Instance // Works!

❌ This will not work for non-singleton windows.

var window = UpgradeWindow.Instance // Results in an error!

Section 3: Reference Required Fields

Add fields that will be used to reference the required components. We need to reference the blocks we added in the previous step and an inventory block that displays the player's inventory.

You don't need to keep the same naming convention if you don't want to.

public TextBlock nameDisplay;

public ImageBlock iconDisplay;

public ItemSlotBlock socket1;

public ItemSlotBlock socket2;

public InventoryBlock playerInventory;

Each field can now be set from the inspector, which we can do later.

Also, add a fields to store the target item and names of the sockets as they are in data.

private ItemStack targetItem;

private readonly string socket1Name = "Socket 1";

private readonly string socket2Name = "Socket 2";

Section 4: On Cache

You may see errors in this step, which will be resolved later on.

For all blocks, it's recommended to override OnCache to "prepare" the object as you would in Awake or Start for general Unity components.

protected override void OnCache()
{
    base.OnCache();
}

The first thing we're going to do inside this method is set up the slots We need the slots to work with a specific inventory, which we already have a reference to. However, the InventoryBlock is not the inventory itself—it simply binds to one. So we need to ensure the InventoryBlock is bound before setting the link on the slots.

We can do this by using Schedule, a Blocks feature built around coroutines, to wait for the inventory to be bound.

Schedule(() => 
{
    socket1.slot.linkedInventory = playerInventory.BoundObject;
    socket2.slot.linkedInventory = playerInventory.BoundObject;
}).WaitUntil(() => playerInventory.IsBound);

socket1.slot.removeItemFromInventory = true;
socket2.slot.removeItemFromInventory = true;

Next, we need a way to open the window and target a specific inventory item. We can do this by customization the actionMenuOptionsGetter of the inventory block.

So, the only way we can open the window is through the ActionMenuBlock and only supported items (items with at least one socket) will have the option to open it.

playerInventory.actionMenuOptionsGetter = itemStackBlock =>
{
    var options = itemStackBlock.GetDefaultActionMenuOptions();

    if (itemStackBlock.BoundObject.HasField(socket1Name))
    {
        var upgradeOption = new ActionMenuOption<string>(() =>
        {
            Open(itemStackBlock.BoundObject);
        }, () => "Upgrade", Color.magenta);

        options.Add(upgradeOption);
    }

    return options;
};

Finally, we need to add events to the slots that will update socketed data based on the inserted items.

socket1.OnBind.AddListener(socketedItem => ItemSocketed(socket1Name, socketedItem));
socket1.OnUnbind.AddListener(unsocketedItem => ItemUnsocketed(socket1Name, unsocketedItem));
socket2.OnBind.AddListener(socketedItem => ItemSocketed(socket2Name, socketedItem));
socket2.OnUnbind.AddListener(unsocketedItem => ItemUnsocketed(socket2Name, unsocketedItem));

Section 5: Event Handlers

In the previous section, we added events, but referenced methods that don't exist yet. We're going to create them in this section.

The method will be fairly simple—they will simply update the socket data, combine or uncombine socket item stats with or from the target item, and update the display name.

private void ItemSocketed(string socketName, ItemStack socketedItem)
{
    targetItem.SetItemStack(socketName, socketedItem);

    targetItem.profile.CombineStats(socketedItem.profile.stats);

    nameDisplay.Refresh();
}

private void ItemUnsocketed(string socketName, ItemStack unsocketedItem)
{
    targetItem.SetItemStack(socketName, null);

    targetItem.profile.UncombineStats(unsocketedItem.profile.stats);

    nameDisplay.Refresh();
}

Section 6: Open Window

All windows already have an Open method, but we need one that will also set the target to a specific item.

public void Open(ItemStack targetItem)
{
    
}

First of all, we need to understand what Open should do. This method is called when the UI should be shown to the player, so it should populate all UI elements to accurately represent the data of the target item.

So, start off the method by setting the target item. The if statement is just for null safety checks (optional).

if (targetItem == null || !targetItem.item)
{
    return;
}

this.targetItem = targetItem;

Silently unbind both sockets (slots) so that any previous data isn't displayed while avoiding invoking events.

socket1.UnbindWithoutNotify();
socket2.UnbindWithoutNotify();

Call the open method. This is the method that actually enables the window.

Open();

Bind the iconDisplay field to the target item's icon (displays the icon).

iconDisplay.BindWith(() => targetItem.GetIcon());

At this stage, the sockets need to reflect the current socket state of the target item. To do this, we simply retrieve the socket data and bind it to each slot—without invoking binding events, since those would trigger data updates that aren’t needed when the UI first opens.

Additionally, if the target item does not include a particular socket, that slot should be disabled so it isn’t displayed.

if (targetItem.TryGetValue(socket1Name, out ItemStack socketedItem1))
{
    socket1.gameObject.SetActive(true);
    socket1.BindWithoutNotify(socketedItem1);
}
else
{
    socket1.gameObject.SetActive(false);
}

if (targetItem.TryGetValue(socket2Name, out ItemStack socketedItem2))
{
    socket2.gameObject.SetActive(true);
    socket2.BindWithoutNotify(socketedItem2);
}
else
{
    socket2.gameObject.SetActive(false);
}

Finally, to allow the display name to update dynamically based on socketed items, we bind the name display block using custom logic. This logic extracts the prefix and suffix from the socketed items and combines them with the base name of the target item.

nameDisplay.BindWith(() => 
{
    var prefix = socket1.IsBound ? socket1.BoundObject.GetString("Prefix") : string.Empty;
    var suffix = socket2.IsBound ? socket2.BoundObject.GetString("Suffix") : string.Empty;

    return prefix + targetItem.DisplayName + suffix;
});

That's all! See Complete Script for the full script.

Step 6: Replace Original Draggable Window Script

Click on the Draggable Window Block we added in Step 4: Custom Window remove the Draggable Window Block component, and add the Upgrade Window component.

Also, set all its required properties through the inspector. Note: Content must be the first child object of the window.

Complete Script

using Esper.Inventool.Blocks;
using Esper.Inventool.Blocks.UGUI;
using Esper.Inventool.Items;
using UnityEngine;

/// <summary>
/// A custom singleton window that allows the player to upgrade supported items. This example only supports 2 sockets.
/// </summary>
public class UpgradeWindow : DraggableWindowBlock<UpgradeWindow>
{
    /// <summary>
    /// A block that displays the target item's name.
    /// </summary>
    public TextBlock nameDisplay;

    /// <summary>
    /// A block that displays the target item's icon.
    /// </summary>
    public ImageBlock iconDisplay;

    /// <summary>
    /// The first socket.
    /// </summary>
    public ItemSlotBlock socket1;

    /// <summary>
    /// The second socket.
    /// </summary>
    public ItemSlotBlock socket2;

    /// <summary>
    /// The inventory to link the slots with.
    /// </summary>
    public InventoryBlock playerInventory;

    /// <summary>
    /// The targetted item.
    /// </summary>
    private ItemStack targetItem;

     /// <summary>
    /// The name of the first socket in data.
    /// </summary>
    private readonly string socket1Name = "Socket 1";

    /// <summary>
    /// The name of the second socket in data.
    /// </summary>
    private readonly string socket2Name = "Socket 2";

    protected override void OnCache()
    {
        base.OnCache();

        Schedule(() => 
        {
            // Set inventory link
            socket1.slot.linkedInventory = playerInventory.BoundObject;
            socket2.slot.linkedInventory = playerInventory.BoundObject;
        }).WaitUntil(() => playerInventory.IsBound); // Wait until the inventory is bound for this task

        // Sockets combine items, so they should be remove the item from the inventory
        socket1.slot.removeItemFromInventory = true;
        socket2.slot.removeItemFromInventory = true;

        // Customize action menu for each item stack instance in the inventory
        playerInventory.actionMenuOptionsGetter = itemStackBlock =>
        {
            // Get the default options
            var options = itemStackBlock.GetDefaultActionMenuOptions();

            // Add an option that will open this window for the item stack (only for items with sockets)
            if (itemStackBlock.BoundObject.HasField(socket1Name))
            {
                // Create the option and add it
                var upgradeOption = new ActionMenuOption<string>(() =>
                {
                    Open(itemStackBlock.BoundObject);
                }, () => "Upgrade", Color.magenta);

                options.Add(upgradeOption);
            }

            return options;
        };

        // Add events that will update the socket fields of the item stack
        socket1.OnBind.AddListener(socketedItem => ItemSocketed(socket1Name, socketedItem));
        socket1.OnUnbind.AddListener(unsocketedItem => ItemUnsocketed(socket1Name, unsocketedItem));
        socket2.OnBind.AddListener(socketedItem => ItemSocketed(socket2Name, socketedItem));
        socket2.OnUnbind.AddListener(unsocketedItem => ItemUnsocketed(socket2Name, unsocketedItem));
    }

    /// <summary>
    /// Updates the socket data of the targeted item by setting a new socketed item.
    /// </summary>
    /// <param name="socketName">The name of the socket.</param>
    /// <param name="socketedItem">The item that was socketed.</param>
    private void ItemSocketed(string socketName, ItemStack socketedItem)
    {
        // Update the socket data on the item
        // Note: even if the item doesn't have enough or any sockets, SetField is safe as it simply does nothing if the
        // specified field doesn't exist
        targetItem.SetItemStack(socketName, socketedItem);

        // Combine stats
        targetItem.profile.CombineStats(socketedItem.profile.stats);

        // Refresh the name display block since so that it reflects the new socketed items
        nameDisplay.Refresh();
    }

    /// <summary>
    /// Updates the socket data of the targeted item by setting a new socketed item.
    /// </summary>
    /// <param name="socketName">The name of the socket.</param>
    /// <param name="unsocketedItem">The item that was socketed.</param>
    private void ItemUnsocketed(string socketName, ItemStack unsocketedItem)
    {
        // Set to null since the item was removed
        targetItem.SetItemStack(socketName, null);

        // Uncombine stats this time since it's been removed
        targetItem.profile.UncombineStats(unsocketedItem.profile.stats);

        nameDisplay.Refresh();
    }

    /// <summary>
    /// Opens the window and targets an item.
    /// </summary>
    /// <param name="targetItem">The item to target.</param>
    public void Open(ItemStack targetItem)
    {
        // Do nothing if target is null (for safety)
        if (targetItem == null || !targetItem.item)
        {
            return;
        }

        this.targetItem = targetItem;

        // Silently unbind sockets to ensure previous socketed items aren't accidentally displayed while avoiding invoking events
        socket1.UnbindWithoutNotify();
        socket2.UnbindWithoutNotify();

        // Call base open method (this actually enables the window)
        Open();

        // Display the item icon
        iconDisplay.BindWith(() => targetItem.GetIcon());

        // Get the current socketed items
        if (targetItem.TryGetValue(socket1Name, out ItemStack socketedItem1))
        {
            // Enable the socket and silently set the item on the socket (avoid invoking any binding events at this point)
            socket1.gameObject.SetActive(true);
            socket1.BindWithoutNotify(socketedItem1);
        }
        else
        {
            // Code reaching here means that the targeted item does not support the first socket, therefore, disable it
            socket1.gameObject.SetActive(false);
        }

        // Same thing for second socket
        if (targetItem.TryGetValue(socket2Name, out ItemStack socketedItem2))
        {
            socket2.gameObject.SetActive(true);
            socket2.BindWithoutNotify(socketedItem2);
        }
        else
        {
            socket2.gameObject.SetActive(false);
        }

        // Dynamic name example: take the custom prefix/suffix from the socketed items (exclude disabled/no socket set)
        // Note: this example doesn't support localization
        nameDisplay.BindWith(() => 
        {
            // Prefix will come from socketed item 1 and suffix from socketed item 2
            var prefix = socket1.IsBound ? socket1.BoundObject.GetString("Prefix") : string.Empty;
            var suffix = socket2.IsBound ? socket2.BoundObject.GetString("Suffix") : string.Empty;

            // Combine with regular name
            return prefix + targetItem.DisplayName + suffix;
        });

        // Since the targeted item data is updated through events, the Blocks system can handle the rest
    }
}

Final Result

See this system in action!