FAQ Troubleshooting

This page answers common questions that come up while integrating ItemVault.

How should I add ItemVault services to a scene?

Add an ItemVaultRuntime node to scenes that need an item database and pickup-to-inventory routing. The runtime owns scoped services for the scene and keeps tests, menus, split-screen scenes, and demos isolated.

If your game already has a global inventory service, keep it in the game layer and pass the relevant inventory target into ItemVaultRuntime.

Where do game-specific item terms go?

Use ItemDefinition.id, category, and tags for item-type vocabulary. Use ItemStack.instance_id when a specific stack needs to link to game-owned instance data.

Use WorldItemStackMeta only for the spawned world-node handoff of an ItemVault ItemStack.

What happens if a pickup disappears or the world unloads?

WorldItemStackMeta stores the stack on the pickup node's Godot metadata. It is not a global registry.

If the pickup node is freed, the stack metadata is freed with the node. If the world unloads, unsaved pickup-node metadata is gone. No registry cleanup is required.

If dropped pickups need to persist, save the stack before removing the node:

var stack := WorldItemStackMeta.read(pickup)
if stack != null:
	save_world_drop(pickup.global_position, stack.to_dict())

On load, recreate the pickup node, rebuild the stack from saved data, and write it back with WorldItemStackMeta.write(pickup, stack).

Why is the pickup connector called a bridge?

Pickup nodes emit PickupEvent values. InventoryPickupBridge consumes those events and mutates the configured Inventory or Wallet.

That keeps pickup nodes simple while keeping the default flow tightly integrated:

PickupEvent -> InventoryPickupBridge -> Inventory or Wallet

Why is SpawnEvent.dimension not a routing key?

The field is diagnostic. Your code should branch on the actual node type when it needs dimension-specific behavior:

if event.spawner is Node3D:
	var position: Vector3 = event.spawner.global_position
elif event.spawner is Node2D:
	var position: Vector2 = event.spawner.global_position

See dimension-neutral-handling.md.

Why is SpawnEvent.stack null?

The spawned pickup node probably did not carry ItemVault stack metadata. If you spawn pickup scenes manually, attach the stack before the event is emitted:

WorldItemStackMeta.write(pickup, stack)

If you use RandomDrops or InventoryDrop, ItemVault writes this metadata for you when a valid Droppable or inventory item resolves an ItemStack.

Why did an item disappear when loading a save?

ItemVault drops stacks whose id cannot be resolved by ItemDatabase. This keeps old saves loadable after an item is removed or renamed, but stable ids matter.

Fix:

• Keep ItemDefinition.id stable after release.
• Register every item definition in ItemDatabase.
• Add migration code before changing save ids.

What 3D support is in 1.0?

ItemVault 1.0 scopes core 3D item flow:

• SceneSpawner3D
• SpawnSceneAtPoint3D
• Pickup3D
• PickupsCollector3D
• 3D move-on-spawn
• pickup-to-inventory routing

3D convenience spawners ShapeEdgeSceneSpawner3D and LaunchForceSceneSpawner3D are deferred to 1.1.

My inventory is full. How do I show feedback?

Connect the bridge rejection signal:

runtime.bridge.pickup_rejected.connect(_on_pickup_rejected)

func _on_pickup_rejected(event: PickupEvent, overflow: ItemStack) -> void:
	print("Inventory full: %s x%s" % [overflow.item.id, overflow.quantity])

Where should I start?

Start with getting-started.md, then read item-data-and-stack-metadata.md, json-catalogs-and-saves.md, and drop-tables.md.