claudes_game/docs/mission_planning.md

Mission Planning Module - Implementation Plan

Date: January 16, 2026 Status: Phase 1-3 Complete ✅, Phase 4 Debugging Required 🔄 Branch: patched-conics Implementation Progress: 70% complete (3/6 phases complete, 1 phase debugging)

Implementation Progress

✅ Phase 1: Core Transfer Calculations - COMPLETE

Status: All tests passing (3/3) Date Completed: January 16, 2026

Implemented:

• calculate_hohmann_transfer() - Computes transfer orbit parameters
• calculate_angular_position() - Calculates body angle in XY plane
• calculate_required_phase_angle() - Computes optimal launch phase angle

Validation:

• Earth→Mars transfer time: 258.8 days (±0.08% of expected)
• Required phase angle: 44.3° (±0.08° of expected)
• Delta-v injection: 2.94 km/s (±0.01% of expected)
• All NASA reference values validated within 5%

Tests: tests/test_mission_planning.cpp - 17 assertions, 6 test cases, all pass

---

✅ Phase 2: Launch Window Detection - COMPLETE

Status: All tests passing Date Completed: January 16, 2026

Implemented:

• check_launch_window() - Tests if current phase angle allows optimal launch
• wait_for_launch_window() - Fast-forwards simulation to launch window

Validation:

• Launch window detection works correctly
• Fast-forward advances simulation to correct phase (within 1°)
• Wait time: ~94 days for Earth→Mars transfer window
• Phase angle wrapping handled correctly (0-360° range)

Tests: Integrated into mission planning test suite - all pass

---

✅ Phase 3: Spacecraft Spawning - COMPLETE

Status: All tests passing (9/9 assertions) Date Completed: January 16, 2026

Implemented:

• add_body_to_simulation() - Dynamic body creation in simulation.cpp
• spawn_spacecraft_on_transfer() - Creates spacecraft with correct velocity

Validation:

• Spacecraft spawns at correct position (0m error from departure body)
• Spacecraft velocity = departure velocity + Δv (0% error)
• Spacecraft parent = Sun (index 0)
• Local/global coordinates initialized correctly
• SOI radius calculated correctly

Tests: tests/test_hohmann_transfer.cpp::Spacecraft spawning - 9 assertions, all pass

Key Implementation Details:

• Uses departure body's actual velocity direction (not computed from position)
• Spacecraft mass = 1.0 kg (test particle, mass cancels in physics)
• Position and velocity set before adding to simulation
• Coordinate transforms handle parent=0 (Sun) correctly

---

⏸️ Phase 4: Full Transfer Test - DEBUGGING REQUIRED

Status: Partially implemented, trajectory issue identified Date Started: January 16, 2026 Issue: Spacecraft trajectory deviates from expected Hohmann transfer orbit

Implemented:

• Test framework for Earth→Mars transfer
• Launch window detection and waiting
• Spacecraft spawning with transfer parameters
• Energy drift tracking and validation

Current Issue:

• Spacecraft spawns with correct initial conditions (position, velocity, parent)
• Initial orbital energy: -3.52×10⁸ J (correct for transfer orbit)
• After first update_simulation() call, spacecraft trajectory diverges
• Final orbital energy: +3.51×10²³ J (huge energy error, wrong sign!)
• Spacecraft not following Hohmann transfer ellipse
• Energy drift: 9.98×10¹⁶% (unphysically large)

Debugging Findings:

1. Spacecraft spawns correctly:

   • Global position matches Earth: (-6.94×10⁹, -1.49×10¹¹, 0) m
   • Global velocity correct: (-32697.6, 1518.47, 0) m/s
   • Parent = Sun (index 0)
   • Local position initially correct relative to Sun

2. After first update_simulation():

   • Local position jumps incorrectly to: (6.11×10⁷, -2.84×10⁶, 0) m
   • This suggests compute_global_coordinates() or local frame integration is wrong

