RPG-RougeLiteBattler/TOWN_SYSTEM_GUIDE.md

Town System Implementation Guide

Overview

This guide explains how to set up a complete interactive town system with shops, an adventurer's guild, harbor, and other buildings. The system uses Unity UI Toolkit (UXML/USS) for all interfaces and provides a modular approach to town management.

Components Created

Core Town System

• TownManager.cs: Main town controller and team data management
• TownShopManager.cs: Handles UI interactions and shop opening logic
• TownBuilding.cs: Base class for all interactive town buildings
• TownShop.cs: Specialized shop buildings with inventory and pricing
• TownShopUI.cs: Complete shop interface with buy/sell functionality

UI Assets

• TownUI.uxml: Main town visual layout with grid-based building system
• TownUI.uss: Comprehensive styling for the town interface
• TownShopUI.uxml: Shop interface (created programmatically if not found)

Setup Instructions

1. Scene Setup

1. Open or create the TownScene.unity
2. Create an empty GameObject called "TownManager"
3. Add the TownManager component to it
4. Create a UI Document GameObject and assign the TownUI.uxml file
5. Link the UI Document to the TownManager's townUI field

2. Shop Configuration

1. Create empty GameObjects for each shop type:

   • "WeaponShop"
   • "ArmorShop"
   • "PotionShop"
   • "GeneralStore"

2. Add the TownShop component to each shop GameObject

3. Configure each shop:

   // Weapon Shop
   shopType = ShopType.Weapons
   shopkeeperName = "Gareth the Smith"
   profitMargin = 1.3f (30% markup)
      
   // Armor Shop  
   shopType = ShopType.Armor
   shopkeeperName = "Miranda the Armorer"
   profitMargin = 1.25f (25% markup)
      
   // Potion Shop
   shopType = ShopType.Potions
   shopkeeperName = "Elias the Alchemist" 
   profitMargin = 1.4f (40% markup)
      
   // General Store
   shopType = ShopType.General
   shopkeeperName = "Old Pete"
   profitMargin = 1.2f (20% markup)
   

3. Shop Manager Setup

1. Create an empty GameObject called "ShopManager"
2. Add the TownShopManager component
3. Assign all shop GameObjects to the allShops array
4. Link the UI Document to the townUI field

4. Item Configuration

The shops will automatically load items from Resources/Items/ folders:

• Resources/Items/Weapons/ - Weapon items
• Resources/Items/Armor/ - Armor items
  
• Resources/Items/Miscellaneous/ - Potions and misc items

5. Building Visual Configuration

The town uses a CSS Grid-like layout defined in the UXML:

<!-- Buildings are positioned in rows -->
<ui:VisualElement name="Row1" class="town-row">
    <ui:VisualElement name="WeaponShop" class="town-building weapon-shop">
        <ui:Label text="Weapon Shop" class="building-label" />
    </ui:VisualElement>
    <!-- ... more buildings -->
</ui:VisualElement>

Buildings are styled with CSS classes in the USS file:

• .weapon-shop - Red building for weapons
• .armor-shop - Blue building for armor
• .potion-shop - Green building for potions
• .general-shop - Orange building for general goods

Features Implemented

Shop System

• Dynamic Pricing: Each shop applies a configurable profit margin to base item prices
• Buy/Sell System: Players can buy items from shops and sell items back at reduced prices
• Inventory Filtering: Shops only accept items of appropriate types
• Search and Categorization: Shop UI includes search and category filters
• Multiple Characters: Support for multi-character teams with individual money

Visual Town Layout

• Grid-Based Design: Buildings arranged in a clear grid with roads between
• Interactive Buildings: Click to enter shops or interact with special buildings
• Color-Coded Buildings: Different building types have distinct colors
• Hover Effects: Buildings highlight when hovering
• Responsive Design: Layout adapts to different screen sizes

Special Buildings (Coming Soon)

