Skip to content
ct
Docs
Menu

Item Vault v1.0

Drop Tables

Configure DropsTable, Droppable entries, and item-aware world drops.

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

Drop tables are the single abstraction for both world drops (RandomDrops) and pickup loot (Pickup2D/Pickup3D). Both use DropTable + DropEntry.

Core Types

Type Purpose
ItemDefinition The item type: id, display name, icon, category, tags, stack size, weight, world scene
DropEntry One possible drop / loot entry: item, quantity, odds (0.0–1.0), optional scene override
DropTable A list of possible drops plus roll behavior
DropsGenerator Rolls a DropTable and returns selected DropEntry entries
RandomDrops Node helper that rolls drops and asks a scene spawner to place pickup scenes

Create DropEntry Entries

Each DropEntry points at an ItemDefinition.

var ore_drop:= DropEntry.new()
ore_drop.item= ore_definition
ore_drop.quantity= 3
ore_drop.odds= 0.5  # 50% chance; stored as a 0.0–1.0 float

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:= DropTable.new()
table.possible_drops= [ore_drop]
table.guaranteed_drops= 1
table.combined_odds= false

Important fields:

Field Meaning
possible_drops The list of DropEntry entries that can roll.
guaranteed_drops Minimum number of drops generated for non-combined rolls. ItemVault keeps rolling until this count is reached or the bounded retry guard is exhausted.
combined_odds When false, each entry rolls independently. When true, odds are weighted against each other and one entry is selected.

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[DropEntry]= generator.generate_drops()

for dropin drops:
	var stack:= DropTable.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 DropTable.
  • 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

Problem Fix
Nothing drops Make sure at least one DropEntry.odds is greater than 0.0.
Spawned node has no stack Make sure the DropEntry has an item; DropTable.stack_from(drop) returns null without one.
Scene does not spawn Set ItemDefinition.world_scene or DropEntry.scene_override.
3D drop route feels incomplete 3D point spawning, move-on-spawn, and pickup-to-inventory routing are supported. 3D shape-edge and launch-force convenience spawners are deferred to 1.1.

What's Next