3. Possible root causes:

   • Bug in update_simulation() coordinate transforms for newly added bodies
   • Issue with local frame integration when parent = 0 (Sun)
   • compute_global_coordinates() not called correctly after body addition
   • SOI transition logic interfering with spacecraft (only 1 SOI transition detected)

4. Investigation needed:

   • Add debug output to update_simulation() to track coordinate transforms
   • Check if find_dominant_body() incorrectly changing spacecraft's parent
   • Verify RK4 integration is using correct reference frame
   • Test with spacecraft starting at parent ≠ 0 (compare behavior)

Tests: tests/test_hohmann_transfer.cpp::Earth → Mars Hohmann Transfer - Basic

• Current: 4/5 assertions pass
• Failing: Energy drift validation (expect < 5%, actual 9.98×10¹⁶%)

Next Steps for Debugging:

1. Add detailed logging to update_simulation() to track coordinate transforms
2. Verify spacecraft's local position/velocity before/after each update
3. Check if parent index changes unexpectedly during simulation
4. Consider if add_body_to_simulation() needs to call compute_global_coordinates()
5. Test with simplified scenario (e.g., Earth → fake destination at 1.2 AU)

Estimated Time to Resolve: 2-3 hours of focused debugging

---

⏸️ Phase 5: Enhance Root Body Transition Tests - NOT STARTED

Status: Deferred until Phase 4 debugged Dependency: Phase 4 (working transfer orbits required)

---

⏸️ Phase 6: Round-Trip Mission - NOT STARTED

Status: Deferred until Phase 4 debugged Dependency: Phase 4 (single-leg transfer must work first)

---

Overview

Add a mission planning module to calculate realistic interplanetary transfers with proper departure windows, replacing manual config positioning with computed trajectories. This enables proper testing of patched conics mechanics and provides a foundation for spacecraft simulation.

Design Decisions

1. Spacecraft Mass: Use small but non-zero (1.0 kg) - works with existing physics (mass cancels out in acceleration)
2. Capture Burns: Skip for initial implementation - implement flyby missions only
3. Inclination: Planar first (z=0), defer 3D to future work
4. Scope: Full mission planner with departure window timing, launch window detection, and spacecraft spawning

Key Technical Discovery

The physics engine already supports test particles correctly. The acceleration calculation is:

acceleration = (G × body_mass × parent_mass / r²) / body_mass = G × parent_mass / r²

Body mass cancels out, so any small mass works. We'll use 1.0 kg.

Data Structures

TransferParameters

struct TransferParameters {
    double semi_major_axis;      // Transfer orbit semi-major axis (meters)
    double eccentricity;         // Transfer orbit eccentricity
    double periapsis;            // Closest approach (departure radius)
    double apoapsis;             // Furthest distance (arrival radius)
    double transfer_time;        // Time required for transfer (seconds)
    double departure_velocity;   // Required velocity at departure (m/s)
    double arrival_velocity;     // Velocity at arrival (relative to Sun, m/s)
    double phase_angle_deg;      // Required phase angle for launch (degrees)
    double delta_v_injection;    // Delta-V needed for transfer injection (m/s)
    double delta_v_capture;      // Delta-V needed for capture (optional, future)
};

Implementation Phases

Phase 1: Core Transfer Calculations (1 day)

Goal: Implement orbital mechanics calculations for Hohmann transfers

Files:

• src/mission_planning.h (new) - Function declarations
• src/mission_planning.cpp (new) - Core calculations
• tests/test_mission_planning.cpp (new) - Unit tests for formulas

Functions to implement:

1.1 calculate_hohmann_transfer()

Calculates transfer orbit parameters given departure and arrival radii.

Algorithm:

a_transfer = (r_departure + r_arrival) / 2
e = (r_arrival - r_departure) / (r_arrival + r_departure)
T_transfer = π × sqrt(a³ / GM)

v_departure = sqrt(G × M × (2/r_departure - 1/a))
v_arrival = sqrt(G × M × (2/r_arrival - 1/a))
v_circular = sqrt(G × M / r_departure)

Δv_injection = v_departure - v_circular

Validation: Earth→Mars values:

• Transfer time: ~259 days
• Phase angle: ~44.3°
• Δv: ~2.94 km/s

1.2 calculate_angular_position()

Calculates angular position of a body relative to its center (in XY plane).

Algorithm:

rel_pos = body_position - center_position
angle = atan2(y, x)
Normalize to [0, 2π)

1.3 calculate_required_phase_angle()

Calculates optimal phase angle for launch.

Algorithm:

ω_departure = 2π / T_departure
α = ω_departure × T_transfer
phase_angle = π - α (in radians)
Convert to degrees

Tests:

• Validate transfer parameters against NASA reference values (±5%)
• Verify angular position calculations for circular orbits
• Test phase angle formula with known cases

Expected outcome:

• ✅ Accurate transfer orbit calculations
• ✅ Verified against known mission parameters

Estimated complexity: Low Risk: Low (well-known orbital mechanics formulas)

---

Phase 2: Launch Window Detection (1 day)

Goal: Detect when launch window is open and advance simulation to it

Files:

• src/mission_planning.cpp (extend)
• tests/test_launch_window.cpp (new)

Functions to implement:

2.1 check_launch_window()

Tests if current positions allow optimal launch.

Algorithm:

θ_depart = calculate_angular_position(departure, sun)
θ_arrival = calculate_angular_position(arrival, sun)

current_phase = θ_arrival - θ_depart (normalize to [0, 2π))
current_phase_deg = current_phase × (180/π)

error = |current_phase_deg - required_phase_angle_deg|
Handle wrap-around: if error > 180°, use |error - 360°|

return error <= tolerance

2.2 wait_for_launch_window()

Advances simulation until launch window opens.

Algorithm:

while !check_launch_window(...):
    Fast-forward by 1 day per iteration (for efficiency)
    for i in 0..(86400 / dt):
        update_simulation(sim)

Tests:

• Create Earth+Mars config at wrong phase angle
• Call wait_for_launch_window() - should advance simulation
• Verify phase angle is now within tolerance (1°)
• Measure time waited - should be reasonable (weeks to months)

Expected outcome:

• ✅ Can detect proper launch windows
• ✅ Can advance simulation to launch window
• ✅ Phase angle accuracy within 1°

Estimated complexity: Low-Medium Risk: Low (simulation fast-forward is safe)

---

Phase 3: Spacecraft Spawning (1.5 days)

Goal: Create spacecraft at departure with correct velocity

Files:

• src/simulation.h (+3 lines) - Add function declaration
• src/simulation.cpp (+30 lines) - Implement dynamic body addition
• src/mission_planning.cpp (+40 lines) - Spacecraft spawning logic

Functions to implement:

3.1 add_body_to_simulation() (in simulation.cpp)

Adds a new body to the simulation at runtime.

Algorithm:

Check capacity (body_count < max_bodies)
Copy body to next available slot
Initialize local coordinates:
    if parent_index >= 0:
        local_pos = global_pos - parent_pos
        local_vel = global_vel - parent_vel
    else:
        local_pos = global_pos
        local_vel = global_vel
Calculate SOI radius (if has parent)
Increment body_count
Return new body index

3.2 spawn_spacecraft_on_transfer() (in mission_planning.cpp)

Creates spacecraft on transfer trajectory at departure.

Algorithm:

Create spacecraft body:
    name = "Spacecraft"
    mass = 1.0 kg (negligible but non-zero)
    radius = 1.0 km (for visualization)
    color = magenta/pink
    eccentricity = transfer.eccentricity
    semi_major_axis = transfer.semi_major_axis

Position = departure.position

Velocity = departure.velocity + Δv_injection:
    departure_pos = departure.position - sun.position
    orbit_dir = normalize(cross(departure_pos, z_axis))
    delta_v = orbit_dir × transfer.delta_v_injection
    spacecraft.velocity = departure.velocity + delta_v

Parent = Sun (index 0)
Add to simulation via add_body_to_simulation()
Return spacecraft index

Tests:

• Spawn spacecraft at Earth
• Verify initial position matches Earth
• Verify velocity = Earth velocity + Δv
• Verify parent = Sun
• Verify local coordinates initialized correctly

Expected outcome:

• ✅ Spacecraft spawns correctly at departure
• ✅ Initial velocity matches transfer requirements
• ✅ Parent set to Sun for transfer orbit
• ✅ Local/global coordinates consistent

Estimated complexity: Medium Risk: Medium (dynamic body addition affects simulation state)

---

Phase 4: Full Transfer Test (1.5 days)

Goal: End-to-end test of Earth→Mars Hohmann transfer

Files:

• tests/test_hohmann_transfer.cpp (new) - Main integration test
• tests/configs/earth_mars_simple.toml (new) - Simple 3-body config

Test scenario:

TEST_CASE("Earth → Mars Hohmann Transfer", "[mission][hohmann]") {
    // 1. Load Earth+Mars system
    // 2. Calculate transfer parameters
    // 3. Wait for launch window (within 1° tolerance)
    // 4. Record departure time
    // 5. Spawn spacecraft on transfer trajectory
    // 6. Simulate until arrival (transfer_time × 1.1)
    // 7. Track SOI transitions (Earth→Sun→Mars)
    // 8. Verify arrival at Mars (distance < 2×SOI)
    // 9. Verify transfer time accuracy (±10%)
}

Success criteria:

• Spacecraft enters Mars SOI
• Transfer time: 259 ± 26 days
• Final distance to Mars < 2 × Mars_SOI
• SOI transitions: Earth→Sun→Mars (tracked)
• Energy drift < 1% during transfer

Expected outcome:

• ✅ Complete end-to-end transfer validated
• ✅ Patched conics mechanics tested (3 SOI changes)
• ✅ Transfer trajectory matches prediction

Estimated complexity: Medium-High Risk: Medium-High (integration test may reveal edge cases)

---

Phase 5: Enhance Root Body Transition Tests (0.5 days)

Goal: Replace manual config positioning with calculated transfers

Files:

• tests/test_root_body_transitions.cpp (refactor)
• Remove tests/configs/manual_root_transition.toml

Changes:

1. Replace "Root body transition - Earth to Sun" test:

   • Use spawn_spacecraft_on_transfer() instead of manual config
   • Calculate transfer parameters
   • Wait for launch window
   • Verify Earth→Sun transition happens

2. Replace "Root body round-trip" test:

   • Calculate Earth→Mars transfer
   • Wait for window
   • Spawn spacecraft
   • Verify round-trip SOI transitions

3. Add better validation:

   • Verify transition order (Earth→Sun→Mars)
   • Verify arrival distance < threshold
   • Verify energy conservation
   • Verify spacecraft follows predicted trajectory

Expected outcome:

• ✅ Realistic mission-based testing
• ✅ Better validation than sun_transitions >= 1
• ✅ Eliminates manual config positioning
• ✅ Tests use actual orbital mechanics

Estimated complexity: Low Risk: Low (refactoring existing tests)

---

Phase 6: Round-Trip Mission (1 day) - Optional

Goal: Validate full mission lifecycle with return journey

Files:

• tests/test_round_trip.cpp (new)

Test scenario:

TEST_CASE("Earth → Mars → Earth Round Trip", "[mission][round-trip]") {
    // 1. Earth→Mars transfer
    // 2. Verify arrival at Mars
    // 3. Wait for Mars→Earth return window
    // 4. Spawn new spacecraft at Mars for return
    // 5. Simulate Mars→Earth return
    // 6. Verify both transfers complete
    // 7. Verify return arrival at Earth
}

Success criteria:

• Both transfers complete successfully
• Return time: ~259 ± 26 days
• Final distance to Earth < 2 × Earth_SOI
• Energy conserved across entire round-trip

Expected outcome:

• ✅ Full mission lifecycle validated
• ✅ Multiple departure windows handled
• ✅ Patched conics round-trip confirmed

Estimated complexity: Medium Risk: Medium (long simulation time)

---

Integration with Existing Code

Reuses Existing Components:

Physics Module:

• rk4_step() - RK4 integration works with any mass
• evaluate_acceleration() - Mass cancels out, test particles work

Simulation Module:

• find_dominant_body() - SOI transitions work with parent_index = 0 (Sun)
• update_simulation() - Handles root bodies correctly
• Coordinate frames - Local/global transformations already work

Test Utilities:

• calculate_orbital_metrics() - Can use for trajectory validation
• OrbitTracker - Can track orbital progress

New Components:

Mission Planning Module:

• mission_planning.h/cpp - Mission calculations
• TransferParameters struct - Transfer orbit description
• Phase angle calculations - Launch window detection

Simulation Extensions:

• add_body_to_simulation() - Dynamic spacecraft creation
• Runtime body addition - No more config-only initialization

---

Build System Changes

Makefile Modifications

Add to OBJECTS list:

OBJECTS = main.o physics.o simulation.o config_loader.o renderer.o \
          test_utilities.o mission_planning.o

Add build rule:

mission_planning.o: src/mission_planning.cpp src/mission_planning.h
    $(CXX) $(CXXFLAGS) -c src/mission_planning.cpp -o mission_planning.o

Add to test build:

# Test executable includes mission_planning.o
test: test_build
    ./orbit_test

---

Test Configurations

earth_mars_simple.toml

Simple 3-body system for transfer testing:

[[bodies]]
name = "Sun"
mass = 1.989e30
radius = 6.96e8
position = { x = 0.0, y = 0.0, z = 0.0 }
parent_index = -1
color = { r = 1.0, g = 1.0, b = 0.0 }
eccentricity = 0.0
semi_major_axis = 0.0

[[bodies]]
name = "Earth"
mass = 5.972e24
radius = 6.371e6
position = { x = 1.496e11, y = 0.0, z = 0.0 }
parent_index = 0
color = { r = 0.0, g = 0.5, b = 1.0 }
eccentricity = 0.0
semi_major_axis = 1.496e11

[[bodies]]
name = "Mars"
mass = 6.39e23
radius = 3.3895e6
position = { x = 2.279e11, y = 0.0, z = 0.0 }
parent_index = 0
color = { r = 0.8, g = 0.3, b = 0.1 }
eccentricity = 0.0
semi_major_axis = 2.279e11

---

Success Criteria

✅ Phase 1-2 Success - COMPLETE

• Transfer parameters match NASA reference (±5%)
• Phase angle calculations accurate (±1°)
• Launch window detection works
• Fast-forward to launch window succeeds

✅ Phase 3 Success - COMPLETE

• Spacecraft spawns at correct position
• Initial velocity = Earth velocity + Δv
• Parent = Sun for transfer orbit
• Local/global coordinates consistent

⏸️ Phase 4 Success - IN PROGRESS (DEBUGGING)

• Earth→Mars transfer completes (time ±10%)
• Spacecraft reaches Mars SOI (distance < 2×SOI)
• SOI transitions: Earth→Sun→Mars tracked correctly
• Energy drift < 1% during transfer (currently 9.98×10¹⁶%)

⏸️ Phase 5 Success - NOT STARTED

• Root body transition tests use calculated trajectory
• Manual config positioning eliminated
• Better validation than sun_transitions >= 1

⏸️ Phase 6 Success - NOT STARTED

• Round-trip mission completes
• Both transfers validated
• Return journey matches expectations

---

Timeline Estimate vs. Actual

Planned:

• Phase 1: 1 day - Core transfer calculations ✅ COMPLETED (1 day)
• Phase 2: 1 day - Launch window detection ✅ COMPLETED (same day)
• Phase 3: 1.5 days - Spacecraft spawning ✅ COMPLETED (same day)
• Phase 4: 1.5 days - Full transfer integration test ⏸️ IN DEBUGGING
• Phase 5: 0.5 days - Enhanced transition tests ⏸️ NOT STARTED
• Phase 6: 1 day - Round-trip mission (optional) ⏸️ NOT STARTED

Actual Progress (January 16, 2026):

