@johnmorrisdotca/uchusen-rockets 0.2.2 → 0.4.0

package/dist/embed.d.ts

@@ -0,0 +1,131 @@
+import { type RocketOptions } from "./attrs.ts";
+/**
+ * The six ways `embedCode` writes a rocket for another page: `element`, `iframe`, `module`, `svg`, `data` and `link`.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
+export declare const EMBED_KINDS: readonly ["element", "iframe", "module", "svg", "data", "link"];
+/**
+ * One of the ways in `EMBED_KINDS`.
+ *
+ * @example
+ * ```ts
+ * import type { EmbedKind } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const kind: EmbedKind = "iframe";
+ * console.log(kind);
+ * ```
+ */
+export type EmbedKind = (typeof EMBED_KINDS)[number];
+/**
+ * Where the embed code points: the address of the demo that holds `embed.html`, and the CDN folder the element loads from. Both default to this package's own.
+ *
+ * @example
+ * ```ts
+ * import { embedCode, type EmbedSettings } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const settings: EmbedSettings = { site: "https://example.test/rockets/" };
+ * console.log(embedCode({ rocket: "starship" }, "iframe", settings));
+ * ```
+ */
+export interface EmbedSettings {
+    /** The address of the published demo, where `embed.html` is. */
+    site?: string;
+    /** The CDN or package path the element is loaded from. */
+    cdn?: string;
+}
+/**
+ * The address of the published demo, where `embed.html` is.
+ *
+ * @example
+ * ```ts
+ * import { SITE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SITE);
+ * ```
+ */
+export declare const SITE = "https://johnmorrisdotca.github.io/uchusen-rockets/";
+/**
+ * The folder on a CDN the element loads from when the embed is a plain script with no bundler.
+ *
+ * @example
+ * ```ts
+ * import { CDN } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(CDN);
+ * ```
+ */
+export declare const CDN = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/uchusen-rockets@0";
+/**
+ * The three.js a page with no bundler takes from the CDN: the version this package is built and tested with.
+ *
+ * @example
+ * ```ts
+ * import { THREE_VERSION } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(THREE_VERSION);
+ * ```
+ */
+export declare const THREE_VERSION = "0.186.1";
+/**
+ * What an embed asks of the page around it, in words: a line for the demo to show.
+ *
+ * @param kind Which way of embedding.
+ * @param options The rocket being embedded.
+ * @returns A line of text for the demo to show beside the code.
+ * @example
+ * ```ts
+ * import { embedNote } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedNote("iframe", { rocket: "starship" }));
+ * ```
+ */
+export declare function embedNote(kind: EmbedKind, options: RocketOptions): string;
+/**
+ * The CC BY line for a painted rocket, generated from the parts that are showing. Empty when the look is not painted, or when those parts are this package's own paint.
+ *
+ * @param options The rocket as it will be drawn.
+ * @returns The credit line, or an empty text when nothing needs crediting.
+ * @example
+ * ```ts
+ * import { paintedCredit } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "painted" }));
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "line" }) === "");
+ * ```
+ */
+export declare function paintedCredit(options: RocketOptions): string;
+/**
+ * The shipped picture of these options, under the package's `dist/assets/`: `starship-v3.svg`, `falcon-9-block-5-apart.thick.svg`. These are drawn from the default view, with no flames. Null for a custom build, which has no file, or a variant, part or look that does not exist.
+ *
+ * @param options The rocket, variant, look, view and what to show.
+ * @returns The path of the shipped picture under `dist/assets/`, or null when none is shipped for those options.
+ * @example
+ * ```ts
+ * import { assetPathOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(assetPathOf({ rocket: "starship", variant: "v3" }));
+ * ```
+ */
+export declare function assetPathOf(options: RocketOptions): string | null;
+/**
+ * The text of one embed. The `module` one imports the package; the `data` one is a `data:image/svg+xml` address for an `<img>`.
+ *
+ * @param options The rocket and how it looks.
+ * @param kind Which way to write it. Defaults to the element.
+ * @param settings Where the demo and the CDN are, if not the package's own.
+ * @returns The text to paste into a page. A painted rocket's credit is part of it.
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5", look: "thick" }));
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5" }, "iframe"));
+ * ```
+ */
+export declare function embedCode(options: RocketOptions, kind?: EmbedKind, settings?: EmbedSettings): string;

