# 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:
   ```csharp
   // 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:

```xml
<!-- 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:
   ```csharp
   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.
