feat(naval-drone): add the naval drone explainer

explainers/naval-drone/explainer.json

@@ -0,0 +1,12 @@
+{
+  "slug": "naval-drone",
+  "tags": ["vehicles", "physics", "weapons"],
+  "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 uncrewed boat skimming over the sea at dawn with spray flying from its chines, beside the title How a naval drone works"
+  }
+}

explainers/naval-drone/src/ids.ts

@@ -0,0 +1,161 @@
+export const PART_IDS = [
+  'hull',
+  'chines',
+  'sprayRails',
+  'payloadBay',
+  'fuelTanks',
+  'engine',
+  'electronicsBay',
+  'starlinkPanels',
+  'backupPanel',
+  'cameraDome',
+  'bowCamera',
+  'intake',
+  'duct',
+  'driveShaft',
+  'impeller',
+  'waterjet',
+  'stator',
+  'nozzle',
+  'steeringNozzle',
+  'reverseBucket',
+  'missileRails',
+  'jetStream',
+  'bowWave',
+  'spray',
+  'wake',
+  'wettedLength',
+  'videoGhost',
+  'satLink',
+  'backupLink',
+  'satellite',
+  'backupSatellite',
+  'groundStation',
+  'ship',
+  'shipRadar',
+  'companions',
+] as const;
+
+export type PartId = (typeof PART_IDS)[number];
+
+export const PHASE_IDS = ['launch', 'hump', 'cruise', 'sprint', 'arrival'] as const;
+
+export type PhaseId = (typeof PHASE_IDS)[number];
+
+export const MOMENT_IDS = [
+  'hullSpeed',
+  'humpPeak',
+  'onPlane',
+  'cruiseSpeed',
+  'throttleUp',
+  'topSpeed',
+  'alongside',
+] as const;
+
+export type MomentId = (typeof MOMENT_IDS)[number];
+
+export const PRESET_IDS = ['overview', 'hull', 'jet', 'link', 'horizon', 'fleet'] as const;
+
+export type PresetId = (typeof PRESET_IDS)[number];
+
+export const FIT_IDS = ['standard', 'missile'] as const;
+
+export type FitId = (typeof FIT_IDS)[number];
+
+export const HELM_IDS = ['left', 'straight', 'right', 'reverse'] as const;
+
+export type HelmId = (typeof HELM_IDS)[number];
+
+export const LINK_MODES = ['satellite', 'backup', 'lost'] as const;
+
+export type LinkMode = (typeof LINK_MODES)[number];
+
+export const SEA_STATE_IDS = ['smooth', 'slight', 'moderate', 'rough'] as const;
+
+export type SeaStateId = (typeof SEA_STATE_IDS)[number];
+
+export const SPEED_MARK_IDS = ['hullSpeed', 'hump', 'planing', 'cruise', 'top'] as const;
+
+export type SpeedMarkId = (typeof SPEED_MARK_IDS)[number];
+
+export const HULL_MODES = ['floating', 'hump', 'planing'] as const;
+
+export type HullMode = (typeof HULL_MODES)[number];
+
+export type CameraView = 'chase' | 'waterline' | 'stern' | 'sky' | 'eye' | 'group';
+
+export type RegionId = 'scene' | 'boat' | 'ship' | 'shore';
+
+export type AnchorId =
+  'boat' | 'dome' | 'stern' | 'ship' | 'satellite' | 'backupSatellite' | 'groundStation';
+
+export type Point = readonly [x: number, y: number, z: number];
+
+export interface RoutePose {
+  position: Point;
+  heading: number;
+}
+
+export type CompanionReading = RoutePose;
+
+export interface BoatReading extends RoutePose {
+  knots: number;
+  distance: number;
+  held: boolean;
+}
+
+export interface PlaningReading {
+  knots: number;
+  mode: HullMode;
+  trim: number;
+  heave: number;
+  transomDepth: number;
+  wettedLength: number;
+  keelWettedLength: number;
+  chineWettedLength: number;
+  liftShare: number;
+  speedLengthRatio: number;
+}
+
+export interface JetReading {
+  throttle: number;
+  flow: number;
+  jetSpeed: number;
+  thrust: number;
+  efficiency: number;
+  impellerShare: number;
+  nozzleAngle: number;
+  bucket: number;
+}
+
+export interface SeaReading {
+  state: SeaStateId;
+  waveHeight: number;
+}
+
+export interface LinkReading {
+  mode: LinkMode;
+  ghost: RoutePose | null;
+}
+
+export interface ViewOptions {
+  cutaway: boolean;
+  flow: boolean;
+  links: boolean;
+  labels: boolean;
+}
+
+export interface AssemblyState {
+  phase: number;
+  playing: boolean;
+  boat: BoatReading;
+  planing: PlaningReading;
+  jet: JetReading;
+  companions: readonly CompanionReading[];
+  sea: SeaReading;
+  link: LinkReading;
+  fit: FitId;
+  view: ViewOptions;
+  waterSection: boolean;
+  wettedBar: boolean;
+}

explainers/naval-drone/src/index.ts

@@ -0,0 +1,28 @@
+import './style.css';
+import { defineExplainer } from '@core/explainer';
+import { SCENE_OPTIONS, mountNavalDroneScene } from './scene';
+import { PART_INFO } from './scene/partInfo';
+import { PRESETS, createNavalDroneStore } from './state';
+import type { NavalDroneStoreState } from './state';
+import { NAVAL_DRONE_TIMELINE } from './timeline';
+import {
+  CHAPTER_ACTIONS,
+  NAVAL_DRONE_CHOICES,
+  NAVAL_DRONE_READOUTS,
+  VIEW_TOGGLES,
+  mountNavalDroneUi,
+} from './ui';
+
+export default defineExplainer<NavalDroneStoreState>({
+  id: 'naval-drone',
+  timeline: NAVAL_DRONE_TIMELINE,
+  presets: PRESETS,
+  parts: PART_INFO,
+  createStore: () => createNavalDroneStore(),
+  dock: { choices: NAVAL_DRONE_CHOICES, toggles: VIEW_TOGGLES },
+  readouts: NAVAL_DRONE_READOUTS,
+  actions: CHAPTER_ACTIONS,
+  scene: SCENE_OPTIONS,
+  mountScene: mountNavalDroneScene,
+  mountUi: mountNavalDroneUi,
+});

