feat(tesla-flying-roadster): add the Tesla flying Roadster explainer

explainers/tesla-flying-roadster/explainer.json

@@ -0,0 +1,13 @@
+{
+  "slug": "tesla-flying-roadster",
+  "tags": ["vehicles", "physics", "flight"],
+  "topic": "cold-gas thruster car",
+  "cover": "cover.webp",
+  "entry": "src/index.ts",
+  "chapters": "chapters.html",
+  "locales": ["en", "zh", "es", "uk", "pt", "fr", "de", "ja"],
+  "social": {
+    "image": "social/og-image.png",
+    "alt": "A grey single-seat sports car upside down above a curled ramp at dusk, white gas jets at its corners, beside the title How a cold-gas thruster hops a car"
+  }
+}

explainers/tesla-flying-roadster/src/ids.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ANCHOR_IDS,
+  CAMERA_VIEW_IDS,
+  CAR_ANCHOR_IDS,
+  CAR_REGION_IDS,
+  LABEL_PRIORITY,
+  NOZZLE_IDS,
+  NOZZLE_PARTS,
+  PART_IDS,
+  PHASE_IDS,
+  PRESET_IDS,
+  REGION_IDS,
+} from './ids';
+
+function unique(values: readonly string[]): boolean {
+  return new Set(values).size === values.length;
+}
+
+describe('ids', () => {
+  it('names every part, phase, preset, nozzle and view once', () => {
+    [PART_IDS, PHASE_IDS, PRESET_IDS, CAMERA_VIEW_IDS, NOZZLE_IDS].forEach((ids) =>
+      expect(unique(ids)).toBe(true),
+    );
+  });
+
+  it('ranks every part for labels exactly once', () => {
+    expect([...LABEL_PRIORITY].sort()).toEqual([...PART_IDS].sort());
+  });
+
+  it('gives each chapter its own camera view', () => {
+    expect(PRESET_IDS).toHaveLength(CAMERA_VIEW_IDS.length);
+  });
+
+  it('has ten nozzles in three part groups', () => {
+    expect(NOZZLE_IDS).toHaveLength(10);
+    expect(Object.keys(NOZZLE_PARTS)).toEqual([...NOZZLE_IDS]);
+    const groups = Object.values(NOZZLE_PARTS);
+    expect(groups.filter((group) => group === 'cornerNozzles')).toHaveLength(4);
+    expect(groups.filter((group) => group === 'frontNozzles')).toHaveLength(2);
+    expect(groups.filter((group) => group === 'rearNozzles')).toHaveLength(4);
+  });
+
+  it('splits regions and anchors into the ones on the car and the ones on the site', () => {
+    CAR_REGION_IDS.forEach((id) => expect(REGION_IDS).toContain(id));
+    CAR_ANCHOR_IDS.forEach((id) => expect(ANCHOR_IDS).toContain(id));
+  });
+});

explainers/tesla-flying-roadster/src/ids.ts

