# 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 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.