# MapScene2 Settlement Interaction Setup Guide

## Overview
This guide explains how to set up the settlement interaction system that allows players to enter towns and villages from the map scene.

## Components Created

### 1. SettlementInteractionManager.cs
**Purpose**: Detects when TeamMarker is near settlements and handles town scene loading
**Key Features**:
- Detects TeamMarker proximity to settlements
- Handles input for entering settlements
- Sets up SettlementContext for scene transitions
- Optional auto-enter when stationary
- Configurable interaction distance and keys

### 2. SettlementInteractionUI.cs
**Purpose**: Displays UI prompts when near settlements
**Key Features**:
- Shows settlement name and interaction instructions
- Automatically appears/disappears based on proximity
- Customizable UI element names
- Clean event-driven architecture

### 3. UI Files
- **SettlementInteractionUI.uxml**: UI layout for interaction prompts
- **SettlementInteractionUI.uss**: Styling for the interaction UI

## Setup Instructions

### Step 1: Add to MapScene2
1. Open your MapScene2 scene
2. Create an empty GameObject called "SettlementInteractionManager"
3. Add the `SettlementInteractionManager` component to it
4. Configure the settings:
   - **Team Marker**: Will auto-find "TeamMarker" GameObject
   - **Interaction Distance**: 2.0 (how close to be to interact)
   - **Enter Settlement Key**: E (key to press to enter)
   - **Auto Enter On Stop**: Optional automatic entry
   - **Town Scene Name**: "TownSceen" (your town scene name)

### Step 2: Add Settlement Interaction UI
1. Create another empty GameObject called "SettlementInteractionUI"
2. Add a `UIDocument` component to it
3. Assign the `SettlementInteractionUI.uxml` file to the UIDocument
4. Add the `SettlementInteractionUI` component to it
5. The component will automatically connect to the SettlementInteractionManager

### Step 3: Configure TeamMarker
Make sure your TeamMarker GameObject:
- Is named "TeamMarker" (or manually assign in SettlementInteractionManager)
- Has a Transform that moves around the map
- Is positioned correctly relative to the map tiles

### Step 4: Verify Map Data Integration
The system requires:
- MapMaker2 component in the scene
- MapData with settlements properly generated
- MapVisualizer for coordinate conversion

## How It Works

### Detection Flow
1. **Position Tracking**: SettlementInteractionManager tracks TeamMarker position
2. **Coordinate Conversion**: Converts world position to map tile coordinates
3. **Settlement Check**: Searches for settlements within interaction distance
4. **UI Update**: Shows/hides interaction prompt based on proximity
5. **Input Handling**: Listens for interaction key press
6. **Scene Transition**: Sets up SettlementContext and loads town scene

### Settlement Context Setup
When entering a settlement, the system:
1. **Creates SettlementContext**: Persistent singleton for cross-scene data
2. **Sets Settlement Data**: Name, type (town/village), position
3. **Determines Harbor**: Checks nearby tiles for water
4. **Generates Seed**: Consistent generation based on position and name
5. **Loads Town Scene**: Transitions to town with proper context

### Town Scene Integration
The town scene will automatically:
1. **Read SettlementContext**: Get settlement data from the persistent singleton
2. **Configure Shops**: Set up appropriate shops for town vs village
3. **Apply Names**: Use randomized shop names based on settlement
4. **Handle Harbor**: Show/hide harbor based on hasHarbor setting

## Configuration Options

### SettlementInteractionManager Settings
```csharp
[Header("Settlement Detection")]
public Transform teamMarker;              // Auto-finds "TeamMarker"
public float interactionDistance = 2f;   // How close to interact
public KeyCode enterSettlementKey = KeyCode.E;  // Interaction key
public bool autoEnterOnStop = false;     // Auto-enter when stationary
public float autoEnterDelay = 1f;        // Delay for auto-enter

[Header("Scene Loading")]
public string townSceneName = "TownSceen";  // Town scene to load

[Header("Debug")]
public bool enableDebugLogs = true;       // Enable debug console output
```

### SettlementInteractionUI Settings
```csharp
[Header("UI Element Names")]
public string promptContainerName = "SettlementPrompt";
public string settlementNameLabelName = "SettlementName";
public string instructionLabelName = "InteractionInstruction";
```

## Testing

### Manual Testing
1. **Find Settlement**: Move TeamMarker near a town or village on the map
2. **Check Proximity**: UI prompt should appear when close enough
3. **Press Interaction Key**: Press E (or configured key) to enter
4. **Verify Scene Load**: Should load town scene with correct settlement data
5. **Check Town Configuration**: Verify shops match settlement type

### Debug Features
- **Enable Debug Logs**: Set `enableDebugLogs = true` for console output
- **Test Enter Current Settlement**: Use context menu on SettlementInteractionManager
- **Monitor Settlement Detection**: Watch console for proximity messages

### Context Menu Testing
Right-click SettlementInteractionManager component:
- **Test Enter Current Settlement**: Enter currently nearby settlement

## Troubleshooting

### Common Issues

1. **TeamMarker Not Found**
   - Ensure GameObject is named "TeamMarker"
   - Or manually assign in SettlementInteractionManager

2. **No Settlement Detection**
   - Check MapMaker2 is in scene and has MapData
   - Verify settlements are generated in MapData
   - Check interaction distance setting

3. **UI Not Showing**
   - Verify UIDocument has correct UXML file
   - Check UI element names match configuration
   - Ensure SettlementInteractionUI component is added

4. **Town Scene Doesn't Load**
   - Check town scene name is correct
   - Verify scene is added to Build Settings
   - Check console for SceneManager errors

5. **Settlement Context Not Working**
   - Ensure SettlementContext persists with DontDestroyOnLoad
   - Check town scene has components that read SettlementContext
   - Verify TownShopManager integration

### Debug Console Messages
When `enableDebugLogs = true`, you'll see:
```
[SettlementInteraction] Found TeamMarker automatically
[SettlementInteraction] Connected to MapMaker2 - Map size: 150x150
[SettlementInteraction] Near settlement: Riverside Town (Town)
[SettlementInteraction] Entering settlement: Riverside Town (Town)
[SettlementInteraction] SettlementContext configured: Riverside Town (Town) - Harbor: true
[SettlementInteraction] Loading town scene: TownSceen
```

## Integration with Existing Systems

### MapMaker2 Integration
- Uses existing MapData and settlement generation
- Leverages MapVisualizer for coordinate conversion
- Works with current team marker placement system

### SettlementContext Integration
- Extends existing town/village distinction system
- Integrates with TownShopManager for shop configuration
- Works with existing randomized shop names

### Scene Management Integration
- Uses existing "Return to Map" functionality
- Maintains team position between scene transitions
- Preserves game state through GameStateManager

## Future Enhancements

1. **Visual Indicators**: Add markers or highlights on settlements
2. **Settlement Info**: Show settlement details before entering
3. **Fast Travel**: Quick travel between discovered settlements
4. **Settlement Reputation**: Track relationship with each settlement
5. **Custom Interaction Range**: Per-settlement interaction distances
6. **Animation**: Smooth transitions and UI animations

This system provides a solid foundation for map-to-settlement transitions while integrating seamlessly with your existing town and village systems.