API Reference¶

Overview¶

A modular, data-driven inventory system for Godot 4.6. Provides inventory management with drag and drop, item stacking, durability, slot rules, and automated item logic behaviors.

1. Autoload Singletons¶

DragDropSystem¶

Extends: Node
Manages drag operations from UI slots, calculating drop targets, and dropping items into the 3D world.

Properties:

Property	Type	Description
`is_dragging`	`bool`	`true` during an active drag operation.
`source_inv`	`Inventory`	The inventory being dragged from.
`source_data`	`SlotData`	The data of the item being dragged.
`source_idx`	`int`	The slot index being dragged from.
`drag_amount`	`int`	The current quantity of items being dragged.

Signals:

Signal	Description
`drag_started(inv: Inventory, data: SlotData, source_idx: int)`	Emitted when a drag begins.
`drag_ended`	Emitted when a drag ends (dropped or cancelled).
`dropped(target_inv: Inventory, target_idx: int, amount: int)`	Emitted on a successful drop into a slot.

Methods:

Method	Description
`start_drag(inv, data, idx, button, is_right_click)`	Begins a drag operation.
`end_drag()`	Ends the current drag and cleans up previews.
`set_drop_target(target_inv, target_idx)`	Sets the drop target and performs the drop logic.
`spawn_world_item(item_def, count, durability, drop_pos)`	(Public) Spawns a `DroppedItem` in the 3D world with physics.

InputMode¶

Extends: Node

Controls mouse capture state for 3D games, preventing conflicts between player camera control and UI interaction.

Properties:

Property	Type	Default	Description
`startup_mode`	`bool`	`true`	`true` = game mode, `false` = UI mode on startup.
`prevent_game_input_in_ui`	`bool`	`true`	Blocks game input when UI is visible.

Methods:

Method	Description
`ui()`	Switch to UI mode (mouse visible, uncaptured).
`game()`	Switch to game mode (mouse captured, hidden).
`toggle()`	Toggle between UI and game modes.
`is_game_mode() -> bool`	Returns `true` if in game mode.
`allow_game_input() -> bool`	Returns `true` if in game mode AND not currently dragging.
`set_mode(is_game: bool)`	Direct mode setter.

UICoordinator¶

Extends: Node
Calculates and sets screen positions for multiple inventory panels. Managed automatically by UIStateManager.

Methods:

Method	Description
`arrange_panels(panels: Array[Control])`	Automatically positions an array of panels based on their `ui_role` metadata.
`position_panel(panel: Control, layout_mode: String)`	Positions a panel manually. Modes: `"primary"`, `"secondary"`, `"primary_centered"`, `"centered"`.

UIStateManager¶

Extends: Node
Manages a stack of UI panels, background overlays, game pausing, and quick-move targeting.

Enums:

UIType: BLOCK_INPUT, PAUSE_GAME

Signals:

Signal	Description
`panel_spawned(panel: Control, scene: PackedScene, role: String)`	Emitted when a panel is instantiated and added.
`panel_closed(panel: Control)`	Emitted when a panel is removed and freed.

Methods:

Method	Description
`open_panel(scene, inv, title, role, type) -> Control`	Instantiates a UI panel, binds the inventory, and arranges it.
`close_top_ui()`	Closes only the most recently opened panel.
`close_panel(panel: Control)`	Closes a specific panel instance.
`close_all()`	Closes all open panels, restores mouse capture, removes overlays.
`get_other_inventory(current_inv) -> Inventory`	Finds the second open inventory (used for Quick Move).
`get_panel_by_role(role: String) -> Control`	Returns the panel with the specified role.
`has_open_ui() -> bool`	Returns `true` if any panels are open.

2. Core Components¶

EquipmentManager¶

Extends: Node
Automates item logic execution, 3D model equipping, and input handling for the active hotbar item.

Properties:

Property	Type	Description
`player`	`Node3D`	The player node.
`main_inventory`	`InventoryComponent`	The player's inventory.
`hotbar`	`ModularHotbar`	The hotbar to track active items from.
`item_socket`	`Marker3D`	Optional 3D node to attach weapon models to.
`animations_enabled`	`bool`	Enables/disables equip/unequip tweens.
`default_equip_animation`	`String`	Default tween type (`scale`, `slide`, `rotate`, `fade`, `none`).
`default_unequip_animation`	`String`	Default unequip tween type.

Signals:

Signal	Description
`item_equipped(item: ItemDefinition, slot_index: int)`	Emitted when an item is equipped.
`active_item_changed(item: ItemDefinition, slot_index: int)`	Emitted when the player scrolls to a new hotbar slot.

Methods:

Method	Description
`drop_active_item(amount: int = 1)`	Drops the currently held active item into the 3D world.

InventoryComponent¶

Extends: Node
Node attached to Player, Chests, or Enemies to give them an inventory. Connects the Inventory resource to the game world.

Properties:

Property	Type	Default	Description
`inventory`	`Inventory`	`null`	The actual Resource holding the data.
`capacity`	`int`	`20`	Used to generate a new Inventory if `create_if_missing` is true.
`slot_definitions`	`Array[SlotDefinition]`	`[]`	Copied to the new Inventory if generated at runtime.
`create_if_missing`	`bool`	`true`	Auto-creates an `Inventory` resource on `_ready()` if none is assigned.

Signals:

Signal	Description
`inventory_ready(inv: Inventory)`	Emitted when the inventory is initialized.

Methods:

Method	Description
`get_inventory() -> Inventory`	Returns the attached `Inventory` resource.

InventoryDisplayComponent¶

Extends: Node3D
Displays inventory items in the 3D world using Marker3D nodes.

Properties:

Property	Type	Description
`inventory_component`	`InventoryComponent`	The inventory to display.
`marker_container`	`Node3D`	Parent node containing `Marker3D` children.
`auto_discover_markers`	`bool`	Automatically finds `Marker3D` children.
`markers`	`Array[Node3D]`	Manual array of markers to use.

Methods:

Method	Description
`refresh_display()`	Clears and rebuilds the 3D item models based on inventory state.

3. Data Resources¶

Inventory¶

Extends: Resource
Main inventory container that holds slots and manages item operations.

Properties:

Property	Type	Default	Description
`capacity`	`int`	`20`	Number of slots in inventory.
`slot_definitions`	`Array[SlotDefinition]`	`[]`	Rules per slot position.
`slots`	`Array[SlotData]`	`[]`	Actual slot data storage.

Signals:

Signal	Description
`inventory_changed`	Emitted when any change occurs.
`slot_changed(slot_index: int)`	Emitted when a specific slot changes.
`item_added(item: ItemDefinition, count: int)`	Emitted after item added.
`item_removed(item: ItemDefinition, count: int)`	Emitted after item removed.

Methods:

Method	Description
`get_slot(index: int) -> SlotData`	Returns slot data at index, or `null`.
`set_slot(index, item, count)`	Directly sets slot contents.
`add_item(item, amount: int = 1) -> int`	Adds item. Returns remaining amount not added.
`remove_item(item, amount: int = 1) -> bool`	Removes item. Returns `true` if any removed.
`can_accept_at_slot(item, slot_index, amount: int = 1) -> bool`	Checks if slot accepts item, factoring in dynamic rule limits.
`clear()`	Empties all slots.
`consume_durability(item, slot_index, amount: int = 1) -> bool`	Reduces durability. Returns `true` if item broke.
`debug_print(label: String = "Inventory")`	Prints inventory contents to console.

ItemDefinition¶

Extends: Resource
Data definition for a game item.

Properties:

Group	Property	Type	Description
Identity	`id`	`String`	Unique identifier.
	`display_name`	`String`	Name shown to player.
	`description`	`String`	Item description.
	`icon`	`Texture2D`	UI icon.
Stacking	`max_stack_size`	`int`	Maximum items per slot.
	`weight`	`float`	Item weight.
Durability	`has_durability`	`bool`	Whether item degrades.
	`max_durability`	`int`	Maximum durability value.
	`durability_loss_per_use`	`int`	Durability lost per use.
	`break_on_zero`	`bool`	Whether item disappears at zero.
Visuals	`model_scene`	`PackedScene`	3D model for dropped item/equipping.
	`placement_scene`	`PackedScene`	Scene used for placement logic.
	`preview_offset`	`Vector3`	Position offset for placement preview.
Behavior	`logic_script`	`Script`	Script inheriting from `ItemLogic`.
State	`default_durability`	`int`	Starting durability.
Metadata	`tags`	`Array[String]`	Categorization tags.
	`equipment_type`	`int`	Defines equipment slot (-1 = none).
	`custom_metadata`	`Dictionary`	Extensible data storage.

