@johnmorrisdotca/uchusen-rockets 0.10.0 → 0.11.0

package/dist/journey/timeline.d.ts

@@ -0,0 +1,115 @@
+import type { BodySource } from "./bodies.ts";
+import { type Phase, type Trip, type Vec3 } from "./trip.ts";
+/**
+ * How fast the screen plays: a multiple of normal speed.
+ *
+ * @example
+ * ```ts
+ * import type { PlaySpeed } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const fast: PlaySpeed = 4;
+ * console.log(fast);
+ * ```
+ */
+export type PlaySpeed = 0.5 | 1 | 2 | 4;
+/**
+ * Where in a trip a moment of playback is: the phase, how far through it, the mission time and how many mission seconds each screen second shows.
+ *
+ * @example
+ * ```ts
+ * import type { Place } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const words = (place: Place) => `${place.phase.id} ${Math.round(place.fraction * 100)} %`;
+ * console.log(typeof words);
+ * ```
+ */
+export interface Place {
+    phase: Phase;
+    index: number;
+    /** How far through the phase, 0 to 1. */
+    fraction: number;
+    /** Mission seconds from lift-off (negative before). */
+    missionS: number;
+    /** Mission seconds shown per second on the screen in this phase. */
+    scale: number;
+}
+/**
+ * What is true of the craft at a moment: its place, speed, acceleration, the distances, the clocks, the signal time home and how far it has turned round.
+ *
+ * @example
+ * ```ts
+ * import type { State } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const speed = (state: State) => `${Math.round(state.speedMs)} m/s`;
+ * console.log(typeof speed);
+ * ```
+ */
+export interface State extends Place {
+    dateMs: number;
+    /** Which way the engine is firing: not at all, pushing it on, or against its motion. */
+    burn: "off" | "forward" | "reverse";
+    /** How the speed is measured: from the start or destination (for a ship that burns all the way), from the Earth, the Sun or the destination. */
+    speedFrame: "start" | "earth" | "sun" | "destination";
+    speedMs: number;
+    gamma: number;
+    /** The acceleration, in g, positive along the motion. */
+    accelG: number;
+    /** Path flown, km, and the fraction of the path, 0 to 1. */
+    doneKm: number;
+    progress: number;
+    /** The straight line from the craft to the destination, km. */
+    toDestinationKm: number;
+    /** The craft's place in the trip's frame, km. */
+    positionKm: Vec3;
+    /** Time on board since lift-off and time since lift-off in the frame of the places, seconds. */
+    shipS: number;
+    frameS: number;
+    /** How long a signal takes to get home from here, seconds. */
+    signalS: number;
+    /** How far the craft has turned round, 0 (facing forward) to 1 (facing back). */
+    turned: number;
+}
+/**
+ * The total time the screen takes to play a trip at a speed.
+ * @param trip A planned trip.
+ * @param speed The play speed.
+ * @returns Seconds.
+ * @example
+ * ```ts no-run
+ * import { playSeconds, type Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const trip: Trip;
+ * console.log(playSeconds(trip, 2));
+ * ```
+ */
+export declare const playSeconds: (trip: Trip, speed?: PlaySpeed) => number;
+/**
+ * Which phase a moment of playback is in, and the mission time it shows. Inside a phase the two are linear; across phases the scale changes, which is how a minute of burn and a month of coast both fit on the screen.
+ * @param trip A planned trip.
+ * @param playbackS Seconds since Play was pressed, at the normal speed (a faster speed multiplies the clock before calling).
+ * @returns The phase, how far through it, the mission time and the scale.
+ * @example
+ * ```ts no-run
+ * import { placeAt, type Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const trip: Trip;
+ * console.log(placeAt(trip, 0).phase.id, placeAt(trip, 1e9).phase.id);
+ * ```
+ */
+export declare function placeAt(trip: Trip, playbackS: number): Place;
+/**
+ * Everything true of the craft at a moment of playback: its place, speed, acceleration, the distances, the clocks and the signal time home.
+ * @param trip A planned trip (one that can be played).
+ * @param source Where the places are.
+ * @param playbackS Seconds since Play was pressed, at the normal speed.
+ * @returns The state.
+ * @example
+ * ```ts no-run
+ * import { stateAt, type BodySource, type Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const trip: Trip;
+ * declare const source: BodySource;
+ * console.log(Math.round(stateAt(trip, source, 30).speedMs));
+ * ```
+ */
+export declare function stateAt(trip: Trip, source: BodySource, playbackS: number): State;