• Phase 1: ✅ COMPLETE - All transfer calculations validated
• Phase 2: ✅ COMPLETE - Launch window detection working
• Phase 3: ✅ COMPLETE - Spacecraft spawning functional
• Phase 4: 🔄 PARTIAL - Test framework complete, trajectory bug identified
• Phase 5: ⏸️ BLOCKED - Waiting on Phase 4
• Phase 6: ⏸️ BLOCKED - Waiting on Phase 4

Time Invested: ~6 hours (Phases 1-3) Estimated Time to Complete Phase 4: 2-3 hours debugging Total for Phases 1-5: ~1 day (excluding Phase 4 debug time)

---

Files Summary

New Files Created:

• src/mission_planning.h (+40 lines) ✅
• src/mission_planning.cpp (+150 lines) ✅
• tests/test_mission_planning.cpp (+95 lines) ✅
• tests/test_hohmann_transfer.cpp (+73 lines) ✅ (Phase 4 partial)
• tests/configs/earth_mars_simple.toml (+30 lines) ✅

Modified Files:

• src/simulation.h (+3 lines) ✅
• src/simulation.cpp (+33 lines) ✅
• Makefile (+5 lines) ✅
• tests/test_root_body_transitions.cpp (refactor - PENDING Phase 5)

Net Lines: ~+429 lines (Phases 1-3 complete, Phase 4 partial)

---

Debugging Notes

Phase 4 Trajectory Bug

Symptom: Spacecraft does not follow expected Hohmann transfer orbit

Initial Conditions (Correct):

Spacecraft global position: (-6.94×10⁹, -1.49×10¹¹, 0) m
Spacecraft global velocity: (-32697.6, 1518.47, 0) m/s
Spacecraft parent: 0 (Sun)
Initial orbital energy: -3.52×10⁸ J (correct for Hohmann transfer)

After First update_simulation() (Incorrect):

Spacecraft local position: (6.11×10⁷, -2.84×10⁶, 0) m
Energy: +3.51×10²³ J (wrong sign, unphysically large)
Energy drift: 9.98×10¹⁶% (should be < 5%)

Expected Behavior:

Spacecraft should follow ellipse:
- Periapsis: 1.496×10¹¹ m (Earth distance)
- Apoapsis: 2.279×10¹¹ m (Mars distance)
- Semi-major axis: 1.888×10¹¹ m
- Period: ~518 days (full orbit), ~259 days (half-orbit to Mars)

Actual Behavior:

• Spacecraft trajectory diverges immediately
• Not following Hohmann ellipse
• Energy becomes positive (hyperbolic, unbound)
• Position magnitude grows to ~10¹³ AU (wrong scale)

Hypothesis: The issue is likely in update_simulation() coordinate transforms for newly added bodies. Specifically:

1. Local frame integration error: rk4_step() integrates local coordinates, but newly added spacecraft may have incorrect local coordinates after first update.

2. compute_global_coordinates() not called: After spawning spacecraft, we set both local and global coordinates manually. The first update_simulation() may recalculate local coordinates incorrectly.

3. SOI transition interference: Spacecraft parent = 0 (Sun), but find_dominant_body() might incorrectly switch parent during first few updates.

4. Order of operations issue: In update_simulation():

   • Check SOI transition
   • If transition: convert local→global, switch parent, convert global→local
   • Integrate: rk4_step() on local coordinates
   • Compute global: compute_global_coordinates()

   The problem: Newly added spacecraft already has correct global coordinates, but compute_global_coordinates() may recalculate them incorrectly from possibly corrupted local coordinates.

Investigation Plan:

1. Add printf statements to update_simulation() to print spacecraft local/global coordinates before/after each operation
2. Check if find_dominant_body() is changing spacecraft parent unexpectedly
3. Verify rk4_step() is using correct parameters (position, velocity, dt, body_mass, parent_mass)
4. Test with spacecraft starting at parent ≠ 0 to see if issue is specific to Sun-centered orbits
5. Consider calling compute_global_coordinates() immediately after add_body_to_simulation() to ensure consistency

