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
Current
Version
v1.0
Updated
2026-07-31

ItemVault 1.0 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.

Included demos (1.0 package)

The demo project ships seven scenes plus a showroom launcher. Scene file names keep historical numbers (01_roundtrip.tscn … 07_…) for tests and docs. The showroom, storefront GIFs, and capture zip use a marketability order (fun first, technical last):

Showroom # Scene file What it proves
01 05_pickup_to_inventory 2D walk + live pickup → inventory
02 07_pickup_to_inventory_3d 3D chest open → sequential collect
03 02_drop_table Weighted rolls; stacks accumulate
04 04_shop Buy / sell / buyback (buyback = sale credit)
05 03_inventory_grid Transfer between containers + toast
06 06_spawning_examples_2d Point / edge / launch spawn patterns
07 01_roundtrip Stack JSON serialize → restore (golden path)

Storefront art shows the golden path only. Robustness cases (unknown item id → null, empty inventory failure paths, diagnostic fallbacks) stay in unit tests so marketing stills and GIFs match what a player sees on success.

Demo boards mount through a shared shell that scales into the stage with room for toast overlays, so UI stays fully visible at common storefront resolutions (including 1152×648 and 1920×1080).

What's Next