package/dist/journey/timeline.js

@@ -0,0 +1,193 @@
+import { C, G0 } from "./constants.js";
+import { accelerating, transferPoint } from "./physics.js";
+import { positionKm } from "./trip.js";
+/**
+ * The total time the screen takes to play a trip at a speed.
+ * @param trip A planned trip.
+ * @param speed The play speed.
+ * @returns Seconds.
+ * @example
+ * ```ts no-run
+ * import { playSeconds, type Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const trip: Trip;
+ * console.log(playSeconds(trip, 2));
+ * ```
+ */
+export const playSeconds = (trip, speed = 1) => trip.phases.reduce((sum, p) => sum + p.screenS, 0) / speed;
+/**
+ * Which phase a moment of playback is in, and the mission time it shows. Inside a phase the two are linear; across phases the scale changes, which is how a minute of burn and a month of coast both fit on the screen.
+ * @param trip A planned trip.
+ * @param playbackS Seconds since Play was pressed, at the normal speed (a faster speed multiplies the clock before calling).
+ * @returns The phase, how far through it, the mission time and the scale.
+ * @example
+ * ```ts no-run
+ * import { placeAt, type Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const trip: Trip;
+ * console.log(placeAt(trip, 0).phase.id, placeAt(trip, 1e9).phase.id);
+ * ```
+ */
+export function placeAt(trip, playbackS) {
+    let left = Math.max(0, playbackS);
+    const last = trip.phases.length - 1;
+    for (let index = 0; index <= last; index += 1) {
+        const phase = trip.phases[index];
+        if (left < phase.screenS || index === last) {
+            const fraction = Math.min(1, left / phase.screenS);
+            return { phase, index, fraction, missionS: phase.startS + fraction * (phase.endS - phase.startS), scale: (phase.endS - phase.startS) / phase.screenS };
+        }
+        left -= phase.screenS;
+    }
+    throw new Error("A trip has phases.");
+}
+const mix = (a, b, f) => a + (b - a) * f;
+/**
+ * Everything true of the craft at a moment of playback: its place, speed, acceleration, the distances, the clocks and the signal time home.
+ * @param trip A planned trip (one that can be played).
+ * @param source Where the places are.
+ * @param playbackS Seconds since Play was pressed, at the normal speed.
+ * @returns The state.
+ * @example
+ * ```ts no-run
+ * import { stateAt, type BodySource, type Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const trip: Trip;
+ * declare const source: BodySource;
+ * console.log(Math.round(stateAt(trip, source, 30).speedMs));
+ * ```
+ */
+export function stateAt(trip, source, playbackS) {
+    const place = placeAt(trip, playbackS);
+    const t = place.missionS;
+    const dateMs = trip.departMs - trip.liftoffBeforeS * 1000 + t * 1000;
+    const base = { ...place, dateMs, shipS: Math.max(0, t), frameS: Math.max(0, t), turned: 0 };
+    const dest = (ms) => positionKm(source, trip.to, ms, trip.frame);
+    const home = (p, ms) => {
+        const earth = positionKm(source, "earth", ms, trip.frame);
+        return Math.hypot(p[0] - earth[0], p[1] - earth[1], p[2] - earth[2]) / (C / 1000);
+    };
+    const b = trip.ballistic;
+    if (b) {
+        const origin = positionKm(source, trip.from, trip.departMs, trip.frame);
+        const id = place.phase.id;
+        const f = place.fraction;
+        const turned = id === "flip" ? f : id === "brake" || id === "flyby" || id === "arrival" ? 1 : 0;
+        let speed = 0;
+        let frameName = "earth";
+        let accel = 0;
+        let burn = "off";
+        let done = 0;
+        let pos = origin;
+        if (id === "preheat" || id === "ignition")
+            speed = 0;
+        else if (id === "ascent") {
+            speed = b.parkSpeed * 1000 * f;
+            accel = (b.parkSpeed * 1000) / b.ascentS / G0;
+            burn = "forward";
+        }
+        else if (id === "burn") {
+            speed = mix(b.parkSpeed, b.burnEndSpeed, f) * 1000;
+            accel = (trip.dv.departure / b.burnS) / G0;
+            burn = "forward";
+        }
+        else if (id === "coast" || id === "flip") {
+            const tau = t - (b.ascentS + b.burnS);
+            const p = transferPoint(b.mu, b.r1, b.r2, b.theta0, Math.min(tau, b.transitS));
+            pos = [p.r * Math.cos(p.theta), p.r * Math.sin(p.theta), 0];
+            speed = p.v * 1000;
+            frameName = trip.frame === "sun" ? "sun" : "earth";
+            done = arcAt(b.arc, Math.min(tau, b.transitS) / b.transitS);
+        }
+        else {
+            pos = dest(dateMs);
+            done = trip.pathKm;
+            frameName = "destination";
+            if (id === "brake") {
+                speed = mix(b.captureSpeedIn, b.captureSpeedOut, f) * 1000;
+                accel = -(trip.dv.arrival / b.brakeS) / G0;
+                burn = "reverse";
+            }
+            else if (id === "flyby")
+                speed = b.captureSpeedIn * 1000;
+            else
+                speed = (trip.verdict.level === "flyby" ? b.captureSpeedIn : b.captureSpeedOut) * 1000;
+        }
+        if (id === "ascent" || id === "burn")
+            done = 0;
+        const target = dest(dateMs);
+        return {
+            ...base,
+            burn,
+            speedFrame: frameName,
+            speedMs: speed,
+            gamma: 1,
+            accelG: accel,
+            doneKm: done,
+            progress: Math.min(1, done / trip.pathKm),
+            toDestinationKm: Math.hypot(target[0] - pos[0], target[1] - pos[1], target[2] - pos[2]),
+            positionKm: pos,
+            signalS: home(pos, dateMs),
+            turned,
+        };
+    }
+    const c = trip.continuous;
+    const tb = c.burnS;
+    const total = tb * 2 + c.flipS;
+    const tt = Math.max(0, Math.min(t, total));
+    let x = 0;
+    let v = 0;
+    let gamma = 1;
+    let proper = 0;
+    let accel = 0;
+    let burn = "off";
+    const peak = accelerating(c.a, tb);
+    if (tt <= tb) {
+        const s = accelerating(c.a, tt);
+        ({ x, v, gamma, proper } = s);
+        accel = t > 0 ? 1 : 0;
+        burn = t > 0 ? "forward" : "off";
+    }
+    else if (tt <= tb + c.flipS) {
+        x = peak.x + peak.v * (tt - tb);
+        v = peak.v;
+        gamma = peak.gamma;
+        proper = peak.proper + (tt - tb) / peak.gamma;
+    }
+    else {
+        const s = accelerating(c.a, total - tt);
+        const d = (peak.x * 2 + peak.v * c.flipS);
+        x = d - s.x;
+        v = s.v;
+        gamma = s.gamma;
+        proper = 2 * peak.proper + c.flipS / peak.gamma - s.proper;
+        accel = -1;
+        burn = "reverse";
+    }
+    const path = trip.pathKm * 1000;
+    const turned = place.phase.id === "flip" ? place.fraction : tt > tb + c.flipS ? 1 : 0;
+    const f = path > 0 ? x / path : 0;
+    const pos = [mix(c.from[0], c.to[0], f), mix(c.from[1], c.to[1], f), mix(c.from[2], c.to[2], f)];
+    return {
+        ...base,
+        burn: place.phase.id === "arrival" ? "off" : burn,
+        speedFrame: "start",
+        speedMs: place.phase.id === "arrival" ? 0 : v,
+        gamma,
+        accelG: place.phase.id === "arrival" ? 0 : (accel * c.a) / G0,
+        doneKm: x / 1000,
+        progress: Math.min(1, Math.max(0, f)),
+        toDestinationKm: Math.max(0, (path - x) / 1000),
+        positionKm: pos,
+        shipS: t <= 0 ? 0 : proper,
+        frameS: Math.max(0, t),
+        signalS: home(pos, dateMs),
+        turned,
+    };
+}
+/** The path flown, km, a fraction of the way through the transit (0 to 1), from the table of cumulative lengths. */
+function arcAt(arc, fraction) {
+    const at = Math.max(0, Math.min(1, fraction)) * (arc.length - 1);
+    const i = Math.min(arc.length - 2, Math.floor(at));
+    return mix(arc[i], arc[i + 1], at - i);
+}

