Orbital plane change: a 28.5° turn costs almost as much as the climb to GEO

// game.js: turn a capsule's orbit onto the equator with one burn and count what it costs.
// Units: km, km/s, s. Earth-centered axes that do not turn: x along the line where the
// starting ring crosses the equator, z toward the north pole. The notebook writes the
// constants, the start, the control ranges, the launch sites, and the land into #data.
"use strict";

const DATA = JSON.parse(document.getElementById("data").textContent);
const {mu: MU, r_e: R_E, r_geo: R_GEO, omega_e: OMEGA_E, theta0: THETA0} = DATA;
const DEG = Math.PI / 180;

// ---- small vector helpers
const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
const scale = (a, k) => [a[0] * k, a[1] * k, a[2] * k];
const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
const len = (a) => Math.hypot(a[0], a[1], a[2]);
const unit = (a) => scale(a, 1 / len(a));

// ---- the orbit model
function circular(r, i, u) {                              // on a circle of radius r, inclination i, u from the node
  const v = Math.sqrt(MU / r);
  return {r: [r * Math.cos(u), r * Math.sin(u) * Math.cos(i), r * Math.sin(u) * Math.sin(i)],
    v: [-v * Math.sin(u), v * Math.cos(u) * Math.cos(i), v * Math.cos(u) * Math.sin(i)]};
}

function elements(r, v) {                                 // angular momentum, eccentricity vector, semi-latus rectum
  const h = cross(r, v);
  const e = sub(scale(cross(v, h), 1 / MU), unit(r));
  return {h, e, p: dot(h, h) / MU};
}

const incl = (r, v) => Math.acos(cross(r, v)[2] / len(cross(r, v)));   // cos i = h_z / |h|

function nextNode(s) {                                    // where the capsule next crosses the equator
  const {h, e, p} = elements(s.r, s.v);
  const n = cross([0, 0, 1], h);                          // toward the ascending node
  if (len(n) < 1e-9 * len(h)) return {pos: null, vh: len(h) / len(s.r)};
  const north = Math.abs(s.r[2]) < 1 ? s.v[2] > 0 : s.r[2] > 0;   // north of the equator: next node descending
  const dir = scale(unit(n), north ? -1 : 1);
  const r = p / (1 + dot(e, dir));
  return {pos: scale(dir, r), vh: len(h) / r};            // the horizontal speed there is h / r
}

const turnAngle = (side, vh) => 2 * Math.asin(Math.min(1, Math.abs(side) / (2 * vh)));

// The burn: turn the horizontal velocity about the radius at constant speed, add the forward
// change, and charge the length of the one push from the old velocity to the new.
function burn(s) {
  const rh = unit(s.r), vr = dot(s.v, rh);
  const vhVec = sub(s.v, scale(rh, vr)), vh = len(vhVec), t = scale(vhVec, 1 / vh);
  const east = unit(cross([0, 0, 1], rh));
  const toward = dot(cross(t, east), rh) < 0 ? -1 : 1;    // the sense of turn that brings t toward east
  const a = toward * Math.sign(s.side) * turnAngle(s.side / 1000, vh);
  const tNew = add(scale(t, Math.cos(a)), scale(cross(rh, t), Math.sin(a)));
  const vNew = add(scale(rh, vr), scale(tNew, vh + s.fwd / 1000));
  s.dv += len(sub(vNew, s.v));
  s.ghost = ring(s);
  s.v = vNew;
  s.armed = false;
}

// ---- velocity Verlet: half a kick, a drift, half a kick
const accel = (r) => scale(r, -MU / len(r) ** 3);
const stepSize = (s) => Math.min(30, 0.001 * len(s.r) / len(s.v));   // s; 6,300 steps per low orbit

function verlet(s, dt) {
  s.v = add(s.v, scale(accel(s.r), dt / 2));
  s.r = add(s.r, scale(s.v, dt));
  s.v = add(s.v, scale(accel(s.r), dt / 2));
  s.t += dt;
}

