godot-inventory-system

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-inventory-system

Build inventory systems with slot-based containers, stacking, weight, and drag-drop UI.

  • Solves designing RPG inventories, survival item management, or loot systems.
  • Depends on Godot 4.7+ and Resource-based item data scripts.
  • Recommends scripts based on inventory type: slot bag, Tetris grid, or equipment.
  • Delivers ready-to-use script references and architecture patterns for inventory logic.

SKILL.md

.github/skills/godot-inventory-systemView on GitHub ↗
---
name: godot-inventory-system
description: "Expert blueprint for inventory systems (Diablo, Resident Evil, Minecraft) covering slot-based containers, stacking logic, weight limits, equipment systems, and drag-drop UI. Use when building RPG inventories, survival item management, or loot systems. Keywords inventory, slot, stack, equipment, crafting, item, Resource, drag-drop."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Inventory System

Resource-first slots, stacking, weight, equipment, and loot — **scripts are source of truth** (no duplicated Inventory/Equipment/Crafting dumps in this body).

## Scenario triggers (which script?)

| Scenario | Open |
|---|---|
| **Slot bag** (WoW-style stacks) | [inventory_data_resource.gd](scripts/inventory_data_resource.gd) + [item_slot_data.gd](scripts/item_slot_data.gd) + [inventory_ui_controller.gd](scripts/inventory_ui_controller.gd) |
| **Tetris grid** (Diablo/RE footprint) | [grid_inventory_logic.gd](scripts/grid_inventory_logic.gd) / [inventory_grid.gd](scripts/inventory_grid.gd) |
| **Equipment** | Item Resources + RPG stats complement; drag via [drag_and_drop_slot.gd](scripts/drag_and_drop_slot.gd) |
| **Loot table** | [loot_table_resource.gd](scripts/loot_table_resource.gd) + [item_pickup_node.gd](scripts/item_pickup_node.gd) |
| **Persist** | [inventory_persistence.gd](scripts/inventory_persistence.gd) (ids + amounts, not nested Resources) |
| **Consumables** | [consumable_item_logic.gd](scripts/consumable_item_logic.gd) |
| **DB lookup** | [item_database_loader.gd](scripts/item_database_loader.gd) |

## MANDATORY reads

1. [inventory_item_resource.gd](scripts/inventory_item_resource.gd) — item blueprint  
2. [inventory_data_resource.gd](scripts/inventory_data_resource.gd) — two-pass stack + weight validation  
3. [inventory_ui_controller.gd](scripts/inventory_ui_controller.gd) — reactive UI that **reuses** slot controls  

## NEVER Do in Inventory Systems

- **NEVER use Nodes for items** — `Item extends Resource`.
- **NEVER add without stack/weight pre-checks** — validate capacity first.
- **NEVER let UI mutate inventory arrays silently** — data owns mutations; UI listens.
- **NEVER use `float` for quantities** — `int` stacks.
- **NEVER emit per-item signals in a batch** — one `inventory_updated` after the loop.
- **NEVER hardcode item references** — String/StringName ids + database.
- **NEVER `queue_free` + recreate all slots every refresh** — reuse slot widgets (see UI controller).
- **NEVER allocate new Resources inside `_process`**.
- **NEVER mutate a shared item blueprint at runtime** — use `duplicate(true)` on stack/slot instances so one pickup cannot corrupt every copy of that `.tres`.
- **NEVER access `.icon` on a null slot item** — guard with `is_instance_valid()` before drawing UI.

## Decision trees

### Add item
1. Weight/volume OK?  
2. Pass 1: fill partial stacks  
3. Pass 2: empty slots / grid footprint  
4. Return overflow count; single UI signal  

### UI
- Bind once to `inventory_updated`  
- Update existing slot nodes; create only when slot count grows  

### Save
- Serialize `item_id` / `resource_path` + `amount` only — [inventory_persistence.gd](scripts/inventory_persistence.gd)


## Deep recipes (on demand)

| Topic | Reference / script |
|-------|-------------------|
| Resource item model | [core-architecture.md](references/core-architecture.md) + [inventory_item_resource.gd](scripts/inventory_item_resource.gd) |
| Two-pass stack add | [inventory-manager.md](references/inventory-manager.md) + [inventory_data_resource.gd](scripts/inventory_data_resource.gd) |
| Tetris grid footprint | [elite-technical-patterns.md](references/elite-technical-patterns.md) + [grid_inventory_logic.gd](scripts/grid_inventory_logic.gd) |
| Equipment & crafting | [equipment-system.md](references/equipment-system.md) / [crafting-integration.md](references/crafting-integration.md) |
| Reactive UI & save ids | [ui-integration.md](references/ui-integration.md) + [inventory_persistence.gd](scripts/inventory_persistence.gd) |


## Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

### Official Documentation
- [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — Items, slots, and inventories should be `Resource` data (not Nodes) so stacks stay lightweight and shareable as `.tres` databases.
- [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) — Use `duplicate(true)` for runtime stack/slot instances so mutating quantity never corrupts the shared item blueprint.
- [GDScript exports](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_exports.html) — `@export` / `@export_group` power Inspector-authored ids, icons, `max_stack`, weight, and loot weights on item Resources.
- [Using signals](https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html) — Emit `inventory_changed` / slot signals so UI reflects data; never let slot widgets mutate arrays silently.
- [Scene organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/scene_organization.html) — Keep “signals up, calls down”: UI listens; inventory Resources/managers own add/remove/stack logic.
- [GUI containers](https://docs.godotengine.org/en/stable/tutorials/ui/gui_containers.html) — `GridContainer` / container sizing is the baseline for slot grids before custom Tetris footprints.
- [Control](https://docs.godotengine.org/en/stable/classes/class_control.html) — Native `_get_drag_data` / `_can_drop_data` / `_drop_data` and `set_drag_preview` implement inventory drag-swap without a custom input stack.
- [Custom GUI controls](https://docs.godotengine.org/en/stable/tutorials/ui/custom_gui_controls.html) — Pattern for building slot `Control`s that draw icons/counts and participate in drag-and-drop.
- [Saving games](https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html) — Persist slot ids + amounts (not full recursive Resources) with the rest of player save data.
- [ResourceLoader](https://docs.godotengine.org/en/stable/classes/class_resourceloader.html) — Resolve item blueprints by `resource_path` / id at load time instead of embedding textures in every save blob.
- [JSON](https://docs.godotengine.org/en/stable/classes/class_json.html) — Compact inventory dictionaries (`path`/`id` + `amount`) for `FileAccess` save files without bloating nested Resource graphs.
- [Random number generation](https://docs.godotengine.org/en/stable/tutorials/math/random_number_generation.html) — Weighted loot rolls and chest contents need seeded RNG patterns, not ad-hoc `randf()` sprinkled in UI code.

### Related Skills

#### Prerequisites
- [godot-resource-data-patterns](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-resource-data-patterns/SKILL.md) — Inventory is Resource-first (items, slots, loot tables); learn composition/serialization patterns before inventing Node-based item trees.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — Batch-safe `inventory_updated` / slot signals keep reactive UI in sync without per-item spam or ghost connections.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — Typed Resources, Array/Dictionary slot maps, and int stack math assume solid GDScript patterns.
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — Slot grids, equipment panels, and responsive inventory windows build on container layout before drag-drop polish.

#### Complements
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — Inventory persistence must round-trip through the project save schema (ids + counts, migration-safe).
- [godot-rpg-stats](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-rpg-stats/SKILL.md) — Equipment bonuses, encumbrance, and consumable effects need a consistent stats/modifier layer.
- [godot-economy-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-economy-system/SKILL.md) — Shops, buy/sell, and rarity-weighted loot tables consume the same item Resources and stack rules.
- [godot-ability-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ability-system/SKILL.md) — Consumable scrolls, skill books, and gear that grants abilities bridge inventory grants into AbilityManager registration.
- [godot-combat-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-combat-system/SKILL.md) — Weapons/armor equipped from inventory feed damage and hit pipelines; keep DamageData separate from item metadata.
- [godot-ui-theming](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-theming/SKILL.md) — Rarity colors, slot styles, and drag previews should live in Theme resources, not hardcoded slot scripts.

#### Downstream / consumers
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — After stack sizes, weights, drop rates, and shop prices are data-driven, Monte Carlo sims prove economy/loot bands before shipping curves.
- [godot-genre-action-rpg](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-action-rpg/SKILL.md) — Action-RPG bags, equipment screens, and loot loops assemble this skill with combat, stats, and quests.
- [godot-genre-survival](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-survival/SKILL.md) — Weight limits, consumables, and scarce loot are core survival inventory constraints.
- [godot-quest-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-quest-system/SKILL.md) — Fetch/collect quests query `has_item` and grant rewards through the same inventory add/remove APIs.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.