claudes_game/docs/config_format.md

Config Format Reference

Overview

Simulation configuration files use TOML format and are loaded via load_system_config() in config_loader.h. The config defines three main sections:

• [[bodies]] - Celestial bodies (stars, planets, moons)
• [[spacecraft]] - Spacecraft orbiting bodies
• [[maneuvers]] - Impulsive burns for spacecraft

Bodies Configuration

Each body entry defines a celestial object with physical properties and orbital elements.

Required Fields

Field	Type	Units	Description
name	string	-	Unique identifier for the body
mass	float	kg	Mass of the body
radius	float	m	Physical radius of the body
parent_index	integer	-	Index of parent body (-1 for root/star)
color	table	RGB	RGB color for rendering

Orbit Table (nested)

Field	Type	Units	Default	Description
semi_major_axis	float	m	0.0	Semi-major axis (elliptical/hyperbolic orbits only)
semi_latus_rectum	float	m	-	Semi-latus rectum (parabolic orbits only)
eccentricity	float	-	0.0	Orbital eccentricity (0-1 for elliptical, ~1 for parabolic, >1 for hyperbolic)
true_anomaly	float	rad	0.0	Initial true anomaly (position along orbit)
inclination	float	rad	0.0	Orbital plane inclination
longitude_of_ascending_node	float	rad	0.0	Longitude of ascending node
argument_of_periapsis	float	rad	0.0	Argument of periapsis

Bodies Example

# Root body (star)
[[bodies]]
name = "Sun"
mass = 1.989e30
radius = 6.96e8
parent_index = -1
color = { r = 1.0, g = 1.0, b = 0.0 }
orbit = {
    semi_major_axis = 0.0,
    eccentricity = 0.0,
    true_anomaly = 0.0
}

# Planet orbiting the star
[[bodies]]
name = "Earth"
mass = 5.972e24
radius = 6.371e6
parent_index = 0
color = { r = 0.0, g = 0.5, b = 1.0 }
orbit = {
    semi_major_axis = 1.496e11,
    eccentricity = 0.0167,
    inclination = 0.0,
    longitude_of_ascending_node = 0.0,
    argument_of_periapsis = 0.0,
    true_anomaly = 0.0
}

# Moon orbiting the planet
[[bodies]]
name = "Moon"
mass = 7.342e22
radius = 1.737e6
parent_index = 1
color = { r = 0.7, g = 0.7, b = 0.7 }
orbit = {
    semi_major_axis = 3.844e8,
    eccentricity = 0.0549,
    inclination = 0.089,
    true_anomaly = 0.0
}

Special Cases

Root Bodies: Set parent_index = -1. Root bodies represent stars and have no parent. Their orbital elements should all be zero.

Parabolic Orbits: When eccentricity ≈ 1.0 (within PARABOLIC_TOLERANCE = 1e-3), use semi_latus_rectum instead of semi_major_axis:

[[bodies]]
name = "Comet"
mass = 1.0e14
radius = 5.0e3
parent_index = 0
color = { r = 0.7, g = 0.8, b = 0.9 }
orbit = {
    semi_latus_rectum = 2.992e11,
    eccentricity = 1.0,
    true_anomaly = 0.0
}

Hyperbolic Orbits: Use negative semi_major_axis for hyperbolic trajectories:

[[bodies]]
name = "InterstellarComet"
mass = 1.0e14
radius = 5.0e3
parent_index = 0
color = { r = 0.5, g = 1.0, b = 0.5 }
orbit = {
    semi_major_axis = -1.496e11,
    eccentricity = 1.5,
    true_anomaly = 0.0
}

3D Orbital Orientation: Use inclination, longitude_of_ascending_node, and argument_of_periapsis for inclined orbits (Molniya example):

[[spacecraft]]
name = "Molniya_Satellite"
mass = 1000.0
parent_index = 0
orbit = {
    semi_major_axis = 26540000.0,
    eccentricity = 0.74,
    true_anomaly = 0.0,
    inclination = 1.107,
    longitude_of_ascending_node = 0.0,
    argument_of_periapsis = 4.71
}

Spacecraft Configuration

Spacecraft are similar to bodies but lack physical radius and sphere of influence. They must orbit an existing body.

Required Fields

Field	Type	Units	Description
name	string	-	Unique identifier for the spacecraft
mass	float	kg	Mass of the spacecraft
parent_index	integer	-	Index of parent body (must reference a valid body)

Orbit Table (nested)

Same as bodies - see orbital elements table above.

Spacecraft Example

[[spacecraft]]
name = "LEO_Satellite"
mass = 1000.0
parent_index = 1
orbit = {
    semi_major_axis = 6.771e6,
    eccentricity = 0.0,
    true_anomaly = 0.0
}

Differences from Bodies

• No radius field
• No color field
• No sphere of influence (SOI)
• parent_index must be a valid body index (cannot be -1)
• Cannot be a parent to other bodies or spacecraft