package/dist/embed.js

@@ -0,0 +1,218 @@
+// `embedCode`: the text to put a rocket in a page, in each of the six ways: the custom element from a CDN, an iframe of `embed.html`, a JavaScript module, the SVG itself, a data address, and a link to the shipped picture.
+// A painted rocket's credit is generated from the parts that show, and every painted form carries it.
+import { build } from "./build/index.js";
+import { creditLine } from "./data/credits.js";
+import { check } from "./fit.js";
+import { cleanView } from "./framing.js";
+import { cleanShow, showsOf } from "./layout.js";
+import { cleanLook, DEFAULT_LOOK } from "./looks.js";
+import { attributesFromOptions, rocketToParams } from "./attrs.js";
+/**
+ * The six ways `embedCode` writes a rocket for another page: `element`, `iframe`, `module`, `svg`, `data` and `link`.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
+export const EMBED_KINDS = ["element", "iframe", "module", "svg", "data", "link"];
+/**
+ * The address of the published demo, where `embed.html` is.
+ *
+ * @example
+ * ```ts
+ * import { SITE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SITE);
+ * ```
+ */
+export const SITE = "https://johnmorrisdotca.github.io/uchusen-rockets/";
+/**
+ * The folder on a CDN the element loads from when the embed is a plain script with no bundler.
+ *
+ * @example
+ * ```ts
+ * import { CDN } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(CDN);
+ * ```
+ */
+export const CDN = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/uchusen-rockets@0";
+/**
+ * The three.js a page with no bundler takes from the CDN: the version this package is built and tested with.
+ *
+ * @example
+ * ```ts
+ * import { THREE_VERSION } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(THREE_VERSION);
+ * ```
+ */
+export const THREE_VERSION = "0.186.1";
+const THREE_CDN = `https://cdn.jsdelivr.net/npm/three@${THREE_VERSION}`;
+const IMPORT_MAP = `<script type="importmap">\n  { "imports": { "three": "${THREE_CDN}/build/three.module.js", "three/addons/": "${THREE_CDN}/examples/jsm/" } }\n</script>`;
+const esc = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const EMPTY_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 640" width="480" height="640" role="img"></svg>`;
+function descriptionOf(options) {
+    if (options.build) {
+        try {
+            const parsed = JSON.parse(options.build);
+            if (parsed && typeof parsed === "object" && typeof parsed.rocket === "string") {
+                return {
+                    rocket: parsed.rocket,
+                    ...(typeof parsed.variant === "string" ? { variant: parsed.variant } : {}),
+                    ...(parsed.parts && typeof parsed.parts === "object" ? { parts: parsed.parts } : {}),
+                };
+            }
+        }
+        catch {
+            // a build that is not JSON falls through to the named rocket
+        }
+    }
+    return { rocket: options.rocket ?? "starship", ...(options.variant ? { variant: options.variant } : {}) };
+}
+/**
+ * What an embed asks of the page around it, in words: a line for the demo to show.
+ *
+ * @param kind Which way of embedding.
+ * @param options The rocket being embedded.
+ * @returns A line of text for the demo to show beside the code.
+ * @example
+ * ```ts
+ * import { embedNote } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedNote("iframe", { rocket: "starship" }));
+ * ```
+ */
+export function embedNote(kind, options) {
+    const notes = {
+        element: "One script from the CDN and the tag. The import map names three.js, for the 3D view; a page with a bundler needs neither, only the package.",
+        iframe: "No script of your own. It draws the drawing at once, and the 3D view when the browser can. Add flight=1 to the address for the flight's controls.",
+        module: "The drawing from a script of your own, with no three.js.",
+        svg: "The drawing itself: nothing to load. Paste it in a page or save it as a file.",
+        data: "The drawing as an address, for an image tag or a stylesheet.",
+        link: options.view && options.view !== "three-quarter" ? "A link to the file in the package. Those show the three-quarter view, with no flames: use the SVG or data tab for this view." : "A link to the file in the package. Those show the three-quarter view, with no flames.",
+    };
+    return notes[kind];
+}
+/**
+ * The CC BY line for a painted rocket, generated from the parts that are showing. Empty when the look is not painted, or when those parts are this package's own paint.
+ *
+ * @param options The rocket as it will be drawn.
+ * @returns The credit line, or an empty text when nothing needs crediting.
+ * @example
+ * ```ts
+ * import { paintedCredit } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "painted" }));
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "line" }) === "");
+ * ```
+ */
+export function paintedCredit(options) {
+    if (cleanLook(options.look) !== "painted")
+        return "";
+    const report = check(descriptionOf(options));
+    if (!report.ok)
+        return "";
+    const show = options.show;
+    const names = new Set(report.parts.filter(({ slot }) => !show || show === "together" || show === "apart" || show === slot).map(({ part }) => part.name));
+    return report.credits
+        .map((credit) => {
+        const used = credit.usedFor.filter((name) => names.has(name));
+        return used.length === 0 ? "" : `${used.join(", ")}: ${creditLine(credit.id)}`;
+    })
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/**
+ * The shipped picture of these options, under the package's `dist/assets/`: `starship-v3.svg`, `falcon-9-block-5-apart.thick.svg`. These are drawn from the default view, with no flames. Null for a custom build, which has no file, or a variant, part or look that does not exist.
+ *
+ * @param options The rocket, variant, look, view and what to show.
+ * @returns The path of the shipped picture under `dist/assets/`, or null when none is shipped for those options.
+ * @example
+ * ```ts
+ * import { assetPathOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(assetPathOf({ rocket: "starship", variant: "v3" }));
+ * ```
+ */
+export function assetPathOf(options) {
+    if (options.build)
+        return null;
+    const description = descriptionOf(options);
+    const report = check(description);
+    if (!report.ok || !report.variant || report.custom)
+        return null;
+    const slots = report.parts.map(({ slot }) => slot);
+    const shows = showsOf(slots);
+    const show = cleanShow(options.show, slots);
+    if (!shows.includes(show))
+        return null;
+    const look = cleanLook(options.look);
+    return `${report.variant.rocket}-${report.variant.id}${show === shows[0] ? "" : `-${show}`}${look === DEFAULT_LOOK ? "" : `.${look}`}.svg`;
+}
+function svgOptionsOf(options) {
+    return {
+        look: cleanLook(options.look),
+        view: cleanView(options.view),
+        ...(options.show ? { show: options.show } : {}),
+        ...(options.engines === "on" ? { engines: true } : {}),
+    };
+}
+function drawingOf(options) {
+    try {
+        const drawn = build(descriptionOf(options)).svg(svgOptionsOf(options));
+        const credit = paintedCredit(options);
+        return credit === "" ? drawn : drawn.replace("</svg>", `<desc>${esc(credit)}</desc></svg>`);
+    }
+    catch {
+        return EMPTY_SVG;
+    }
+}
+const creditHtml = (credit) => (credit === "" ? "" : `\n<p>${esc(credit).replaceAll("\n", "<br>\n")}</p>`);
+/**
+ * The text of one embed. The `module` one imports the package; the `data` one is a `data:image/svg+xml` address for an `<img>`.
+ *
+ * @param options The rocket and how it looks.
+ * @param kind Which way to write it. Defaults to the element.
+ * @param settings Where the demo and the CDN are, if not the package's own.
+ * @returns The text to paste into a page. A painted rocket's credit is part of it.
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5", look: "thick" }));
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5" }, "iframe"));
+ * ```
+ */
+export function embedCode(options, kind = "element", settings = {}) {
+    const site = settings.site ?? SITE;
+    const cdn = settings.cdn ?? CDN;
+    const credit = paintedCredit(options);
+    if (kind === "svg")
+        return drawingOf(options);
+    if (kind === "data")
+        return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(drawingOf(options))}`;
+    if (kind === "link") {
+        const path = assetPathOf(options);
+        const alt = esc(options.label ?? "Rocket");
+        const src = path === null ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(drawingOf(options))}` : `${cdn}/dist/assets/${path}`;
+        return `<img src="${esc(src)}" alt="${alt}" width="480" height="640" loading="lazy">${creditHtml(credit)}`;
+    }
+    if (kind === "iframe") {
+        const query = rocketToParams(options).toString();
+        const src = `${site}embed.html${query === "" ? "" : `?${query}`}`;
+        const title = options.label ?? "Rocket";
+        return `<iframe\n  src="${esc(src)}"\n  title="${esc(title)}"\n  loading="lazy"\n  style="width:100%;max-width:480px;aspect-ratio:3 / 4;border:0"\n></iframe>${creditHtml(credit)}`;
+    }
+    if (kind === "module") {
+        const description = descriptionOf(options);
+        const svgOptions = svgOptionsOf(options);
+        const caption = credit === "" ? "" : `\ndocument.querySelector("#credit").textContent = ${JSON.stringify(credit)};`;
+        return `// In a page with <div id="rocket"></div>${credit === "" ? "" : ' and <p id="credit"></p>'}.\nimport { build } from "${cdn}/dist/build/index.js";\n// or, from npm: import { build } from "@johnmorrisdotca/uchusen-rockets/build";\n\nconst rocket = build(${JSON.stringify(description, null, 2)});\ndocument.querySelector("#rocket").innerHTML = rocket.svg(${JSON.stringify(svgOptions)});${caption}`;
+    }
+    const attrs = Object.entries(attributesFromOptions(options)).map(([name, value]) => `${name}="${esc(value)}"`);
+    return `${IMPORT_MAP}\n<script type="module" src="${cdn}/dist/element.js"></script>\n\n<uchusen-rocket${attrs.length === 0 ? "" : `\n  ${attrs.join("\n  ")}`}\n></uchusen-rocket>${creditHtml(credit)}`;
+}

