@johnmorrisdotca/kyogijo-stadiums 0.54.0 → 0.56.0

package/dist/circuits.pace.js

@@ -0,0 +1,131 @@
+import { FEET_PER_METRE as FT } from "./geometry.js";
+/** The figures of the model, in metres and seconds. */
+export const RACE_PACE = Object.freeze({
+    /** The fastest the car goes on a straight: 94 m/s, about 338 km/h. */
+    top: 94,
+    /** Grip across the car: `grip + downforce × v²` metres a second squared at a speed `v`, about 2.4 g in a hairpin and 5 g in a fast bend. */
+    grip: 22,
+    downforce: 0.0036,
+    /** How hard it brakes, and how hard it pulls away at rest; the pull falls to nothing at `top`. */
+    brake: 34,
+    launch: 17,
+    /** The line is read every `step` metres, and a bend is measured over `reach` either side: a racing car does not follow the middle of the road, so a short kink of it is not a bend. */
+    step: 5,
+    reach: 32,
+    /** The speed limit of the pit lane: 80 km/h. */
+    pitLimit: 80 / 3.6,
+});
+/** The cumulative length of a ring at each of its points (the first 0, one more than the points: the last is the whole length). */
+export function ringLengths(points) {
+    const out = new Float64Array(points.length + 1);
+    for (let i = 0; i < points.length; i += 1) {
+        const a = points[i];
+        const b = points[(i + 1) % points.length];
+        out[i + 1] = out[i] + Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    return out;
+}
+/** The point of a ring `along` units round it from its first point (wrapped), from its lengths (`ringLengths`): found by halving, so a page can ask for twenty a frame. */
+export function ringPoint(points, lengths, along) {
+    const total = lengths[lengths.length - 1];
+    if (!(total > 0))
+        return points[0];
+    const d = ((along % total) + total) % total;
+    let lo = 0;
+    let hi = points.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lengths[mid] <= d)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const a = points[lo];
+    const b = points[(lo + 1) % points.length];
+    const long = lengths[lo + 1] - lengths[lo];
+    const t = long > 0 ? (d - lengths[lo]) / long : 0;
+    return [a[0] + t * (b[0] - a[0]), a[1] + t * (b[1] - a[1])];
+}
+/** The same for an open line: held to its ends. */
+export function linePoint(points, lengths, along) {
+    const total = lengths[points.length - 1];
+    const d = Math.min(Math.max(along, 0), total);
+    let lo = 0;
+    let hi = points.length - 2;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lengths[mid] <= d)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const a = points[lo];
+    const b = points[Math.min(lo + 1, points.length - 1)];
+    const long = lengths[lo + 1] - lengths[lo];
+    const t = long > 0 ? (d - lengths[lo]) / long : 0;
+    return [a[0] + t * (b[0] - a[0]), a[1] + t * (b[1] - a[1])];
+}
+/** The radius of the circle through three points, or Infinity when they lie in a line. */
+function radius(a, b, c) {
+    const ab = Math.hypot(b[0] - a[0], b[1] - a[1]);
+    const bc = Math.hypot(c[0] - b[0], c[1] - b[1]);
+    const ca = Math.hypot(a[0] - c[0], a[1] - c[1]);
+    const cross = Math.abs((b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]));
+    return cross < 1e-9 ? Infinity : (ab * bc * ca) / (2 * cross);
+}
+/** The fastest speed a bend of radius `r` metres allows: `v² = r × (grip + downforce × v²)`, and the top speed where the downforce holds it at any speed. */
+export function cornerSpeed(r, pace = RACE_PACE) {
+    const room = 1 - pace.downforce * r;
+    if (!(r < Infinity) || room <= 0)
+        return pace.top;
+    return Math.min(pace.top, Math.sqrt((pace.grip * r) / room));
+}
+/** How hard the car can pull away at a speed: `launch` at rest, nothing at the top speed. */
+export const pullAt = (v, pace = RACE_PACE) => Math.max(0.4, pace.launch * (1 - (v / pace.top) ** 2));
+/**
+ * A plan's speeds round its lap (`circuitPlan`), from its line alone: the bends' radii give each sample's fastest speed, and two passes round (twice, so that the lap closes on itself) hold it to the engine and the
+ * brakes. The same plan always gives the same profile.
+ * @example
+ * ```ts
+ * import { circuitById, circuitPlan, paceProfile } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const pace = paceProfile(circuitPlan(circuitById("las-vegas")!));
+ * console.log(pace.lap > 90 && pace.lap < 105, Math.max(...pace.speed) * 3.6 > 300);
+ * // true true
+ * ```
+ */
+export function paceProfile(plan, pace = RACE_PACE) {
+    const metres = plan.lap.map(([x, y]) => [x / FT, y / FT]);
+    const lengths = ringLengths(metres);
+    const length = lengths[lengths.length - 1];
+    const n = Math.max(8, Math.round(length / pace.step));
+    const step = length / n;
+    const limit = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const s = i * step;
+        limit[i] = cornerSpeed(radius(ringPoint(metres, lengths, s - pace.reach), ringPoint(metres, lengths, s), ringPoint(metres, lengths, s + pace.reach)), pace);
+    }
+    const speed = Float64Array.from(limit);
+    for (let round = 0; round < 2; round += 1) {
+        for (let k = 1; k <= n; k += 1) {
+            const i = k % n;
+            const before = speed[(k - 1) % n];
+            speed[i] = Math.min(speed[i], Math.sqrt(before * before + 2 * pullAt(before, pace) * step));
+        }
+        for (let k = n - 1; k >= 0; k -= 1) {
+            const after = speed[(k + 1) % n];
+            speed[k] = Math.min(speed[k], Math.sqrt(after * after + 2 * pace.brake * step));
+        }
+    }
+    const time = new Float64Array(n + 1);
+    for (let i = 0; i < n; i += 1)
+        time[i + 1] = time[i] + (2 * step) / (speed[i] + speed[(i + 1) % n]);
+    return { step, length, speed, time, lap: time[n] };
+}
+/** The speed at `along` metres round the lap from the line's first point (wrapped), between the two samples either side. */
+export function speedAt(profile, along) {
+    const n = profile.speed.length;
+    const d = ((along % profile.length) + profile.length) % profile.length;
+    const i = Math.floor(d / profile.step) % n;
+    const t = d / profile.step - Math.floor(d / profile.step);
+    return profile.speed[i] + t * (profile.speed[(i + 1) % n] - profile.speed[i]);
+}

