Godot Inventory System

A slot-based inventory for Godot 4 with stacking, drag and drop, item tooltips, using items, and save data. The data and the UI are separate, so you can keep the logic and restyle the window.

Features

• Item resources. One .tres file per item, with a name, icon, description, stack limit, rarity, value, type and optional equipment stats.
• Stacking. Items stack up to their max_stack, then spill into the next free slot. Non-stackable gear takes one slot each.
• Overflow reporting. add_item() returns how many did not fit, so you can leave the rest on the ground or show "bag full".
• Drag and drop with Godot's built-in GUI drag system: drop on an empty slot to move, on the same item to stack, on a different item to swap.
• Tooltips that open next to the mouse and stay on screen, with the item name in its rarity colour and equipment stats listed.
• Using items. Right click uses an item; consumables are used up and the UI emits item_used so your game can react.
• Save and load. save_data() returns a plain dictionary that refers to items by resource path, and load_data() puts it back.
• Data and UI are separate. Inventory is a plain node with signals. InventoryUI listens and redraws, so any number of windows can show one bag.

Demo

demo/InventoryDemo.tscn starts with a small kit: potions, a sword and a shield. Press I to open and close the bag, click items, drag them around, and press 1 to add random loot.

Requirements

• Godot 4.7 or later, standard build (GDScript only, no .NET needed).
• Tested on Godot 4.7.2 stable on Windows. Earlier 4.x versions are untested.
• Uses the Compatibility renderer, so it runs on older GPUs too.

Installation

Clone the repository:

git clone https://github.com/CodingQuests/godot-inventory-system.git

Or download it with Code > Download ZIP and unzip it.

Then open Godot, click Import, pick the project.godot file inside the folder, and click Import & Edit.

Quick Start

1. Press F5.
2. Left click an item to see its details.
3. Right click a potion to use it.
4. Drag an item onto another slot. Drop potions on potions to stack them.
5. Press 1 a few times to add loot, 2 to empty the bag, S to save the contents and L to load them back. I opens and closes the bag.

How It Works

Three pieces of data

• Item (a Resource) is what an item is. The same resource is shared by every slot that holds it, so two slots hold the same item when slot_a.item == slot_b.item.
• InventorySlot (a Resource) is one cell: an item and a quantity. It emits item_changed whenever either changes.
• Inventory (a Node) owns the slots and the rules: add, remove, count, stack, save.

Adding stacks onto matching slots first, then fills empty ones, and hands back whatever is left:

var overflow := inventory.add_item(health_potion, 30)
if overflow > 0:
	drop_on_ground(health_potion, overflow)

The UI only listens

InventoryUI builds one InventoryUISlot per inventory slot and listens for inventory_changed. It never decides anything itself: a drop calls the slots' merge_with() or swaps their contents, and the display updates from the signals.

Each InventoryUISlot uses Godot's own drag and drop callbacks:

Callback	What it does here
_get_drag_data()	Returns {slot_index, item, quantity} and a preview of the icon
_can_drop_data()	Accepts any slot data and highlights the slot green
_drop_data()	Emits slot_dropped(from, to); InventoryUI stacks or swaps

Saving

var data := inventory.save_data()   # {"size": 20, "slots": [{"item_path": "res://items/iron_sword.tres", "quantity": 1}, null, ...]}
inventory.load_data(data)

Items are stored by resource path, so the save stays small and picks up any changes you make to an item's stats later.

Project Structure

project.godot                        Project file and the toggle_inventory action
inventory/Item.gd                    An item definition (Resource)
inventory/InventorySlot.gd           One slot: item and quantity (Resource)
inventory/Inventory.gd               The bag: slots, stacking, add, remove, save
inventory/GUI/InventoryUI.tscn       The inventory window: grid plus info panel
inventory/GUI/InventoryUI.gd         Builds the grid, handles clicks, drops and tooltips
inventory/GUI/InventoryUISlot.tscn   One cell: icon and quantity
inventory/GUI/InventoryUISlot.gd     Drawing a slot and drag and drop
items/                               Six example items (.tres)
demo/InventoryDemo.tscn              The demo scene
demo/inventory_demo.gd               Demo only: starting kit, loot keys, messages
assets/kenney_tiny-dungeon/          Kenney Tiny Dungeon item icons (CC0) and their license

Using It In Your Own Game

1. Copy the inventory/ folder into your project.

2. Add an input action named toggle_inventory (Project > Project Settings > Input Map) and bind a key to it.

3. Add an Inventory node to your player.

4. Instance inventory/GUI/InventoryUI.tscn under a CanvasLayer and set its inventory property to that node.

5. Make your items: right click in the FileSystem dock, New Resource, pick Item, fill it in, and save it as a .tres.

6. Add items from gameplay:

   @export var potion: Item
   
   func _on_pickup(body: Node) -> void:
   	var left: int = body.get_node("Inventory").add_item(potion, 1)
   	if left == 0:
   		queue_free()

7. React to use: connect InventoryUI.item_used, or extend Item and override use().

Customizing It

• Size: inventory_size on the Inventory node (20 by default).
• Layout: columns, slot_size and slot_spacing on InventoryUI.
• Look: the StyleBoxFlat resources in InventoryUI.tscn, and create_slot_style() in InventoryUISlot.gd.
• Rarity colours: get_rarity_color() in Item.gd.
• Item behaviour: make a script that extends Item, override use(), and use it for those items' resources.

Known Limitations

• Equipment stats are shown in the tooltip but nothing equips them. Hook item_used up to your own equipment or stats system.
• Splitting a stack (taking half) is not built in.
• use() only removes one of an item when its type is Consumable. Other types are left in the bag for your game to handle.
• Saves store items by resource path. Moving or renaming an item's .tres file breaks old saves unless you migrate them.
• The demo is a UI on a plain background, not a game scene.
• Tested on Godot 4.7.2 on Windows only.

License

MIT for the code. See LICENSE.

Third-Party Assets

The item icons are from Tiny Dungeon by Kenney, released under CC0 1.0. Details in THIRD_PARTY_ASSETS.md, and the pack's original license is in assets/kenney_tiny-dungeon/License.txt.

Learn How It Works

Want to understand how this works instead of just copying it?

CodingQuests teaches you how to build systems like this step by step in Godot, with interactive lessons and real projects.

• Inventory System builds this inventory from the data model up: items, slots, the UI and using items. Free, 10 lessons.
• Advanced Inventory UI carries on with an equipment paper doll, a hotbar, sorting and tooltips that compare gear. It is part of the paid Guild Hall membership.

More Free Godot Resources from CodingQuests

Other free, MIT-licensed Godot 4 projects that work well next to this one:

• Save System: Save slots where picked-up items stay picked up and opened chests stay open.
• Stats and Leveling: Health and mana pools, attributes, modifiers tagged by source, an XP curve and stat points.
• Dialogue and Quest System: Branching dialogue with conditions and effects, quests that track themselves, and a visual dialogue editor.
• Menu System: Main, pause and options menus with saved settings, fade transitions and gamepad support.

All twelve are listed on the CodingQuests GitHub profile.

Made by CodingQuests.