explainers/naval-drone/src/model/fleet.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { BOAT_COST_USD, KOTOV_VALUE_MUSD, PAYLOAD_MAX_KG } from './fleet';
+
+describe('fleet figures', () => {
+  it('costs about a quarter of a million dollars and carries up to 320 kg', () => {
+    expect(BOAT_COST_USD).toEqual([250000, 273000]);
+    expect(PAYLOAD_MAX_KG).toBe(320);
+  });
+
+  it('quotes the patrol ship at the value GUR gave', () => {
+    expect(KOTOV_VALUE_MUSD).toBe(65);
+  });
+});

explainers/naval-drone/src/model/fleet.ts

@@ -0,0 +1,3 @@
+export const BOAT_COST_USD = [250000, 273000] as const;
+export const PAYLOAD_MAX_KG = 320;
+export const KOTOV_VALUE_MUSD = 65;

explainers/naval-drone/src/model/horizon.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DETECTION_KM,
+  LENS_HEIGHT_M,
+  RADAR_HEIGHT_M,
+  detectionCovered,
+  hiddenUpToHalf,
+  minutesAtTopSpeed,
+  radarLineOfSightKm,
+  surfaceDropM,
+  visualHorizonKm,
+} from './horizon';
+
+describe('horizon', () => {
+  it('sees a 0.5 m boat from a 20 m radar out to about 21 km', () => {
+    expect(radarLineOfSightKm(20)).toBeCloseTo(21.3, 1);
+    expect(RADAR_HEIGHT_M).toEqual({ min: 5, max: 50, step: 1, default: 20 });
+  });
+
+  it('puts the horizon about 3 km from the 0.7 m camera', () => {
+    expect(LENS_HEIGHT_M).toBe(0.7);
+    expect(visualHorizonKm(LENS_HEIGHT_M)).toBeCloseTo(3.2, 1);
+  });
+
+  it('crosses 21 km at 42 kn in about 16 minutes and the 9 km detection range in about 7', () => {
+    expect(minutesAtTopSpeed(radarLineOfSightKm(20))).toBeCloseTo(16.5, 1);
+    expect(DETECTION_KM).toBe(9.26);
+    expect(minutesAtTopSpeed(DETECTION_KM)).toBeCloseTo(7.1, 1);
+  });
+
+  it('bends the sea so the line of sight grazes it at the radar horizon', () => {
+    const radarHeight = 20;
+    const horizonKm = radarLineOfSightKm(radarHeight) - radarLineOfSightKm(0);
+    expect(surfaceDropM(horizonKm)).toBeCloseTo(radarHeight, 9);
+    expect(surfaceDropM(0)).toBe(0);
+  });
+
+  it('expects detection only up to a moderate sea, sea state 4', () => {
+    expect(detectionCovered('smooth')).toBe(true);
+    expect(detectionCovered('moderate')).toBe(true);
+    expect(detectionCovered('rough')).toBe(false);
+  });
+
+  it('hides the boat behind waves up to half the time from a slight sea up', () => {
+    expect(hiddenUpToHalf('smooth')).toBe(false);
+    expect(hiddenUpToHalf('slight')).toBe(true);
+    expect(hiddenUpToHalf('rough')).toBe(true);
+  });
+});

explainers/naval-drone/src/model/horizon.ts

@@ -0,0 +1,45 @@
+import { SEA_STATE_IDS } from '../ids';
+import type { SeaStateId } from '../ids';
+import { BOAT } from './layout';
+import { knotsToMs } from './scale';
+
+export const RADAR_K = 4.12;
+export const VISUAL_K = 3.86;
+export const TARGET_HEIGHT_M = 0.5;
+export const LENS_HEIGHT_M = BOAT.lensHeight;
+export const RADAR_HEIGHT_M = { min: 5, max: 50, step: 1, default: 20 } as const;
+export const DETECTION_KM = 9.26;
+export const METRES_PER_KM = 1000;
+export const SECONDS_PER_MINUTE = 60;
+
+const DETECTION_COVERED_UP_TO: SeaStateId = 'moderate';
+const HIDDEN_FROM: SeaStateId = 'slight';
+
+export function radarLineOfSightKm(radarHeight: number): number {
+  return RADAR_K * (Math.sqrt(radarHeight) + Math.sqrt(TARGET_HEIGHT_M));
+}
+
+export function visualHorizonKm(eyeHeight: number): number {
+  return VISUAL_K * Math.sqrt(eyeHeight);
+}
+
+export function minutesAtTopSpeed(km: number): number {
+  const seconds = (km * METRES_PER_KM) / knotsToMs(BOAT.topKnots);
+  return seconds / SECONDS_PER_MINUTE;
+}
+
+export function surfaceDropM(km: number): number {
+  return (km / RADAR_K) ** 2;
+}
+
+function seaRank(state: SeaStateId): number {
+  return SEA_STATE_IDS.indexOf(state);
+}
+
+export function detectionCovered(state: SeaStateId): boolean {
+  return seaRank(state) <= seaRank(DETECTION_COVERED_UP_TO);
+}
+
+export function hiddenUpToHalf(state: SeaStateId): boolean {
+  return seaRank(state) >= seaRank(HIDDEN_FROM);
+}