• Adventurer's Guild: Quest system and job board
• Harbor: Travel to other locations by sea
• Inn: Rest, healing, and save game functionality
• Houses: NPC interactions and side quests

Item Creation

Creating New Items

1. Right-click in Project window
2. Go to Create > RPG > Items > [Type]

3. Configure the item properties:

   itemName = "Iron Sword"
   description = "A sturdy iron blade"
   goldCost = 25
   silverCost = 0
   copperCost = 0
   rarity = ItemRarity.Common
   

Adding Items to Shops

Items are automatically added to appropriate shops based on their ItemType:

• ItemType.Weapon → Weapon Shop
• ItemType.Armor → Armor Shop
  
• ItemType.Consumable → Potion Shop
• ItemType.Miscellaneous → General Store

You can also manually add items to a shop's baseInventory list.

Shop Economics

Pricing System

• Base Price: Set in the Item ScriptableObject
• Shop Markup: Configurable per shop (typically 20-40%)
• Sell-back Rate: Players get 60% of base price when selling
• Currency: Gold/Silver/Copper system (1g = 10s = 100c)

Example Pricing

Iron Sword (Base: 25g)
- Weapon Shop: 32g 5s (30% markup)  
- Sell back: 15g (60% of base)

Health Potion (Base: 3g)
- Potion Shop: 4g 2s (40% markup)
- Sell back: 1g 8s (60% of base)

Integration with Existing Systems

Team Character System

The town system integrates with the existing TeamCharacter class:

• Reads money from gold, silver, copper fields
• Adds purchased items to weapons, armor, miscItems lists
• Removes sold items from character inventories

Save System

Team data is automatically saved through the existing GameStateManager:

• Money changes persist between scenes
• Inventory changes are maintained
• Shop restock timers are preserved

Scene Transitions

• Return to map via "Return to Map" button
• Automatic save when leaving town
• Team data transfers seamlessly

Customization Options

Visual Theming

Modify TownUI.uss to change:

• Building colors and styles
• Layout and spacing
• Fonts and text styling
• Hover and interaction effects

Shop Behavior

Adjust shop properties:

• profitMargin: How much markup shops apply
• sellbackRate: How much players get when selling
• maxInventorySize: Maximum items per shop
• restockDaily: Whether shops restock over time

Building Layout

Edit TownUI.uxml to:

• Add or remove buildings
• Change building positions
• Modify the grid layout
• Add new building types

Troubleshooting

Common Issues

1. Shops not opening: Ensure TownShopManager is properly configured with shop references
2. Items not loading: Check that items are placed in correct Resources folders
3. UI not displaying: Verify UXML and USS files are properly linked
4. Money not updating: Ensure team data is properly loaded in TownManager

Debug Tips

• Check console for setup completion messages
• Use "Check Shop Setup" context menu on shops
• Verify team data loading in TownManager Start()
• Test with sample items if custom items aren't working

Future Enhancements

Planned Features

• Quest System: Adventurer's Guild with dynamic quests
• NPC Dialogue: Conversations with shopkeepers and townspeople
• Day/Night Cycle: Different shops and activities based on time
• Random Events: Special sales, traveling merchants, etc.
• Building Upgrades: Shops can be improved over time

Extension Points

The system is designed for easy extension:

• Add new BuildingType values for new building types
• Create specialized TownBuilding subclasses
• Implement additional shop types with custom behavior
• Add new UI panels for different interactions

Code Architecture

Key Classes

• TownManager: Central coordinator, loads team data
• TownShopManager: UI event handling and shop interaction
• TownBuilding: Base building class with click handling
• TownShop: Shop-specific logic and inventory management
• TownShopUI: Complete shop interface implementation

Design Patterns

• Component System: Modular building components
• Event-Driven UI: UI events trigger business logic
• Resource Loading: Automatic item discovery and loading
• State Management: Centralized team and shop state

This town system provides a solid foundation for a complete RPG town experience that can be easily extended and customized for your specific game needs.