claudes_game/docs/ui_implementation_plan.md

UI Implementation Plan - Body Selection and Information Display

Overview

Add UI elements using raygui to list celestial bodies and display detailed information about selected bodies.

UI Library Choice

raygui - raylib's official immediate-mode GUI library

• Seamless integration with existing raylib code
• Lightweight and follows raylib's C-style conventions
• Provides GuiListView() for body lists and GuiWindowBox() for information panels
• No additional dependencies beyond raylib

Implementation Phases

Phase 1: Add raygui Submodule

1. Add raygui as git submodule

   git submodule add https://github.com/raysan5/raygui.git ext/raygui
   

   • Follows existing pattern with ext/ directory
   • Keeps raygui version-controlled and easily updatable
   • Matches current dependency management approach

2. Update .gitmodules (automatic)

   • Will add new entry for raygui submodule

Phase 2: Update Build System

1. Modify Makefile

   • Add raygui include path: -I./ext/raygui/src
   • Add raygui.c compilation rule (similar to tomlc17)
   • Update linking to include raygui objects

2. Integration approach

   • Follow existing pattern from tomlc17 integration
   • Add raygui.c to C_SOURCES or create separate raygui object rule
   • Ensure raygui is built before main target

Phase 3: Code Integration

1. Update renderer.h

   #include "raygui.h"  // after raylib include
   
   struct RenderState {
       // existing fields...
       int selected_body_index;    // -1 = no selection
       bool show_body_list;        // Toggle for list panel
       bool show_body_info;        // Toggle for info panel
   };
   

2. Add UI functions to renderer.h

   // UI rendering functions
   void render_body_list_ui(SimulationState* sim, RenderState* render_state);
   void render_body_info_ui(SimulationState* sim, RenderState* render_state);
   

Phase 4: Implementation Details

1. UI Layout Strategy

   • Left panel (200px): Body list using GuiListView()
   • Right panel (250px): Detailed info using GuiLabel() and text
   • Both panels toggleable with keyboard shortcuts

2. raygui-specific considerations

   • raygui uses immediate-mode, no state management needed
   • Requires #define RAYGUI_IMPLEMENTATION in one .c file
   • Can be compiled alongside raylib without conflicts

3. Controls Integration

   • 'B' key: Toggle body list
   • 'I' key: Existing info toggle (extend to show body info)
   • Mouse: Select from list, drag windows
   • ESC: Close panels (or keep for quit)

4. Body Information Display When a body is selected, display:

   • Name, mass, radius
   • Current position/velocity
   • Orbital parameters (eccentricity, semi-major axis)
   • Parent body and SOI radius
   • Real-time orbital metrics

Phase 5: Integration and Polish

1. Update main render loop

   • Call UI rendering functions after 3D rendering but before EndDrawing()
   • Maintain proper depth ordering

2. Enhance user experience

   • Highlight selected body in 3D view
   • Add visual indicators for selected body's orbit
   • Camera focus option on selected body

Key Technical Details

raygui Functions to Use:

• GuiWindowBox(bounds, title) - Draggable window containers
• GuiListView(bounds, text, scrollIndex, active) - Scrollable body list
• GuiLabel(bounds, text) - Information display
• GuiToggle(bounds, text, active) - Toggle switches for panels

Data Flow:

1. Simulation populates SimulationState with bodies
2. UI reads body names from sim->bodies[i].name
3. Selection updates render_state->selected_body_index
4. Info panel displays detailed data from selected body

Layout Strategy:

• Body list: Left side of screen (200px wide)
• Info panel: Right side of screen (250px wide)
• Both panels can be toggled independently
• Maintain existing 3D viewport in center

Files to Modify:

1. Makefile - Add raygui compilation
2. src/renderer.h - Add UI declarations and RenderState extensions
3. src/renderer.cpp - Implement UI rendering functions
4. src/main.cpp - Initialize UI state and add keyboard controls

Integration Notes:

• Maintains C-style architecture
• Immediate-mode UI fits existing rendering loop
• Minimal state management required
• Follows existing dependency patterns (git submodules)