currently in early active development surface intent · in validation X-Plane 12 first · MSFS after core maturity

System Architecture

How VibePilot ATC Is Built

Seven layers. No controller logic fires until spatial certainty is proven underneath it. The system earns its way from raw simulator data to real ATC clearances — one verified layer at a time.

47,824 airports indexed
75,000+ runways in dataset
5 / 7 layers operational
X-Plane 12 primary target
I Seeing the aircraft
01 Simulator Intake
Operational

X-Plane sends a UDP packet every simulation tick. This layer opens the socket, receives it, validates it, and renames the raw fields into the system's own vocabulary.

Raw simulator transport and metadata normalisation. UDP socket payload received, validated, and mapped to internal field names.
NetworkServiceReceives simulator UDP frames and forwards validated telemetry internally. → XPlaneMetadataBridgeExtracts aircraft identity and environment context from simulator metadata.
Receives: UDP Payload
latitude, longitude float heading_true float groundspeed float altitude_msl, vertical_speed float on_ground, sim_time bool/float
Emits: AircraftStateRaw
lat, lon float headingTrue float groundspeedKt float altitudeFt, verticalSpeedFpm float onGround, timestamp bool/float
AircraftStateRaw
↓
02 Aircraft State Construction
Operational

Takes that raw frame and builds the first real aircraft object. It remembers the previous sample — so the system knows not just where the aircraft is, but where it was, and how much time passed.

Constructs a stable, continuous operational aircraft object. First continuity layer, preserving previous sample for delta calculations.
AircraftStateFirst normalised aircraft object combining raw motion and simulator metadata. → .fromTelemetry()Constructs the operational AircraftState from normalised telemetry input.
Receives: AircraftStateRaw
lat, lon, headingTrue groundspeedKt, altitudeFt verticalSpeedFpm, onGround timestamp
Emits: AircraftState
position {lat,lon} heading, track float groundspeed, altitude float previousPosition {lat,lon} deltaTime float
AircraftState
↓
04 Reference Dataset
Operational

A permanently loaded map of every airport and runway on Earth. Given any aircraft position, it returns the nearby runways — their exact threshold coordinates, heading, dimensions — in milliseconds. Feeds both the geometry layer and the intent engine on every frame.

Persistent runway reference layer supplying geometry and runway intelligence with spatial context.
AptDatLoaderParses X-Plane apt.dat runway definitions into structured memory. → RunwayRepositoryPersistent runway dataset used by all higher runway logic. → RunwayFamilyIndexGroups reciprocal runways into operational families. → AirportSpatialIndexFast lookup structure for nearby airport geometry.
Receives: Context Request
aircraft position search radius
Emits: RunwayCandidateSet
runwayId, airportIcao thresholdA {lat,lon} thresholdB {lat,lon} heading, length, width
RunwayCandidateSet
47,824 airports · 75,000+ runways · X-Plane apt.dat ↷ feeds L03 (geometry) and L05 (RISEngine) on every frame
↓
03 Geometry Core
Operational

This is where the aircraft first gets a relationship to a runway. It calculates how far off-centreline the aircraft is, how far from the threshold, whether the headings align, and applies magnetic variation so everything is in real-world magnetic reference.

Converts aircraft state into runway-relative geometry. First layer where runway relation becomes measurable, fed continuously by L04 runway candidates.
GeoMathLow-level spatial calculations used across geometry and runway logic. → GeoCalculatorDerives headings, distances, bearings and positional deltas. → MagneticModelConverts true bearings into local magnetic reference. → RunwayHeadingResolverAligns aircraft track against runway magnetic heading families.
Receives
AircraftState RunwayCandidateSet ← L04
Emits: GeometryState
distanceToThreshold bearingToThreshold crossTrackMeters alongTrackMeters headingDelta alignedRunways[]
GeometryState
↶ cross-layer feed: RunwayCandidateSet from L04 on every frame
II Understanding intent
↓
05 RISEngine — Runway Intelligence
Operational

