RPG-RougeLiteBattler/MAP_LOCATION_NAMES_LEGEND_GUIDE.md

Map Location Names and Legend System Setup Guide

Overview

This system adds named geographic features (forests, lakes, plains, mountains, rivers) and a toggleable map legend to MapScene2. The legend allows players to toggle the visibility of different types of location names and implements click blocking to prevent map interaction when the UI is active.

Components Created

1. Geographic Feature System

• GeographicFeature.cs: Data structure for named geographic features
• GeographicFeatureGenerator.cs: Analyzes the map and creates named features
• GeographicFeatureManager.cs: Manages the feature generation process

2. Map Legend and Name Display

• MapSceneLegendUI.cs: Interactive legend with terrain colors and name toggles
• MapLocationNameDisplay.cs: Displays location names on the map
• MapLegend.uss: Updated styles for the legend and location names

3. Integration

• Uses existing IClickBlocker.cs and ClickManager.cs for UI interaction

Features

🏰 Named Locations

• Settlements: Town and village names (existing system enhanced)
• Forests: "Whispering Woods", "Ancient Grove", "Darkwood Forest", etc.
• Lakes: "Crystal Lake", "Mirror Waters", "Dragon's Rest Lake", etc.
• Plains: "Golden Plains", "Emerald Fields", "Windswept Meadows", etc.
• Mountains: "Frostpeak Mountains", "Dragon's Spine", "Stormhaven Peaks", etc.
• Rivers: "Swift Current", "Silver Stream", "Moonflow River", etc.

🗺️ Interactive Map Legend

• Terrain Colors: Visual legend showing terrain types
• Name Toggles: Individual toggles for each location name type
• Collapsible: Toggle button to show/hide the legend
• Click Blocking: Prevents map interaction when legend is active

🎨 Visual Design

• Color-coded Names: Different colors for each feature type
• Proper Sizing: Larger names for important features
• Discovery System: Support for discovered/undiscovered features
• Non-intrusive: Names don't block map interaction

Setup Instructions

Step 1: Add Geographic Feature System to MapScene2

1. Create an empty GameObject called "GeographicFeatureManager"
2. Add the GeographicFeatureManager component to it
3. Configure settings:
   • Auto Generate Features: ✓ (checked)
   • Regenerate On Map Change: ✓ (checked)
   • Debug Mode: ✓ (optional for testing)

Step 2: Add Location Name Display

1. Create an empty GameObject called "MapLocationNameDisplay"
2. Add the MapLocationNameDisplay component to it
3. Configure settings:
   • Map UI Document: Assign your map's UIDocument
   • Show [Feature Type] Names: Configure which types to show by default
   • [Feature Type] Name Color: Customize colors for each feature type
   • Map UI Size: Set to match your map UI dimensions (e.g., 1920x1080)

Step 3: Add Map Legend UI

1. Create an empty GameObject called "MapSceneLegendUI"
2. Add a UIDocument component to it
3. Add the MapSceneLegendUI component to it
4. Configure settings:
   • UI Document: The UIDocument component on the same GameObject
   • Start Visible: ✓ (if you want legend visible by default)
   • Toggle Key: L (or your preferred key)

Step 4: Verify Integration

The system will automatically:

• Generate geographic features when the map loads
• Display settlement names from existing settlements
• Create and display the map legend
• Register click blocking with the ClickManager

Configuration Options

GeographicFeatureManager Settings

[Header("Feature Configuration")]
public bool autoGenerateFeatures = true;        // Auto-generate on start
public bool regenerateOnMapChange = true;       // Update when map changes
public bool debugMode = false;                  // Enable debug logging

MapLocationNameDisplay Settings

[Header("Display Settings")]
public bool showSettlementNames = true;         // Show town/village names
public bool showForestNames = true;             // Show forest names
public bool showLakeNames = true;               // Show lake names
public bool showPlainNames = true;              // Show plain names
public bool showMountainNames = true;           // Show mountain names
public bool showRiverNames = true;              // Show river names

[Header("Visual Settings")]
public Color settlementNameColor = Color.white; // Settlement name color
public Color forestNameColor = Color.green;     // Forest name color
// ... (other color settings)

MapSceneLegendUI Settings

[Header("Settings")]
public bool startVisible = true;                // Legend visible on start
public KeyCode toggleKey = KeyCode.L;           // Key to toggle legend

