Skip to content

Inventory API

Jump to bottom
Oen44 edited this page Jun 5, 2026 · 7 revisions

InventorySystem

Description

Main system for controlling the inventory. Handles base items and moving_items between inventories.

Properties

items_path: String # Directory where ItemBase resources are located.
player_inventory: String # ID of the player's inventory.
default_currency: ItemBase # Default currency item to use in the system.
held_item: InventoryItem # UI element that follows the cursor when holding an item.
held_item_quantity: Label # Label to show the quantity of the held item if it's stackable.

Methods

## Registers a new inventory with the system.
register_inventory(inventory: InventoryModel) -> void
## Unregisters an inventory from the system.
unregister_inventory(inventory: InventoryModel) -> void
## Retrieves an inventory by its ID.
get_inventory(inventory_id: String) -> InventoryModel
## Convenience method for accessing the player's inventory
get_player_inventory() -> InventoryModel
## Picks up an item to be held by the cursor.
pick_up_item(item: Item) -> void
## Drops the currently held item (if any).
drop_held_item() -> void
## Retrieves the currently held item.
get_held_item() -> Item
## Returns true if the user is currently holding an item.
is_holding_item() -> bool
## Called when an InventoryItem is hovered/unhovered (typically from UI signals).
on_item_hover(inventory_item: InventoryItem, hovered: bool) -> void
## Retrieves a base item by its ID.
get_item_base(item_id: String) -> ItemBase
## Retrieves the default currency item.
get_currency_item() -> ItemBase

Signals

# Emitted when a new inventory is registered with the system.
inventory_registered(inventory: InventoryModel)
# Emitted when an inventory is unregistered from the system.
inventory_unregistered(inventory: InventoryModel)

BaseInventoryModel

Description

Base class for inventory models, providing common functionality for different inventory types.

Properties

id: String ## Unique identifier for this inventory, used for saving.

Methods

## Stacks item A with item B, if item B can be stacked with item A
stack_items(item_a: Item, item_b: Item) -> bool

InventoryModel

Description

Manages the inventory data structure.

Handles adding, removing, and querying items. Saves and loads inventory state from disk. Saves inventory to disk using its unique ID. Uses binary serialization for items.

Properties

config: InventoryConfig ## Configuration for this inventory
inventory_view: InventoryView
items: Dictionary[int, Item] ## Maps slot index to InventoryItem
empty_slot: int ## Tracks the lowest empty slot index for efficient empty slot search

Methods

## Initializes the inventory (registers it in InventorySystem, initializes view, connects input, and loads from disk).
init() -> void
## Used for temporary inventories, ones that can be removed completely.
## Example: party member inventory that is wiped when they leave the party.
destroy() -> void
## Returns true if the inventory can create the given quantity of the specified ItemBase (based on stacking rules and free slots).
can_create_item(item_base: ItemBase, quantity: int = 1) -> bool
## Returns true if the inventory can create the given quantity of the item with the specified base ID.
can_create_item_by_id(item_id: String, quantity: int = 1) -> bool
## Creates (adds) an item with the given base ID and quantity, if possible.
create_item_by_id(item_id: String, quantity: int = 1) -> bool
## Creates (adds) an item with the given base and quantity, if possible.
create_item(item_base: ItemBase, quantity: int = 1) -> bool
## Creates (adds) an item at the specified slot index, if the slot is empty.
create_item_at(slot_index: int, item_base: ItemBase, quantity: int = 1) -> bool
## Returns true if the provided Item can be added to the inventory (based on stacking rules and free slots).
can_add_item(item: Item) -> bool
## Adds an existing Item instance into the inventory (preserving the item data).
add_item(item: Item) -> bool
## Adds an existing Item instance into the inventory at a specific slot (if empty).
add_item_at(item: Item, slot_index: int) -> bool
## Removes the given item from the inventory (based on its slot_id).
remove_item(item: Item) -> void
## Removes the item at the specified slot index.
remove_item_at(slot_index: int) -> void
## Removes a quantity of items matching the specified base ID (consuming stacks as needed).
remove_item_by_id(item_id: String, quantity: int = 1) -> void
## Removes currency by amount using the system currency item (if configured).
remove_currency(amount: int) -> bool
## Returns the item located at the given slot index, or null if empty.
get_item_at(slot_index: int) -> Item
## Returns the number of empty slots currently available.
get_empty_slot_count() -> int
## Returns the total quantity of an item across the inventory (summed across all stacks) for the specified base ID.
get_item_count(item_id: String) -> int
## Returns the total currency amount currently held in this inventory.
get_currency_amount() -> int

