Drop Tables

ItemVault drop tables reference ItemDefinition resources. The item definition owns the stable id and optional world_scene; the drop table only decides what can drop and how many units are produced.

Core Types

Create Droppable Entries

Each Droppable points at an ItemDefinition.

var ore_drop := Droppable.new()
ore_drop.item = ore_definition
ore_drop.quantity = 3
ore_drop.odds = 0.5

If ore_definition.world_scene is set, ItemVault uses that scene when the item is spawned into the world. Use scene_override only when this specific drop needs a different scene.

Create a Drop Table

var table := DropsTable.new()
table.possible_drops = [ore_drop]
table.guaranteed_drops = 1
table.combined_odds = false

Important fields:

Roll Drops Without Spawning

Use DropsGenerator when your game wants to decide what dropped before doing custom placement.

var generator := DropsGenerator.new(table, 1.0)
var drops: Array[Droppable] = generator.generate_drops()

for drop in drops:
	var stack := DropsTable.stack_from(drop)
	print("%s x%s" % [stack.item.id, stack.quantity])

The second constructor argument is an odds multiplier. Use 1.0 for normal rolls. For non-combined tables, guaranteed_drops is bounded by DropsGenerator.max_guaranteed_roll_attempts (default 1024) so impossible or very-low-odds tables cannot hang the game/editor. If guaranteed_drops > 0 and odds_multiplier <= 0.0, ItemVault returns the drops already rolled and emits a warning instead of retrying forever. If the retry ceiling is reached before the guarantee is satisfied, ItemVault returns partial drops with a warning; increase the drop odds or lower guaranteed_drops for deterministic guarantees.

combined_odds = true keeps the weighted-one-result behavior: one possible drop is selected per generate_drops() call, and guaranteed_drops does not repeat the combined roll.

Spawn Drops Into the World

Use RandomDrops when you want ItemVault to roll a table and call a scene spawner.

@export var random_drops: RandomDrops

func drop_loot() -> void:
	var spawned: Array[Node] = random_drops.spawn_drops(1)
	print("Spawned %d pickup nodes" % spawned.size())

Configure RandomDrops with:

• drops_table: your DropsTable.
• scene_spawner: a SceneSpawner2D, SceneSpawner3D, or compatible object with spawn(scene).

When a node is spawned, ItemVault writes the resolved stack to the world node with WorldItemStackMeta. That is how ItemVault pickup events recover the item stack that should enter inventory.

Combined Odds Example

Use combined_odds when you want one weighted result.

table.combined_odds = true

If one entry has odds = 2.0 and another has odds = 1.0, the first entry is twice as likely as the second.

Troubleshooting

What's Next

• Read item-data-and-stack-metadata.md for how spawned pickup nodes carry stacks.
• Read runtime-and-pickup-bridge.md for routing pickups into inventory.