claudes_game/docs/refactor_update_simulation.md

Refactoring Plan: Break Up update_simulation

Current State

update_simulation() function is long with multiple responsibilities:

1. Body RK4 updates and SOI transitions (~60 lines)
2. Body global coordinate computation (~5 lines)
3. Spacecraft RK4 updates (~15 lines)
4. Maneuver execution checking (~20 lines)
5. Spacecraft global coordinate computation (~15 lines)

Proposed Helper Functions

1. update_bodies_physics(SimulationState* sim)

• Handle body RK4 integration
• Handle SOI transitions
• ~60 lines of current body update logic

2. compute_body_globals(SimulationState* sim)

• Compute global coordinates for all bodies
• Reuse existing function or inline it
• ~5 lines

3. update_spacecraft_physics(SimulationState* sim)

• RK4 integration for spacecraft
• ~15 lines

4. execute_pending_maneuvers(SimulationState* sim)

• Check maneuver triggers
• Execute triggered maneuvers
• ~20 lines

5. compute_spacecraft_globals(SimulationState* sim)

• Compute global coordinates for spacecraft
• ~15 lines

6. Simplified update_simulation(SimulationState* sim)

void update_simulation(SimulationState* sim) {
    update_bodies_physics(sim);
    compute_body_globals(sim);
    update_spacecraft_physics(sim);
    execute_pending_maneuvers(sim);
    compute_spacecraft_globals(sim);
    sim->time += sim->dt;
}

Implementation Order

1. Move body update logic to update_bodies_physics()
2. Move spacecraft physics logic to update_spacecraft_physics()
3. Create execute_pending_maneuvers() from existing maneuver loop
4. Move spacecraft globals logic to compute_spacecraft_globals()
5. Simplify update_simulation() to call helpers
6. Update simulation.h with helper declarations
7. Test to ensure behavior is identical

Benefits

• Single responsibility for each function
• Easier to test individual components
• Cleaner update_simulation() that reads like a sequence
• Easier to debug issues in specific areas
• Functions can be reused or tested independently