Orbital Mechanics Simulation

A 3D orbital mechanics simulation using a 2-body gravitational model with sphere of influence (SOI) transitions. Features real-time visualization of celestial bodies using raylib.

Features

• 2-body gravitational physics with Euler integration
• Sphere of influence (SOI) transitions between gravitational parents
• 3D real-time visualization using raylib
• Configurable star systems via simple text files
• Interactive camera controls (rotate, zoom)
• Simulation controls (pause, resume, speed adjustment)
• Solar system and binary star example configurations

Getting Started

Cloning the Project

This project includes raylib as a git submodule. Clone with submodules:

git clone --recursive https://github.com/yourusername/claudes_game.git
cd claudes_game

If you already cloned without --recursive, initialize the submodule:

git submodule update --init --recursive

Dependencies (Debian 13)

Install the required system packages:

sudo apt-get update
sudo apt-get install -y \
    build-essential \
    g++ \
    make \
    libx11-dev \
    libxcursor-dev \
    libxrandr-dev \
    libxinerama-dev \
    libxi-dev \
    libgl1-mesa-dev \
    libglu1-mesa-dev

Note: You don't need to install raylib separately - it's included as a git submodule and will be built automatically by the Makefile.

Building

make

This will:

1. Build raylib from the submodule (first time only)
2. Compile all source files
3. Create the orbit_sim executable in the project directory

To clean and rebuild:

make rebuild

To clean everything including raylib:

make clean-all

Running

Run with the default solar system configuration:

./orbit_sim

Run with a custom configuration file:

./orbit_sim configs/example_binary_star.txt

Controls

• Arrow Keys: Rotate and zoom camera
• Space: Pause/Resume simulation
• +/-: Speed up/slow down simulation
• I: Toggle info display
• ESC: Quit

Configuration File Format

Configuration files define celestial bodies in a simple text format:

# Comments start with #
# 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
Moon 7.342e22 1.737e6 1.500e11 0 0 1 0.7 0.7 0.7

Fields:

• name: Body name (string, no spaces)
• mass: Mass in kilograms
• radius: Radius in meters
• x, y, z: Initial position in meters
• parent_index: Index of gravitational parent (-1 for root bodies like stars)
• r, g, b: RGB color values (0.0 to 1.0)

Velocities are calculated automatically for circular orbits.

Project Structure

claudes_game/
├── src/
│   ├── main.cpp           - Main program loop
│   ├── physics.cpp/h      - Vector math and physics
│   ├── bodies.cpp/h       - Celestial bodies and simulation
│   ├── config_loader.cpp/h - Configuration file parser
│   └── renderer.cpp/h     - 3D rendering with raylib
├── configs/
│   ├── solar_system.txt   - Solar system configuration
│   └── example_binary_star.txt - Binary star example
├── docs/
│   └── implementation_plan.md - Detailed implementation plan
├── Makefile
└── README.md

Technical Details

• Physics: 2-body gravitational model using Newton's law of gravitation
• Integration: Euler method with configurable time step (default: 60 seconds)
• SOI Detection: Hill sphere approximation for sphere of influence
• Rendering: Logarithmic distance scaling and exponential size scaling for visualization
• Language: C-style C++ (structs and functions, no classes or templates)

Future Enhancements

• Quaternion-based rotations for realistic body orientation
• Orbit trail rendering
• N-body simulation mode
• More accurate integration methods (RK4, Verlet)
• Save/load simulation state
• Interactive body selection and information display
• Multiple reference frames

License

This project is provided as-is for educational and research purposes.