Skip to content
ct
Docs
Menu

Item Vault v1.0

Getting Started

Create a minimal Item Vault setup with item definitions, database, inventory target, and pickup routing.

Status
Draft
Version
v1.0
Updated
Development docs generated from GDScript source

This is unreleased documentation in active development. APIs, class names, and behavior may change before the final release.

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 node that creates and connects ItemVault services for one scene. 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

Problem Check
Item cannot be found by id Ensure ItemDefinition.id is stable and registered in ItemDatabase.
Pickups do not enter inventory Ensure runtime.set_inventory_target(...) was called and runtime.connect_pickup(pickup) returned true.
Pickup stack is missing Ensure the pickup scene or drop route writes an ItemStack with WorldItemStackMeta.write(node, stack).
You need global inventory state Keep the inventory in your game architecture and pass it into ItemVaultRuntime; ItemVault runtime services can still stay scene-owned.

What's Next