Geometry says where the aircraft is. This layer says what it's trying to do. It watches approach corridors, lateral stability, and phase of flight — and commits to a runway assignment before the pilot crosses the threshold. Touchdown, rollout, and vacate are latched, not re-evaluated.

Converts geometry into runway intent. RISEngine orchestrates the call chain. Corridor and lateral detectors run as sibling branches feeding RunwayIntentPredictor after phase is resolved.
RISEngineCentral runway-intelligence orchestrator resolving runway intent. → RunwayPhaseResolverDetermines whether aircraft is approach, rollout, or airborne relative to runway. → ApproachCorridorDetectorMeasures corridor alignment before runway threshold entry. branch RunwayLateralDetectorTracks lateral displacement relative to runway centreline. → ApproachStabilityMonitorEvaluates approach continuity before intent confirmation. → RunwayIntentPredictorPredicts target runway before physical threshold crossing.
Receives
AircraftState GeometryState RunwayCandidateSet ← L04
Emits: RunwayIntentState
assignedRunway phase stableApproach bool lateralConfidence float occupancyPrediction
RunwayIntentState
Touchdown · Rollout · Vacated latch
↓
06 Surface Interpretation
In Progress

Once on the ground, intent changes character. Four parallel detectors distinguish between lining up for departure, crossing a runway without departing, backtracking along it, or accelerating into a takeoff roll. Each answer is a boolean that feeds directly into controller logic.

Extends runway intelligence into ground operations through parallel surface detectors resolved under SurfaceIntentResolver.
RunwayIntentPredictorPredicts target runway before physical threshold crossing. → LineupDetectorDetects deliberate runway entry for departure positioning. parallel RunwayCrossingDetectorIdentifies lateral runway traversal without departure intent. · BacktrackDetectorDetects reverse runway movement after entry. · DepartureRollDetectorConfirms acceleration consistent with takeoff roll.
Receives
RunwayIntentState AircraftState
Emits: SurfaceState
surfaceIntent lineup bool crossing bool backtrack bool departureRoll bool
SurfaceState
Taxi V5.1 · Active development
III Speaking like ATC
↓
07 ATC Controller Decision
Planned

Controller roles only activate after runway certainty and surface intent are proven in the layers below. Three roles — Ground, Tower, Approach — each derive clearances from the state stack. A phraseology layer converts those decisions into standard ATC language. A voice renderer speaks them.

Controller roles derive clearances only after runway certainty and spatial confidence are established in lower layers.
GroundControllerTaxi clearances, crossings and surface sequencing. roles TowerControllerDepartures, landings and runway occupancy decisions. · ApproachControllerArrivals before tower handoff and runway assignment continuity. → PhraseologyLayerConverts decisions into standard ATC language. → VoiceRendererConverts operational decisions into ATC voice output.
Receives
RunwayIntentState SurfaceState traffic state (future)
Emits: Clearance
clearanceType assignedRunway phraseology string voice audio
e.g. CLEARED TO LAND RWY 28R
Signal Flow PHASE I — SEEING PHASE II — INTENT PHASE III — SPEAKING L01 L02 L04 REFERENCE L03 L05 L06 L07 Simulator Intake State Construction Geometry Core RISEngine Surface Interp. ATC Decision Airport & Runway Ref. RunwayCandidateSet RunwayCandidateSet
operational
in progress
planned
cross-layer ref
Full system signal map · updated with each architectural revision
Layer Resolution Monitor — 4.8nm final, RWY 28, Zurich
[01]lat=47.4481 lon=8.6649 hdg=278° gs=138kt alt=2920ft vs=-720fpm gnd=0 [02]track=277° dt=0.10s prev=(47.4479,8.6646) — continuity established [04]cand=12 aligned=[28,34] thr28=(47.4588,8.5551) — reference ready [03]xtrk=-10m atrk=4.8nm dthr=4.8nm hdgΔ=1.0° — inside corridor [05]phase=FINAL corr=VALID lat=STABLE conf=0.96 → RWY 28 ASSIGNED [06]intent=APPROACH | lineup=0 crossing=0 backtrack=0 depRoll=0 [07]rwy=28 clr=PENDING phraseology=inactive — layer not yet built