Migration Guide

This guide helps you upgrade from Stack Inventory v0.x to v1.0.0.

Breaking Changes

1. ActionSettingsResource → ActionSettings

What Changed:

• ActionSettingsResource (Godot Resource) removed
• Replaced with ActionSettings (POCS class)
• Same structure, different implementation

Migration Steps:

Step 1: Find All Uses

Search your project for:

ActionSettingsResource

Step 2: Update Type References

Before (v0.x):

using StackInventory.Game.Resources;

public partial class MyNode : Node
{
    [Export] public ActionSettingsResource Settings { get; set; }
}

After (v1.0.0):

using StackInventory.Game.Settings;  // Changed namespace!

public partial class MyNode : Node
{
    [Export] public ActionSettings Settings { get; set; }
}

Step 3: Update Resource Files

Your .tres files will need recreation:

Old file (res://settings/my_actions.tres):

[ext_resource type="Script" path="res://addons/stack_inventory_cs/Game/Resources/ActionSettingsResource.cs" id="1"]

[resource]
script = ExtResource("1")
DropStrength = 300.0
PickupRadius = 50.0

New approach - Use C# initialization:

// In your scene/script
Settings = new ActionSettings
{
    DropStrength = 300f,
    PickupRadius = 50f
};

Or create a new Resource wrapper (advanced):

// Create your own wrapper if you prefer .tres files
public partial class MyActionSettings : Resource
{
    private ActionSettings _settings = new();

    [Export] public float DropStrength
    {
        get => _settings.DropStrength;
        set => _settings.DropStrength = value;
    }

    [Export] public float PickupRadius
    {
        get => _settings.PickupRadius;
        set => _settings.PickupRadius = value;
    }

    public ActionSettings GetSettings() => _settings;
}

2. IItem Interface Introduction

What Changed:

• New IItem interface for item abstraction
• Both ItemDefinition and Item implement it
• All methods now accept IItem instead of concrete types

Migration Impact:

Before (v0.x):

public void AddItem(ItemDefinition definition, int amount)
{
    // Only worked with ItemDefinition
}

After (v1.0.0):

public void AddItem(IItem item, int amount)
{
    // Works with BOTH ItemDefinition AND Item!
}

Benefits:

• ✅ No code changes needed if passing ItemDefinition
• ✅ Now also accepts Item POCS for serialization
• ✅ More flexible, same or better performance

3. Pickup2D.Item Property

What Changed:

• Pickup2D.Item is now a computed property
• Returns ItemDefinition as IItem (just a cast)
• Cannot be assigned directly

Migration Steps:

Before (v0.x):

pickup.Item = null;  // Could directly assign

After (v1.0.0):

pickup.ItemDefinition = null;  // Assign to ItemDefinition
// pickup.Item automatically returns ItemDefinition as IItem

Why: Zero-overhead access to IItem interface without storing duplicate data.

4. Namespace Changes

Some classes moved namespaces:

Class	Old Namespace	New Namespace
ActionSettings	StackInventory.Game.Resources	StackInventory.Game.Settings
IItem	N/A (new)	StackInventory.Core.Items

Find & Replace:

// Update all imports
using StackInventory.Game.Resources;  // Remove
using StackInventory.Game.Settings;   // Add
using StackInventory.Core.Items;      // Add (for IItem)

New Features

Use Item POCS for Serialization

Before (v0.x): Only ItemDefinition (Godot Resource) available:

// Couldn't easily serialize to JSON/save files

After (v1.0.0): Use Item POCS class:

using StackInventory.Core.Items;

// Serialize with any library!
var item = new Item(
    id: Guid.NewGuid(),
    name: "Sword",
    value: 100f,
    tags: new List<ItemTag>(),
    stackMaximum: 1
);

string json = JsonSerializer.Serialize(item);

Interface-Based APIs

All APIs now accept IItem:

public interface IInventory
{
    void AddItem(IItem item, int amount);
    bool RemoveItem(IItem item, int amount);
    bool HasItem(IItem item);
}

Works with both:

inventory.AddItem(itemDefinition, 10);  // Godot Resource
inventory.AddItem(itemPOCS, 5);         // C# class

Migration Checklist

• Search for ActionSettingsResource

  • Replace with ActionSettings
  • Update namespace: Game.Resources → Game.Settings

• Update .tres files

  • Convert to C# initialization
  • Or create custom wrapper Resources

• Add using StackInventory.Core.Items

  • Wherever you use items

• Test pickup interactions

  • Verify Pickup2D.Item property works
  • Check ItemDefinition assignment

• Consider POCS usage

  • For save systems: use Item class
  • For runtime generation: use Item class
  • For editor-defined items: keep ItemDefinition

• Update method signatures

  • Change ItemDefinition parameters to IItem
  • Enables future flexibility

Example: Full Migration

Before (v0.x):

using StackInventory.Game.Resources;

public partial class Inventory : Node
{
    [Export] public ActionSettingsResource Settings { get; set; }

    public void AddItem(ItemDefinition definition, int amount)
    {
        GD.Print($"Adding {definition.Name}");
        // ... inventory logic
    }
}

After (v1.0.0):

using StackInventory.Core.Items;      // New
using StackInventory.Game.Settings;   // Changed namespace

public partial class Inventory : Node
{
    // No [Export] - initialize in _Ready or constructor
    public ActionSettings Settings { get; set; } = new()
    {
        DropStrength = 300f,
        PickupRadius = 50f
    };

    public void AddItem(IItem item, int amount)  // IItem instead of ItemDefinition
    {
        GD.Print($"Adding {item.Name}");
        // ... inventory logic (no changes needed here!)
    }
}

Testing After Migration

1. Compile and check for errors

   cd godot
   dotnet build

2. Test in Godot Editor

   • Load scenes with Pickup2D nodes
   • Verify Inspector shows properties correctly
   • Test pickup interactions

3. Run your game

   • Test item pickups
   • Test inventory operations
   • Test save/load if using POCS

4. Check for warnings

   • Look for obsolete API usage warnings
   • Update any deprecated code

Learn More

If you need additional help:

1. API Reference - Complete class documentation
2. Getting Started - Review examples
3. Architecture Guide - Understand the design

Performance Notes

v1.0.0 is 10-100x faster than v0.x in many scenarios:

• Direct property access (no lookups)
• Interface casting (zero overhead)
• Optimized tag operations
• Reduced allocations

Your migrated code should run faster without changes!