From e35c48abf8d5f68b3303f1196eac75f4f49eff29 Mon Sep 17 00:00:00 2001
From: cinnaboot <cinnaboot@protonmail.com>
Date: Wed, 22 Apr 2026 13:03:24 -0400
Subject: [PATCH] update docs/technical_reference.md

---
 docs/technical_reference.md | 46 ++++++++++++++++++++++---------------
 1 file changed, 28 insertions(+), 18 deletions(-)

diff --git a/docs/technical_reference.md b/docs/technical_reference.md
index e3af733..b7b49c2 100644
--- a/docs/technical_reference.md
+++ b/docs/technical_reference.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-N-body orbital mechanics simulator using **analytical propagation** for precise Keplerian trajectories. Supports elliptical, parabolic, and hyperbolic orbits with dynamic Sphere of Influence (SOI) transitions, impulsive burns, and 3D visualization via Raylib.
+2-body orbital mechanics simulator using **analytical propagation** for precise Keplerian trajectories. Supports elliptical, parabolic, and hyperbolic orbits with dynamic Sphere of Influence (SOI) transitions, impulsive burns, and 3D visualization via Raylib.
 
 ## Architecture
 
@@ -131,15 +131,18 @@ Sequence: argument_of_periapsis (ω) → inclination (i) → longitude_of_ascend
 - BURN_CUSTOM: user-specified vector
 
 ### Exact Position Execution
-True anomaly triggers must execute at precise orbital position:
-1. `check_maneuver_trigger()` calculates scheduled_dt to target anomaly (triggers when angular distance < 0.01 rad)
-2. If scheduled_dt < sim->dt, trigger fires
-3. Propagate spacecraft by scheduled_dt to exact position
-4. Execute burn (apply delta-v, reconstruct elements)
-5. Propagate remaining time (sim->dt - scheduled_dt)
-6. Mark spacecraft as handled to skip in update_spacecraft_physics()
+True anomaly triggers use analytical mean anomaly delta to compute exact time to target, eliminating per-frame propagation probes:
 
-**Wraparound handling**: When current_nu > 5.0 and future_nu < 1.0, detect 2π→0 crossing at periapsis.
+1. `check_maneuver_trigger()` converts current and target true anomaly to mean anomaly, computes delta-M, divides by mean motion to get `dt_needed`
+2. If `0 < dt_needed <= sim->dt`, trigger fires and `scheduled_dt` is set
+3. In `update_spacecraft_physics()`, for each spacecraft: check all pending maneuvers for that craft
+4. If a maneuver fires: propagate by `burn_dt` (scheduled_dt), execute burn, propagate remaining (`sim->dt - burn_dt`)
+5. No separate maneuver execution step — all inline in the spacecraft propagation loop
+
+**TRIGGER_TIME**: `scheduled_dt` is always 0 (burn at step boundary, quantization error in [0, DT)).
+**TRIGGER_TRUE_ANOMALY**: Sub-step timing supported via analytical mean anomaly calculation.
+
+**Future TODO**: Parabolic (Barker's equation) and hyperbolic branches for `check_maneuver_trigger()`.
 
 ### Hohmann Transfer
 `calculate_hohmann_transfer()` computes optimal two-burn transfer between two circular orbits using the vis-viva equation. Transfer time equals half the period of the transfer ellipse.
@@ -173,15 +176,22 @@ Handles orbital rendezvous planning and execution via Hohmann transfers and phas
 5. Main loop begins
 
 **Main Loop Order**:
-1. reset_spacecraft_tracking() - reset spacecraft handled flags
-2. update_bodies_physics() - SOI checks, drift detection, propagation
-3. compute_global_coordinates()
-4. execute_pending_maneuvers()
-5. update_spacecraft_physics()
-6. compute_spacecraft_globals()
-7. time += dt
-
-**Body Physics Per-Frame**:
+1. update_bodies_physics() - SOI checks, drift detection, propagation
+2. compute_global_coordinates()
+3. update_spacecraft_physics() - maneuver checking, propagation, burns
+4. compute_spacecraft_globals()
+5. time += dt
+
+**Spacecraft Physics Per-Frame** (`update_spacecraft_physics`):
+- For each spacecraft:
+  1. Validate local velocity against expected Keplerian velocity; if vel_diff > 1e-6, recalculate orbital elements
+  2. Check all pending maneuvers for this craft — if a trigger fires:
+     a. Propagate by `burn_dt` (scheduled sub-step offset)
+     b. Execute the maneuver (apply delta-v)
+     c. Propagate remaining (`sim->dt - burn_dt`)
+  3. If no maneuver: propagate full `sim->dt`
+
+**Body Physics Per-Frame** (`update_bodies_physics`):
 - Check SOI via find_dominant_body()
 - Handle transitions (compute global, update parent, compute local, reconstruct elements)
 - Check velocity drift (> 1e-6 m/s) and reconstruct if needed