Key Code Sections to Examine:

• src/simulation.cpp::update_simulation() - lines 95-141
• src/simulation.cpp::add_body_to_simulation() - lines 29-67
• src/physics.cpp::rk4_step() - lines 56-89
• src/physics.cpp::evaluate_acceleration() - lines 91-104

Potential Fix: The issue may be that we're setting spacecraft global coordinates manually in add_body_to_simulation(), but update_simulation() expects to compute them from local coordinates. The fix might be to:

1. Set only local coordinates when adding spacecraft
2. Let update_simulation() handle global coordinate computation
3. OR: Add a flag to skip compute_global_coordinates() for the first few updates after spawning

Workaround for Testing: For now, test Phase 1-3 components separately without running full transfer simulation. The core functionality (calculations, launch window, spawning) is validated and working correctly.

---

Risks and Mitigations

High Risk

• Energy conservation during transfer

  • Mitigation: Verify with energy tracking in tests
  • Backup: Use smaller timestep if needed

• SOI transition edge cases

  • Mitigation: Comprehensive transition tracking in tests
  • Backup: Adjust hysteresis if oscillation occurs

Medium Risk

• Launch window calculation accuracy

  • Mitigation: Validate against known missions (NASA data)
  • Backup: Increase tolerance window if needed

• Spacecraft spawning bugs

  • Mitigation: Unit tests for velocity/position
  • Backup: Manual verification with visualization

Low Risk

• Fast-forward simulation stability
  • Mitigation: Use existing update_simulation() (tested)
  • Backup: Reduce fast-forward steps if needed

---

Future Work (Post-Implementation)

Immediate Next Steps

1. Inclination Support - Extend to 3D transfers

   • Need 3D angular position calculations
   • Longitude of ascending node, inclination, argument of periapsis
   • Phase angle calculations in 3D

2. Capture Burns - Add velocity reduction at arrival

   • Simulate retrograde burns for orbital capture
   • Calculate Δv needed for circularization

3. Lambert Solver - General transfer solver

   • Not just Hohmann transfers
   • Arbitrary departure/arrival positions and times
   • Non-planar transfers

Visualization Features

4. Mission GUI - Interactive departure window visualization

   • Show current phase angle vs. required
   • Countdown to launch window
   • Transfer trajectory preview

5. Multiple Burns - Support for course corrections

   • Mid-course corrections
   • Gravity assist maneuvers
   • Powered flybys

6. SOI Visualization - Render SOI boundaries

   • Wireframe spheres for each body
   • Color-coded by mass
   • Toggle with keyboard

Advanced Features

7. Mission Planner - Complete mission design tool

   • Multi-leg missions
   • Optimization (minimum Δv, minimum time)
   • Launch date search

8. Real Ephemeris - Use actual planetary positions

   • JPL Horizons API integration
   • Date-based initialization
   • Real mission planning

---

References

• docs/patched_conics_plan.md - SOI transition implementation
• docs/hierarchical_frames_plan.md - Local frame integration (archived)
• docs/implementation_plan.md - Overall system architecture
• NASA Technical Memorandum "Hohmann Transfer Calculations"
• Orbital Mechanics for Engineering Students (Curtis)

---

Notes

Coordinate System:

• All calculations assume planar motion (z = 0) for initial implementation
• Angular positions measured in XY plane
• Future work: Extend to 3D with inclination

Timekeeping:

• Simulation time in seconds, conversions to days for display
• Fast-forward uses 1-day steps for efficiency
• Timestep remains 60s during fast-forward

Mass Strategy:

• Spacecraft mass = 1.0 kg (negligible but non-zero)
• Physics engine handles test particles correctly (mass cancels)
• No N-body perturbations from spacecraft

Validation Strategy:

• Compare against NASA reference missions (Viking, Curiosity, etc.)
• Energy conservation tracking
• Transfer time accuracy
• SOI transition verification

Testing Approach:

• Unit tests for each function (formulas, calculations)
• Integration tests for full missions
• Regression tests against manual config approach