@@ -0,0 +1,206 @@
+export const PART_IDS = [
+  'body',
+  'wheels',
+  'seat',
+  'tank',
+  'tankValve',
+  'cornerNozzles',
+  'frontNozzles',
+  'rearNozzles',
+  'jets',
+  'forceArrows',
+  'fans',
+  'runway',
+  'ramp',
+  'landingPad',
+  'ghostPath',
+  'parkedRow',
+] as const;
+
+export type PartId = (typeof PART_IDS)[number];
+
+export const LABEL_PRIORITY: readonly PartId[] = [
+  'jets',
+  'cornerNozzles',
+  'rearNozzles',
+  'tank',
+  'ramp',
+  'landingPad',
+  'forceArrows',
+  'ghostPath',
+  'tankValve',
+  'seat',
+  'frontNozzles',
+  'fans',
+  'wheels',
+  'body',
+  'parkedRow',
+  'runway',
+];
+
+export const PHASE_IDS = [
+  'sprint',
+  'settle',
+  'ramp',
+  'brake',
+  'hold',
+  'deck',
+  'flip',
+  'catch',
+  'runUp',
+  'leap',
+  'twist',
+  'landing',
+  'rest',
+] as const;
+
+export type PhaseId = (typeof PHASE_IDS)[number];
+
+export const MOMENT_IDS = [
+  'sixty',
+  'inverted',
+  'held',
+  'leavesRamp',
+  'rollComplete',
+  'touchdown',
+  'liftOff',
+  'apex',
+  'twistComplete',
+  'landed',
+  'stopped',
+] as const;
+
+export type MomentId = (typeof MOMENT_IDS)[number];
+
+export const PRESET_IDS = ['tank', 'nozzle', 'boost', 'hook', 'flip', 'jump', 'limits'] as const;
+
+export type PresetId = (typeof PRESET_IDS)[number];
+
+export const CHAPTER_ACTION_IDS = ['gas', 'tank', 'replay', 'moment'] as const;
+
+export type ChapterActionId = (typeof CHAPTER_ACTION_IDS)[number];
+
+export const GAS_IDS = ['air', 'nitrogen', 'helium'] as const;
+
+export type GasId = (typeof GAS_IDS)[number];
+
+export const TANK_CHOICE_IDS = ['400', '600'] as const;
+
+export type TankChoiceId = (typeof TANK_CHOICE_IDS)[number];
+
+export const CORNER_NOZZLE_IDS = [
+  'cornerFrontLeft',
+  'cornerFrontRight',
+  'cornerRearLeft',
+  'cornerRearRight',
+] as const;
+
+export const FRONT_NOZZLE_IDS = ['frontLeft', 'frontRight'] as const;
+
+export const REAR_NOZZLE_IDS = [
+  'rearOuterLeft',
+  'rearInnerLeft',
+  'rearInnerRight',
+  'rearOuterRight',
+] as const;
+
+export const NOZZLE_IDS = [...CORNER_NOZZLE_IDS, ...FRONT_NOZZLE_IDS, ...REAR_NOZZLE_IDS] as const;
+
+export type NozzleId = (typeof NOZZLE_IDS)[number];
+
+export type NozzlePartId = Extract<PartId, 'cornerNozzles' | 'frontNozzles' | 'rearNozzles'>;
+
+export const NOZZLE_PARTS: Readonly<Record<NozzleId, NozzlePartId>> = {
+  cornerFrontLeft: 'cornerNozzles',
+  cornerFrontRight: 'cornerNozzles',
+  cornerRearLeft: 'cornerNozzles',
+  cornerRearRight: 'cornerNozzles',
+  frontLeft: 'frontNozzles',
+  frontRight: 'frontNozzles',
+  rearOuterLeft: 'rearNozzles',
+  rearInnerLeft: 'rearNozzles',
+  rearInnerRight: 'rearNozzles',
+  rearOuterRight: 'rearNozzles',
+};
+
+export type NozzleThrusts = Readonly<Record<NozzleId, number>>;
+
+export const VIEW_IDS = ['nozzles', 'forces', 'tank', 'ghost', 'labels'] as const;
+
+export type ViewId = (typeof VIEW_IDS)[number];
+
+export type ViewOptions = Record<ViewId, boolean>;
+
+export const CAMERA_VIEW_IDS = [
+  'tankClose',
+  'nozzleClose',
+  'boostSide',
+  'rampWide',
+  'flipChase',
+  'jumpWide',
+  'siteWide',
+] as const;
+
+export type CameraView = (typeof CAMERA_VIEW_IDS)[number];
+
+export const REGION_IDS = ['site', 'car', 'cabin', 'tail', 'ramp', 'arc', 'jump'] as const;
+
+export type RegionId = (typeof REGION_IDS)[number];
+
+export const CAR_REGION_IDS = ['car', 'cabin', 'tail'] as const;
+
+export type CarRegionId = (typeof CAR_REGION_IDS)[number];
+
+export type SiteRegionId = Exclude<RegionId, CarRegionId>;
+
+export const ANCHOR_IDS = ['car', 'tank', 'tail', 'rampExit', 'pad', 'row'] as const;
+
+export type AnchorId = (typeof ANCHOR_IDS)[number];
+
+export const CAR_ANCHOR_IDS = ['car', 'tank', 'tail'] as const;
+
+export type CarAnchorId = (typeof CAR_ANCHOR_IDS)[number];
+
+export type SiteAnchorId = Exclude<AnchorId, CarAnchorId>;
+
+export type Point = readonly [x: number, y: number, z: number];
+
+export interface CarReading {
+  position: Point;
+  speed: number;
+  height: number;
+  roll: number;
+  pitch: number;
+  onGround: boolean;
+  onRamp: boolean;
+  airborne: boolean;
+}
+
+export interface TankReading {
+  pressureBar: number;
+  massKg: number;
+  massShare: number;
+  empty: boolean;
+  emptyAtSeconds: number | null;
+  shortfallMs: number;
+}
+
+export interface ChaseTarget {
+  position: Point;
+  heading: number;
+  pitch: number;
+  roll: number;
+  span: number;
+}
+
+export interface AssemblyState {
+  phase: number;
+  playing: boolean;
+  gas: GasId;
+  tankLitres: number;
+  car: CarReading;
+  nozzles: NozzleThrusts;
+  tank: TankReading;
+  fans: boolean;
+  view: ViewOptions;
+}

explainers/tesla-flying-roadster/src/index.ts

