Getting Started

ItemVault gives your game one shared item model for drops, pickups, inventory, and save/load. The fastest useful setup is:

1. Create ItemDefinition data.
2. Register definitions in an ItemDatabase.
3. Create an inventory target.
4. Route pickup events into inventory through ItemVaultRuntime.

ItemVault uses scene-owned runtime services. Add ItemVaultRuntime to scenes that need item database and pickup-to-inventory behavior.

When building demos or sample scenes, prefer a scene-first workflow: author the node hierarchy, world layout, and Control UI in .tscn files, then use scripts only to wire behavior and update state. A plugin user should be able to open a demo scene in the editor and understand the structure before running it.

Prerequisites

• Godot 4.4+.
• The addons/item_vault/ folder installed in your project.
• At least one pickup scene that emits ItemVault pickup events.

1. Define an Item

Create an ItemDefinition for each item type your game knows about. The id is the stable save/load key; do not use file paths as item ids.

var ore := ItemDefinition.new()
ore.id = &"iron_ore"
ore.display_name = "Iron Ore"
ore.category = &"material"
ore.tags = [&"ore", &"smithing"]
ore.max_stack = 99
ore.weight = 0.25

If the item can appear in the world, assign world_scene to the pickup scene used when the item drops.

2. Register Items in a Database

For small games or tests, register definitions directly:

var database := ItemDatabase.new()
database.register(ore)

For authored resource catalogs, scan folders containing .tres or .res ItemDefinition files:

var database := ItemDatabase.new()
database.definition_dirs = ["res://items"]
database.reload()

For JSON-first catalogs, set definition_json_files instead. See json-catalogs-and-saves.md for the full JSON catalog shape.

ItemDatabase.get_def(&"iron_ore") returns the registered definition or null with a warning if the id is unknown.

3. Create an Inventory Target

ItemVault's Inventory type is the primary target for collected pickups:

var inventory := Inventory.new()

For full inventory containers, create and add ItemContainer instances using your game's container setup. If a target cannot accept a whole stack, the bridge treats the leftover stack as overflow.

4. Add ItemVaultRuntime

ItemVaultRuntime is the scene-owned composition root. It creates scoped runtime services for the scene:

• ItemVaultBus
• ItemDatabase
• InventoryPickupBridge

Script setup:

var runtime := ItemVaultRuntime.new()
add_child(runtime)
runtime.database = database
runtime.set_inventory_target(inventory)
runtime.initialize()

Inspector setup:

• Add an ItemVaultRuntime node to the scene.
• Set database_dirs if you want it to scan item definition folders.
• Enable auto_reload_database if runtime should reload the database on _ready().
• Assign inventory_target from script if the target is not a scene node.

5. Connect Pickups

If a pickup node emits ItemVault's picked_up(event: PickupEvent) signal, connect it through the runtime:

runtime.connect_pickup(pickup)

When the pickup emits a PickupEvent, the bridge attempts to add the event stack to the configured inventory target.

6. Save Later

ItemVault stacks save by stable item id:

{
  "id": "iron_ore",
  "qty": 12
}

See ../save-schema.md for the full save format and json-catalogs-and-saves.md for JSON catalog loading.

Troubleshooting

What's Next

• Read item-data-and-stack-metadata.md for item ids, tags, and per-stack data.
• Read json-catalogs-and-saves.md for JSON catalogs and stack dictionaries.
• Read drop-tables.md to spawn item-aware drops.
• Read runtime-and-pickup-bridge.md for bridge details.