Stack Inventory v1.0.0

Welcome to the Stack Inventory documentation! A high-performance, interface-based inventory system for Godot 4 C# projects.

Key Features

Interface-Based Architecture

• Unified IItem interface for both Resources and POCS classes
• Zero-overhead performance with direct property access
• No conversion overhead in hot paths
• Works seamlessly with both editor-defined and runtime-generated items

Flexible Item Creation

• ItemDefinition Resources - Visual editing in Godot Inspector
• Item POCS Classes - Runtime creation, serialization, networking
• Both implement the same IItem interface

Comprehensive Testing

• 191 total tests ensuring reliability
  • 143 xUnit tests (POCS logic)
  • 48 GoDotTest tests (Godot integration)
• Full coverage of core functionality

High Performance

• 10-100x faster than string-based lookup systems
• Zero allocations for interface casts
• Cache-friendly data structures
• Optimized for item-heavy games

Quick Links

• Getting Started - Set up your first inventory
• API Reference - Complete class documentation
• Migration Guide - Upgrade from previous versions
• Architecture Overview - Understand the design

Key Features

Zero-Overhead Interface Usage

// Before (old pattern - still works)
Item item = itemDefinition.ToCore();  // Creates new object

// After (new pattern - recommended)
IItem item = itemDefinition;  // Just a cast, zero allocation!

Hierarchical Tag System

// Define tag hierarchy in editor
var equipment = new ItemTagDefinition { Name = "Equipment" };
var weapon = new ItemTagDefinition { Name = "Weapon", Parent = equipment };

// Check tags with hierarchy support
if (itemDef.HasTag(equipment.ToCore()))
{
    GD.Print("This is equipment!");
}

Flexible Stack Management

// Intelligent stacking with overflow handling
var pickup = new Pickup2D
{
    ItemDefinition = swordDef,
    Amount = 10
};

var takenAmount = player.TryTake(pickup);
// Automatically distributes across available stacks

Architecture

Stack Inventory uses a three-layer architecture:

1. Core Layer (POCS)

Pure C# interfaces and classes:

• IItem - Item interface
• Item - POCS class for serialization
• ItemTag - Tag with hierarchy support
• IActionSettings - Settings interface

2. Game Layer (Godot Resources)

Resources implementing core interfaces:

• ItemDefinition - Implements IItem
• ItemTagDefinition - Converts to ItemTag
• ActionSettings - Implements IActionSettings

3. UI Layer (Godot Nodes)

Nodes using interfaces:

• Pickup2D - Uses IItem
• StackView - Uses IActionSettings
• ItemCountsView - Uses IItem

Benefits

✅ Performance - Zero-overhead interface casts
✅ Flexibility - Easy serialization and network support
✅ Testability - Pure C# logic testable with xUnit
✅ Integration - Seamless Godot editor integration
✅ Maintainability - Clean separation of concerns

Breaking Changes

Only ONE breaking change: ActionSettingsResource renamed to ActionSettings

Migration time: ~5 minutes (simple find/replace)

See the Migration Guide for details.

Next Steps

1. Install Stack Inventory
2. Follow the Quick Start
3. Explore the API
4. Read Architecture Guide