RPG-RougeLiteBattler/MAP_SETTLEMENT_INTERACTION_GUIDE.md

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

[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

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