Inventory — the system everyone builds twice
Almost nobody gets an inventory right the first time, and the reason is always the same: they start from the grid of squares on screen. The squares are the last thing you should build. Start there and the item data ends up living inside UI nodes, and then saving the game means reading labels off buttons.
Start from the other end — what is an item, really? — and the UI becomes a thin thing that draws whatever the data says. Saving becomes almost free. Two different UIs (a hotbar and a chest window) become two views of one list rather than two copies of the logic.
The one distinction that decides everything#
A sword and your sword are different objects.
- A sword — name, icon, max stack size, damage, description. Identical for every sword in the game. Authored once, never changes at runtime. This is a definition.
- Your sword — sitting in slot 4, 12 durability left, enchanted. Yours alone, changes constantly, must be saved. This is runtime state.
Collapse these two into one object and you get the classic bug: the player drinks one health potion and every health potion in the world reports being half-empty. That isn't a hypothetical — it's what happens when you edit a shared resource at runtime, and Godot's resource cache makes it easy to do by accident. Part 01 covers exactly how and why.
What this shelf teaches#
| Part | You build | The idea |
|---|---|---|
| 01 | ItemData as a custom Resource, authored as .tres files | Adding an item becomes a file, not code |
| 02 | An Inventory that holds stacks, adds, removes, and emits changed | The truth lives in data, not nodes |
| 03 | A grid UI that redraws from the data and knows nothing about game rules | UI observes; it never owns |
By the end you have an inventory that survives being saved, being displayed twice at once, and being reasoned about at 2am.
Design decisions this shelf makes explicit#
There is no universal correct inventory. Three choices genuinely fork, and each part flags its own where it arises:
Slots or a bag? A fixed array of N slots (Minecraft — position matters, gaps exist, you can sort) versus a dictionary of item → count (Stardew's early game, most RPG "key items" — no positions, no gaps, no sorting). Slots are more code and more capability. Choose by whether players will ever arrange things.
Stacks or instances? If 99 identical potions are one entry with a count, stacking is trivial and per-item state is impossible. If each potion is its own object, durability and enchantments work but a full bag is 99 objects. Games usually need both, split by item type.
Who enforces the rules? Can the inventory refuse an item? Does it know about weight limits, quest items, equipment slots? Every rule you put inside it is a rule the UI can't get wrong — and a rule you can't change without touching the core.
This shelf builds slots + stacking + rules-inside, because that combination is the most common and the most instructive. Where your game wants something else, the parts say which line to change.
Prerequisites#
Custom Resource subclasses and @export are the backbone here — if
Resources are new
to you, read that page first. Part 03 needs Control nodes and containers. The
typed GDScript rules apply throughout; an untyped
inventory is a runtime crash waiting for a bad key.
Where this shows up in the projects#
The farming game builds the minimum viable
version of part 02 in stage 06 — a counting inventory with a changed signal, no UI. This
shelf is the full treatment, and reading part 01 before that stage makes the definition/state
split land properly instead of feeling like ceremony.