package/dist/engines.d.ts

@@ -0,0 +1,126 @@
+import type { Piece } from "./model/pieces.ts";
+/** How many exit-radii a drawn flame reaches, and the most any reaches in metres. A picture, not a measured length. */
+export declare const PLUME_EXITS = 34;
+export declare const PLUME_MOST_M = 26;
+/** How many shock diamonds a flame shows near the ground. A picture. */
+export declare const PLUME_DIAMONDS = 6;
+/**
+ * With no one touching anything, a flame stops moving after this long and nothing draws: a lit rocket at rest costs the same as a dark one.
+ *
+ * @example
+ * ```ts
+ * import { FLAME_SETTLE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(FLAME_SETTLE_MS / 1000, "seconds");
+ * ```
+ */
+export declare const FLAME_SETTLE_MS = 15000;
+/** A flame that only flickers is drawn at most this often. A turn or a move still draws once a frame. */
+export declare const FLAME_GAP_MS = 33;
+/**
+ * How long a flame is drawn, in metres, for an engine whose bell is `exit` metres across at the mouth. The length is a picture, not a measured flame.
+ *
+ * @param exit The exit radius of the bell, in metres.
+ * @returns The flame's length in metres.
+ * @example
+ * ```ts
+ * import { plumeLength } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(plumeLength(0.45).toFixed(2));
+ * ```
+ */
+export declare function plumeLength(exit: number): number;
+/**
+ * `on` asks for them, and a reader who asked for reduced motion has them off whatever the page says. Anything else, or nothing, is off.
+ *
+ * @param attribute The value of the `engines` attribute, or null when it is missing.
+ * @param reduced True when the reader asked for reduced motion.
+ * @returns True when the flames should be drawn.
+ * @example
+ * ```ts
+ * import { enginesWanted } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(enginesWanted("on", false), enginesWanted("on", true), enginesWanted(null, false));
+ * ```
+ */
+export declare function enginesWanted(attribute: string | null, reduced: boolean): boolean;
+/**
+ * One engine bell as the drawing has it: where it stands across the part, the height of its mouth and its exit radius, all in metres in the part's own frame.
+ *
+ * @example
+ * ```ts
+ * import { bellsOf, type Bell } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const bells: Bell[] = bellsOf([]);
+ * console.log(bells.length);
+ * ```
+ */
+export interface Bell {
+    x: number;
+    z: number;
+    /** Height of the mouth, in the part's own metres. */
+    y: number;
+    /** Exit radius, metres. */
+    exit: number;
+}
+/**
+ * One bell for every engine the pieces already draw. The mouth is the first point of the bell.
+ *
+ * @param pieces The pieces of a part, as the builder makes them.
+ * @returns The bells, one for each engine the pieces already draw.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? bellsOf(booster.pieces).length : 0);
+ * ```
+ */
+export declare function bellsOf(pieces: readonly Piece[]): Bell[];
+export interface LitBell extends Bell {
+    slot: string;
+}
+/**
+ * The engines that are alight at full thrust. Stacked, only the parts on the ground or beside the stack, as an orbiter is: a ship's engines are buried in the booster.
+ * Apart, or one part on its own, every bell that part draws. A part whose engines no source tells of (`dark`, a stage that has landed) draws no flame.
+ */
+export declare function litBells(parts: readonly {
+    slot: string;
+    atY: number;
+    shown: boolean;
+    pieces: readonly Piece[];
+    beside?: boolean;
+    dark?: boolean;
+}[], together: boolean): LitBell[];
+/**
+ * The bells grouped by how far they are from the part's axis, innermost ring first, and each ring in order round the axis.
+ *
+ * @param bells The bells of one part.
+ * @returns The rings, innermost first, each a list of bells.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, ringsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? ringsOf(bellsOf(booster.pieces)).map((ring) => ring.length) : []);
+ * ```
+ */
+export declare function ringsOf(bells: readonly Bell[]): Bell[][];
+/**
+ * Which `count` engines burn: from the middle out, and a ring that is only partly used has them evenly round it, so three of a Falcon 9's nine are the middle one and two opposite. A source says how many; where they stand is this rule.
+ *
+ * @param bells All the bells of a part.
+ * @param count How many burn.
+ * @returns The bells that burn.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, pickBells } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? pickBells(bellsOf(booster.pieces), 3).length : 0);
+ * ```
+ */
+export declare function pickBells(bells: readonly Bell[], count: number): Bell[];