Methods:

Method	Description
`is_broken(current_durability: int) -> bool`	Returns `true` if durability <= 0.
`get_durability_percent(current_durability: int) -> float`	Returns 0.0 to 1.0 durability ratio.
`has_tag(tag: String) -> bool`	Checks if item has tag.
`get_meta_value(key: String, default)`	Gets custom metadata value.
`set_meta_value(key: String, value)`	Sets custom metadata value.
`is_equipment_type(type: int) -> bool`	Compares equipment type.

ItemLogic¶

Extends: RefCounted
Base class for item behaviors. Assigned to ItemDefinition.logic_script.

Signals:

Signal	Description
`use_started`	Emitted when use begins.
`use_ended`	Emitted when use ends.
`use_finished(item: ItemDefinition, success: bool)`	Emitted when use completes.

Methods:

Method	Description
`setup(item, player, slot_index, weapon_model, inventory)`	Called with full context by the `EquipmentManager`.
`on_input(event: InputEvent)`	Raw input event passed from `EquipmentManager`.
`can_use() -> bool`	Returns `true` if item can be used.
`on_primary_use(slot_index: int = -1)`	Called on primary action (Left Click).
`on_secondary_use(slot_index: int = -1)`	Called on secondary action (Right Click).
`on_release()`	Called when use button released.
`update(delta: float)`	Called every frame while active.
`cleanup()`	Called when the item is unequipped. Override to free custom nodes.
`_consume_item_durability(slot_index, amount: int = 1) -> bool`	Reduces durability, returns `true` if broken.

SlotData¶

Extends: Resource
Data container for a single inventory slot.

Properties:

Property	Type	Default	Description
`item`	`ItemDefinition`	`null`	Item in this slot.
`count`	`int`	`0`	Quantity of item.
`current_durability`	`int`	`-1`	Current durability (-1 = no durability).

Methods:

Method	Description
`get_effective_durability() -> int`	Returns current durability or max if not set.
`is_empty() -> bool`	Returns `true` if item is null or count <= 0.
`is_broken() -> bool`	Returns `true` if item has durability and durability <= 0.
`set_value(item, count, durability: int = -1)`	Sets all slot values.
`clear()`	Resets slot to empty.
`copy() -> SlotData`	Creates a duplicate of this slot.

SlotDefinition¶

Extends: Resource
Defines rules for a specific slot position.

Properties:

Property	Type	Description
`display_name`	`String`	Slot label.
`icon_placeholder`	`Texture2D`	Empty slot icon.
`rules`	`Array[SlotRule]`	Rule instances applied to slot.
`allow_drag_out`	`bool`	Whether items can be dragged from slot.
`allow_right_click`	`bool`	Whether right-click actions work.
`custom_data`	`Dictionary`	Extensible data.

Methods:

Method	Description
`can_accept_item(item, slot_index, inventory, amount: int = 1) -> bool`	Checks all rules.
`get_rejection_reason(item, slot_index) -> String`	Returns first failure reason.
`get_max_allowed_amount(item, current_count, inventory) -> int`	Returns max stack size allowed by rules.
`is_locked() -> bool`	Checks if slot is locked by rules.

4. Slot Rules¶

SlotRule (Base Class)¶

Extends: Resource
Base class for slot restrictions.

Properties:

Property	Type	Description
`rule_name`	`String`	Display name for rule.

Methods:

Method	Description
`can_accept_item(item, slot_index, inventory, amount: int = 1) -> bool`	Returns `true` if item allowed.
`get_rejection_reason(item, slot_index) -> String`	Returns explanation.
`get_invalid_drop_feedback() -> Color`	Returns color to flash on invalid drop.
`get_max_allowed_amount(item, current_count, inventory) -> int`	Returns max stack size allowed. Return `-1` to defer to item default.
`item_has_tag(item, tag) -> bool`	(Static) Helper to check tags.

Built-in Rules¶

Class	Properties	Description
`EquipmentTypeRule`	`equipment_type: int`	Locks a slot to a specific integer `equipment_type`.
`ItemTagRule`	`required_tags: Array[String]`, `match_any: bool`	Requires items to have specific string tags.
`MaxOneRule`	(None)	Prevents stacking (max stack size 1). Implements `get_max_allowed_amount` to return `1`.

5. Systems¶

InventoryTransfer¶

Extends: RefCounted
Static utility class for moving items between inventories.

