Getting Started

This guide will help you set up and use Stack Inventory in your Godot 4 project.

Prerequisites

• Godot 4.2+ with .NET support
• C# knowledge (basic to intermediate)
• Your project must be a C# project

Installation

Option 1: Clone as Submodule (Recommended)

cd your-godot-project
git submodule add https://github.com/ChrisTutorials/stack_inventory_godot.git addons/stack_inventory_godot
git submodule add https://github.com/ChrisTutorials/stack_inventory_cs.git addons/stack_inventory_cs

Option 2: Download

1. Download the latest release from GitHub
2. Extract to your project’s addons/ folder
3. Ensure both stack_inventory_godot and stack_inventory_cs are present

Enable the Plugin

1. Open your project in Godot
2. Go to Project > Project Settings > Plugins
3. Enable Stack Inventory
4. Restart Godot Editor

Quick Example: Your First Item

Step 1: Create an Item Definition

Create a new Resource file: res://items/health_potion.tres

# In the Inspector, set:
Script: ItemDefinition
Name: "Health Potion"
Value: 50.0
Stack Maximum: 99
Icon: (load your icon texture)
Tooltip: "Restores 50 health points"

Step 2: Create a Pickup

Create a new scene with Pickup2D as the root:

// In your pickup scene's script
using Godot;
using StackInventory.Game.Definitions;

public partial class HealthPotionPickup : Pickup2D
{
    public override void _Ready()
    {
        base._Ready();

        // The Item property gives you IItem interface access
        GD.Print($"Pickup ready: {Item.Name}");
        GD.Print($"Can stack up to: {Item.StackMaximum}");
    }
}

Step 3: Use in Your Game

// In your player or collector script
public partial class Player : CharacterBody2D
{
    private void OnPickupAreaEntered(Area2D area)
    {
        if (area is Pickup2D pickup)
        {
            var amount = pickup.Amount;
            GD.Print($"Picked up {amount}x {pickup.Item.Name}");

            // Add to inventory (you'll implement this)
            _inventory.AddItem(pickup.Item, amount);

            // Remove from world
            pickup.QueueFree();
        }
    }
}

Understanding the Architecture

Core Concepts

IItem Interface

• Defines what an item is (Name, Value, StackMaximum, etc.)
• Implemented by ItemDefinition (Godot Resource)
• Can also be implemented by pure C# Item class for serialization

Zero-Overhead Access

// No conversion needed!
IItem item = itemDefinition;  // Just a cast

// Access properties directly
string name = item.Name;
int maxStack = item.StackMaximum;

When to Use What

Scenario	Use	Why
Editor-defined items	ItemDefinition (Resource)	Visual editing, direct use
Runtime/procedural items	Item (POCS class)	Flexible creation
Network/save data	Item (POCS class)	Easy serialization
UI display	IItem (interface)	Works with both!

Next Steps

1. Learn about Tags - Tag System Guide
2. Create Containers - Container Guide
3. Build Inventory UI - UI Guide
4. Explore the API - API Reference

Common Patterns

Checking if Item Has Tag

var consumableTag = new ItemTag("Consumable");
if (itemDef.HasTag(consumableTag))
{
    GD.Print("This is a consumable item!");
}

Creating Items Dynamically

// For runtime-created items (not from Resources)
var dynamicItem = new Item(
    id: Guid.NewGuid(),
    name: "Dynamic Sword",
    value: 100f,
    tags: new List<ItemTag>(),
    stackMaximum: 1
);

Using with Inventory Systems

public partial class SimpleInventory : Node
{
    private readonly List<(IItem item, int amount)> _items = new();

    public void AddItem(IItem item, int amount)
    {
        // Check if we already have this item
        var existing = _items.FirstOrDefault(i => i.item.Name == item.Name);
        if (existing.item != null)
        {
            // Stack with existing
            _items[_items.IndexOf(existing)] = (existing.item, existing.amount + amount);
        }
        else
        {
            // Add new
            _items.Add((item, amount));
        }
    }
}

Troubleshooting

”Type or namespace name ‘IItem’ could not be found”

Solution: Ensure you have the using statement:

using StackInventory.Core.Items;

“Property ‘Item’ cannot be assigned to — it is read only”

Solution: Pickup2D.Item is now a computed property. Don’t try to assign it:

// ❌ Wrong
pickup.Item = something;

// ✅ Correct
pickup.ItemDefinition = itemDefinition;
// Item property automatically returns ItemDefinition as IItem

Items Not Stacking Properly

Solution: Ensure StackMaximum is set > 1:

itemDef.StackMaximum = 99;  // Can stack up to 99

Learn More

• API Reference - Complete class documentation
• Architecture Guide - Understand the three-layer design
• Tag System - Work with hierarchical tags