claudes_game/docs/implementation_plan.md

Orbital Mechanics Simulation - Technical Reference

Overview

3D orbital mechanics simulation using 2-body gravitational model with sphere of influence (SOI) transitions. Built with C-style C++ and raylib.

Technical Constraints

• C-style C++ only: structs and functions, no classes or templates
• RK4 (Runge-Kutta 4th order) integration for physics
• Simple rotations (quaternions deferred)
• raylib for 3D visualization

Core Data Structures

Vec3 (physics.h)

struct Vec3 {
    double x, y, z;
};

CelestialBody (bodies.h)

struct CelestialBody {
    char name[64];
    double mass;              // kg
    double radius;            // meters
    Vec3 position;            // meters from origin
    Vec3 velocity;            // m/s
    double soi_radius;        // sphere of influence radius (meters)
    int parent_index;         // index of gravitational parent (-1 for root)
    float color[3];           // RGB for rendering
    double eccentricity;      // orbital eccentricity (0 = circular)
    double semi_major_axis;   // meters
};

SimulationState (bodies.h)

struct SimulationState {
    CelestialBody* bodies;
    int body_count;
    int max_bodies;
    double time;              // simulation time (seconds)
    double dt;                // time step (seconds)
};

RenderState (renderer.h)

struct RenderState {
    Camera3D camera;
    double distance_scale;    // Scale factor for distances
    double size_scale;        // Scale factor for body sizes
    bool show_info;           // Display simulation info
};

OrbitalElements (bodies.h)

struct OrbitalElements {
    double time_days;
    double semi_major_axis_au;
    double eccentricity;
    double specific_energy;
    double distance_to_sun_au;
    double distance_to_ref_body_au;
    double velocity_magnitude;
};

AccelerationContext (physics.h)

struct AccelerationContext {
    SimulationState* sim;
    CelestialBody* current_body;
    int body_index;
};

Module Overview

Physics (physics.cpp/h)

Vector math and gravity calculations. RK4 (Runge-Kutta 4th order) integration with rk4_step().

Bodies (bodies.cpp/h)

Simulation state management and updates. SOI detection using Hill sphere: r_soi = a * (m/M)^(2/5)

Config Loader (config_loader.cpp/h)

TOML-based config parser using tomlc17 library. Auto-calculates circular orbit velocities and SOI radii.

Config format (TOML):

[[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

Renderer (renderer.cpp/h)

Raylib 3D visualization with logarithmic distance scaling and size scaling for visibility.

Implementation Status

✅ Completed

• Phase 1-4: Core physics, simulation, config loading, and rendering
• Raylib integration with 3D camera
• Distance and size scaling for visualization
• TOML config file system with solar_system.toml, example_binary_star.toml, test_simple.toml
• RK4 (Runge-Kutta 4th order) integration for improved accuracy
• Time scaling controls (speed up/slow down simulation)
• Pause/resume functionality
• Orbital elements calculation
• Binary/multiple star system support with barycentric orbits

🔨 Remaining/Future Work

• More accurate integration methods (Newton-Raphson propagation)
• Interactive body selection
• Reference frame switching

Technical Notes

Scaling for Visualization

• Distance: logarithmic/power-law scaling for solar system scale
• Size: minimum visible radius to prevent tiny bodies from disappearing
• Origin at Sun for simplicity

Physics Considerations

• Timestep: ~60 seconds for solar system scale
• Circular orbit velocity: v = sqrt(G * M / r)
• May need multiple physics sub-steps per render frame

Future Enhancements

• More accurate integration methods (Newton-Raphson propagation)
• Interactive body selection
• Reference frame switching
• 3D orbital visualization with inclination