Staging & the delta-v budget

1 — Burnout mass. Divide by I_spg₀ and exponentiate both sides:

Note the negative exponent — that's the form you want in code, because it's numerically better behaved and reads as "shrink the mass by this factor".

2 — Propellant required.

This is the single most useful rearrangement in the whole game. It answers "can I make this burn with what's in the tank?" without simulating anything.

3 — Numbers. I_spg₀ = 320 × 9.80665 = 3138.1 m/s.

Now shave 2 t of dry mass. Propellant was 40 − 14 = 26 t, so the new masses are m₀ = 38 t, m_f = 12 t:

+323 m/s for 2 tonnes. That's the whole argument for staging in one line: mass you're no longer accelerating is Δv you get to keep. An empty tank is dead weight that the logarithm punishes you for, and dropping it mid-flight is the only way to move the ratio.

1 — Mass flow. Substitute v_e and solve for ṁ:

2 — Time to expend the propellant. Constant flow, so it's just quantity over rate:

3 — In terms of Δv. Substitute m_f = m₀e^{−Δv/I_spg₀}, factor out m₀:

Give this one a name — it's how you'll split a maneuver node in half in Tutorial 10, so that you start burning early enough to finish late enough. Every burn you plan from here on runs through it.

4 — Units. kN ÷ (s × m/s²) = kN ÷ (m/s) = (kg·m/s²·10³) ÷ (m/s) = 10³ kg/s = t/s. So ṁ is in tonnes per second, and tonnes ÷ (t/s) gives seconds. The kilo-prefix on newtons and the kilo-prefix on grams cancel exactly. This is why KSP's unit choices are quietly excellent and why you should never introduce a conversion factor in kOS — if you find yourself writing 1000 somewhere, you've made an error.

// launch3.ks — pitch program + autostaging + live stage dV.

CLEARSCREEN.

// ---- tuning ----
SET azimuth   TO 90.
SET targetAp  TO 75000.
SET turnStart TO 1000.
SET turnEnd   TO 45000.
SET pitch0    TO 90.
SET pitch1    TO 0.
SET kShape    TO 0.5.

// ---- staging state ----
SET g0            TO 9.80665.
SET stageCooldown TO 1.0.
SET lastStageAt   TO 0.

// ---- launch ----
SAS OFF. RCS OFF.
LOCK THROTTLE TO 1.
LOCK STEERING TO HEADING(azimuth, pitchAt(SHIP:ALTITUDE)).
SET lastStageAt TO TIME:SECONDS.
STAGE.
PRINT "LIFTOFF          " AT (0,0).

UNTIL SHIP:APOAPSIS > targetAp {
  autoStage().
  telemetry().
  WAIT 0.
}

LOCK THROTTLE TO 0.
PRINT "MECO             " AT (0,0).
WAIT 1.
UNLOCK STEERING. UNLOCK THROTTLE. SAS ON.

// =========== pitch program (from tutorial 02) ===========
FUNCTION pitchAt {
  DECLARE PARAMETER h.
  LOCAL f IS (h - turnStart) / (turnEnd - turnStart).
  SET f TO MIN(MAX(f, 0), 1).
  RETURN pitch0 + (pitch1 - pitch0) * (f ^ kShape).
}

// =========== staging ===========
FUNCTION shouldStage {
  // Guard 1: never while coasting.
  IF THROTTLE <= 0.01 { RETURN FALSE. }

  // Guard 4: never when the staging system is busy.
  IF NOT STAGE:READY { RETURN FALSE. }

  // Guard 2: debounce.
  IF TIME:SECONDS < lastStageAt + stageCooldown { RETURN FALSE. }

  // Guard 3: every lit engine must be spent.
  LOCAL es IS LIST().
  LIST ENGINES IN es.
  LOCAL lit IS 0.
  LOCAL spent IS 0.
  FOR e IN es {
    IF e:IGNITION {
      SET lit TO lit + 1.
      IF e:FLAMEOUT { SET spent TO spent + 1. }
    }
  }
  IF lit = 0 { RETURN TRUE. }   // nothing lit and we want thrust
  RETURN spent = lit.
}

FUNCTION autoStage {
  IF shouldStage() {
    SET lastStageAt TO TIME:SECONDS.
    STAGE.
    PRINT "STAGE " + STAGE:NUMBER + "          " AT (0,0).
  }
}

