# Map Location Name System - Quick Setup & Debug Guide

## Quick Setup Instructions

### 1. Scene Setup
1. Open MapScene2 in Unity
2. Add these components to empty GameObjects or existing UI objects:
   - **MapLocationSystemInitializer** (on any GameObject)
   - **MapLocationDebugger** (on any GameObject)
   - **GeographicFeatureManager** (if not already present)
   - **MapLocationNameDisplay** (attach to GameObject with UIDocument)
   - **MapSceneLegendUI** (attach to GameObject with UIDocument for legend)

### 2. Component Configuration
- **MapLocationSystemInitializer**: 
  - Enable debug mode for detailed logging
  - Configure which name types to show by default
  - Auto-finds all required components
  
- **MapLocationDebugger**:
  - Provides runtime debug controls via keyboard shortcuts
  - No configuration needed

### 3. Testing the System

#### Debug Controls (MapLocationDebugger)
- **F9**: Print detailed debug information
- **F10**: Toggle legend visibility
- **F11**: Toggle settlement names
- **F12**: Refresh location names

#### What to Look For
1. **Console Messages**: Check for initialization logs
2. **Legend UI**: Should appear on screen (toggle with L key or F10)
3. **Location Names**: Should appear on settlements and features
4. **Interactive Toggles**: Legend checkboxes should control name visibility

## Troubleshooting

### Legend Not Showing
1. Check console for "Legend Container Found: False"
2. Verify UIDocument is attached to MapSceneLegendUI GameObject
3. Press F9 to get detailed UI element information
4. Try pressing F10 to manually toggle legend

### Names Not Positioned Correctly
1. Check console for coordinate conversion warnings
2. Press F9 to see map container size information
3. Verify MapMaker2 is generating map data properly
4. Press F12 to refresh name positions

### Names Not Showing At All
1. Check if geographic features are generated (F9 shows count)
2. Verify name display toggles are enabled
3. Check console for "MapData is null" warnings
4. Use F11 to manually toggle settlement names

### Geographic Features Not Generated
1. Check if MapMaker2 has completed map generation
2. Verify GeographicFeatureManager is attached to scene
3. Use context menu "Reinitialize System" on MapLocationSystemInitializer
4. Check console for feature generation logs

## Console Debug Output Guide

### Normal Initialization Sequence:
```
MapLocationSystemInitializer: Starting system initialization...
Found components - FeatureManager: True, NameDisplay: True, LegendUI: True, MapMaker: True
MapLocationSystemInitializer: Map generation complete
MapLocationSystemInitializer: Generating geographic features...
MapLocationSystemInitializer: Generated X geographic features
MapLocationSystemInitializer: Name display initialized
MapLocationSystemInitializer: Legend UI initialized
MapLocationSystemInitializer: System initialization complete!
```

### Debug Information (F9):
- UI element positions and sizes
- Geographic feature count and sample data
- Name display settings and container info
- Legend UI visibility and positioning

## Manual Testing Steps

1. **Start the game** and check console for initialization messages
2. **Press F9** to see detailed debug info
3. **Press F10** to toggle legend - should see legend panel appear/disappear
4. **Press F11** to toggle settlement names - should see names appear/disappear on towns
5. **Use legend checkboxes** to toggle different name types
6. **Press L key** to toggle legend (alternative method)

## Common Issues and Solutions

### Issue: "MapData is null"
**Solution**: Ensure MapMaker2 has generated the map before the name system initializes. The MapLocationSystemInitializer waits for this automatically.

### Issue: "nameContainer is null"
**Solution**: Check that UIDocument is properly attached and contains the root visual element. The system creates containers automatically if missing.

### Issue: Names appear but are positioned incorrectly
**Solution**: This is usually a coordinate conversion issue. The debug output (F9) will show container bounds and conversion calculations.

### Issue: Legend shows but toggles don't work
**Solution**: Check that MapLocationNameDisplay is found by the legend UI. Console will show connection status during initialization.

## Performance Notes

- Geographic feature generation happens once at startup
- Name positioning is calculated when names are toggled on
- Debug mode adds console logging - disable in production
- UI containers are created automatically and reused

## File Structure
```
Assets/Scripts/UI/MapScene/
├── GeographicFeature.cs               (Feature data structure)
├── GeographicFeatureGenerator.cs      (Feature detection algorithms)
├── GeographicFeatureManager.cs        (Feature management)
├── MapLocationNameDisplay.cs          (Name positioning and display)
├── MapLegendUI.cs                     (Legend UI - class: MapSceneLegendUI)
├── MapLocationSystemInitializer.cs    (Setup and initialization)
└── MapLocationDebugger.cs            (Runtime debugging tools)
```