function step(s) {
  const dt = stepSize(s), z0 = s.r[2], before = {r: s.r, v: s.v, t: s.t};
  verlet(s, dt);
  const z1 = s.r[2];
  if (s.armed && z0 !== 0 && Math.sign(z1) !== Math.sign(z0)) {
    const toNode = dt * z0 / (z0 - z1);                   // redo the step in two parts, stopping on the equator
    Object.assign(s, before);
    verlet(s, toNode);
    burn(s);
    verlet(s, dt - toNode);
  }
  if (len(s.r) < R_E) Object.assign(s, {running: false, crashed: true});
}

function tick(s, dtReal) {
  const end = s.t + Math.min(dtReal, 0.05) * DATA.warps[s.warp];   // the cap stops jumps
  while (s.running && s.t < end) step(s);
}

// ---- the state: everything that changes, in one object
function fresh() {
  const c = circular(R_E + DATA.start.alt, DATA.start.inc * DEG, DATA.start.u * DEG);
  return {r: c.r, v: c.v, t: 0, warp: DATA.warp_start, side: DATA.side.preset, fwd: DATA.fwd.preset,
    armed: false, dv: 0, ghost: null, running: true, crashed: false, zoom: null};
}
const state = fresh();

function ring(s, n = 240) {                               // points of the current orbit, from its elements
  const {h, e, p} = elements(s.r, s.v), ecc = len(e);
  const P = ecc > 1e-6 ? unit(e) : unit(s.r), Q = cross(unit(h), P);
  const nuMax = ecc < 1 ? Math.PI : 0.97 * Math.acos(-1 / ecc);
  const pts = [];
  for (let k = 0; k <= n; k++) {
    const nu = -nuMax + (2 * nuMax * k) / n, r = p / (1 + ecc * Math.cos(nu));
    pts.push(add(scale(P, r * Math.cos(nu)), scale(Q, r * Math.sin(nu))));
  }
  return pts;
}

function zoomTarget(s) {                                  // half the view: 20 % beyond the farthest point
  const {e, p} = elements(s.r, s.v), ecc = len(e);
  const far = ecc < 1 ? p / (1 - ecc) : Infinity;
  return Math.min(160000, Math.max(7800, 1.2 * far));
}

// ---- drawing
const $ = (id) => document.getElementById(id);
const color = (name) => getComputedStyle(document.documentElement).getPropertyValue(`--${name}`).trim();
const FONT = "14px system-ui, sans-serif";
const views = {side: {id: "side", name: "side view", proj: (p) => [p[1], p[2], p[0]]},   // looking along x
  top: {id: "top", name: "top view", proj: (p) => [p[0], p[1], p[2]]}};                  // from above the pole

function fit(v) {                                         // size a canvas to its box, sharp on any screen
  const c = $(v.id), box = c.parentElement.getBoundingClientRect(), dpr = window.devicePixelRatio || 1;
  c.width = Math.round(box.width * dpr);
  c.height = Math.round(box.height * dpr);
  v.ctx = c.getContext("2d");
  v.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  Object.assign(v, {w: box.width, h: box.height});
}

function layout() {
  const W = document.documentElement.clientWidth, H = document.documentElement.clientHeight;
  document.body.className = H > W ? "upright" : "wide";
  fit(views.side);
  fit(views.top);
  render();
}

function line(ctx, pts, style, width, dash = []) {
  ctx.beginPath();
  let pen = false;
  for (const p of pts) {                                  // null breaks the line
    if (!p) { pen = false; continue; }
    if (pen) ctx.lineTo(p[0], p[1]); else ctx.moveTo(p[0], p[1]);
    pen = true;
  }
  ctx.strokeStyle = style;
  ctx.lineWidth = width;
  ctx.setLineDash(dash);
  ctx.stroke();
  ctx.setLineDash([]);
}

function disk(ctx, [x, y], r, fill, stroke) {
  ctx.beginPath();
  ctx.arc(x, y, r, 0, 2 * Math.PI);
  if (fill) { ctx.fillStyle = fill; ctx.fill(); }
  if (stroke) { ctx.strokeStyle = stroke; ctx.lineWidth = 2; ctx.stroke(); }
}

