diff --git a/docs/ui_implementation_plan.md b/docs/ui_implementation_plan.md new file mode 100644 index 0000000..8905f18 --- /dev/null +++ b/docs/ui_implementation_plan.md @@ -0,0 +1,123 @@ +# 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** + ```bash + 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** + ```cpp + #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** + ```cpp + // 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) \ No newline at end of file