🎒 Lesson 7.3: An Inventory System

ItemData: An Item as an Asset

Every "Health Potion" in your game is the same thing: same icon, same name, same "heals 25" rule, same max stack of 20. That shared definition should exist once, as an asset, not be copied into every potion GameObject. This is the ScriptableObject pattern from Lesson 2.3 — data as an asset.

using UnityEngine;

[CreateAssetMenu(fileName = "New Item", menuName = "Inventory/Item")]
public class ItemData : ScriptableObject
{
    public string displayName = "New Item";
    [TextArea] public string description;
    public Sprite icon;

    [Header("Stacking")]
    public bool stackable = true;
    public int maxStack = 20;
}

The [CreateAssetMenu] attribute adds an entry to the Assets ▸ Create ▸ Inventory ▸ Item menu. Right-click in the Project window, create an ItemData, and fill in the fields in the Inspector. Make a HealthPotion, a Key (not stackable, maxStack 1), some Ammo (maxStack 99). No code per item — just assets a designer can author.

Slots: Item + Count

An inventory is a list of slots. A slot pairs an ItemData definition with how many of it you're holding. This is plain runtime data, so a small serializable class does the job:

using System;

[Serializable]
public class InventorySlot
{
    public ItemData item;   // WHICH item (the shared asset)
    public int count;       // HOW MANY (this player's runtime state)

    public InventorySlot(ItemData item, int count)
    {
        this.item = item;
        this.count = count;
    }

    public bool IsFull => item != null && count >= item.maxStack;
    public int SpaceLeft => item == null ? 0 : item.maxStack - count;
}