Maneuvers Configuration

Maneuvers define impulsive burns that modify spacecraft velocity. Each maneuver specifies when and how to execute a burn.

Required Fields

Field	Type	Units	Description
name	string	-	Unique identifier for the maneuver
spacecraft_name	string	-	Name of the spacecraft to apply burn to
direction	string	-	Burn direction (see valid values below)
delta_v	float	m/s	Velocity change magnitude
trigger_type	string	-	Trigger condition type
trigger_value	float	varies	Trigger condition value

Valid Direction Values

Direction	Description
"prograde"	Along velocity vector (increases orbital energy)
"retrograde"	Opposite velocity vector (decreases orbital energy)
"normal"	Along angular momentum vector (orbit normal)
"antinormal"	Opposite angular momentum vector
"radial_in"	Toward parent body
"radial_out"	Away from parent body

Valid Trigger Types

Trigger Type	trigger_value	Description
"time"	seconds	Execute when simulation time >= trigger_value
"true_anomaly"	radians	Execute when spacecraft true anomaly within 0.01 rad of trigger_value

Maneuvers Example

# Time-based burn at 1 hour
[[maneuvers]]
name = "orbit_raise_1"
spacecraft_name = "LEO_Satellite"
trigger_type = "time"
trigger_value = 3600.0
direction = "prograde"
delta_v = 500.0

# True anomaly-based burn at periapsis (ν = 0)
[[maneuvers]]
name = "periapsis_burn"
spacecraft_name = "LEO_Satellite"
trigger_type = "true_anomaly"
trigger_value = 0.0
direction = "prograde"
delta_v = 1000.0

# Retrograde burn at apogee for orbit circularization
[[maneuvers]]
name = "circularize"
spacecraft_name = "LEO_Satellite"
trigger_type = "true_anomaly"
trigger_value = 3.14159
direction = "retrograde"
delta_v = 500.0

Parsing Details

Parabolic vs Non-Parabolic Orbits

The parser uses eccentricity to determine which orbit parameter is required:

• Parabolic (|e - 1.0| < 1e-3): Requires semi_latus_rectum, semi_major_axis is ignored
• Non-parabolic (e ≠ 1.0): Requires semi_major_axis, semi_latus_rectum is ignored

Default Values

Orbital elements default to 0.0 if not specified:

• true_anomaly = 0.0
• inclination = 0.0
• longitude_of_ascending_node = 0.0
• argument_of_periapsis = 0.0

Parent Index Behavior

The parent_index field defines orbital hierarchy:

• -1: Root body (no parent, typically a star)
• 0 to N: Index of parent body in the bodies array
• Bodies must be ordered such that parents appear before children
• Spacecraft parent_index must reference a valid body index

Numeric Type Handling

All numeric fields accept either integers or floating-point values:

• mass, radius, semi_major_axis, etc.: Accept int or float
• parent_index: Accepts int (preferred) or float (converted to int)
• Color components: Accept int or float (0-1 range typical)

Validation Rules

The config validator (config_validator.cpp) runs automatically after loading. All validations must pass for the simulation to start.

Validation Constants

Constant	Value	Description
MIN_MASS_RATIO	1000.0	Minimum parent/child mass ratio for large bodies
PARABOLIC_TOLERANCE	1e-3	Tolerance for detecting parabolic orbits
NESTED_ORBIT_FRACTION	5.0	Max orbit radius as fraction of parent SOI

Parent Index Ordering

Rule: Body parent_index must be < body index or -1.

Purpose: Ensures parents are defined before children in the config file.

Example Error:

Body 'Moon' (index 3) has invalid parent_index 3 - must be < 3 or -1

Spacecraft Validation: Spacecraft parent_index must be a valid body index (0 to body_count-1).

Orbital Elements

Elliptical Orbits (e < 1):

• semi_major_axis must be > 0

Parabolic Orbits (|e - 1.0| < 1e-3):

• semi_latus_rectum must be > 0
• semi_major_axis is not used

Hyperbolic Orbits (e > 1):

• semi_major_axis must be < 0 (negative for hyperbolic)
• semi_major_axis must not be 0

General:

• eccentricity must be >= 0
• semi_major_axis or semi_latus_rectum must not be 0

True Anomaly Ranges (Hyperbolic Orbits)

Rule: For hyperbolic orbits (e > 1), true anomaly must be within valid asymptotic bounds.

Valid Range: [0, arccos(-1/e)] ∪ [2π - arccos(-1/e), 2π]

Purpose: Prevents specifying positions in the forbidden region of hyperbolic orbits.

Example Error:

Spacecraft 'Test' has invalid true_anomaly for hyperbolic orbit
  Eccentricity: 1.5000
  True anomaly: 2.0000 rad
  Valid range: [0, 2.3005] ∪ [3.9827, 2π]

Initial Positions

Rule: Distance between body and parent must exceed combined radii.

Purpose: Prevents objects from starting inside their parent.

