AeroShield

An interactive, cinematic 3D visualization that explains, step by step, the conceptual stages of ballistic-missile defense: launch, ascent, radar detection, track establishment, threat assessment, the decision to engage, interceptor launch, interception and post-event analysis.

Live demo

Educational visualization. The place, objects, distances, timings and the "Patriot-like" defensive system are fictional and deliberately simplified. Nothing here represents the real performance, parameters or procedures of any real system.

Screenshots

What you can do

• Run three scenarios: a successful intercept by day, a missed intercept at sunset, and a night defense from a different direction.
• Control time: play, pause, step event by event, restart, change speed (¼× to 10×) and scrub the timeline. The simulation is deterministic, so every jump is exact and every replay is identical.
• Learn as you watch: read a plain-language "What is happening?" explanation for every stage. Open Learn for background on ballistic missiles, radar, tracking, command and control, interceptors, interception, and the simulation's limits.
• Choose a camera: six modes (Cinematic, Free, Follow target, Follow interceptor, Overview, Top down) with smooth transitions. Dragging the view switches to Free.
• Change what you see: toggle trajectories, radar scan, detection area, data links, labels, particles and atmosphere, and switch lighting between Day, Sunset and Night.
• Inspect the model: the inspector shows the conceptual state of every part of the simulation. Export the event timeline or a replay record.
• Keep the scene clear: on wider screens the side panels shrink to one-line summaries while the simulation plays, and open again when you step, pick an event or the run ends.

The world

• A procedural landscape: rolling hills, forests, a meandering river with flowing water, and roads linking a fictional battery to the town it protects.

• A living town: Aldmere has houses with gardens, apartment blocks, shops with flats above, an office tower, warehouses, a church and a town hall. It has streets with markings, sidewalks and crossings, two stone bridges, street lights and parked cars, and its windows light up at night.

• Realistic explosions:

  • A blinding flash lights the valley.
  • A fireball cools from white-hot to orange to soot, and the smoke cloud billows and drifts downwind.
  • Sparks streak outward, and burning fragments arc away trailing smoke.
  • A ground impact also throws up dirt, sends a dust ring along the ground and leaves a scorch mark.

• Sound:

  • rocket motors and the interceptor leaving its canister;
  • blasts that arrive after their flash and echo across the valley;
  • the town's civil-defense siren;
  • wind, birds by day, crickets and owls at night, the river, the town and the battery's generator.

  Every sound is synthesized in the browser, so there are no audio files and no licenses. Switch it off with M or set the volume in Settings.

• Everything is first-party: models, textures and sounds are generated by the project itself. Nothing is downloaded from third parties, and the app works offline once loaded.

Accessibility

• Keyboard: every control works from the keyboard (see the shortcuts below), with visible focus.
• Screen readers: a live region announces each new stage.
• Reduced motion: follows your system setting or can be set in Settings. It cuts between camera shots, calms particles and softens the explosion flash.
• Low-end devices: quality adjusts automatically, with Low, Balanced and High profiles. Without WebGL the app explains why, and the timeline and explanations keep working.

Tech stack

Area	Technology
App	Next.js 16 (App Router), React 19, TypeScript (strict)
3D	three.js, React Three Fiber, drei, postprocessing (bloom, ACES tone mapping)
Simulation	Framework-free deterministic engine in src/engine (no React, no three.js)
State and data	Zustand stores, Zod-validated scenarios
UI	Tailwind CSS 4, Radix primitives, lucide icons
Animation	React Three Fiber frame loop; GSAP for camera transitions
Sound	Web Audio API, with the sound material generated in a Web Worker
Testing	Vitest, Testing Library, Playwright

Quick start

Requirements: Node.js 22+ and pnpm 10 (corepack enable provides pnpm).

pnpm install
pnpm dev            # http://localhost:3000

Production build:

pnpm build && pnpm start

Deployment

AeroShield is a standard Next.js app with no backend, database, API keys or environment variables.

