# 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
- Euler integration for physics
- Simple rotations (quaternions deferred)
- raylib for 3D visualization

## Core Data Structures

### Vec3 (physics.h)
```cpp
struct Vec3 {
    double x, y, z;
};
```

### CelestialBody (bodies.h)
```cpp
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)
```cpp
struct SimulationState {
    CelestialBody* bodies;
    int body_count;
    int max_bodies;
    double time;              // simulation time (seconds)
    double dt;                // time step (seconds)
};
```

### RenderState (renderer.h)
```cpp
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
};
```

## Module Overview

### Physics (physics.cpp/h)
Vector math and gravity calculations. Euler integration with `euler_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)
Text-based config parser. Auto-calculates circular orbit velocities and SOI radii.

**Config format:**
```
# name mass(kg) radius(m) x(m) y(m) z(m) parent_index r g b
Sun 1.989e30 6.96e8 0 0 0 -1 1.0 1.0 0.0
Earth 5.972e24 6.371e6 1.496e11 0 0 0 0.0 0.5 1.0
```

### 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
- Config file system with solar_system.txt

### 🔨 Remaining/Future Work
- Time scaling controls (speed up/slow down)
- Pause/resume functionality
- Additional config files (binary star, etc.)
- Time step tuning for stability

## 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 (RK4, Verlet), NOTE: try Newton-Raphson propagation method with testing first
- Interactive body selection
- Reference frame switching