Skip to content

Drag & Drop System

DragDropSystem is an Autoload that handles all mouse interactions for moving items between slots, splitting stacks, and dropping items into the 3D world.

Mouse Controls

Drag & Drop

  • Left Click (Hold & Drag): Picks up the entire stack.
  • Right Click (Hold & Drag): Picks up exactly 1 item.
  • While dragging: Use the Scroll Wheel to dynamically adjust the drag_amount up or down.
  • Shift + Left Click: Instantly transfers the entire stack to another open inventory (Quick Move).

Quick Move Behavior

Quick move only works when two inventory panels are open simultaneously (e.g., player inventory + chest). The system automatically finds the other visible panel and transfers items to it. This is fully implemented in the default SlotUI, SlotGrid, and InventoryBinder components.

Drop Targets

For a UI Control to receive dropped items, it must meet two requirements:

  1. Be in the inventory_drop_targets group.
  2. Have two metadata properties set:
  3. "inventory": Inventory resource reference.
  4. "slot_index": integer index of the slot.

SlotUI script handles this automatically when instantiated by the inventory panels.

Dropping to the 3D World

If you drag an item outside of any valid UI drop target and release the mouse, DragDropSystem will drop the item into the 3D world.

  • It finds the player node (via the "player" group or the first CharacterBody3D).
  • Spawns the DroppedItem scene 1.5 units in front of the player.
  • Applies a random physics impulse so the item tumbles realistically.

Public API for Dropping

In v2.0, DragDropSystem.spawn_world_item(item_def, count, durability, drop_pos) is a public method. You can call this directly from your own scripts (e.g., from EquipmentManager when dropping the active item) to spawn items into the 3D world with physics.

InventoryTransfer (Static Helper)

InventoryTransfer class contains the logic of moving items between inventories.

  • transfer(): Moves items from source to target, automatically finding empty slots or stacking onto existing items.
  • drop_to_slot(): Handles direct slot-to-slot drops. It can exchange items when one is dragged onto another item (if you drag a sword onto a shield, they swap places, provided both slots' rules allow it).
  • quick_move(): A backend helper method to instantly move an entire stack from one inventory to another.

Durability Handling

When splitting stacks or moving partial amounts, InventoryTransfer now correctly calculates and transfers the proportional durability of the items to the new slots.