RPG-RougeLiteBattler/SHOP_MIGRATION_GUIDE.md

Shop System Migration Guide

Overview

The shop system has been updated to use ScriptableObject-based Item assets instead of hardcoded SimpleShopItem data. This allows for better data management, persistence, and easier content creation.

What Changed

Old System (SimpleShopManager)

• Used hardcoded SimpleShopItem objects created in code
• Items were temporary and lost when the game closed
• Limited flexibility for item properties

New System (ItemShopManager)

• Uses Item ScriptableObjects that persist as asset files
• Supports WeaponItem, ArmorItem, and MiscellaneousItem types
• Items can be created and modified in the Unity Inspector
• Items are loaded automatically from the Resources/Items folder

Migration Steps

1. Run the Migration Tool

In Unity, go to the menu: RPG > Migrate Shop System

This will:

• Convert any SimpleShopManager components to ItemShopManager
• Preserve existing settings like shop name
• Save the scene automatically

2. Create Sample Items (Optional)

Run: RPG > Create Sample Items

This creates example items including:

• Simple Sword, Simple Bow, Iron Sword (Weapons)
• Leather Armor, Iron Chainmail (Armor)
• Health Potion, Mana Potion, Hemp Rope (Miscellaneous)

3. Verify Setup

Run: RPG > Verify Shop Setup

This checks:

• ItemShopManager components are present
• No old SimpleShopManager components remain
• Items are properly loaded
• UI components are configured

Creating New Items

Via Unity Menu

1. Right-click in Project window
2. Go to Create > RPG > Items
3. Choose Weapon, Armor, or Miscellaneous
4. Configure the item properties in the Inspector
5. Save the asset in Assets/Resources/Items/ (or subfolders)

Item Properties

All Items (Base Item class)

• Item Name: Display name
• Description: Item description
• Icon: Item icon sprite
• Model 3D: 3D representation
• Item Type: Weapon, Armor, Consumable, Tool, Accessory, Miscellaneous
• Rarity: Common, Uncommon, Rare, Epic, Legendary
• Cost: Gold, Silver, Copper prices
• Search Tags: Keywords for shop search functionality

Weapon Items

• Min/Max Damage: Damage range
• Range: Attack range
• Weapon Modifier: Bonus to hit
• Attack Speed: Animation speed
• Weapon Type: Sword, Bow, Crossbow, etc.
• Weapon Class Name: Code class to instantiate

Armor Items

• Armor Class: AC bonus
• Attribute Modifiers: STR, DEX, CON, WIS bonuses/penalties
• Armor Type: Light, Medium, Heavy, Shield
• Armor Slot: Head, Chest, Legs, etc.

Miscellaneous Items

• Is Consumable: Whether item is used up
• Is Stackable: Whether items can stack
• Max Stack Size: Maximum stack count
• Health/Mana Restoration: Dice-based or range-based healing

Shop Features

Automatic Item Loading

The ItemShopManager automatically loads all Item ScriptableObjects from:

• Assets/Resources/Items/ folder and all subfolders
• Direct Assets/Resources/ folder (as fallback)

Filtering and Search

• Category Filter: Filter by item type (Weapons, Armor, etc.)
• Search Field: Search by item name, description, or tags
• Combined Filtering: Category and search work together

Purchase System

• Checks if player can afford items
• Handles gold/silver/copper currency conversion
• Updates player money automatically
• Adds purchased items to character inventory (requires inventory system integration)

Integration Notes

Character Inventory

The shop calls AddItemToCustomerInventory(Item item) when items are purchased. You'll need to implement this method based on your inventory system:

private void AddItemToCustomerInventory(Item item)
{
    // Example integration:
    currentCustomer.inventory.AddItem(item);
    
    // Or if using a different system:
    InventoryManager.Instance.AddItemToCharacter(currentCustomer, item);
}

Bank System

The shop uses a Bank helper class for currency operations. The current implementation converts between character money and the bank format automatically.

UI Integration

The shop uses the existing ShopUI.uxml file. Make sure the UIDocument component has this visual tree asset assigned.

File Structure

Assets/
├── Resources/
│   └── Items/
│       ├── Weapons/
│       │   ├── SimpleSword.asset
│       │   ├── SimpleBow.asset
│       │   └── IronSword.asset
│       ├── Armor/
│       │   ├── LeatherArmor.asset
│       │   └── IronChainmail.asset
│       └── Miscellaneous/
│           ├── HealthPotion.asset
│           ├── ManaPotion.asset
│           └── HempRope.asset
├── Scripts/
│   ├── Objects/Items/
│   │   ├── Item.cs (base class)
│   │   ├── WeaponItem.cs
│   │   ├── ArmorItem.cs
│   │   └── MiscellaneousItem.cs
│   ├── UI/
│   │   ├── ItemShopManager.cs (new)
│   │   └── SimpleShopManager.cs (deprecated)
│   └── Editor/
│       ├── CreateSampleItems.cs
│       └── ShopSystemMigrator.cs

Troubleshooting

"No items found" in shop

1. Check that items are saved in Assets/Resources/Items/ or subfolders
2. Run RPG > Create Sample Items to create test items
3. Run RPG > Verify Shop Setup to check configuration

Shop not opening

1. Verify ItemShopManager component exists in scene
2. Check that UIDocument has ShopUI.uxml assigned
3. Ensure MainTeamSelectScript is updated to use ItemShopManager

Compile errors

1. Make sure all old SimpleShopManager references are updated to ItemShopManager
2. Check that the new script files are properly imported
3. Verify all required using statements are present

Benefits of New System

1. Persistent Data: Items are saved as asset files
2. Designer Friendly: Non-programmers can create items in Unity Inspector
3. Version Control: Item assets can be tracked in source control
4. Modular: Easy to add new item types and properties
5. Performance: Items are loaded once at startup
6. Flexible: Supports complex item properties and behaviors

Next Steps

1. Create your own custom items using the Unity Inspector
2. Integrate the shop with your character inventory system
3. Add item icons and 3D models to enhance visual presentation
4. Consider adding item tooltips and detailed stat displays
5. Implement item rarity-based visual effects in the shop UI