Methods:

Method	Description
`transfer(source, target, source_slot_index, amount: int = 0) -> int`	Moves items to first available slot. Returns moved count.
`drop_to_slot(source, target, src_idx, tgt_idx, amount: int) -> bool`	Moves items to specific slot. Handles stacking and swapping.
`quick_move(source, target, source_slot_index) -> bool`	Moves item to compatible slot in target inventory.

6. UI Components¶

InventoryUI (Base Class)¶

Extends: Control
Base class for inventory display panels.

Properties:

Property	Type	Default	Description
`source_component`	`InventoryComponent`	`null`	Inventory component to display.
`auto_bind_to_owner`	`bool`	`true`	Automatically finds `InventoryComponent` on owner.
`defer_binding`	`bool`	`false`	Skips `_bind_inventory()` in `_ready()` (used by `InventoryBinder`).

Methods:

Method	Description
`bind_inventory(inv: Inventory)`	Manually binds an inventory to the UI.

ModularInventoryPanel¶

Extends: InventoryUI
Full inventory grid panel.

Properties:

Property	Type	Description
`grid_container`	`GridContainer`	Container for slot nodes.
`slot_scene`	`PackedScene`	Scene to instantiate for each slot.
`tooltip`	`ItemTooltip`	Tooltip display node.

ModularHotbar¶

Extends: InventoryUI
Hotbar with selection and mouse wheel navigation.

Properties:

Property	Type	Default	Description
`slots_container`	`HBoxContainer`	Required	Container for hotbar slots.
`hotbar_size`	`int`	`9`	Number of visible slots.
`start_index`	`int`	`0`	Starting inventory slot index.
`enable_scroll_navigation`	`bool`	`true`	Enable mouse wheel slot cycling.
`scroll_wraps`	`bool`	`true`	Wrap around at ends.
`selected_index`	`int`	`0`	Currently selected hotbar position.

Signals:

Signal	Description
`selection_changed(new_index: int)`	Emitted when selection changes.

Methods:

Method	Description
`get_selected_global_index() -> int`	Returns inventory slot index of selected position.

SlotUI¶

Extends: Control
Individual inventory slot display.

Properties:

Property	Type	Default	Description
`slot_index`	`int`	`-1`	The index of this slot in the inventory.
`enable_tooltip`	`bool`	`true`	Show item tooltip on hover.
`tooltip_delay`	`float`	`0.3`	Seconds before tooltip appears.

Signals:

Signal	Description
`slot_input_event(event: InputEvent)`	Emitted for all input events.
`tooltip_requested(slot_data, global_pos)`	Emitted to request tooltip display.
`tooltip_hidden()`	Emitted when tooltip should hide.

Methods:

Method	Description
`set_slot_data(slot_data: SlotData, index: int)`	Updates display with slot data.
`set_drop_valid(is_valid: bool)`	Highlights slot as valid/invalid drop target.
`set_hotbar_selected(is_selected: bool)`	Highlights slot as active hotbar selection.
`generate_tooltip_text(slot_data) -> String`	(Static) Returns formatted BBCode tooltip text.

ItemTooltip¶

Extends: Control
Floating tooltip that follows mouse.

Properties:

Property	Type	Default	Description
`tooltip_label`	`RichTextLabel`	Required	Label for formatted text.
`offset`	`Vector2`	`(16, 16)`	Offset from mouse position.
`max_width`	`int`	`250`	Maximum tooltip width.

Methods:

Method	Description
`show_tooltip(slot_data, screen_pos)`	Displays tooltip at position.
`hide_tooltip()`	Hides tooltip.

InventoryBinder & SlotGrid (Advanced UI)¶

InventoryBinder (Control): Automatically searches its children for SlotUI nodes and binds them to an Inventory. Handles tooltip routing and quick-move logic.

Method: bind_inventory(inv: Inventory)

SlotGrid (GridContainer): Dynamically generates SlotUI nodes based on a slot_count export.

Properties: slot_scene, start_index, slot_count.
Method: bind_inventory(inv: Inventory)

7. World Objects¶

DroppedItem¶

Extends: RigidBody3D
Physical item that can be picked up.

Properties:

Property	Type	Description
`item_`	`ItemDefinition`	Item definition.
`count`	`int`	Quantity.
`durability`	`int`	Durability of dropped item.

Behavior: Automatically creates model from item_.model_scene or fallback cube.