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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