cinnaboot
/
claudes_game
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

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
main
cinnaboot 5 months ago
parent
5ecd8805e2
commit
883695cd43
1 changed files with 410 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 410
      docs/planning/maneuver_dialog_design.md

410
docs/planning/maneuver_dialog_design.md
Unescape View File

@ -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
Write Preview
Loading…
Cancel
Save