Skip to content

Quick Start

Get up and running with the Modular Inventory System in just a few steps. This guide will walk you through creating an inventory, defining an item, adding it to the player, and displaying it on the screen.

1. Add InventoryComponent

First, give your Player (or a Chest/Container) an inventory by attaching the InventoryComponent node.

Via Code: 

extends CharacterBody3D

var inventory_component: InventoryComponent

func _ready():
    inventory_component = InventoryComponent.new()
    add_child(inventory_component)
    inventory_component.capacity = 20

Via Editor:

  1. Select your Player node.

  2. Click Add Child Node and search for InventoryComponent.

  3. In the Inspector, set the Capacity (e.g., 20).

  4. Optional: Check Create If Missing so it automatically generates an Inventory resource on startup.

2. Create an Item Definition

Items are data-driven using the ItemDefinition resource.

Via Editor (Recommended):

  1. In the FileSystem dock, right-click your items/ folder and select Create New > Resource.

  2. Search for and select ItemDefinition.

  3. Name it apple.tres.

  4. In the Inspector, fill out the properties:

  5. ID: apple
  6. Display Name: Apple
  7. Max Stack Size: 1
  8. Icon: Drag and drop your 2D Apple icon here.

Via Code: 

var item = ItemDefinition.new()
item.id = "apple"
item.display_name = "Apple"
item.max_stack_size = 1
# item.icon = preload("res://path/to/icon.png")

3. Add Items to Inventory

Now, let's put the item into the player's inventory when the game starts.

extends CharacterBody3D

@export var starting_apple: ItemDefinition

func _ready():
    # ... (InventoryComponent setup from Step 1) ...

    # Wait for the inventory to be ready
    inventory_component.inventory_ready.connect(_on_inventory_ready)

func _on_inventory_ready(inv: Inventory):
    if starting_apple:
        var remaining = inv.add_item(starting_apple, 1)
        if remaining == 0:
            print("Successfully added apple to inventory!")
        else:
            print("Inventory was full or rejected the item.")

4. Setup the UI

To see your inventory, you need to set up the UI components.

Inventory Panel

  1. Add a CanvasLayer to your player scene.
  2. Add a ModularInventoryPanel node as a child of the CanvasLayer.
  3. In the Inspector:
  4. Grid Container: Create a GridContainer child, assign it here, and set its columns (e.g., 5).
  5. Source Component: Drag your player's InventoryComponent node into this slot.
  6. Tooltip: Create an ItemTooltip node somewhere in your UI and assign it here (or leave it empty, and the panel will auto-find it).
  7. Set the panel's visible property to false initially.

Hotbar (Optional)

  1. Add a ModularHotbar node to your CanvasLayer.
  2. In the Inspector:
  3. Slots Container: Create an HBoxContainer child and assign it here.
  4. Source Component: Assign your InventoryComponent.
  5. Hotbar Size: 9
  6. Start Index: 0

5. Toggle the UI

Finally, add a script to your player to open and close the inventory using an Input Action (e.g., map the I or E key to an action named toggle_inventory in Project Settings).

extends CharacterBody3D

@export var inventory_panel: ModularInventoryPanel
@export var toggle_action: StringName = &"toggle_inventory"

func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed(toggle_action):
        toggle_inventory()
        get_viewport().set_input_as_handled()

func toggle_inventory() -> void:
    var is_open = not inventory_panel.visible
    inventory_panel.visible = is_open

    if is_open:
        InputMode.ui()      # Show mouse cursor, release capture
    else:
        InputMode.game()    # Hide mouse cursor, capture for camera

Next Steps