Runtime Bootstrap

ItemVault does not require a global autoload. The runtime is a small set of services that you can create, wire, and own yourself. This guide shows how to bootstrap the runtime for three common integration styles.

---

1. Use ItemVaultRuntime (default)

The simplest path is the scene-owned ItemVaultRuntime node:

var runtime:= ItemVaultRuntime.new()
add_child(runtime)
runtime.database_dirs= ["res://items"]
runtime.auto_reload_database= true
runtime.set_inventory_target(player_inventory)
runtime.initialize()

# Connect pickup nodes as they appear
for pickupin spawned_pickups:
    runtime.connect_pickup(pickup)

ItemVaultRuntime creates ItemVaultBus, ItemDatabase, and InventoryPickupBridge for you. It keeps these services scoped to one scene, so tests, menus, and split-screen scenes do not share state.

---

2. Manual wiring (custom script)

If your game already has a global service provider, create the same services manually and wire them together:

var bus:= ItemVaultBus.new()
var database:= ItemDatabase.new()
var bridge:= InventoryPickupBridge.new()

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

bridge.target= player_inventory
bridge.enabled= true
bridge.connect_bus(bus)

# Connect pickup signals to the bus manually
for pickupin spawned_pickups:
    pickup.picked_up.connect(_on_pickup)

func _on_pickup(event:PickupEvent)-> void:
    bus.emit_pickup(event)

The InventoryPickupBridge listens on ItemVaultBus for PickupEvent values and routes them to the configured target. You can replace the bridge with your own consumer if you want different game-specific behavior.

---

3. Adapting an existing inventory

The bridge target is any object that implements add(stack: ItemStack) -> ItemStack:

func add(stack:ItemStack)-> ItemStack:
    # Return null if the full stack is accepted.
    # Return a leftover ItemStack if only part fits.
    return _my_inventory.add(stack)

If the target exposes wallet, currency stacks (category &"currency") route there automatically.

---

4. No bridge: consume PickupEvent directly

You can also skip InventoryPickupBridge and use PickupEvent directly:

pickup.picked_up.connect(_on_pickup)

func _on_pickup(event:PickupEvent)-> void:
    if event.fully_accepted():
        # Play pickup sound, show toast.
        pass
    elif event.fully_rejected():
        # Show "inventory full" feedback.
        pass
    else:
        # Partial accept; some items remain on the ground.
        print("Took some,%d remaining" % event.overflow.quantity)

This is useful when ItemVault is a drop/pickup library but your game owns inventory and save logic.

---

5. Bootstrap checklist

Step	What to do
Create ItemDatabase	Register ItemDefinition resources or scan definition_dirs.
Create ItemVaultRuntime or wire services	Choose scene-owned ItemVaultRuntime or manual wiring.
Set inventory target	Must implement add(stack: ItemStack) -> ItemStack.
Connect pickups	runtime.connect_pickup(pickup) or connect picked_up to a custom handler.
Write stack metadata for manual spawns	WorldItemStackMeta.write(pickup, stack) before the event fires.

---

What's Next

• Read runtime-and-pickup-bridge.md for bridge overflow and currency behavior.
• Read item-data-and-stack-metadata.md for WorldItemStackMeta usage.
• Read getting-started.md for the minimal end-to-end setup.