flight: Aircraft Dynamics, Route Guidance & Weather

An aircraft route specifies where an aircraft should go. Getting there requires a model of what the aircraft can do.

flight is tsim’s native fixed-wing truth generator. It turns route requests into throttle and control-surface commands, advances a nonlinear rigid-body model, and publishes the resulting state through DIS. Wind, engine response, aerodynamic limits, and runway contact all affect the trajectory.

This article covers the flight system introduced in the tsim overview. Its output also supplies the moving targets used in the sensor and fusion pipeline.

Two Clocks, One Aircraft State

The default world tick is 20 Hz, while aircraft physics runs at 100 Hz. Each world tick therefore contains five physics steps. A fourth-order Runge–Kutta integrator advances the rigid-body state at the smaller interval; the service publishes DIS state at the world rate.

graph LR
    route["Route and speed constraints"] --> guidance["Guidance and envelope protection"]
    guidance --> controls["Throttle and control surfaces"]
    controls --> forces["Aerodynamics, propulsion, contact"]
    weather["Atmosphere and wind"] --> forces
    forces --> integrator["100 Hz rigid-body integration"]
    integrator --> state["Position, velocity, attitude"]
    state --> guidance
    state --> dis["20 Hz DIS truth"]

The runtime distributes independent aircraft across Taskflow workers, then commits their published state in order. Physics and weather sampling do not require a renderer, so the same model can run headlessly or feed several viewers.

The separate rates matter when evaluating performance. A 20 Hz world has a 50 ms tick budget, but each aircraft still needs its substeps completed within that budget. A viewer drawing at a higher rate does not increase the underlying physics rate.

Coordinate Frames Are Part of the Model

Flight combines several coordinate systems:

A quaternion expresses body attitude relative to NED. Forces computed in body coordinates must be transformed before updating navigation state; DIS consumers receive Earth-fixed position and motion. Scenario fields use SI units, with angular fields explicitly named _deg where degrees are expected.

These conventions also explain why a heading is insufficient to describe an aircraft. Bank and pitch determine how body forces act in the navigation frame, while ground velocity and air-relative velocity can point in different directions.

Airspeed Drives Aerodynamic Forces

The important velocity for aerodynamics is velocity relative to the surrounding air:

v_air = v_ground - wind
V = length(v_air)
q = 0.5 * air_density * V²
Lift = q * wing_area * C_L
Drag = q * wing_area * C_D

The model interpolates aerodynamic coefficient tables over angle of attack, including the stall region. Drag includes induced drag associated with lift, Mach-dependent drag rise, and changes from flaps and landing gear. Moments combine static stability, rotational damping, and control-surface effects.

This produces useful interactions. Increasing bank changes the lift needed to hold altitude. Holding pitch while losing airspeed can move the aircraft toward stall. Deploying flaps changes the aerodynamic configuration instead of merely changing a displayed label.

The propulsion layer supports electric propellers, piston propellers, turboprops, and jet engines. Engine response includes lag, and fuel consumption updates aircraft mass. Available thrust and aerodynamic forces therefore evolve with the state rather than following a fixed speed schedule.

The included profiles are generic approximations:

They provide different operating envelopes and engine behavior for simulation scenarios. Their coefficients are not validated flight-test datasets for particular production aircraft. Profile structure and equations are documented in the modeling guide.

Routes Become Control Commands

Lateral guidance uses great-circle route geometry, cross-track error, and turn anticipation. The controller leads a turn instead of waiting for the aircraft to arrive exactly at a waypoint and then changing direction instantly.

Vertical and speed guidance use a total-energy approach. Specific mechanical energy combines height and speed:

energy_per_unit_mass = g * height + 0.5 * airspeed²

Throttle changes the total available energy; pitch helps distribute it between altitude and speed. Envelope protection limits commands around angle of attack, load factor, overspeed, and configuration constraints. These limits influence the commanded maneuver; they do not make every requested route physically achievable.

For example, this waypoint fragment requests 2,100 m ellipsoid height and 61 m/s indicated airspeed:

{
  "name": "CRUISE",
  "latitude_deg": 39.19,
  "longitude_deg": -77.05,
  "altitude_m": 2100.0,
  "speed": { "kind": "ias", "value": 61.0 },
  "acceptance_radius_m": 900.0
}

The acceptance radius defines arrival tolerance. The aircraft’s path between waypoints emerges from guidance and physics; positions are not interpolated or snapped to the route.

Flight phases manage takeoff and landing behavior. A typical successful sequence is:

graph LR
    GroundRoll --> Rotation --> Climb --> Enroute --> Descent --> Approach --> Flare --> Rollout --> Complete
    Approach --> GoAround
    GoAround --> Approach

The state machine also supports holding and failure states. A go-around gives an aircraft another approach opportunity within configured retry limits, rather than silently forcing a landing.

The Runway Is a Contact Surface

Ground behavior includes spring-and-damper landing gear, wheel friction, nose-wheel steering, and runway slope. Gear contact affects forces and moments, so takeoff rotation and landing rollout remain part of the dynamics.

A post-integration surface projection stabilizes gear contact numerically. This corrects penetration at the contact surface; it is separate from route guidance and does not place airborne aircraft on waypoint coordinates.

Scenario-defined runways work without an external catalog. An OurAirports-compatible runways.csv can supply additional runway data, and the editors expose runway search when that catalog is available.

Weather Changes the Aircraft’s Response

The baseline atmosphere is ISA with deterministic gusts. The runtime’s gust variation uses deterministic sinusoids, making repeated scenarios easier to compare.

The GRIB2 weather path samples NOAA/NCEP fields independently of the graphics layer. It uses horizontal bilinear interpolation, height-based vertical sampling from geopotential levels, and interpolation between available times. Physics caches weather at 1 Hz and interpolates between samples; degraded data can retain usable fields rather than discarding the entire atmosphere.

Wind changes the relationship between heading, airspeed, and ground track. Temperature and pressure affect atmospheric properties. These are physical inputs to the model, while the globe weather overlays provide a way to inspect selected fields visually.

Run, Edit, and Observe

After the shared build steps, launch the installed service from the repository root:

./build/dist/bin/flight \
  --profiles ./build/dist/bin/profiles \
  --scenario ./build/dist/bin/flight_scenario.json \
  --web-root ./build/dist/bin/web

The browser editor is served at http://127.0.0.1:33104/web. It provides map-based waypoint placement, great-circle route rendering, runway search, live aircraft tracking at 4 Hz, and scenario load/save/apply. The API exposes state, profile and runway catalogs, configuration updates, and pause/resume/reset commands.

tview supplies a globe-based Flight Routes editor and can apply the complete scenario through the service API:

./build/dist/bin/tview \
  --flight-scenario ./build/dist/bin/flight_scenario.json \
  --flight-api-url http://127.0.0.1:33104

flightview supplies the aircraft HUD. For a finite headless smoke run, the repository documents:

build/src/flight/flight --no-network --no-api --unpaced --max-ticks 400

The source includes model, scenario, and weather tests. When investigating a route, inspect phase transitions, airspeed, attitude, and weather alongside position: a trajectory alone does not explain which controller or physical limit shaped it. See the flight service guide and runtime implementation for current controls and execution details.

Continue with sensor detections and track fusion, or return to the tsim overview.