@@ -0,0 +1,27 @@
+import './style.css';
+import { defineExplainer } from '@core/explainer';
+import { SCENE_OPTIONS, mountThrusterCarScene } from './scene';
+import { PART_INFO } from './scene/partInfo';
+import { PRESETS, createThrusterCarStore } from './state';
+import type { ThrusterCarStoreState } from './state';
+import { THRUSTER_CAR_TIMELINE } from './timeline';
+import {
+  CHAPTER_ACTIONS,
+  THRUSTER_CAR_CHOICES,
+  THRUSTER_CAR_READOUTS,
+  VIEW_TOGGLES,
+  mountThrusterCarUi,
+} from './ui';
+
+export default defineExplainer<ThrusterCarStoreState>({
+  timeline: THRUSTER_CAR_TIMELINE,
+  presets: PRESETS,
+  parts: PART_INFO,
+  createStore: () => createThrusterCarStore(),
+  dock: { choices: THRUSTER_CAR_CHOICES, toggles: VIEW_TOGGLES },
+  readouts: THRUSTER_CAR_READOUTS,
+  actions: CHAPTER_ACTIONS,
+  scene: SCENE_OPTIONS,
+  mountScene: mountThrusterCarScene,
+  mountUi: mountThrusterCarUi,
+});

explainers/tesla-flying-roadster/src/model/boost.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { ENTRY_SPEED_MS, SIXTY_MPH_MS } from './constants';
+import {
+  SETTLE_DECEL,
+  SETTLE_SECONDS,
+  SPRINT_ACCEL,
+  SPRINT_DISTANCE_M,
+  SPRINT_SECONDS,
+  SPRINT_THRUST_N,
+  boostAccel,
+  boostLastsSeconds,
+  zeroToSixtySeconds,
+} from './boost';
+import { RAMP, SITE } from './layout';
+import { G } from './constants';
+
+describe('boost', () => {
+  it('runs 0 to 60 mph in 0.81 s at 3.4 g on about 56 kN', () => {
+    expect(zeroToSixtySeconds(SPRINT_THRUST_N)).toBeCloseTo(SPRINT_SECONDS, 9);
+    expect(SPRINT_ACCEL / G).toBeCloseTo(3.4, 1);
+    expect(SPRINT_THRUST_N / 1000).toBeCloseTo(56.3, 1);
+    expect(SPRINT_DISTANCE_M).toBeCloseTo(SITE.finishLineX, 1);
+  });
+
+  it('brakes at about 4 m/s2 to reach the loop at 18 m/s', () => {
+    expect(SETTLE_DECEL).toBeCloseTo(4.0, 1);
+    expect(SPRINT_SECONDS + SETTLE_SECONDS).toBeCloseTo(3.0, 2);
+    const settled = SIXTY_MPH_MS * SETTLE_SECONDS - 0.5 * SETTLE_DECEL * SETTLE_SECONDS ** 2;
+    expect(SPRINT_DISTANCE_M + settled).toBeCloseTo(RAMP.entryX, 9);
+    expect(SIXTY_MPH_MS - SETTLE_DECEL * SETTLE_SECONDS).toBeCloseTo(ENTRY_SPEED_MS, 9);
+  });
+
+  it('empties 600 L of air in 2.7 s at the full 80 kN', () => {
+    expect(Math.floor(boostLastsSeconds(80000, 'air', 600) * 10) / 10).toBe(2.7);
+    expect(boostAccel(17000)).toBe(10);
+  });
+});

explainers/tesla-flying-roadster/src/model/boost.ts

@@ -0,0 +1,24 @@
+import type { GasId } from '../ids';
+import { CAR_MASS_KG, ENTRY_SPEED_MS, SIXTY_MPH_MS } from './constants';
+import { massFlow, storedMass } from './gas';
+import { RAMP } from './layout';
+
+export const SPRINT_SECONDS = 0.81;
+export const SPRINT_ACCEL = SIXTY_MPH_MS / SPRINT_SECONDS;
+export const SPRINT_THRUST_N = CAR_MASS_KG * SPRINT_ACCEL;
+export const SPRINT_DISTANCE_M = (SIXTY_MPH_MS * SPRINT_SECONDS) / 2;
+export const SETTLE_DECEL =
+  (SIXTY_MPH_MS ** 2 - ENTRY_SPEED_MS ** 2) / (2 * (RAMP.entryX - SPRINT_DISTANCE_M));
+export const SETTLE_SECONDS = (SIXTY_MPH_MS - ENTRY_SPEED_MS) / SETTLE_DECEL;
+
+export function boostAccel(thrustN: number): number {
+  return thrustN / CAR_MASS_KG;
+}
+
+export function zeroToSixtySeconds(thrustN: number): number {
+  return SIXTY_MPH_MS / boostAccel(thrustN);
+}
+
+export function boostLastsSeconds(thrustN: number, gas: GasId, litres: number): number {
+  return storedMass(gas, litres) / massFlow(thrustN, gas);
+}