From 883695cd43233fba4a4a4ae872edc50fb8c0cb81 Mon Sep 17 00:00:00 2001 From: cinnaboot Date: Wed, 4 Feb 2026 19:57:07 -0500 Subject: [PATCH] docs: Add maneuver management dialog design Comprehensive design for modal maneuver management dialog including: - Three-tab interface (Create, Hohmann, Edit) - Real-time orbital preview using preview_burn_result() - Hohmann transfer calculator - Enhanced maneuver list with quick actions - Complete UIState extension with ManeuverDialogState - Detailed implementation plan with 6 phases - Edge case handling and visual design guidelines --- docs/planning/maneuver_dialog_design.md | 410 ++++++++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 docs/planning/maneuver_dialog_design.md diff --git a/docs/planning/maneuver_dialog_design.md b/docs/planning/maneuver_dialog_design.md new file mode 100644 index 0000000..b0838ff --- /dev/null +++ b/docs/planning/maneuver_dialog_design.md @@ -0,0 +1,410 @@ +# Maneuver Management Dialog - Design Document + +## 1. Overview + +A comprehensive modal dialog for creating, editing, and managing spacecraft maneuvers with real-time orbital preview and Hohmann transfer calculations. + +## 2. Dialog Architecture + +### 2.1 Positioning & Dimensions + +``` +Screen Layout: +┌─────────────────────────────────────────────────────────────┐ +│ Objects │ │ Body Info │ +│ (200×400) │ │ (250×300) │ +├──────────────┤ ├──────────────────┤ +│ │ │ Maneuvers: Craft │ +│ │ │ (300×400) │ +│ │ │ │ +│ │ │ [Manage...] Btn │ +│ │ ├──────────────────┤ +│ │ │ │ +├──────────────┴──────────────────────────┴──────────────────┤ +│ Info Panel (300×300) │ +└─────────────────────────────────────────────────────────────┘ + +When "Manage..." clicked, open modal dialog centered: +┌─────────────────────────────────────────────────────────────┐ +│ ┌─ Maneuver Management ─────────────────────────── [X]─┐ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────┐ │ │ +│ │ │ Tab: [Create Maneuver] [Hohmann Transfer] │ │ │ +│ │ │ │ │ │ +│ │ │ Spacecraft: [Dropdown ▼] │ │ │ +│ │ │ Maneuver Name: [________________] │ │ │ +│ │ │ │ │ │ +│ │ │ Burn Direction: [Dropdown ▼] │ │ │ +│ │ │ Delta-V: [=======O=======] 1000 m/s [___] m/s │ │ │ +│ │ │ │ │ │ +│ │ │ Trigger Type: [Dropdown ▼] │ │ │ +│ │ │ Trigger Value: [=======O===] 0.00 rad [___] │ │ │ +│ │ │ │ │ │ +│ │ │ ┌─ ORBITAL PREVIEW ──────────────────────────┐ │ │ │ +│ │ │ │ Current: e=0.0167, a=1.496e11 m │ │ │ │ +│ │ │ │ Preview: e=0.0523, a=1.724e11 m │ │ │ │ +│ │ │ │ Δperiapsis: +2.28e10 m Δapoapsis: +4.52e10m│ │ │ │ +│ │ │ │ ✓ Parameters Valid │ │ │ │ +│ │ │ └────────────────────────────────────────────┘ │ │ │ +│ │ │ │ │ │ +│ │ │ [Cancel] [Create Maneuver] │ │ │ +│ │ └─────────────────────────────────────────────────┘ │ │ +│ │ │ │ +└──┴────────────────────────────────────────────────────────┴─┘ +``` + +**Dialog Dimensions:** +- Width: 550 pixels +- Height: 480 pixels +- Position: Centered on screen +- Style: Same Amber style as rest of UI + +### 2.2 UIState Extension + +Add to `ui_renderer.h`: + +```cpp +// Maneuver dialog state +enum ManeuverDialogTab { + MD_TAB_CREATE, + MD_TAB_HOHMANN, + MD_TAB_EDIT +}; + +struct ManeuverDialogState { + bool open; // Dialog visibility + ManeuverDialogTab active_tab; // Current tab + + // Create/Edit tab state + int craft_index; // Selected spacecraft + char name[64]; // Maneuver name buffer + int direction_active; // Selected burn direction (0-6) + double delta_v; // Delta-v value + int trigger_type_active; // Trigger type (0-1) + double trigger_value; // Trigger value + int edit_maneuver_index; // Index for edit mode (-1 = create) + + // Hohmann tab state + int target_body_index; // Target body for transfer + int transfer_body_index; // Parent body for transfer orbit + bool show_hohmann_preview; // Show/hide preview + HohmannTransfer last_calc; // Last Hohmann calculation + + // Preview state + bool show_preview; // Show orbital preview + bool preview_valid; // Preview validation result + OrbitalElements preview_elements; // Previewed orbital elements + + // Error messages + char error_message[256]; + bool show_error; +}; +``` + +Extend `UIState`: + +```cpp +struct UIState { + int body_list_scroll; + int body_list_active; + int selected_craft_index; + + ManeuverDialogState maneuver_dialog; // New dialog state + + // For edit mode in maneuver list + int maneuver_list_active; // Selected maneuver index in list + int maneuver_list_scroll; // Scroll position +}; +``` + +## 3. Detailed Dialog Design + +### 3.1 Create Maneuver Tab + +**Layout:** +``` +┌────────────────────────────────────────────────────────┐ +│ Spacecraft: [Vessel Alpha ▼] │ +│ Maneuver Name: [Transfer to Mars____________________] │ +│ │ +│ Burn Direction: [Prograde ▼] │ +│ │ +│ Delta-V: │ +│ [==========O==========] 1000 m/s │ +│ Min: 0 Max: 50000 Value: [1000] m/s │ +│ │ +│ Trigger Type: [True Anomaly ▼] │ +│ │ +│ Trigger Value: │ +│ [=======O========] 0.00 rad │ +│ Min: 0 Max: 2π Value: [0.00] rad │ +│ │ +│ ┌─ ORBITAL PREVIEW ──────────────────────────────┐ │ +│ │ Current Orbit: │ │ +│ │ e = 0.0167, a = 1.496e11 m, ν = 0.00 rad │ │ +│ │ │ │ +│ │ Preview Orbit: │ │ +│ │ e = 0.0523, a = 1.724e11 m, ν = 0.00 rad │ │ +│ │ │ │ +│ │ Δ Periapsis: +2.28e10 m Δ Apoapsis: +4.52e10 m│ │ +│ │ Δ Energy: +5.12e9 J/kg Δ Period: +68.3 days │ │ +│ │ │ │ +│ │ ✓ All parameters valid │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ [Cancel] [Create Maneuver] │ +└────────────────────────────────────────────────────────┘ +``` + +**Widgets Used:** +- GuiLabel() - Labels for each field +- GuiDropdownBox() - Spacecraft selector +- GuiTextBox() - Name input +- GuiComboBox() - Burn direction selector +- GuiSlider() - Delta-v slider (0-50000 m/s) +- GuiValueBoxFloat() - Precise delta-v input +- GuiComboBox() - Trigger type selector +- GuiSlider() - Trigger value slider (0-2π rad for true anomaly) +- GuiValueBoxFloat() - Precise trigger value input +- GuiLabel() - Preview panel content +- GuiButton() - Cancel and Create buttons + +**Input Validation:** +- Spacecraft must be selected +- Name must be non-empty and unique +- Delta-v must be ≥ 0 and ≤ 50000 m/s +- Trigger value must be in valid range +- Parent body must exist for spacecraft + +### 3.2 Hohmann Transfer Tab + +**Layout:** +``` +┌────────────────────────────────────────────────────────┐ +│ Calculate optimal Hohmann transfer between orbits │ +│ │ +│ Transfer Parent: [Sun ▼] │ +│ Current Body: [Earth ▼] │ +│ Target Body: [Mars ▼] │ +│ │ +│ [Calculate Transfer] │ +│ │ +│ ┌─ HOHMANN RESULTS ────────────────────────────────┐ │ +│ │ Transfer Orbit Properties: │ │ +│ │ Semi-major axis: 1.890e11 m │ │ +│ │ Transfer time: 258.9 days │ │ +│ │ │ │ +│ │ Burn 1 (at periapsis of current orbit): │ │ +│ │ Δv1 = 2.94 km/s │ │ +│ │ Direction: Prograde │ │ +│ │ True anomaly: 0.00 rad │ │ +│ │ │ │ +│ │ Burn 2 (at apoapsis of transfer orbit): │ │ +│ │ Δv2 = 2.65 km/s │ │ +│ │ Direction: Prograde │ │ +│ │ True anomaly: 3.14 rad │ │ +│ │ │ │ +│ │ Total Δv: 5.59 km/s │ │ +│ │ │ │ +│ │ [Create Both Burns] [Create Burn 1 Only] │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ [Cancel] │ +└────────────────────────────────────────────────────────┘ +``` + +### 3.3 Edit Maneuver Tab + +Triggered by clicking a maneuver in list, or from context menu. + +**Layout:** +``` +┌────────────────────────────────────────────────────────┐ +│ Edit: Transfer to Mars │ +│ │ +│ Spacecraft: [Vessel Alpha ▼] (locked) │ +│ Maneuver Name: [Transfer to Mars____________________] │ +│ │ +│ Burn Direction: [Prograde ▼] │ +│ │ +│ Delta-V: │ +│ [==========O==========] 1000 m/s │ +│ Min: 0 Max: 50000 Value: [1000] m/s │ +│ │ +│ Trigger Type: [True Anomaly ▼] │ +│ │ +│ Trigger Value: │ +│ [=======O========] 0.00 rad │ +│ Min: 0 Max: 2π Value: [0.00] rad │ +│ │ +│ ┌─ ORBITAL PREVIEW ──────────────────────────────┐ │ +│ │ Same preview as create tab │ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ [Cancel] [Delete Maneuver] [Save Changes] │ +└────────────────────────────────────────────────────────┘ +``` + +**Edit Mode Features:** +- Spacecraft field is locked (cannot change spacecraft) +- Name field is editable but validated for uniqueness +- All other fields editable +- "Delete Maneuver" button shows confirmation dialog +- "Save Changes" updates existing maneuver in simulation + +### 3.4 Existing Maneuvers Panel Enhancement + +Enhance the current maneuver list panel (at bottom-right, Y=320): + +**Enhanced Layout:** +``` +┌─────────────────────────────────────┐ +│ Maneuvers: Vessel Alpha │ +├─────────────────────────────────────┤ +│ [PENDING] Transfer to Mars │ +│ [PENDING] Plane Change │ +│ [DONE] Launch Burn │ +│ │ +│ Selected: │ +│ Name: Transfer to Mars │ +│ Direction: Prograde │ +│ Delta-V: 2940 m/s │ +│ Trigger: True Anomaly @ 0.00 rad │ +│ │ +│ ┌─ ORBITAL PREVIEW ─────────────┐ │ +│ │ e=0.052, a=1.724e11 m │ │ +│ │ Δperiapsis: +2.28e10 m │ │ +│ └───────────────────────────────┘ │ +│ │ +│ [+ Create Maneuver] [Hohmann...] │ +│ [Edit Selected] [Delete Selected] │ +└─────────────────────────────────────┘ +``` + +## 4. Implementation Details + +### 4.1 New Functions for ui_renderer.cpp + +```cpp +// Dialog rendering +void render_maneuver_dialog(SimulationState* sim, RenderState* render_state, UIState* ui_state); +void render_maneuver_create_tab(SimulationState* sim, UIState* ui_state); +void render_maneuver_hohmann_tab(SimulationState* sim, UIState* ui_state); +void render_maneuver_edit_tab(SimulationState* sim, UIState* ui_state); +void render_orbital_preview(OrbitalElements* current, OrbitalElements* preview, Rectangle bounds); + +// Helper functions +void update_orbital_preview(SimulationState* sim, UIState* ui_state); +void create_maneuver_from_dialog(SimulationState* sim, UIState* ui_state); +void update_maneuver_from_dialog(SimulationState* sim, UIState* ui_state); +bool validate_maneuver_inputs(UIState* ui_state); +void calculate_hohmann_for_dialog(SimulationState* sim, UIState* ui_state); +void create_hohmann_burns(SimulationState* sim, UIState* ui_state, bool both_burns); + +// Enhanced maneuver list +void render_enhanced_maneuver_list(SimulationState* sim, RenderState* render_state, UIState* ui_state); +void render_maneuver_preview_panel(Maneuver* maneuver, Spacecraft* craft, Rectangle bounds); +``` + +### 4.2 Dialog Positioning Calculation + +```cpp +// In render_maneuver_dialog(): +int dialog_width = 550; +int dialog_height = 480; +int dialog_x = (GetScreenWidth() - dialog_width) / 2; +int dialog_y = (GetScreenHeight() - dialog_height) / 2; +``` + +### 4.3 Widget Type Mappings + +| Field | Widget | Parameters | +|-------|--------|------------| +| Spacecraft | GuiComboBox() | Craft names, index pointer | +| Name | GuiTextBox() | char buffer, size, edit mode | +| Direction | GuiComboBox() | Direction names, index pointer | +| Delta-V slider | GuiSlider() | Label left/right, value pointer, min/max | +| Delta-V input | GuiValueBoxFloat() | Label, text buffer, value pointer | +| Trigger Type | GuiComboBox() | Type names, index pointer | +| Trigger Value slider | GuiSlider() | Label left/right, value pointer, min/max | +| Trigger Value input | GuiValueBoxFloat() | Label, text buffer, value pointer | +| Create/Edit buttons | GuiButton() | Rectangle bounds, text | +| Cancel | GuiButton() | Rectangle bounds, text | + +## 5. User Workflows + +### 5.1 Create Simple Burn + +1. Click "[+ Create Maneuver]" button in Maneuvers panel +2. Dialog opens with "Create Maneuver" tab selected +3. Spacecraft dropdown auto-selects currently selected craft +4. Enter name in text box +5. Select burn direction from dropdown +6. Adjust delta-v using slider or type precise value +7. Select trigger type (Time or True Anomaly) +8. Set trigger value using slider or precise input +9. Review orbital preview panel +10. Click "Create Maneuver" +11. Maneuver added to simulation and appears in list + +### 5.2 Hohmann Transfer + +1. Click "[Hohmann...]" button in Maneuvers panel +2. Dialog opens with "Hohmann Transfer" tab selected +3. Select transfer parent (e.g., Sun) +4. Select current body (spacecraft's current parent) +5. Select target body (destination) +6. Click "Calculate Transfer" +7. Results display delta-v1, delta-v2, transfer time +8. Click "Create Both Burns" to add both maneuvers +9. Both maneuvers added with descriptive names +10. Dialog closes, list shows two new pending burns + +## 6. Implementation Order + +### Phase 1: Foundation (Recommended First) +1. Add ManeuverDialogState to ui_renderer.h +2. Extend UIState with maneuver_dialog field +3. Add maneuver_list_active and maneuver_list_scroll to UIState +4. Create render_maneuver_dialog() skeleton +5. Add tab bar widget +6. Test dialog open/close with "Create Maneuver" button + +### Phase 2: Create Tab +7. Implement render_maneuver_create_tab() skeleton +8. Add all input widgets (spacecraft, name, direction, delta-v, triggers) +9. Implement update_orbital_preview() using preview_burn_result() +10. Implement render_orbital_preview() to display results +11. Add validation logic with validate_burn_parameters() +12. Implement create_maneuver_from_dialog() using add_maneuver_to_simulation() +13. Test create workflow end-to-end + +### Phase 3: Hohmann Tab +14. Implement render_maneuver_hohmann_tab() skeleton +15. Add body selector widgets +16. Implement calculate_hohmann_for_dialog() using calculate_hohmann_transfer() +17. Display Hohmann results +18. Implement create_hohmann_burns() to add both maneuvers +19. Test Hohmann workflow + +### Phase 4: Edit Tab +20. Implement render_maneuver_edit_tab() skeleton +21. Load existing maneuver data into fields +22. Lock spacecraft field +23. Implement update_maneuver_from_dialog() +24. Add delete confirmation dialog +25. Test edit and delete workflows + +### Phase 5: Enhanced Maneuver List +26. Modify render_maneuver_list_ui() for selectable items +27. Add maneuver preview panel to list +28. Add action buttons (Create, Hohmann, Edit, Delete) +29. Connect buttons to dialog +30. Test enhanced list interaction + +### Phase 6: Polish +31. Add keyboard shortcuts (Enter to confirm, Escape to cancel) +32. Improve error messages +33. Add tooltips for complex fields +34. Handle all edge cases +35. Test with various configurations