Atmospheric Drag

Overview

Atmospheric drag decelerates objects in low orbits around bodies with atmospheres. Drag causes orbital decay, orbit circularization, and eventual re-entry for uncontrolled objects.

Related: Ships for ship class properties, Tick Processor for integration

Drag Model

Drag acceleration opposes the velocity of the object relative to the co-rotating atmosphere:

a_drag = -1/2 * rho * Cd * (A/m) * |v_rel|^2 * v_rel_hat

Where:

• rho – atmospheric density at altitude (exponential model)
• Cd – drag coefficient (dimensionless)
• A – cross-sectional area (m^2)
• m – total mass of the object (kg)
• v_rel – velocity relative to the rotating atmosphere
• v_rel_hat – unit vector of v_rel

Atmosphere Co-rotation

The atmosphere co-rotates with the body. The relative velocity accounts for this:

v_rel = v_object - v_body - (omega x r)

Where:

• v_object – object velocity in ICRF
• v_body – body velocity in ICRF
• omega – body angular velocity vector (rad/s), aligned with spin axis
• r – position of object relative to body center (ICRF)
• omega = (2*pi / rotation_period) * spin_axis_unit

For Earth: omega ~ 7.292e-5 rad/s, surface co-rotation speed ~ 465 m/s at equator (~6% of LEO orbital velocity).

Exponential Atmosphere Model

Density decreases exponentially with altitude:

rho(h) = rho_0 * exp(-h / H)

Where:

• h – altitude above body surface (m): h = |r| - body_radius
• rho_0 – surface density (kg/m^3)
• H – scale height (m)

Atmosphere Data

Body	rho_0 (kg/m^3)	H (km)	Effective ceiling (km)	Notes
Earth	1.225	8.5	600	Standard atmosphere
Mars	0.020	11.1	200	~1.6% of Earth surface density, 95% CO₂

Above the effective ceiling, density is treated as zero (no drag computed). This avoids computing negligible drag for high orbits.

Future Bodies

These bodies will be added in later phases:

Body	rho_0 (kg/m^3)	H (km)	Effective ceiling (km)
Venus	65.0	15.9	400
Titan	5.4	21.0	600

Affected Objects

Drag applies to:

• Ships – using per-class drag_area and drag_coefficient
• Stations – using fixed drag properties
• Jump gates – using fixed drag properties

Ship Class Drag Properties

Each ship class defines drag area and drag coefficient:

Ship Class	Cd	Area (m^2)	Notes
Fast Frigate	2.2	15	Small cross-section
Cargo Hauler	2.5	80	Large cargo pods increase drag
Long-Range Explorer	2.2	40	Medium hull

Station / Jump Gate Drag Properties

Object Type	Cd	Area (m^2)	Notes
Station	2.2	2000	ISS-scale, large solar panels
Jump gate	2.2	500	Compact structure

Integration

Drag acceleration is added to the total acceleration in the Leapfrog integrator, alongside gravity and thrust:

total_accel = gravity + thrust + drag

For ships, drag is computed at both Leapfrog kick steps (same as gravity) using pre-update body positions to preserve symplecticity.

For stations and jump gates, drag is computed alongside gravity in update_station().

Performance

Drag computation is O(bodies_with_atmospheres * objects). With Earth-only atmosphere, this adds one distance check per object per tick. The exponential and vector math are only computed when altitude < effective ceiling.

Orbital Decay Warning

When a ship’s orbit is decaying due to atmospheric drag, the physics service sets a flag on the ship state to notify the player:

• Field: atmosphere_warning (boolean) on ship Redis hash
• Condition: Set to true when drag acceleration magnitude > 1e-6 m/s^2 (roughly equivalent to altitude < 300 km for Earth)
• Client display: Warning indicator in the ship systems HUD (implementation deferred to web-client)
• Clearing: Set to false when drag drops below threshold

This does not prevent destruction – if the orbit decays to body radius, existing collision detection handles the crash and respawn.

Data Source

Atmosphere parameters (rho_0, scale_height, ceiling) are defined in services/shared/galaxy_config/shared_data.json under the ATMOSPHERES key. This is the single source of truth – both the physics server (drag.py) and the web client (drag.js) import from this shared config, preventing sync errors.

Constants

Constant	Value	Description
Drag threshold	1e-6 m/s^2	Below this, drag is negligible (skip computation)
Warning threshold	1e-6 m/s^2	Drag magnitude that triggers atmosphere warning
Earth rho_0	1.225 kg/m^3	Sea-level density
Earth scale height	8500 m	Exponential decay constant
Earth ceiling	600 km	Above this, no drag computed
Default Cd	2.2	Typical spacecraft drag coefficient