---
name: inventory-system
description: Use when building or replacing an inventory system — Resource-based items, slots, stacking, and UI binding. Not for extending an existing one
title: inventory-system
canonical_url: https://skilld.dev/gh/jame581/godotprompter/inventory-system
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/core-classes.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/core-classes.md), [references/equipment.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/equipment.md), [references/serialization.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/serialization.md), [references/ui-binding.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/ui-binding.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/inventory-system`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/inventory-system`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/inventory-system) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/inventory-system`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/inventory-system --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/inventory-system --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Inventory Systems in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. This skill carries the decisions; the implementations live in `references/` (GDScript first, then C#) — load the one you need.

> **Related skills:** **resource-pattern** for custom Resource data containers, **save-load** for inventory serialization, **event-bus** for inventory change notifications, **hud-system** for inventory UI display, **popochiu** for adventure-game inventory.

---

## 1. Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                        UI Layer                         │
│   InventoryUI (Control)                                 │
│     └─ GridContainer                                    │
│           └─ SlotUI × N (Button)                        │
│                 └─ TextureRect (icon) + Label (qty)     │
│                                                         │
│   Connects to: inventory_changed signal                 │
│   Drag-and-drop via _get_drag_data / _drop_data         │
└───────────────────────┬─────────────────────────────────┘
                        │ reads / mutates
┌───────────────────────▼─────────────────────────────────┐
│                    Inventory (Node)                      │
│   slots: Array[InventorySlot]                           │
│   add_item(item, qty) → leftover: int                   │
│   remove_item(item, qty)                                │
│   has_item(item, qty) → bool                            │
│   get_item_count(item) → int                            │
│                                                         │
│   signals: inventory_changed                            │
│             item_added(item, quantity)                  │
│             item_removed(item, quantity)                │
└───────────────────────┬─────────────────────────────────┘
                        │ references
┌───────────────────────▼─────────────────────────────────┐
│                   Data Layer (Resources)                 │
│   ItemData (Resource)                                   │
│     id, name, description, icon, max_stack_size,        │
│     item_type enum                                      │
│                                                         │
│   InventorySlot (inner class / Resource)                │
│     item: ItemData, quantity: int                       │
└─────────────────────────────────────────────────────────┘
```

---

## 2. The Decisions That Matter

Three choices shape every inventory. Make them explicitly and state which you picked — the rest is mechanical.

| Decision | Take | Why |
|---|---|---|
| Item identity: `Resource` vs. Dictionary / JSON | **`Resource` in `.tres`** | `@export` slots accept typed items, the Inspector edits them, and shared instances compare by reference |
| Slot container: `Resource` vs. `RefCounted` | **`RefCounted`** | Slots are runtime state, not authored assets. A `Resource` invites saving slots to disk and reloading stale item copies |
| `add_item` return: `bool` vs. leftover count | **leftover `int`** | Partial adds are the common case (stack caps, full bag). A `bool` forces the caller to re-query what actually fit |

If your game needs something else — a weight-based bag with no slots, a grid inventory with shaped items, an infinite stack list — say so before building. The fixed slot array this skill describes is the wrong skeleton for all three.

### Non-obvious specifics

- **Fill existing stacks before empty slots** — two passes, in that order. A single naive pass scatters one item type across several slots and reports the bag full while space remains.
- **Emit `inventory_changed` once per operation**, after both passes complete — not once per slot touched. Per-slot emission re-renders the whole UI N times for one `add_item`.
- **Items compare by reference.** Godot caches loaded resources, so `load()` on the same `.tres` returns the same instance and `slot.item == item` is correct and cheap. If you `duplicate()` items at runtime, that breaks — key off `ItemData.id` instead.
- **Clear `item` to `null` when quantity reaches 0**, or `is_empty()` lies and the slot is never reusable.
- **Prevent stacking with data, not branches** — set `max_stack_size = 1` on `EQUIPMENT` and `KEY_ITEM` items rather than special-casing them in `add_item`.
- **C#: mark `ItemData` `[GlobalClass]`** or the Inspector will not offer it as a type when creating `.tres` files.

### Inventory API contract

| Member | Returns | Contract |
|---|---|---|
| `add_item(item, quantity)` | `int` | Leftover that did not fit; `0` means everything was added |
| `remove_item(item, quantity)` | — | Removes up to `quantity`; silent when fewer are held |
| `has_item(item, quantity)` | `bool` | Convenience over `get_item_count` |
| `get_item_count(item)` | `int` | Summed across every slot |
| `inventory_changed` | signal | Fired once per mutating operation — drives all UI |
| `item_added(item, quantity)` | signal | Carries the amount actually added |
| `item_removed(item, quantity)` | signal | Carries the amount actually removed |

> Full `ItemData`, `Inventory`, and `InventorySlot` implementations in GDScript and C#: [references/core-classes.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/core-classes.md)

---

## 3. Equipment Extension

Add equipment slots (`HEAD`, `CHEST`, `WEAPON`, etc.) with an `Equipment` node beside the `Inventory`, holding a slot map keyed by a `SlotType` enum. Stat aggregation sums a `stats` Dictionary (a property you add to `ItemData`) across equipped items; signal `equipment_changed` when slots change.

> See [references/equipment.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/equipment.md) for the full GDScript and C# `Equipment` class with `SlotType` enum, equip / unequip API, and stat aggregation.

---

## 4. UI Binding

Slot-grid UI: a `GridContainer` of `Button` slot widgets, each rendering one `InventorySlot`. Drag-and-drop uses `_get_drag_data` / `_drop_data` / `_can_drop_data` on the slot widget. The Inventory emits `inventory_changed`; the UI re-renders affected slots.

> See [references/ui-binding.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/ui-binding.md) for the full GDScript and C# slot widget (drag/drop, hover preview), inventory grid layout, and tooltip wiring.

---

## 5. Serialization

Persist each slot as an `{id, qty}` pair (`null` for an empty slot), never the `ItemData` itself or its path. An `ItemRegistry` autoload loads `res://items/` at startup and resolves ids back to items on load.

> See [references/serialization.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/inventory-system/references/serialization.md) for the GDScript and C# `ItemRegistry` with `serialize_inventory` / `deserialize_inventory`; put the result in your save file (see **save-load** for its `version` field).

---

---

## Implementation Checklist

- [ ] `ItemData` extends `Resource` with a stable `id` string set in the Inspector
- [ ] `ItemData` files live under `res://items/` and are committed to version control
- [ ] `Inventory.add_item()` returns leftover count; callers handle a full inventory
- [ ] `inventory_changed` signal drives all UI updates — UI never polls per-frame
- [ ] `InventorySlot.remove_from_stack()` clears `item` to `null` when quantity reaches 0
- [ ] Equipment slots keyed by `SlotType` enum, not by string, to catch typos at compile time
- [ ] `Equipment.get_total_stat()` is called when stats are needed, not cached unless profiling demands it
- [ ] Serialization stores `id + quantity` only — never full `ItemData` objects or resource paths
- [ ] `ItemRegistry` loads items at startup; all deserialization goes through it
- [ ] Drag-and-drop swaps slot contents directly then emits `inventory_changed` once
- [ ] `max_stack_size = 1` on `EQUIPMENT` and `KEY_ITEM` types to prevent stacking
- [ ] All `push_error()` messages include the class name and method for easy tracing