package/dist/circuits.race.d.ts

@@ -0,0 +1,80 @@
+import { type CircuitPlan } from "./circuits.ts";
+import { type PaceProfile } from "./circuits.pace.ts";
+import { type RaceDriver, type RaceTeam } from "./circuits.race.field.ts";
+import type { Circuit } from "./circuits.types.ts";
+/** What a race is made from: the circuit, and a seed, laps and cars of your own. */
+export interface RaceOptions {
+    /** The circuit's key: `las-vegas`. */
+    circuit: string;
+    /** The seed every choice of the race is drawn from: a whole number, 1 by default. Another seed is another race. */
+    seed?: number;
+    /** How many laps: by default a full race distance, the fewest laps that make 305 km (`raceLaps`). 1 to 200. */
+    laps?: number;
+    /** How many cars: 2 to 20, 20 by default. */
+    cars?: number;
+}
+/** A car of the race: its driver and team (made up) and where it started. */
+export interface RaceCar {
+    /** The driver's code in lower case: `hlv`. */
+    id: string;
+    driver: RaceDriver;
+    team: RaceTeam;
+    /** Its place on the grid, 1 for pole. */
+    grid: number;
+}
+/** A pit stop: the lap it ends, the time the car left the track and joined it again, and how long it stood still. */
+export interface RaceStop {
+    lap: number;
+    in: number;
+    out: number;
+    stop: number;
+}
+/** A race worked out: the cars, and each one's distance at every second, its laps, stops and finish. */
+export interface CircuitRace {
+    circuit: Circuit;
+    plan: CircuitPlan;
+    seed: number;
+    laps: number;
+    cars: readonly RaceCar[];
+    /** The lap's length along the drawn line, in metres, and how far round it from the line's first point the timing line (the finish) is. */
+    lapLength: number;
+    lineAlong: number;
+    /** The pit lane: where it leaves the lap and joins it again (metres round the lap from the line's first point), and its length in metres. */
+    pitLane: {
+        entry: number;
+        exit: number;
+        length: number;
+    };
+    /** The lap's speeds the cars run. */
+    pace: PaceProfile;
+    /** Seconds between two samples, the time the chequered flag fell and the time the race ends (every car home and slowed). */
+    sample: number;
+    flag: number;
+    duration: number;
+    /** Each car's race distance at every sample, in metres: 0 at the timing line, a lap is done at each `lapLength`. A car on the grid behind the line starts below 0. */
+    distance: readonly Float64Array[];
+    /** Each car's distance along the pit lane at every sample, in metres, or NaN while it is on the track. */
+    pit: readonly Float32Array[];
+    /** The time each car completed each lap, from the start. */
+    crossings: readonly (readonly number[])[];
+    stops: readonly (readonly RaceStop[])[];
+    /** The time a car took the chequered flag, or retired: `undefined` for neither. */
+    finish: readonly (number | undefined)[];
+    out: readonly (number | undefined)[];
+}
+/** The distance of a race: the fewest laps that make more than 305 km, as a Grand Prix's is set. */
+export declare const RACE_DISTANCE = 305000;
+/** The laps of a full race distance on a circuit: 50 at Las Vegas. */
+export declare const raceLaps: (circuit: Pick<Circuit, "length">) => number;
+/**
+ * A race on a circuit, worked out from a seed: made-up cars from the grid to the flag over a full race distance (50 laps of Las Vegas, about an hour and a half), with the gaps, overtakes, pit stops and retirements
+ * the model gives. The same options always give the same race; the last few asked for are kept.
+ * @example
+ * ```ts
+ * import { simulateRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = simulateRace({ circuit: "las-vegas", laps: 5, cars: 6, seed: 7 });
+ * console.log(race.laps, race.cars.length, race.flag > 5 * 90 && race.flag < 5 * 110);
+ * // 5 6 true
+ * ```
+ */
+export declare function simulateRace(options: RaceOptions): CircuitRace;