The [Serializable] attribute lets Unity show the slot in the Inspector and (later, in Module 5's save system) write it to disk. IsFull and SpaceLeft are convenience helpers the Add logic will lean on.

The Inventory Component

The Inventory MonoBehaviour holds the slots and exposes Add/Remove. It has a fixed number of slots (like most game inventories — a grid of, say, 20) and raises an event whenever anything changes so the UI can redraw. Here is the skeleton; we fill in Add and Remove next:

using System;
using System.Collections.Generic;
using UnityEngine;

public class Inventory : MonoBehaviour
{
    [SerializeField] int capacity = 20;                 // number of grid slots
    readonly List<InventorySlot> slots = new();

    // UI subscribes to this; Inventory never touches the UI directly
    public event Action OnInventoryChanged;

    // read-only view for the UI to render
    public IReadOnlyList<InventorySlot> Slots => slots;
    public int Capacity => capacity;

    // ... Add() and Remove() below ...
}

Notice the same decoupling principle from the whole module: Inventory exposes a read-only Slots list and an OnInventoryChanged event. It knows nothing about buttons or icons — the UI reads the data and listens for the ping.

Adding with Stacking Logic

Adding an item is the interesting part, because of stacking. If you pick up a potion and already have 3 (max 20), it should become 4 in the same slot — not open a new one. Only when existing stacks are full, or the item isn't stackable, do you take a fresh slot. And if the bag is full, the add should fail gracefully.

The algorithm, in order:

1. If the item is stackable, look for existing slots of that item with room and top them up first.
2. Whatever amount remains goes into new slots, up to maxStack each, while there's capacity.
3. Return how many we couldn't fit (0 means everything went in).
4. If anything at all changed, fire OnInventoryChanged.

public int Add(ItemData item, int amount)
{
    if (item == null || amount <= 0) return amount;
    int remaining = amount;

    // 1) Top up existing stacks of this item
    if (item.stackable)
    {
        foreach (var slot in slots)
        {
            if (slot.item != item || slot.IsFull) continue;
            int moved = Mathf.Min(slot.SpaceLeft, remaining);
            slot.count += moved;
            remaining -= moved;
            if (remaining == 0) break;
        }
    }

    // 2) Open new slots for the leftover, while we have capacity
    while (remaining > 0 && slots.Count < capacity)
    {
        int stack = item.stackable ? Mathf.Min(item.maxStack, remaining) : 1;
        slots.Add(new InventorySlot(item, stack));
        remaining -= stack;
    }

    // 4) Notify listeners if anything actually landed
    if (remaining < amount)
        OnInventoryChanged?.Invoke();

    return remaining;   // 3) leftover that didn't fit (0 = all added)
}

Returning the leftover is a small touch that matters: a pickup can check the result and only destroy itself if everything was collected, leaving a partial pile on the ground if the bag was nearly full. We use that in the next lesson's mini-project.

Here is the whole decision as a flow — trace a potion through it:

Figure 1: The add-with-stacking algorithm. Existing stacks fill first, then new slots open until capacity runs out; any leftover is returned.

Removing & the Change Event

Removing is the mirror image: subtract from stacks of that item until the requested amount is gone, and drop any slot that hits zero. Use it when a potion is consumed, ammo is spent, or an item is dropped.

public bool Remove(ItemData item, int amount)
{
    if (item == null || amount <= 0) return false;
    if (CountOf(item) < amount) return false;   // not enough — refuse

    int remaining = amount;
    // walk backwards so we can safely remove emptied slots
    for (int i = slots.Count - 1; i >= 0 && remaining > 0; i--)
    {
        if (slots[i].item != item) continue;
        int taken = Mathf.Min(slots[i].count, remaining);
        slots[i].count -= taken;
        remaining -= taken;
        if (slots[i].count == 0) slots.RemoveAt(i);
    }

    OnInventoryChanged?.Invoke();
    return true;
}

public int CountOf(ItemData item)
{
    int total = 0;
    foreach (var slot in slots)
        if (slot.item == item) total += slot.count;
    return total;
}

Two details worth noting. We iterate backwards so removing an emptied slot doesn't shuffle indices we haven't visited yet. And Remove checks CountOf first and refuses if you don't have enough — an all-or-nothing removal is far easier for callers to reason about than a partial one.

Both Add and Remove end by firing OnInventoryChanged. That single event is the entire connection between the data and the screen — exactly the event pattern from Lesson 2.2, applied to inventory.

💡 Why an event and not a direct UI call? If Inventory called inventoryUI.Refresh() itself, it would depend on the UI, couldn't exist without it, and couldn't be tested or reused headless. Firing an event flips the dependency: the UI depends on the inventory, never the other way round. Save systems, achievement trackers, and quest checkers can all listen to the same ping.

The Inventory Grid UI

The UI is a grid of slot cells. Each cell shows an item's icon and, for stacks, a count in the corner; empty cells show nothing. When OnInventoryChanged fires, the UI rebuilds its cells from inventory.Slots. Here is the grid we're aiming for, drawn as it appears in-game:

A slot-view script per cell keeps this simple — it takes an InventorySlot and paints itself:

using UnityEngine;
using UnityEngine.UI;
using TMPro;

public class SlotView : MonoBehaviour
{
    [SerializeField] Image icon;
    [SerializeField] TMP_Text countLabel;

    public void Render(InventorySlot slot)
    {
        bool has = slot != null && slot.item != null;
        icon.enabled = has;
        if (has) icon.sprite = slot.item.icon;

        // show a number only for stacks greater than 1
        bool showCount = has && slot.item.stackable && slot.count > 1;
        countLabel.enabled = showCount;
        if (showCount) countLabel.text = slot.count.ToString();
    }
}

The parent InventoryUI subscribes to OnInventoryChanged, then loops the slots calling Render on each cell — the same subscribe-in-OnEnable, unsubscribe-in-OnDisable discipline from Lesson 7.1.

Hands-on Challenge

Summary

🚀 What's Next?

You have items and a bag to hold them — but nothing to pick up yet, and no way to use what you carry. In Lesson 7.4: Pickups & Equipping (Mini-Project) we tie the whole module together: world pickups that add themselves to the inventory on touch, equipping a weapon that changes your damage output (back to Lesson 7.2!), and dropping items back into the world.