Signals

# Emitted after inventory is loaded from disk.
loaded
# Emitted when an item is added to the inventory.
item_added(item: Item, slot_index: int)
# Emitted when an item is removed from the inventory.
item_removed(slot_index: int)
# Emitted when an item is used (right-clicked) from the inventory.
item_used(inventory_item: InventoryItem)

InventoryConfig

Description

Configuration resource for an inventory. Controls slot count, auto-loading, interaction rules, persistence, and containment restrictions.

Properties

slots: int # Number of slots in the inventory.
autoload: bool # If true, inventory will automatically load on ready.
interactable: bool # If false, items cannot be placed into this inventory, but can still be removed (for containers or loot piles).
persistent: bool # If true, inventory will be saved.
contained: bool # If true, only items coming from this inventory can be placed back into it.
whitelist: Array[String] # List of inventory IDs that are allowed to place items into this inventory.

InventoryView

Description

Displays the inventory UI.

Contains slots for items and handles user interaction.

Properties

inventory_model: InventoryModel # The InventoryModel this view is displaying.

Methods

## Initializes the view with an InventoryModel and populates slots based on its config.
init(model: InventoryModel) -> void
## Clears existing slots and creates slot nodes based on the model's configured slot count.
_populate_slots() -> void
## Sets


# InventorySlot

### Description
Represents a single slot in the inventory UI.

Can hold an InventoryItem or be empty.

### Properties
```gdscript
quantity_label: Label # Label used to display the stack quantity for stackable items.

Methods

## Sets an InventoryItem as the slot contents and updates quantity label for stackable items.
set_item(inventory_item: InventoryItem) -> void
## Removes the InventoryItem from this slot (if present) and clears the quantity label.
remove_item() -> void
## Returns the InventoryItem currently in this slot, or null if empty.
get_inventory_item() -> InventoryItem
## Returns the Item currently in this slot, or null if empty.
get_item() -> Item

Signals

# Emitted when the slot is clicked.
slot_clicked(slot: InventorySlot, button: MouseButton, ctrl_pressed: bool, shift_pressed: bool)

InventoryItem

Description

Holds item data and displays its icon.

Every inventory item is based on ItemBase resource. Per item instance data is stored here.

Properties

item: Item # Item instance stored by this UI element.

Methods

## Creates a new Item instance from an ItemBase and sets the icon accordingly.
create_item(item_base: ItemBase, quantity: int = 1) -> void
## Assigns an existing Item instance to this InventoryItem and updates the icon.
set_item(new_item: Item) -> void
## Returns the Item instance stored in this InventoryItem.
get_item() -> Item
## Updates the displayed texture based on the current item's base icon (or clears it if none).
_update_icon() -> void

QuantitySelector

Properties

item_icon: TextureRect
item_name_label: Label
quantity_label: RichTextLabel
slider: HSlider
confirm_button: Button
cancel_button: Button
item: Item

Methods

## Confirms the selected quantity and emits confirmed(quantity).
_on_confirm_pressed() -> void
## Cancels selection and emits canceled.
_on_cancel_pressed() -> void
## Assigns the item being split and initializes UI (icon, name, slider range, and quantity label).
set_item(new_item: Item) -> void
## Updates the quantity label when the slider value changes.
_on_slider_value_changed(value: float) -> void

Signals

# Emitted when the user confirms a quantity selection.
confirmed(quantity: int)
# Emitted when the user cancels the quantity selection.
canceled

Clone this wiki locally