function label(ctx, text, x, y, style, align = "left") {
  ctx.font = FONT;
  ctx.textAlign = align;
  ctx.fillStyle = style;
  ctx.fillText(text, x, y);
}

const onEarth = (lon, lat, theta) => {                    // a point on the turning globe, in the fixed axes
  const l = (lon * DEG) + theta, b = lat * DEG;
  return [R_E * Math.cos(b) * Math.cos(l), R_E * Math.cos(b) * Math.sin(l), R_E * Math.sin(b)];
};

function drawView(v, c) {
  const {ctx, w, h} = v, k = Math.min(w, h - 24) / (2 * state.zoom);   // px per km; room for the name
  const cx = w / 2, cy = 24 + (h - 24) / 2;
  const at = (p) => { const q = v.proj(p); return [cx + q[0] * k, cy - q[1] * k]; };
  const hidden = (p) => { const q = v.proj(p); return q[2] < 0 && q[0] ** 2 + q[1] ** 2 < R_E ** 2; };
  const visible = (pts) => pts.map((p) => (hidden(p) ? null : at(p)));
  ctx.clearRect(0, 0, w, h);
  const theta = THETA0 + OMEGA_E * state.t;

  // the equator and the GEO ring, flat on it
  if (v.id === "side") {
    line(ctx, [[0, cy], [w, cy]], c.muted, 1);
    line(ctx, [at([0, -R_GEO, 0]), at([0, R_GEO, 0])], c.second, 2);
  } else {
    line(ctx, [[0, cy], [w, cy]], c.muted, 1, [4, 4]);    // where the starting ring crosses the equator
    const geo = [];
    for (let a = 0; a <= 360; a += 3) geo.push(at([R_GEO * Math.cos(a * DEG), R_GEO * Math.sin(a * DEG), 0]));
    line(ctx, geo, c.second, 2);
  }
  // the globe, its land on the near side, and the launch sites
  disk(ctx, [cx, cy], R_E * k, c.globe);
  ctx.globalAlpha = 0.5;                                  // rim and land faint, so a ring close to the rim stands out
  ctx.beginPath();
  ctx.arc(cx, cy, R_E * k, 0, 2 * Math.PI);
  ctx.strokeStyle = c.ink;
  ctx.lineWidth = 1;
  ctx.stroke();
  for (const coast of DATA.land) {
    const pts = [];
    for (let j = 0; j < coast.length; j += 2) {
      const p = onEarth(coast[j], coast[j + 1], theta);
      pts.push(v.proj(p)[2] < 0 ? null : at(p));
    }
    line(ctx, pts, c.ink, 0.8);
  }
  ctx.globalAlpha = 1;
  for (const site of DATA.sites) {
    const p = onEarth(site.lon, site.lat, theta);
    if (v.proj(p)[2] >= 0) disk(ctx, at(p), 3, site.name === DATA.active_site ? c.ink : c.muted);
  }
  // the ring before the last burn, the ring now, the capsule, and the armed burn
  if (state.ghost) line(ctx, visible(state.ghost), c.muted, 1.2);
  line(ctx, visible(ring(state)), c.accent, 2);
  if (state.armed) {
    const node = nextNode(state).pos;
    if (node) {
      const [x, y] = at(node);
      disk(ctx, [x, y], 8, null, c.accent);
      label(ctx, "burn here", x + 11, y - 8, c.accent);
    }
  }
  // the capsule: a dot ringed in the background color, larger than a site; behind the globe only its outline
  if (hidden(state.r)) disk(ctx, at(state.r), 4.5, null, c.fg);
  else disk(ctx, at(state.r), 5.5, c.fg, c.bg);
  label(ctx, v.name, 6, 16, c.fg);
  if (v.id === "side") label(ctx, "GEO ring, edge on", 6, h - 6, c.second);
  else if (state.zoom < R_GEO) label(ctx, "GEO ring off view", 6, h - 6, c.second);
}