// =========== performance ===========
FUNCTION activeIsp {
  LOCAL es IS LIST().
  LIST ENGINES IN es.
  LOCAL fTot IS 0.
  LOCAL fOverIsp IS 0.
  FOR e IN es {
    IF e:IGNITION AND NOT e:FLAMEOUT AND e:ISP > 0 {
      SET fTot TO fTot + e:AVAILABLETHRUST.
      SET fOverIsp TO fOverIsp + e:AVAILABLETHRUST / e:ISP.
    }
  }
  IF fOverIsp <= 0 { RETURN 0. }
  RETURN fTot / fOverIsp.
}

// Approximate: treats all remaining onboard propellant as usable.
// Honest about being an upper bound. See the notes below.
FUNCTION vesselDeltaV {
  LOCAL isp IS activeIsp().
  IF isp <= 0 { RETURN 0. }
  LOCAL m0 IS SHIP:MASS.
  LOCAL mf IS SHIP:DRYMASS.
  IF mf <= 0 { RETURN 0. }
  RETURN isp * g0 * LN(m0 / mf).
}

FUNCTION burnTimeFor {
  DECLARE PARAMETER dv.
  LOCAL isp IS activeIsp().
  LOCAL f IS SHIP:AVAILABLETHRUST.
  IF isp <= 0 OR f <= 0 { RETURN 0. }
  LOCAL ve IS isp * g0.
  RETURN (SHIP:MASS * ve / f) * (1 - CONSTANT:E ^ (-dv / ve)).
}

FUNCTION telemetry {
  PRINT "ALT    " + ROUND(SHIP:ALTITUDE) + "     "       AT (0,2).
  PRINT "AP     " + ROUND(SHIP:APOAPSIS) + "     "       AT (0,3).
  PRINT "SPD    " + ROUND(SHIP:VELOCITY:SURFACE:MAG,1)+"   " AT (0,4).
  PRINT "PITCH  " + ROUND(pitchAt(SHIP:ALTITUDE),1)+"     " AT (0,5).
  PRINT "STAGE  " + STAGE:NUMBER + "          "         AT (0,6).
  PRINT "ISP    " + ROUND(activeIsp(),1) + "       "    AT (0,7).
  PRINT "dV     " + ROUND(vesselDeltaV()) + "        "   AT (0,8).
  PRINT "TWR    " + ROUND(SHIP:AVAILABLETHRUST/(SHIP:MASS*9.81),2)+"  " AT (0,9).
}

On the mass-weighted Isp

Combining engines of different Isp is not an average of their Isp values. The correct combination weights by mass flow, and since flow is F/(I_spg₀), the total flow is ΣF_i/I_sp,i divided by g₀. Setting total thrust over total flow equal to an effective Isp gives:

That's a thrust-weighted harmonic mean, which is exactly what activeIsp() computes. Take a plain arithmetic average of a 320 s vacuum engine and a 170 s solid booster and you'll overestimate your Δv badly — the low-Isp engine is gulping propellant far faster than its thrust share suggests.

On requirement 5 — and why it's marked approximate

vesselDeltaV() uses SHIP:DRYMASS, which is the whole vessel with every tank empty. So during your first stage it counts the propellant sitting in stages two and three as though the first stage's engines could burn it. The number is an upper bound, and it's wrong by more the earlier in the flight you are.

Doing this properly means walking the fuel-crossfeed graph: for each burning engine, find which tanks it can actually draw from, sum only those resources, and account for tanks that will separate. kOS exposes what you'd need — e:CONSUMEDRESOURCES, part-level resource lists, decoupler stage assignments — but assembling it correctly is a genuine project, not a paragraph.

So the right call for now is the one taken above: compute the approximation, and know it's an approximation. Flight software full of quantities whose error you haven't characterised is how missions get lost. A number you understand the bias of is more useful than a number you merely hope is right. When you build the per-stage version in Arc 3, the logged data will tell you exactly how far off this one was.

The edge case in guard 3

IF lit = 0 { RETURN TRUE. } reads as reckless — no engines lit, so stage. It's safe here only because guards 1, 2 and 4 have already run: throttle is up, the cooldown has elapsed, and staging is ready. Together those mean "we are asking for thrust, we've waited, and nothing is burning" — which genuinely is the signal to fire the next stage, and it's what catches a separation where the next engine needs an explicit ignition.

Reorder those four checks and this becomes a rocket-shredder. Guard ordering is load-bearing, not stylistic.