How It Works

Feature Generation Process

1. Map Analysis: System analyzes terrain types in the generated map
2. Cluster Detection: Finds connected areas of the same terrain type
3. Size Filtering: Only names areas above minimum size thresholds
4. Name Assignment: Randomly assigns appropriate names from predefined lists
5. Center Calculation: Determines optimal position for name display

Legend Integration

1. Terrain Legend: Shows color codes for all terrain types
2. Name Toggles: Individual switches for each location name type
3. Real-time Updates: Immediately shows/hides names when toggled
4. Click Blocking: Prevents map clicks when legend area is active

Click Management

1. IClickBlocker: Legend implements the interface for click blocking
2. ClickManager: Centralized system manages all UI click blocking
3. Position Detection: Checks if clicks fall within legend bounds
4. Map Protection: Prevents accidental map interaction

Testing

Verify Feature Generation

1. Play the scene - Features should generate automatically
2. Check Console - Enable debug mode to see generation messages
3. Context Menu - Use "Regenerate Features" on GeographicFeatureManager

Test Legend Functionality

1. Toggle Visibility - Press L (or configured key) to show/hide legend
2. Name Toggles - Turn individual name types on/off
3. Click Blocking - Verify map doesn't respond to clicks over legend
4. Visual Feedback - Check that legend shows proper terrain colors

Debug Features

• Console Logs: Enable debug mode for detailed generation info
• Context Menus: Use component context menus for manual testing
• Feature Counts: Check console for number of features generated

Customization

Adding New Feature Types

1. Update GeographicFeatureType enum in GeographicFeature.cs
2. Add name arrays in GeographicFeatureGenerator.cs
3. Create generation method following existing patterns
4. Update display systems to handle the new type

Adjusting Generation Parameters

// In GeographicFeatureGenerator.cs
var forestClusters = FindConnectedAreas(mapData, TerrainType.Forest, 6); // Min 6 tiles
var lakeClusters = FindConnectedAreas(mapData, TerrainType.Lake, 4);     // Min 4 tiles
var plainClusters = FindConnectedAreas(mapData, TerrainType.Plains, 25); // Min 25 tiles

Customizing Names

Edit the name arrays in GeographicFeatureGenerator.cs:

private static readonly string[] forestNames = {
    "Whispering Woods", "Ancient Grove", "Your Custom Forest Name"
};

Troubleshooting

No Names Appearing

1. Check Generation: Verify GeographicFeatureManager is in scene and active
2. Check Display: Ensure MapLocationNameDisplay has correct UI references
3. Check Map Size: Verify mapUISize settings match your actual UI
4. Check Toggles: Make sure name types are enabled in the legend

Legend Not Showing

1. Check UIDocument: Verify MapSceneLegendUI has UIDocument component
2. Check Key Binding: Press L or configured toggle key
3. Check Start Visible: Verify startVisible setting
4. Check Console: Look for UI setup errors

Click Blocking Issues

1. Check ClickManager: Verify ClickManager exists in scene
2. Check Registration: Legend should auto-register with ClickManager
3. Check Position: Verify legend bounds detection is working

Performance Issues

1. Reduce Feature Count: Increase minimum cluster sizes
2. Limit Name Updates: Avoid frequent RefreshLocationNames() calls
3. Optimize Generation: Consider caching generated features

Integration with Existing Systems

MapMaker2 Integration

• Automatic Detection: System finds and uses existing MapMaker2
• MapData Access: Reads terrain and settlement data from MapMaker2
• Coordinate Conversion: Handles world-to-UI coordinate mapping

Settlement System Integration

• Existing Names: Preserves and displays existing settlement names
• Color Coding: Towns and villages have distinct visual styles
• Discovery System: Ready for integration with discovery mechanics

UI System Integration

• IClickBlocker: Follows established UI interaction patterns
• ClickManager: Integrates with existing click management system
• UI Toolkit: Built with Unity's modern UI system

Future Enhancements

1. Discovery System: Show/hide names based on exploration
2. Interactive Features: Click names for more information
3. Dynamic Names: Generate contextual names based on surroundings
4. Distance Filtering: Show different names at different zoom levels
5. Custom Icons: Add visual markers for different feature types
6. Save/Load: Persist discovered features between sessions

This system provides a solid foundation for map location naming while maintaining clean integration with your existing RPG systems.