Example Error:

Body 'Satellite' (index 2) too close to parent 'Earth' (index 1)
  Distance: 6.37e6 m
  Minimum required: 6.47e6 m (parent radius + body radius)

Spacecraft: Distance must be >= parent radius (spacecraft has no radius).

Mass Ratios

Rule: For root children with radius > 50% of parent, mass ratio >= 1000.

Purpose: Ensures hierarchical system stability for large bodies.

Example Error:

Body 'LargeMoon' (mass=1.00e25 kg, radius=4.00e6 m) has insufficient mass ratio with root parent 'Earth' (mass=5.97e24 kg, radius=6.37e6 m)
  Mass ratio: 0.60 (minimum required: 1000.00)
  Radius ratio: 0.63 (triggers validation for radius > 50% of parent)

SOI Overlap

Rule: Bodies sharing the same parent must not have overlapping spheres of influence.

Purpose: Prevents ambiguous SOI boundaries that could cause numerical instability.

Example Error:

Bodies 'MoonA' and 'MoonB' have overlapping SOIs while sharing same parent 'Planet'
  Separation: 1.00e8 m
  Combined SOI: 1.50e8 m (7.00e7 + 8.00e7)
  SOI overlap: 5.00e7 m

Nested Orbits

Rule: Moon-like bodies must orbit within 5x of parent's SOI.

Applies to:

• Bodies with radius < 30% of parent radius
• Bodies with eccentricity < 0.5
• Bodies with mass < 1e20 kg

Purpose: Ensures moon orbits are stable within parent's sphere of influence.

Example Error:

Body 'DistantMoon' orbit extends too far from parent 'Planet'
  Child orbit radius: 2.00e9 m
  Parent SOI radius: 1.00e9 m
  Maximum allowed: 5.00e9 m (500.0% of parent SOI)

Complete Example Config

# Complete Solar System Example with Spacecraft and Maneuvers

[[bodies]]
name = "Sun"
mass = 1.989e30
radius = 6.96e8
parent_index = -1
color = { r = 1.0, g = 1.0, b = 0.0 }
orbit = {
    semi_major_axis = 0.0,
    eccentricity = 0.0,
    true_anomaly = 0.0
}

[[bodies]]
name = "Earth"
mass = 5.972e24
radius = 6.371e6
parent_index = 0
color = { r = 0.0, g = 0.5, b = 1.0 }
orbit = {
    semi_major_axis = 1.496e11,
    eccentricity = 0.0167,
    inclination = 0.0,
    longitude_of_ascending_node = 0.0,
    argument_of_periapsis = 0.0,
    true_anomaly = 0.0
}

[[bodies]]
name = "Moon"
mass = 7.342e22
radius = 1.737e6
parent_index = 1
color = { r = 0.7, g = 0.7, b = 0.7 }
orbit = {
    semi_major_axis = 3.844e8,
    eccentricity = 0.0549,
    inclination = 0.089,
    true_anomaly = 0.0
}

[[spacecraft]]
name = "LEO_Satellite"
mass = 1000.0
parent_index = 1
orbit = {
    semi_major_axis = 6.771e6,
    eccentricity = 0.0,
    true_anomaly = 0.0
}

[[spacecraft]]
name = "Molniya_Satellite"
mass = 1000.0
parent_index = 1
orbit = {
    semi_major_axis = 26540000.0,
    eccentricity = 0.74,
    true_anomaly = 0.0,
    inclination = 1.107,
    longitude_of_ascending_node = 0.0,
    argument_of_periapsis = 4.71
}

[[maneuvers]]
name = "orbit_raise"
spacecraft_name = "LEO_Satellite"
trigger_type = "time"
trigger_value = 3600.0
direction = "prograde"
delta_v = 500.0

[[maneuvers]]
name = "periapsis_burn"
spacecraft_name = "Molniya_Satellite"
trigger_type = "true_anomaly"
trigger_value = 0.0
direction = "prograde"
delta_v = 1000.0

Orbit Type Quick Reference

Eccentricity	Orbit Type	Parameter	Example
e = 0	Circular	semi_major_axis	Planets, moons
0 < e < 1	Elliptical	semi_major_axis (positive)	Typical satellites
e ≈ 1	Parabolic	semi_latus_rectum	Escape trajectories
e > 1	Hyperbolic	semi_major_axis (negative)	Interstellar objects

Tips

1. Units: Always use SI units (kg, meters, seconds, radians)
2. Angles: Use radians for all angular values (inclination, true_anomaly, etc.)
3. Ordering: List bodies from star -> planets -> moons in order
4. Testing: Start with circular orbits (e=0) before adding complexity
5. Validation: Read error messages carefully - they indicate specific violations
6. Precision: Use scientific notation for large/small values (e.g., 1.496e11)
7. Colors: Use RGB values in [0, 1] range for realistic rendering
8. Hyperbolic: Remember true_anomaly limits for hyperbolic orbits