package/dist/journey/trip.d.ts

@@ -0,0 +1,213 @@
+import type { BodySource } from "./bodies.ts";
+import type { CapacityKind, Craft } from "./crafts.ts";
+/** The kinds of phase a trip is made of: the countdown, the climb, the burns, the coast, the turn round, the braking and the arrival. */
+export type PhaseId = "preheat" | "ignition" | "ascent" | "burn" | "coast" | "flip" | "brake" | "flyby" | "accelerate" | "decelerate" | "arrival";
+/**
+ * One stretch of a trip: its length in mission seconds (from lift-off, which is 0) and how long it takes on the screen at normal speed.
+ *
+ * @example
+ * ```ts
+ * import type { Phase } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const coast: Phase = { id: "coast", startS: 1_050, endS: 430_000, screenS: 22 };
+ * console.log(coast.endS - coast.startS);
+ * ```
+ */
+export interface Phase {
+    id: PhaseId;
+    startS: number;
+    endS: number;
+    screenS: number;
+}
+/** How a craft stands on a trip: rated, rated at least, fine, not rated, flyby only, or cannot. */
+export type VerdictLevel = "rated" | "at-least" | "ok" | "not-rated" | "flyby" | "cannot";
+/**
+ * What a craft can do on a trip, in one plain line, with the lines behind it.
+ *
+ * @example
+ * ```ts
+ * import type { Verdict } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const verdict: Verdict = { level: "cannot", line: "Not enough fuel.", because: [], playable: false };
+ * console.log(verdict.line, verdict.playable);
+ * ```
+ */
+export interface Verdict {
+    level: VerdictLevel;
+    /** The one line shown beside the picker. */
+    line: string;
+    /** More lines, each a fact the verdict rests on. */
+    because: string[];
+    /** Whether Play is offered. */
+    playable: boolean;
+}
+/** A place or a speed as x, y and z. */
+export type Vec3 = readonly [number, number, number];
+/**
+ * A trip, planned: when it leaves, its phases, its verdict, its distances, its speed changes and what is true of the craft at the peak. Plain data, with no function in it.
+ *
+ * @example
+ * ```ts
+ * import type { Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const describe = (trip: Trip) => `${trip.from} to ${trip.to}: ${trip.verdict.line}`;
+ * console.log(typeof describe);
+ * ```
+ */
+export interface Trip {
+    from: string;
+    to: string;
+    craftId: string;
+    drive: "ballistic" | "continuous";
+    /** What the positions are measured from: the Sun, or the Earth for a trip to the Moon. */
+    frame: "sun" | "earth";
+    /** When the departure burn (or the first burn of a ship that burns all the way) begins, milliseconds since 1970. */
+    departMs: number;
+    /** When lift-off is, seconds before `departMs` (0 for a ship that starts in orbit). */
+    liftoffBeforeS: number;
+    phases: Phase[];
+    totalS: number;
+    verdict: Verdict;
+    /** Names of the figures in this plan that are estimates, not sources. */
+    estimated: string[];
+    /** The straight line from the start to the end at departure, km. */
+    straightKm: number;
+    /** The length of the path flown, km. */
+    pathKm: number;
+    /** Speed changes, m/s. */
+    dv: {
+        departure: number;
+        arrival: number;
+        total: number;
+    };
+    /** The greatest acceleration felt, g. */
+    peakG: number;
+    /** The greatest speed, m/s, and the Lorentz factor then. */
+    peakSpeed: number;
+    peakGamma: number;
+    /** Time on board and in the frame of the two ends, seconds, from lift-off. */
+    shipS: number;
+    frameS: number;
+    /** The propellant a ship that burns all the way uses, tonnes, and carries. */
+    propellantUsedT?: number;
+    propellantCarriedT?: number;
+    /** The propellant of the trip: tonnes used (and carried, where it is known), or null with the reason no figure can be given. */
+    fuel: {
+        usedT: number | null;
+        carriedT: number | null;
+        note: string;
+    };
+    /** What the craft carries to the end of this trip: kilograms (at least, where only a harder trip is rated), or null with the reason. */
+    payload: {
+        kg: number | null;
+        atLeast: boolean;
+        note: string;
+    };
+    ballistic?: {
+        mu: number;
+        r1: number;
+        r2: number;
+        theta0: number;
+        transitS: number;
+        parkKm: number;
+        parkSpeed: number;
+        burnEndSpeed: number;
+        captureKm: number;
+        captureSpeedIn: number;
+        captureSpeedOut: number;
+        burnS: number;
+        brakeS: number;
+        flipS: number;
+        ascentS: number;
+        vInfDeparture: number;
+        vInfArrival: number;
+        /** Cumulative path length at equal steps of the transit, km. */
+        arc: number[];
+        /** Where the departure and the destination body are in the frame, km, and the destination at arrival. */
+        c3: number;
+    };
+    continuous?: {
+        from: Vec3;
+        to: Vec3;
+        a: number;
+        burnS: number;
+        flipS: number;
+        peakRapidity: number;
+        blockedBySun: boolean;
+    };
+}
+/** A place's position in a frame, km: round the Sun for a planet, round the Earth for the Moon (and the Earth's own is the origin of the Earth's frame). */
+export declare function positionKm(source: BodySource, id: string, ms: number, frame: "sun" | "earth"): Vec3;
+/**
+ * A day a ballistic craft can leave on, with the flight time and the two speed changes of the Sun's frame.
+ *
+ * @example
+ * ```ts
+ * import type { Window } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const next: Window = { dateMs: Date.UTC(2026, 10, 4), days: 265, dv1: 3.2, dv2: 2.9 };
+ * console.log(new Date(next.dateMs).toISOString());
+ * ```
+ */
+export interface Window {
+    dateMs: number;
+    /** The flight time, days. */
+    days: number;
+    /** The heliocentric speed changes, km/s. */
+    dv1: number;
+    dv2: number;
+}
+/**
+ * The next dates a craft can leave one planet for another on a Hohmann transfer: the days on which the destination will be where the craft arrives. Found by scanning day by day and bisecting each crossing, from the planets' real positions.
+ * @param source Where the planets are.
+ * @param from The starting planet's id.
+ * @param to The destination planet's id.
+ * @param afterMs The earliest date, milliseconds since 1970.
+ * @param count How many windows.
+ * @returns The windows, soonest first.
+ * @example
+ * ```ts no-run
+ * import { windows, type BodySource } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const source: BodySource;
+ * console.log(windows(source, "earth", "mars", Date.UTC(2026, 10, 4), 2).map((one) => new Date(one.dateMs).toISOString().slice(0, 10)));
+ * ```
+ */
+export declare function windows(source: BodySource, from: string, to: string, afterMs: number, count: number): Window[];
+/** The energy (km^2/s^2, the speed squared at infinity) each kind of payload figure is for. Lower is easier. */
+export declare function c3Of(source: BodySource, kind: CapacityKind): number;
+/**
+ * Plans a trip: the transfer or the flip and burn, the burns, the times, and what the craft can and cannot do. A craft that cannot make the trip comes back with a verdict that says why in one line and no phases.
+ * @param source Where the places are.
+ * @param craft The craft.
+ * @param from The starting place's id.
+ * @param to The destination's id.
+ * @param departMs When the departure burn begins, milliseconds since 1970 (for a ballistic trip to a planet, one of `windows`).
+ * @returns The planned trip.
+ * @example
+ * ```ts no-run
+ * import { craftOf, planTrip, type BodySource } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const source: BodySource;
+ * const trip = planTrip(source, craftOf("saturn-v")!, "earth", "moon", Date.UTC(2026, 10, 5));
+ * console.log(trip.verdict.line, Math.round(trip.dv.departure));
+ * ```
+ */
+export declare function planTrip(source: BodySource, craft: Craft, from: string, to: string, departMs: number): Trip;
+/**
+ * The departure date, for a craft that burns all the way, with the shortest trip in the next two years.
+ * @param source Where the places are.
+ * @param craft The craft.
+ * @param from The starting place's id.
+ * @param to The destination's id.
+ * @param afterMs The earliest date.
+ * @returns The date, milliseconds since 1970.
+ * @example
+ * ```ts no-run
+ * import { bestDate, craftOf, type BodySource } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const source: BodySource;
+ * console.log(new Date(bestDate(source, craftOf("kaminari")!, "earth", "mars", Date.UTC(2026, 10, 4))).toISOString());
+ * ```
+ */
+export declare function bestDate(source: BodySource, craft: Craft, from: string, to: string, afterMs: number): number;