claudes_game/docs/planning/maneuver_ui_controls.md

Maneuver UI Controls - Implementation Plan

Overview

Add functionality to the maneuver.h module to support UI controls for creating and managing maneuvers in the graphical simulation.

Current Interface Analysis

The maneuver module currently has:

• Burn direction functions: calculate_prograde_dir(), calculate_normal_dir(), etc.
• Burn application: apply_impulsive_burn(), apply_custom_burn()
• Maneuver execution: check_maneuver_trigger(), execute_maneuver()
• No dynamic maneuver management: Maneuvers are only loaded from config files

Recommended Additions to maneuver.h

1. Maneuver Creation and Management

// Create a new maneuver structure from parameters
Maneuver create_maneuver(const char* name, int craft_index, BurnDirection direction,
                         double delta_v, TriggerType trigger_type, double trigger_value);

// Add maneuver to simulation (returns index or -1 on error)
int add_maneuver_to_simulation(SimulationState* sim, Maneuver maneuver);

// Remove maneuver by name or index
bool remove_maneuver_by_name(SimulationState* sim, const char* name);
bool remove_maneuver_by_index(SimulationState* sim, int index);

// Clear all unexecuted maneuvers for a spacecraft
void clear_pending_maneuvers(SimulationState* sim, int craft_index);

2. Burn Preview/Optimization

// Preview burn result without executing (returns new orbital elements)
OrbitalElements preview_burn_result(Spacecraft* craft, BurnDirection direction,
                                    double delta_v, double parent_mass);

// Calculate required delta-v for target orbital elements
double calculate_delta_v_for_elements(Spacecraft* craft, OrbitalElements target_elements,
                                      double parent_mass);

// Calculate Hohmann transfer delta-v (two burns)
struct HohmannTransfer {
    double dv1;          // First burn delta-v
    double dv2;          // Second burn delta-v
    double transfer_time;  // Time to apoapsis
    double true_anomaly_2;  // True anomaly for second burn
};
HohmannTransfer calculate_hohmann_transfer(double r1, double r2, double central_mass);

3. Maneuver Information and Validation

// Get descriptive string for burn direction
const char* get_burn_direction_name(BurnDirection direction);

// Get descriptive string for trigger type
const char* get_trigger_type_name(TriggerType trigger_type);

// Check if a burn is feasible (e.g., not exceeding escape velocity if unintended)
bool validate_burn_parameters(Spacecraft* craft, BurnDirection direction,
                              double delta_v, double parent_mass);

// Calculate time until true anomaly trigger
double calculate_time_to_true_anomaly(Spacecraft* craft, double target_anomaly,
                                      double parent_mass);

4. Undo/Snapshot Support

// Save spacecraft state before burn
struct SpacecraftSnapshot {
    OrbitalElements orbit;
    Vec3 local_position;
    Vec3 local_velocity;
};
SpacecraftSnapshot save_spacecraft_snapshot(Spacecraft* craft);

// Restore spacecraft state
void restore_spacecraft_snapshot(Spacecraft* craft, SpacecraftSnapshot snapshot);

// Create reversible maneuver structure
struct ReversibleManeuver {
    Maneuver maneuver;
    SpacecraftSnapshot pre_burn_state;
};

5. Maneuver Query Functions

// Find maneuver by name (already exists in tests but not in header)
int find_maneuver_by_name(SimulationState* sim, const char* name);

// Get next pending maneuver for a spacecraft
Maneuver* get_next_pending_maneuver(SimulationState* sim, int craft_index);

// Get count of pending maneuvers for a spacecraft
int get_pending_maneuver_count(SimulationState* sim, int craft_index);

// Get all pending maneuvers for a spacecraft (returns array and count)
Maneuver** get_pending_maneuvers_for_craft(SimulationState* sim, int craft_index, int* out_count);

6. Burn Direction Visualization

// Get burn direction vector at specific orbital position
Vec3 get_burn_direction_at_anomaly(Spacecraft* craft, BurnDirection direction,
                                    double true_anomaly, double parent_mass);

Implementation Considerations

1. Dynamic array management: Since SimulationState has max_maneuvers, the add function should check capacity before adding.

2. Name uniqueness: The config loader already enforces unique names; the UI should too.

3. Craft index validation: When adding maneuvers via UI, verify the craft index is valid.

4. UI integration points: These functions would be called from:

   • Main loop: When user adds/edits maneuvers
   • UI renderer: For displaying burn previews and validation feedback
   • Config saving: To export UI-created maneuvers to TOML

Priority Recommendations

High Priority (core UI functionality):

1. add_maneuver_to_simulation() - Essential for UI creation
2. remove_maneuver_by_index() - For editing/deleting
3. create_maneuver() - Helper for constructing maneuvers
4. get_burn_direction_name() - For UI labels

Medium Priority (enhanced UX): 5. preview_burn_result() - Show result before committing 6. calculate_hohmann_transfer() - Common operation 7. validate_burn_parameters() - Prevent errors

Lower Priority (advanced features): 8. Snapshot/undo functions 9. Time-to-trigger calculations 10. Reversible maneuvers

This follows the existing C-style patterns in the codebase (structs, enums, simple functions) and provides the core functionality needed for a maneuver creation UI.