@thedivergentai/godot-inventory-system

Scenario triggers (which script?)

MANDATORY reads

1. inventory_item_resource.gd — item blueprint
2. inventory_data_resource.gd — two-pass stack + weight validation
3. 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

Deep recipes (on demand)

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 — Items, slots, and inventories should be Resource data (not Nodes) so stacks stay lightweight and shareable as .tres databases.
• Resource — Use duplicate(true) for runtime stack/slot instances so mutating quantity never corrupts the shared item blueprint.
• GDScript exports — @export / @export_group power Inspector-authored ids, icons, max_stack, weight, and loot weights on item Resources.
• Using signals — Emit inventory_changed / slot signals so UI reflects data; never let slot widgets mutate arrays silently.
• Scene organization — Keep “signals up, calls down”: UI listens; inventory Resources/managers own add/remove/stack logic.
• GUI containers — GridContainer / container sizing is the baseline for slot grids before custom Tetris footprints.
• Control — 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 — Pattern for building slot Controls that draw icons/counts and participate in drag-and-drop.
• Saving games — Persist slot ids + amounts (not full recursive Resources) with the rest of player save data.
• ResourceLoader — Resolve item blueprints by resource_path / id at load time instead of embedding textures in every save blob.
• JSON — Compact inventory dictionaries (path/id + amount) for FileAccess save files without bloating nested Resource graphs.
• Random number generation — 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 — Inventory is Resource-first (items, slots, loot tables); learn composition/serialization patterns before inventing Node-based item trees.
• godot-signal-architecture — Batch-safe inventory_updated / slot signals keep reactive UI in sync without per-item spam or ghost connections.
• godot-gdscript-mastery — Typed Resources, Array/Dictionary slot maps, and int stack math assume solid GDScript patterns.
• godot-ui-containers — Slot grids, equipment panels, and responsive inventory windows build on container layout before drag-drop polish.

Complements

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

Downstream / consumers

• godot-monte-carlo-balancer — 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 — Action-RPG bags, equipment screens, and loot loops assemble this skill with combat, stats, and quests.
• godot-genre-survival — Weight limits, consumables, and scarce loot are core survival inventory constraints.
• godot-quest-system — Fetch/collect quests query has_item and grant rewards through the same inventory add/remove APIs.

Master

• godot-master — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.