claudes_game/docs/config_assumptions.md

Configuration File Assumptions and Issues

Recent Updates:

• ✅ FIXED: Eccentric orbit support added via eccentricity and semi_major_axis parameters
• ✅ FIXED: Binary star barycenter calculation
• ✅ FIXED: Refactored main.cpp into focused functions (parse args, run_headless, run_gui)
• ✅ FIXED: Added initial state capture in headless mode for comparison with final state
• ⚠️ TODO: Update configs/solar_system.txt to new 12-field format
• ⚠️ TODO: Update configs/example_binary_star.txt to new 12-field format
• ⚠️ TODO: Fix Moon and Jupiter's moons positions in solar_system.txt

Key Assumptions Found:

1. Format Assumptions (from config_loader.cpp)

• Line buffer limited to 256 characters (config_loader.cpp:39)
• Name limited to 64 characters (config_loader.cpp:40)
• All 12 fields must be present: name mass radius x y z parent_index r g b eccentricity semi_major_axis (config_loader.cpp:16-20)
• File format is space-delimited

2. Solar System Configuration Issues:

Problem 1: Moon position is incorrect

• Earth is at: (1.496e11, 0, 0) m
• Moon is at: (1.500e11, 0, 0) m
• Distance: ~4 million km, but Earth-Moon distance should be ~384,400 km (~3.844e8 m)
• The Moon should be at approximately (1.496e11 + 3.844e8, 0, 0) or similar

Problem 2: Jupiter's moons positions

• Jupiter is at: (7.785e11, 0, 0) m
• Io is at: (8.207e11, 0, 0) m - 422 million km from Jupiter (should be ~422,000 km = 4.22e8 m)
• Europa is at: (8.456e11, 0, 0) m - 671 million km from Jupiter (should be ~671,000 km = 6.71e8 m)
• Ganymede/Callisto have similar issues

The moon positions appear to use absolute coordinates matching their orbital radii around the Sun, not relative positions around their parent bodies!

3. Binary Star Configuration Issues:

Problem 1: Both stars have parent_index = -1 - FIXED

• StarA: parent_index = -1
• StarB: parent_index = -1
• This means both are treated as root bodies with zero velocity (config_loader.cpp:69)
• They won't orbit each other!
• FIXED: System now detects multiple root bodies, calculates barycenter, and sets appropriate orbital velocities (config_loader.cpp:64-146, bodies.cpp:101-124)

Problem 2: Planet positions

• PlanetA1 is at (3.5e11, 0, 0) while StarA is at (3.0e11, 0, 0) - only 50 million km apart
• PlanetB1 is at (-4.2e11, 0, 0) while StarB is at (-3.7e11, 0, 0) - only 50 million km apart
• These seem reasonable as absolute positions (now supports both circular and eccentric orbits)

4. Velocity Calculation Assumptions (config_loader.cpp:78-245):

• All orbits are assumed to be circular - FIXED: Now supports both circular (e=0) and eccentric (e>0) orbits
• Velocities calculated using vis-viva equation: v = sqrt(G*M*(2/r - 1/a))
  • For circular orbits: e=0, a=orbital_radius
  • For eccentric orbits: e>0, a=semi_major_axis
• Orbits are calculated in the XY plane perpendicular to Z-axis (config_loader.cpp:219-226)
• Root bodies (parent_index = -1) get zero velocity (or orbit barycenter if multiple roots)
• Velocities are calculated relative to parent, then parent's velocity is added

5. Critical Assumption:

The code assumes positions are absolute (heliocentric), but for child bodies like moons, the positions in the config should be relative to their parent. This is not clearly documented and appears inconsistent!

Recommended Actions:

High Priority:

1. Update config files to new format - All config files need to be updated to 12-field format

   • ⚠️ configs/solar_system.txt - Still uses old 10-field format
   • ⚠️ configs/example_binary_star.txt - Still uses old 10-field format
   • ✅ configs/test_simple.txt - Already updated

2. Fix moon positions - Moon and Jupiter's moons use incorrect absolute coordinates

   • Moon should be at ~(1.496e11 + 3.844e8, 0, 0) not (1.500e11, 0, 0)
   • Jupiter's moons should be relative to Jupiter's position

Medium Priority:

3. Add config file validation - Warn when child bodies seem incorrectly positioned
4. Document coordinate system - Clarify that positions are absolute (heliocentric)

Low Priority:

5. Consider relative coordinate option - Allow specifying child positions relative to parent
6. Add 3D orbit support - Currently all orbits are in XY plane

---

Session Notes (2026-01-03):

Changes Made:

1. Refactored main.cpp - Broke 215-line main() into focused functions:

   • parse_command_line_args() - Parse command line arguments into ProgramArgs struct
   • print_startup_info() - Print simulation configuration
   • run_headless_simulation() - Terminal-based simulation with initial/final state capture
   • run_gui_simulation() - 3D visualization mode
   • Main function now ~25 lines of setup and dispatch

2. Added eccentric orbit support:

   • Extended config format from 10 to 12 fields (added eccentricity, semi_major_axis)
   • Implemented vis-viva equation: v = sqrt(G*M*(2/r - 1/a))
   • Circular orbits: e=0, a=orbital_radius
   • Elliptical orbits: e>0, a=semi_major_axis
   • Renamed calculate_initial_velocities_with_params() → calculate_velocities()

3. Updated test_simple.txt:

   • Added Comet with highly eccentric orbit (e=0.7, a=2.5 AU)
   • Perihelion: 0.75 AU, Aphelion: 4.25 AU
   • Successfully tested - comet swings from 0.75 AU to ~3.8 AU

4. Documentation updates:

   • Updated README.md with new 12-field format and examples
   • Updated this file with fixed issues and TODOs
   • Added eccentric orbit feature to feature list

Known Issues:

• Old config files still use 10-field format and need updating
• Moon positions in solar_system.txt are physically incorrect
• No validation for unrealistic body positions