• Build command: pnpm build. It first regenerates the 3D models (pnpm assets:generate, which uses the tsx dev dependency), so the build environment must install dev dependencies. Most hosts do by default.
• Run command: pnpm start. It serves the production build and uses the PORT environment variable if set.
• Runtime: Node.js 22 or newer. pnpm is pinned through the packageManager field in package.json.

On Vercel, import the repository: it detects Next.js and pnpm from the lockfile, and the default settings work. On any other Node.js host:

pnpm install --frozen-lockfile
pnpm build
PORT=8080 pnpm start

After deploying, put the URL at the top of this README (the line marked LIVE DEMO).

Scripts

Command	What it does
pnpm dev	Development server with hot reload
pnpm build	Regenerates the GLB models, then builds for production
pnpm start	Serves the production build
pnpm typecheck	Strict TypeScript check
pnpm lint	ESLint (includes a rule keeping the engine free of React/three)
pnpm format	Prettier (with Tailwind class sorting)
pnpm test	Unit and component tests (Vitest + Testing Library)
pnpm test:e2e	End-to-end tests (Playwright; run pnpm build first)
pnpm verify	Typecheck, lint, unit tests and build in one go
pnpm assets:generate	Exports the procedural models to public/assets/models/*.glb

First-time Playwright setup: pnpm exec playwright install chromium.

Keyboard shortcuts

Key	Action
Space	Play / pause
→	Step to the next timeline event
.	Step a single simulation tick
R	Restart
1–6	Camera: Cinematic, Free, Follow target, Follow interceptor, Overview, Top down
L	Open Learn
I	Toggle the inspector
H	Compact or expand both side panels
M	Sound on / off
Shift + D / ?debug	Developer diagnostics
Timeline focused: ← → Home End	Scrub (Shift for 5 s steps)

On wider screens the side panels follow playback: while the simulation plays they compact to a one-line summary (current stage, decision chain) so the scene stays in view, and they open again when you step (→), pick a timeline event, or the run ends. A plain pause leaves them compact. Each panel has its own compact/expand button; a panel you compact yourself stays compact until you open it. Turn the automatic behaviour off under Settings → Compact panels while playing.

Project layout

src/
  engine/        Deterministic simulation (pure TypeScript: no React, no three.js)
  scenarios/     Scenario data, validated with Zod at load
  features/      Runtime (engine ↔ app bridge), education content, camera modes, timeline maths, sound start-up
  stores/        Zustand stores: simulation view, scenario, camera, UI, settings
  components/    React UI: HUD, timeline, panels, accessible primitives
  three/         React Three Fiber scene: environment, town, entities, overlays, explosions, cameras
  audio/         Synthesized soundscape (Web Audio), driven by simulation state and the camera
  app/           Next.js entry (layout, page, global styles)
e2e/             Playwright tests
scripts/         Asset generation
docs/            README screenshots

Documentation

• ARCHITECTURE.md: layers, data flow, and how to add a defense system, camera mode or event
• SIMULATION.md: clock, phases, events, trajectories, sensor and engagement models, determinism
• 3D.md: scene composition, terrain, town, lighting, explosions, cameras, performance
• SOUND.md: the synthesized soundscape, how it follows the simulation, levels, adding a sound
• ASSETS.md: model pipeline, manifest, licenses, replacing models
• SCENARIOS.md: scenario schema and how to write one
• CONTRIBUTING.md: workflow, testing, quality and safety checklists

Browser support

The 3D view needs WebGL 2 (current Chrome, Edge, Firefox and Safari). Without WebGL the app explains why, and the timeline, controls and explanations keep working. Phones get a simplified layout and the low graphics profile automatically. Sound needs the Web Audio API (all current browsers); where it is missing, the sound controls are hidden.

Safety boundary

This project visualizes concepts at the level of a museum exhibit. It does not and must not contain real coordinates, real engagement envelopes, classified or proprietary specifications, real guidance or firing solutions, deployment optimization, or vulnerability analysis. See CONTRIBUTING.md.