@ -1,89 +1,47 @@
# 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.
A 3D orbital mechanics simulation using a 2-body gravitational model with sphere of influence (SOI) transitions. Built with C-style C++ and raylib.
## Features
- **2-body gravitational physics** with Euler integration
- **Eccentric orbit support** - circular and elliptical orbits using vis-viva equation
- **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)
- 2-body gravitational physics with SOI transitions
- Eccentric orbit support (circular and elliptical)
- 3D real-time visualization with interactive camera
- Configurable star systems via text files
- Simulation controls (pause, 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:
```bash
git clone --recursive https://github.com/yourusername/claudes_game.git
cd claudes_game
```
If you already cloned without `--recursive` , initialize the submodule:
```bash
git submodule update --init --recursive
git submodule update --init --recursive # If already cloned without --recursive
```
### Dependencies (Debian 13)
Install the required system packages:
```bash
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
sudo apt update
sudo apt 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
```bash
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:
```bash
make rebuild
```
To clean everything including raylib:
```bash
make clean-all
make # Build raylib (first time) and compile sources
make rebuild # Clean and rebuild
make clean-all # Clean everything including raylib
```
## Running
Run with the default solar system configuration:
```bash
./orbit_sim
```
Run with a custom configuration file:
```bash
./orbit_sim configs/example_binary_star.txt
./orbit_sim # Run with the default solar system configuration
./orbit_sim configs/example_binary_star.txt # Run with a custom configuration file:
```
## Controls
@ -94,43 +52,12 @@ Run with a custom configuration file:
- **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 eccentricity semi_major_axis(m)
# Sun at origin
Sun 1.989e30 6.96e8 0 0 0 -1 1.0 1.0 0.0 0 0
# Earth - circular orbit (e=0)
Earth 5.972e24 6.371e6 1.496e11 0 0 0 0.0 0.5 1.0 0 1.496e11
# Comet - eccentric orbit (e=0.7)
Comet 1e14 5e3 1.122e11 0 0 0 0.5 0.8 1.0 0.7 3.74e11
```
## Documentation
Fields:
- **name** : Body name (string, no spaces)
- **mass** : Mass in kilograms
- **radius** : Radius in meters
- **x, y, z** : Initial position in meters (absolute coordinates)
- **parent_index** : Index of gravitational parent (-1 for root bodies like stars)
- **r, g, b** : RGB color values (0.0 to 1.0)
- **eccentricity** : Orbital eccentricity (0 = circular, >0 = elliptical)
- **semi_major_axis** : Semi-major axis in meters (for e=0, use orbital radius)
Velocities are calculated automatically using the vis-viva equation based on position and orbital parameters.
## 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)
- ** [Technical Reference ](docs/implementation_plan.md )** - Data structures and module overview
- ** [Detailed Architecture ](docs/verbose_project_overview.md )** - Complete implementation details and data flow
- ** [Testing Guide ](docs/test_verification.md )** - Verification commands and expected behavior
- ** [Known Issues ](docs/config_assumptions.md )** - Configuration bugs and future improvements
## License
