Implement interactive minimap with draggable camera viewport indicator

[adam4813]

Description

Implement an interactive minimap widget that displays a scaled overview of the entire tower and allows players to navigate by dragging a viewport indicator.

Context

The camera system (include/rendering/camera.h, src/rendering/camera.cpp) provides:

• Full tower bounds awareness via SetTowerBounds(width, height)
• Current camera position via target_position_ (world coordinates)
• Current zoom level via GetZoom() (returns float, 0.25 to 2.0)
• Coordinate conversion methods: WorldToScreen() and ScreenToWorld()

The HUD system (include/ui/hud.h, src/ui/hud.cpp) provides:

• Established UI rendering pipeline and overlay patterns
• Window management system (UIWindowManager)
• Notification and tooltip infrastructure
• Screen-space rendering (unaffected by camera transformations)

The game loop (src/core/game.cpp) has:

• Access to camera instance for coordinate conversions
• Screen dimensions available during rendering
• Tower dimensions from TowerGrid initialization

Feature Specification

Minimap Display

• Position: Top-right corner of screen (similar to camera controls overlay)
• Size: Configurable, default 200x150 pixels
• Content: Scaled representation of full tower (all floors, all columns)
• Background: Semi-transparent dark overlay with border
• Zoom: Always shows 1:1 view of entire tower (minimap fixed at "zoomed out" perspective)

Viewport Indicator

• Appearance: Rectangle outline showing current camera viewport
• Color: Bright color (e.g., YELLOW or LIME) with slight transparency
• Updates: Real-time, follows camera position and zoom changes
• Size: Rectangle dimensions proportional to current camera view
  • Width = (minimap_width * zoom_level) / max_zoom
  • Height = (minimap_height * zoom_level) / max_zoom
• Draggable: Left-click and drag to reposition camera

Interactivity

• Mouse Drag: Click inside viewport indicator and drag to move camera smoothly
• Click Outside: Click anywhere on minimap background to jump camera to that location (centered)
• Keyboard: Can be dismissed/toggled via key (TBD, suggest 'M' for map)
• Input Priority: Minimap input should be processed before general camera input

Rendering Details

• Minimap Bounds: Calculate scaled dimensions of tower
  • minimap_scale = minimap_size / tower_dimension
  • All positions converted: minimap_pos = world_pos * minimap_scale
• Facility Visualization (optional for MVP):
  • Can render facilities as small colored rectangles (matching their tower colors)
  • Or simple grid lines to indicate structure
• Camera Viewport Rect: Calculate from current camera position and visible area
  • visible_width = screen_width / current_zoom
  • visible_height = screen_height / current_zoom
  • Convert to minimap coordinates

Code References

Camera System:

• include/rendering/camera.h - Camera class with bounds, zoom, and position tracking
• src/rendering/camera.cpp - Implementation of coordinate conversion (WorldToScreen, ScreenToWorld)
• docs/CAMERA_SYSTEM.md - Full camera documentation with constants and smoothing info

HUD/UI System:

• include/ui/hud.h - HUD interface with Render() method
• src/ui/hud.cpp - HUD rendering patterns and overlay integration
• include/ui/placement_system.h - Example of camera integration with mouse input handling
• src/ui/analytics_overlay.cpp - Example overlay implementation with mouse event handling

Game Loop Integration:

• include/core/game.h - Game class with camera_ member and screen dimensions
• src/core/game.cpp - Game loop structure and rendering sequence (camera.BeginMode/EndMode patterns)

Coordinate System:

• include/rendering/camera.h lines 78-101 - ScreenToWorld() and WorldToScreen() methods
• src/rendering/camera.cpp lines 201-225 - Coordinate conversion implementation

Tower Bounds:

• src/rendering/camera.cpp lines 243-264 - ApplyBounds() showing tower_width_ and tower_height_ usage
• src/core/game.cpp - Tower initialization with grid dimensions

Implementation Plan

Phase 1: Core Minimap Widget

• Create include/ui/minimap.h with Minimap class
• Implement basic minimap rendering (scaled tower outline)
• Implement viewport indicator rectangle (WorldToScreen conversions)
• Real-time updates based on camera position and zoom

Phase 2: Interactivity

• Implement mouse input handling for viewport indicator dragging
• Implement click-to-jump functionality
• Integrate with HUD input processing (ensure HUD priority)
• Add keyboard toggle (suggest 'M' key)

Phase 3: Integration & Polish

• Integrate Minimap into HUD rendering pipeline
• Add visibility toggle (default: visible)
• Position correctly with other overlays (camera controls overlay, notifications)
• Add settings for minimap position and size
• Add documentation

Phase 4: Enhancement (Optional)

• Render facility dots/rectangles on minimap for overview
• Color-code facilities by type
• Add floor level indicators or grid lines
• Add zoom level indicator on minimap
• Smooth camera movement when jumping to minimap location

Technical Considerations

Coordinate Space Awareness

• Minimap operates entirely in screen-space (not affected by camera transforms)
• Must convert camera world coordinates to minimap space for viewport indicator
• Must convert minimap clicks to world coordinates for camera repositioning
• Formula: minimap_scale = minimap_dimensions / tower_dimensions

Performance

• Minimap rendering should be minimal (rectangle outlines, no complex geometry)
• Consider pre-calculating tower-to-minimap scale factor
• Viewport indicator is just a rectangle (very cheap)
• Optional facility rendering can use batch rendering for efficiency

Input Handling Order

• Check minimap input first (before general camera.HandleInput)
• If minimap consumed input, pass hud_handled=true to camera
• Prevents conflicts between minimap dragging and camera panning

Camera Smoothing

• When jumping via minimap click, use existing camera smoothing (target_zoom_, target_position_)
• When dragging viewport indicator, directly update camera.target_position_ for immediate feedback

Acceptance Criteria

• ✅ Minimap displays in top-right corner with full tower overview
• ✅ Viewport indicator shows current camera view as rectangle
• ✅ Viewport indicator updates in real-time with camera movement and zoom
• ✅ Dragging viewport indicator moves camera smoothly
• ✅ Clicking minimap background jumps camera to location (centered)
• ✅ No performance degradation or input conflicts
• ✅ Minimap can be toggled on/off
• ✅ Documentation with usage examples
• ✅ Keyboard shortcut works (suggest 'M' for map)
• ✅ Coordinate conversions are accurate
• ✅ Works correctly at all zoom levels (0.25 to 2.0)
• created a screenshot of the mini map

Future Enhancements

• Mini facility indicators (colored dots for different facility types)
• Floor navigation shortcuts (click floor numbers on minimap)
• Elevator traffic visualization
• Tenant density heatmap overlay
• Camera presets (save favorite view positions)
• Minimap resize handles

Labels

• enhancement
• feature
• ui

---

This issue is thoroughly detailed with full code context and references. Would you like me to create this issue in the adam4813/towerforge repository, or would you like to adjust any details first?

Copilot is powered by AI, so mistakes are possible. Leave a comment via the 👍 👎 to share your feedback and help improve the experience.