package/dist/circuits.race.dom.d.ts

@@ -0,0 +1,73 @@
+import { type RaceMoment } from "./circuits.race.moment.ts";
+import { type CircuitRace, type RaceOptions } from "./circuits.race.ts";
+import type { CircuitOptions } from "./circuits.types.ts";
+import { type KyogijoTurn } from "./turn.dom.ts";
+import type { TurnSettings } from "./turn.model.ts";
+/** The speeds the controls offer: real time, ten times and sixty times (a minute of the race a second). */
+export declare const RACE_SPEEDS: readonly number[];
+/** What a race's view is drawn from: the circuit's options and the race's. */
+export type RaceViewOptions = CircuitOptions & Omit<RaceOptions, "circuit">;
+/** How a race is shown and played. */
+export interface RaceViewSettings {
+    /** `flat` (the default) or `3d`: the circuit's 3D view, with the cars standing on it as discs that face the eye. */
+    view?: "flat" | "3d";
+    /** The 3D view's own settings (its viewpoint, its controls). */
+    turn?: TurnSettings;
+    /** 1 (the default), 10 or 60; any speed from 1 to 600 is allowed. */
+    speed?: number;
+    /** Seconds from the start to begin at: 0 (the grid) by default. */
+    start?: number;
+    /** Play at once. Ignored for a reader who prefers reduced motion, and while the page is hidden. */
+    autoplay?: boolean;
+    /** `auto` (the default) follows `prefers-reduced-motion`; `smooth` and `step` force one. */
+    motion?: "auto" | "smooth" | "step";
+    /** The timing board under the controls: on by default. */
+    board?: boolean;
+    /** A race already worked out to play instead of a simulation: one from a feed (`raceFromFeed`). */
+    race?: CircuitRace;
+    /** Told when the reader plays, pauses, seeks or changes speed, and when the race ends: not at every frame. */
+    onChange?: (state: RaceState) => void;
+}
+/** What a race's view is doing. */
+export interface RaceState {
+    t: number;
+    duration: number;
+    playing: boolean;
+    ended: boolean;
+    speed: number;
+    motion: "smooth" | "step";
+}
+/** What `mountCircuitRace` gives back. */
+export interface KyogijoRace {
+    /** The race it plays. */
+    readonly race: CircuitRace;
+    /** The 3D view, when the race is on one. */
+    readonly turn: KyogijoTurn<CircuitOptions> | undefined;
+    state(): RaceState;
+    /** The race at the clock's time: the standings, the lap, the fastest lap. */
+    moment(): RaceMoment;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Go to a time, in seconds from the start. */
+    seek(t: number): void;
+    /** Go to the moment the leader next crosses the line. */
+    nextLap(): void;
+    setSpeed(speed: number): void;
+    /** Draw again with new options (the language, the theme): the clock and the race stay where they are. A new circuit, seed, laps or cars is a new race: mount it again. */
+    update(options: RaceViewOptions): void;
+    /** Play another race in the same view (a feed that came in again while a race is followed): the clock stays where it is, held to the new race's end, and stays playing or paused. */
+    replace(race: CircuitRace): void;
+    destroy(): void;
+}
+/**
+ * Mount a simulated race on a circuit: the circuit flat (or in 3D) with a dot for each made-up car, the race clock, play and pause, the speeds 1×, 10× and 60×, a slider over the whole race and the timing board, moving
+ * together. It does nothing until it is played, and nothing while it is paused, hidden or out of sight.
+ * @example
+ * ```ts no-run
+ * import { mountCircuitRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = mountCircuitRace(document.querySelector("#race")!, { circuit: "las-vegas" }, { speed: 10 });
+ * race.play();
+ * ```
+ */
+export declare function mountCircuitRace(host: HTMLElement, initial: RaceViewOptions, settings?: RaceViewSettings): KyogijoRace;