package/dist/engines.js

@@ -0,0 +1,150 @@
+/** How many exit-radii a drawn flame reaches, and the most any reaches in metres. A picture, not a measured length. */
+export const PLUME_EXITS = 34;
+export const PLUME_MOST_M = 26;
+/** How many shock diamonds a flame shows near the ground. A picture. */
+export const PLUME_DIAMONDS = 6;
+/**
+ * With no one touching anything, a flame stops moving after this long and nothing draws: a lit rocket at rest costs the same as a dark one.
+ *
+ * @example
+ * ```ts
+ * import { FLAME_SETTLE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(FLAME_SETTLE_MS / 1000, "seconds");
+ * ```
+ */
+export const FLAME_SETTLE_MS = 15_000;
+/** A flame that only flickers is drawn at most this often. A turn or a move still draws once a frame. */
+export const FLAME_GAP_MS = 33;
+/**
+ * How long a flame is drawn, in metres, for an engine whose bell is `exit` metres across at the mouth. The length is a picture, not a measured flame.
+ *
+ * @param exit The exit radius of the bell, in metres.
+ * @returns The flame's length in metres.
+ * @example
+ * ```ts
+ * import { plumeLength } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(plumeLength(0.45).toFixed(2));
+ * ```
+ */
+export function plumeLength(exit) {
+    return Math.min(exit * PLUME_EXITS, PLUME_MOST_M);
+}
+/**
+ * `on` asks for them, and a reader who asked for reduced motion has them off whatever the page says. Anything else, or nothing, is off.
+ *
+ * @param attribute The value of the `engines` attribute, or null when it is missing.
+ * @param reduced True when the reader asked for reduced motion.
+ * @returns True when the flames should be drawn.
+ * @example
+ * ```ts
+ * import { enginesWanted } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(enginesWanted("on", false), enginesWanted("on", true), enginesWanted(null, false));
+ * ```
+ */
+export function enginesWanted(attribute, reduced) {
+    return attribute === "on" && !reduced;
+}
+/**
+ * One bell for every engine the pieces already draw. The mouth is the first point of the bell.
+ *
+ * @param pieces The pieces of a part, as the builder makes them.
+ * @returns The bells, one for each engine the pieces already draw.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? bellsOf(booster.pieces).length : 0);
+ * ```
+ */
+export function bellsOf(pieces) {
+    const bells = [];
+    for (const piece of pieces) {
+        if (piece.kind !== "lathe" || piece.material !== "bell" || piece.profile.length === 0)
+            continue;
+        const [exit, y] = piece.profile[0];
+        const at = piece.at ?? [0, 0];
+        bells.push({ x: at[0], z: at[1], y, exit });
+    }
+    return bells;
+}
+/**
+ * The engines that are alight at full thrust. Stacked, only the parts on the ground or beside the stack, as an orbiter is: a ship's engines are buried in the booster.
+ * Apart, or one part on its own, every bell that part draws. A part whose engines no source tells of (`dark`, a stage that has landed) draws no flame.
+ */
+export function litBells(parts, together) {
+    const shown = parts.filter((part) => part.shown);
+    if (shown.length === 0)
+        return [];
+    const floor = Math.min(...shown.map((part) => part.atY));
+    const bells = [];
+    for (const part of shown) {
+        if (part.dark || (together && part.atY > floor + 0.5 && !part.beside))
+            continue;
+        for (const bell of bellsOf(part.pieces))
+            bells.push({ ...bell, slot: part.slot });
+    }
+    return bells;
+}
+/**
+ * The bells grouped by how far they are from the part's axis, innermost ring first, and each ring in order round the axis.
+ *
+ * @param bells The bells of one part.
+ * @returns The rings, innermost first, each a list of bells.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, ringsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? ringsOf(bellsOf(booster.pieces)).map((ring) => ring.length) : []);
+ * ```
+ */
+export function ringsOf(bells) {
+    const sorted = [...bells].sort((a, b) => Math.hypot(a.x, a.z) - Math.hypot(b.x, b.z));
+    const rings = [];
+    for (const bell of sorted) {
+        const last = rings[rings.length - 1];
+        if (last && Math.abs(Math.hypot(last[0].x, last[0].z) - Math.hypot(bell.x, bell.z)) < 0.05)
+            last.push(bell);
+        else
+            rings.push([bell]);
+    }
+    for (const ring of rings)
+        ring.sort((a, b) => Math.atan2(a.x, a.z) - Math.atan2(b.x, b.z));
+    return rings;
+}
+/**
+ * Which `count` engines burn: from the middle out, and a ring that is only partly used has them evenly round it, so three of a Falcon 9's nine are the middle one and two opposite. A source says how many; where they stand is this rule.
+ *
+ * @param bells All the bells of a part.
+ * @param count How many burn.
+ * @returns The bells that burn.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, pickBells } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? pickBells(bellsOf(booster.pieces), 3).length : 0);
+ * ```
+ */
+export function pickBells(bells, count) {
+    const wanted = Math.max(0, Math.min(bells.length, Math.floor(count)));
+    const out = [];
+    for (const ring of ringsOf(bells)) {
+        const left = wanted - out.length;
+        if (left <= 0)
+            break;
+        if (ring.length <= left)
+            out.push(...ring);
+        else
+            for (let i = 0; i < left; i++)
+                out.push(ring[Math.floor((i * ring.length) / left)]);
+    }
+    return out;
+}