Modular Inventory System - API Reference¶

Overview¶

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

Core Classes¶

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 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: int, item: ItemDefinition, count: int) -> void`	Directly sets slot contents
`add_item(item: ItemDefinition, amount: int = 1) -> int`	Adds item to inventory. Returns remaining amount not added
`remove_item(item: ItemDefinition, amount: int = 1) -> bool`	Removes item. Returns true if any removed
`can_accept_at_slot(item: ItemDefinition, slot_index: int) -> bool`	Checks if slot accepts item
`clear() -> void`	Empties all slots
`consume_durability(item: ItemDefinition, slot_index: int, amount: int = 1) -> bool`	Reduces durability. Returns true if item broke
`debug_print(label: String = "Inventory") -> void`	Prints inventory contents to console

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: ItemDefinition, count: int, durability: int = -1) -> void`	Sets all slot values
`clear() -> void`	Resets slot to empty
`copy() -> SlotData`	Creates a duplicate of this slot

ItemDefinition¶

Extends: Resource

Data definition for a game item.

Property Groups:

Identity

Property	Type	Description
`id`	`String`	Unique identifier
`display_name`	`String`	Name shown to player
`description`	`String`	Item description
`icon`	`Texture2D`	UI icon

Stacking

Property	Type	Default	Description
`max_stack_size`	`int`	1	Maximum items per slot
`weight`	`float`	0.0	Item weight

Durability

Property	Type	Default	Description
`has_durability`	`bool`	false	Whether item degrades
`max_durability`	`int`	100	Maximum durability value
`durability_loss_per_use`	`int`	1	Durability lost per use
`break_on_zero`	`bool`	true	Whether item disappears at zero

Visuals

Property	Type	Description
`model_scene`	`PackedScene`	3D model for dropped item
`placement_scene`	`PackedScene`	Scene used for placement logic
`preview_offset`	`Vector3`	Position offset for placement preview

Behavior

Property	Type	Description
`logic_script`	`Script`	Script inheriting from ItemLogic

State

Property	Type	Default	Description
`default_durability`	`int`	100	Starting durability

Metadata

Property	Type	Description
`tags`	`Array[String]`	Categorization tags
`equipment_type`	`int`	-1 = none, other values define equipment slot
`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 = null)`	Gets custom metadata value
`set_meta_value(key: String, value) -> void`	Sets custom metadata value
`is_equipment_type(type: int) -> bool`	Compares equipment type

InventoryComponent¶

Extends: Node

Node to attach to player or container for inventory access.

Properties:

Property	Type	Default	Description
`inventory`	`Inventory`	`null`	Reference to inventory resource
`capacity`	`int`	20	Used when creating new inventory
`slot_definitions`	`Array[SlotDefinition]`	`[]`	Used when creating new inventory
`create_if_missing`	`bool`	true	Auto-creates inventory if none assigned

Signal:

Signal	Description
`inventory_ready(inv: Inventory)`	Emitted when inventory is available

Method:

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

InventoryTransfer¶

Extends: RefCounted

Static utility class for moving items between inventories.

Methods:

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

Drag and Drop System¶

DragDropSystem¶

Extends: Node (Autoload singleton)

Manages drag operations from UI slots.

Properties:

Property	Type	Description
`is_dragging`	`bool`	True during active drag
`source_inv`	`Inventory`	Source inventory
`source_data`	`SlotData`	Data being dragged
`source_idx`	`int`	Source slot index
`drag_amount`	`int`	Current drag quantity

Signals:

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

Methods:

Method	Description
`start_drag(inv: Inventory, data: SlotData, idx: int, button: MouseButton, is_right_click: bool) -> void`	Begins drag operation
`end_drag() -> void`	Ends current drag
`set_drop_target(target_inv: Inventory, target_idx: int) -> void`	Sets drop target and performs drop

UI Components¶

InventoryUI¶

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

Methods to override:

Method	Description
`_on_inventory_attached(inv: Inventory)`	Called when inventory is bound
`_refresh_all()`	Refresh all slots
`_refresh_slot(idx: int)`	Refresh specific slot

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

Behavior: Automatically groups as modular_inventory_panel. Creates slot UI for each inventory slot.

ModularHotbar¶

Extends: InventoryUI

Hotbar with selection and mouse wheel navigation.

Properties:

Property	Type	Default	Description
`slots_container`	`HBoxContainer`	Required	Container for hotbar slots
`slot_scene`	`PackedScene`	slot_ui.tscn	Scene for each slot
`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

Signal:

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

Method:

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

SlotUI¶

Extends: Control

Individual inventory slot display.

Node Path Properties:

Property	Type	Default
`icon_path`	`NodePath`	`^"Icon"`
`count_label_path`	`NodePath`	`^"CountLabel"`
`placeholder_path`	`NodePath`	`^"Placeholder"`
`durability_bar_path`	`NodePath`	`^"DurabilityBar"`
`durability_fill_path`	`NodePath`	`^"DurabilityFill"`

Properties:

Property	Type	Default	Description
`enable_tooltip`	`bool`	true	Show item tooltip on hover
`tooltip_delay`	`float`	0.3	Seconds before tooltip appears

Signals:

Signal	Description
`drag_started(slot_index: int, button: MouseButton, is_right_click: bool)`	Emitted when drag begins
`drag_ended(slot_index: int)`	Emitted when drag ends
`slot_input_event(event: InputEvent)`	Emitted for all input events
`tooltip_requested(slot_data: SlotData, global_pos: Vector2)`	Emitted to request tooltip display
`tooltip_hidden()`	Emitted when tooltip should hide

Methods:

Method	Description
`set_slot_data(slot_data: SlotData, index: int) -> void`	Updates display with slot data
`set_drop_valid(is_valid: bool) -> void`	Highlights slot as valid drop target
`generate_tooltip_text(slot_data: SlotData) -> String`	Static method. Returns formatted 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`	`Vector2(16, 16)`	Offset from mouse position
`max_width`	`int`	250	Maximum tooltip width

Methods:

Method	Description
`show_tooltip(slot_data: SlotData, screen_pos: Vector2) -> void`	Displays tooltip at position
`hide_tooltip() -> void`	Hides tooltip

UICoordinator¶

Extends: Node (Autoload singleton)

Static methods for positioning inventory panels.

Methods:

Method	Description
`position_inventory(ui: Control, role: String, other_ui: Control = null) -> void`	Positions UI panel. Roles: "player", "container", "centered"
`reset_inventory(ui: Control) -> void`	Resets to default positioning

Slot Rules System¶

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

Method:

Method	Description
`can_accept_item(item: ItemDefinition, slot_index: int, inventory: Inventory) -> bool`	Checks all rules
`get_rejection_reason(item: ItemDefinition, slot_index: int) -> String`	Returns first failure reason

SlotRule (base class)¶

Extends: Resource

Base class for slot restrictions.

Properties:

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

Methods to override:

Method	Description
`can_accept_item(item: ItemDefinition, slot_index: int, inventory: Inventory) -> bool`	Returns true if item allowed
`get_rejection_reason(item: ItemDefinition, slot_index: int) -> String`	Returns explanation

Available SlotRule Types¶

Class	Description
`ItemTagRule`	Requires item to have specific tags. Properties: `required_tags: Array[String]`, `match_any: bool`
`EquipmentTypeRule`	Requires matching equipment_type value. Property: `equipment_type: int`
`MaxOneRule`	Prevents stacking (max stack size 1)

Item Logic System¶

ItemLogic (base class)¶

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
`tool_used(item: ItemDefinition, user: Node3D, direction: Vector3, range: float)`	Emitted for tool usage

Methods to override:

Method	Description
`setup(item: ItemDefinition, player: Node) -> void`	Called before first use
`can_use() -> bool`	Returns true if item can be used
`on_primary_use(slot_index: int = -1) -> void`	Called on primary action
`on_secondary_use(slot_index: int = -1) -> void`	Called on secondary action
`on_release() -> void`	Called when use button released
`update(delta: float) -> void`	Called every frame while active

Protected method:

Method	Description
`_consume_item_durability(slot_index: int, amount: int = 1) -> bool`	Reduces durability, returns true if broken

Available Logic Implementations¶

Class	Description
`ConsumableLogic`	Food/drink items. Properties: hunger_restore, health_restore, stamina_restore, use_duration, consume_sound
`PlacementLogic`	Place objects in world. Properties: grid_size, use_grid_snap, max_slope_angle, placement_layer_mask, ghost_opacity, rotation_step
`RangedLogic`	Bow/gun weapons. Properties: projectile_scene, charge_speed, max_charge, arrow_tag, draw_sound, release_sound

Input Mode¶

InputMode¶

Extends: Node (Autoload singleton)

Controls mouse capture state for 3D games.

Properties:

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

Methods:

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

World Objects¶

DroppedItem¶

Extends: Node3D

Physical item that can be picked up.

Properties:

Property	Type	Description
`item_`	`ItemDefinition`	Item definition
`count`	`int`	Quantity

Behavior: Automatically creates model from item_.model_scene or fallback cube. Requires PickupComponent (not included in this API).

Autoload Singletons¶

Name	File
`DragDropSystem`	core/drag_drop_system.gd
`InputMode`	components/InputMode.gd
`UICoordinator`	ui/UICoordinator.gd