const fmt = (x, digits = 0) => x.toLocaleString("en-US", {minimumFractionDigits: digits, maximumFractionDigits: digits});

function render() {
  if (state.zoom === null) state.zoom = zoomTarget(state);
  const c = Object.fromEntries(["bg", "fg", "ink", "accent", "second", "muted", "globe"].map((n) => [n, color(n)]));
  drawView(views.side, c);
  drawView(views.top, c);
  $("incl").textContent = `${(incl(state.r, state.v) / DEG).toFixed(2)}°`;
  $("speed").textContent = `${len(state.v).toFixed(2)} km/s`;
  $("alt").textContent = state.crashed ? "hit the Earth" : `${fmt(len(state.r) - R_E)} km up`;
  $("dv").textContent = `${state.dv.toFixed(2)} km/s`;
  $("climb").textContent = `${DATA.climb.toFixed(2)} km/s`;
  $("clock").textContent = `t ${(state.t / 3600).toFixed(1)} h`;
  const node = nextNode(state);
  $("side").value = state.side;
  $("fwd").value = state.fwd;
  $("side-val").textContent = `${fmt(state.side)} m/s · turns ${(turnAngle(state.side / 1000, node.vh) / DEG).toFixed(1)}°`;
  $("fwd-val").textContent = `${state.fwd > 0 ? "+" : ""}${fmt(state.fwd)} m/s`;
  $("burn").textContent = state.armed ? "armed" : "Burn at equator";
  $("burn").classList.toggle("armed", state.armed);
  $("go").textContent = state.running ? "Pause" : "Play";
  $("warp-val").textContent = `${fmt(DATA.warps[state.warp])}×`;
}

// ---- controls, keys, and the loop
function set(partial) {
  Object.assign(state, partial);
  if (!("zoom" in partial)) state.zoom = zoomTarget(state);   // a set jumps to the new size
  render();
}
const clamp = (x, lo, hi) => Math.min(hi, Math.max(lo, x));
const nudge = (key, sign) => set({[key]: clamp(state[key] + sign * DATA[key].step, DATA[key].min, DATA[key].max)});
const nudgeWarp = (sign) => set({warp: clamp(state.warp + sign, 0, DATA.warps.length - 1)});
const arm = () => { if (!state.crashed) set({armed: !state.armed}); };
const go = () => { if (!state.crashed) set({running: !state.running}); };
const reset = () => set(fresh());

for (const key of ["side", "fwd"]) {
  const slider = $(key);
  Object.assign(slider, {min: DATA[key].min, max: DATA[key].max, step: 1});
  slider.addEventListener("input", () => set({[key]: Number(slider.value)}));
  $(`${key}-minus`).addEventListener("click", () => nudge(key, -1));
  $(`${key}-plus`).addEventListener("click", () => nudge(key, 1));
}
$("burn").addEventListener("click", arm);
$("go").addEventListener("click", go);
$("warp-minus").addEventListener("click", () => nudgeWarp(-1));
$("warp-plus").addEventListener("click", () => nudgeWarp(1));
$("reset").addEventListener("click", reset);
document.addEventListener("keydown", (e) => {
  const actions = {b: arm, " ": go, "[": () => nudgeWarp(-1), "]": () => nudgeWarp(1), r: reset};
  const act = actions[e.key.toLowerCase()];
  if (act && !(e.target instanceof HTMLButtonElement && e.key === " ") && !(e.target instanceof HTMLInputElement)) {
    e.preventDefault();
    act();
  }
});

let last = null;
function frame(now) {                                     // called by the browser once per screen refresh
  const dt = last === null ? 0 : (now - last) / 1000;
  last = now;
  if (state.running) tick(state, dt);
  state.zoom += (zoomTarget(state) - state.zoom) * Math.min(1, 3 * dt);   // ease toward the new size in about 1 s
  render();
  requestAnimationFrame(frame);
}

window.addEventListener("resize", layout);
window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", render);
layout();
requestAnimationFrame(frame);
window.game = {state, set, render};