# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

A 3D orbital mechanics simulation using a 2-body gravitational model with sphere of influence (SOI) transitions. The simulation features real-time visualization using raylib and supports configurable star systems via text files.

## Architecture

### Code Style
This project uses **C-style C++**: structs and functions, no classes or templates. All headers use include guards. Memory management uses malloc/free.

### Core Components

**Physics Layer** (`physics.h/cpp`)
- Vector math operations (Vec3 struct with add, sub, scale, normalize, magnitude, distance)
- Gravitational force calculation using Newton's law: F = G * m1 * m2 / r^2
- Euler integration for position/velocity updates
- Defines gravitational constant G = 6.67430e-11

**Simulation Layer** (`bodies.h/cpp`)
- `CelestialBody` struct: stores name, mass, radius, position, velocity, SOI radius, parent index, color
- `SimulationState` struct: manages array of bodies, body count, simulation time, time step (dt)
- SOI (sphere of influence) calculations using Hill sphere approximation
- Dynamic parent switching when bodies cross SOI boundaries
- `find_dominant_body()` determines which body has gravitational dominance
- `update_simulation()` runs one physics step: finds dominant parent, calculates gravity, applies Euler integration

**Configuration Layer** (`config_loader.h/cpp`)
- Parses text configuration files with format: `name mass radius x y z parent_index r g b`
- Automatically calculates circular orbit velocities for all bodies
- Calculates SOI radii for all bodies based on parent relationships
- Comments start with `#`, parent_index -1 indicates root bodies (stars)

**Rendering Layer** (`renderer.h/cpp`)
- `RenderState` struct: manages Camera3D, distance_scale, size_scale, show_info flag
- Uses logarithmic distance scaling for visualization (astronomical distances → screen coordinates)
- Uses exponential size scaling for body rendering (realistic radii → visible spheres)
- Implements 3D camera controls via arrow keys
- Renders bodies as colored spheres using raylib

**Main Program** (`main.cpp`)
- Initializes simulation with MAX_BODIES=100, TIME_STEP=60 seconds
- Runs 100 physics steps per frame for stability (adjustable with speed multiplier)
- Game loop: input handling → camera update → physics update (if not paused) → rendering
- Supports speed multiplier (2x/0.5x per keypress, min 0.125x)

### Data Flow

1. Configuration file → `load_system_config()` → populates `SimulationState`
2. `calculate_initial_velocities()` → sets circular orbit velocities
3. `calculate_soi_radii()` → computes sphere of influence for each body
4. Main loop:
   - `update_simulation()` → for each body:
     - `find_dominant_body()` → determine gravitational parent
     - `calculate_gravity_force()` → compute force from parent
     - `euler_step()` → update position/velocity
   - `render_simulation()` → for each body:
     - `scale_position()` → convert to render coordinates
     - `scale_radius()` → convert to render size
     - `render_body()` → draw sphere with color

### Key Implementation Details

**SOI Transitions**: Bodies dynamically switch gravitational parents when crossing sphere of influence boundaries. The switch uses a 0.5x distance hysteresis to prevent oscillation.

**Rendering Scales**: Astronomical scales are incompatible with graphics. The renderer applies:
- Logarithmic distance scaling to fit solar system in viewport
- Exponential size scaling to make small bodies visible
- Both scales are configurable in `RenderState`

**Physics Stability**: Multiple physics steps per frame (100x by default) provide smoother integration. The time step is 60 seconds, so each frame simulates 6000 seconds of time at 1x speed.

**Velocity Calculation**: Initial velocities for circular orbits are calculated using v = sqrt(G * M / r) where M is parent mass and r is orbital radius.