Skip to content

Aircraft in the world explorer ​

The world explorer includes 54 aircraft: the P-51D Mustang, OH-6 interpretation, Bendy Small Airliner and fifty-one additional real-type interpretations. Each has an editable GLB, reusable entity type, flight physics, an instrumented cockpit and a chase camera. The additions include ten helicopters, ten general aviation aircraft, ten fighters, five cargo transports, the MV-22B Osprey, AV-8B Harrier, thirteen utility, regional, historic and business aircraft, and the OV-10A Bronco twin-boom observation aircraft. All use clean configurations without external weapons.

Compare national markings and camouflage in the livery gallery, then find every aircraft’s choices and reference evidence in the livery catalog.

Use the P-51 Mustang, OH-6 or Bendy Small Airliner buttons to visit the practice airfield, then press E to board. The aircraft buttons also work from the example hub's world view. A direct link can use ?aircraft=p51d, ?aircraft=oh6 or ?aircraft=airliner. The Aircraft catalog selector visits the additional models; direct links also accept suffixes such as ?aircraft=uh_1h, ?aircraft=f_16b, ?aircraft=c_17a, ?aircraft=mv_22b and ?aircraft=ov_10. The three original practice models load initially. Additional GLBs load on selection, with one additional request in flight and intermediate selections coalesced. Replacing a selection releases its model and ECS entity; an occupied aircraft is retained. The host's content-pack byte cache still follows its own cache budget. The catalog does not download all fifty-one new models on entry. See Vehicle interiors and instruments for cockpit source files, per-model instrument bindings and the shared exterior/seated GLB contract.

The practice airfield is a raised 4,500-meter runway and helipad near the initial camera position. Its foundation clears streamed buildings; it is a fictional practice location, not a mapped airport. The aircraft stay in the ECS and retain their position throughout the session, across terrain streaming and floating-origin changes. Reloading starts a fresh session.

Controls ​

ControlAction
EBoard, or exit after landing, stopping and engine shutdown
IStart/stop engine; allow the propeller or rotor to spool
= / −Increase/decrease throttle or helicopter collective; fighter afterburners engage above 85% throttle
W / SNose down / nose up
A / DBank left / right; helicopter cyclic
Z / CLeft / right rudder or anti-torque pedals; ground steering in the Mustang
SpaceWheel brakes
GRetract/extend airplane gear while airborne
FToggle airplane flaps
JCycle powered-lift lever: forward, 22.5°, 45°, 67.5°, vertical; Osprey/Harrier only
MHelicopter cyclic: assisted (bounded tilt, levels itself) or direct (full authority)
VCockpit / chase
MouseLook around the cockpit
RRecover at the airfield after an impact

Mustang: start the engine, set flaps, hold the brake while raising throttle, then release the brake. The propeller swings the nose left as the tail gets light, and a crosswind turns it into the wind: hold a little right rudder (C), or rudder away from the wind, to keep the runway centerline. Rotate around 85–100 knots and release the pitch key once the nose is about 10 degrees up; the airplane keeps the attitude it lifted off at. At climb power the propeller's torque rolls it slowly left, so tap right bank (D) as needed. Retract gear and flaps after climbing. Reduce throttle on approach, lower gear and flaps, and land with wings level and a gentle descent. Arrive firmly and the gear gives part of it back: the airplane skips into the air again, more so the Mustang, whose main wheels sit ahead of its center of mass and pitch the nose up as they touch. Ease the stick forward and let it settle. The wheel brakes do little until the wing has stopped flying, and braking hard lifts the Mustang's tail. Gear-up and hard landings register an impact. To accelerate, ease the nose down toward level flight after cleaning up; holding the takeoff attitude spends engine power on climbing. During a stall, lower the nose, add power and gently level the wings. Let airspeed rebuild before pulling out; hauling back immediately can stall the wing again, and rudder in a stall drops a wing. A stall recovery requires altitude. The stall announces itself: a few degrees before it the airflow starts to break away and the cockpit view shakes, harder the closer you get.

There are no attitude limits: hold A or D to roll through inverted, hold S at speed to loop. Releasing the stick holds the flight path the airplane is on; a brief tap of W or S changes it by a degree or so. Above about 250 knots full back stick stops at 6 g. Hold a hard pull and the pilot feels it: after a few seconds above 4.5 g (6.5 g in the fighters, whose pilots wear g-suits) the edges of the view dim, then the middle; ease off and it clears in a few seconds. Sustained negative g reddens the view. In a bank the wing's lift no longer holds the airplane up, so add back pressure to keep a turn level. Gusts and turbulence from the Weather setting bump, roll and yaw the airplane, more so near the ground on windy days.

OH-6: start the engine and allow roughly six simulation seconds to reach full rotor speed. Raise collective gradually toward 50%; exact hover power varies with altitude and ground effect. Small cyclic inputs tilt rotor thrust to travel. Lower collective gently to land. Switch off the engine and wait for the rotor to stop before exiting. If the engine stops in flight (press I to try it), lower the collective at once: the air rising through the rotor keeps it turning, and the helicopter comes down steadily at about 2,000 feet a minute instead of falling. Keep some forward speed, and just above the ground raise the collective to spend the rotor's speed on a soft touchdown. Hold the collective up instead and the rotor slows, the HUD warns of low rotor RPM, and the lift goes with it. An aircraft cannot be exited or switched to free flight while airborne. After an impact, R resets its aircraft state and places it on the airfield.

The helicopter's cyclic starts assisted: W/S and A/D ask for a tilt of up to about 30°, and the helicopter levels itself when you let go. Press M for direct cyclic. The stick then sets how fast the nose pitches and the fuselage rolls, there are no attitude limits, and releasing it holds whatever attitude you are in, level or not: in a hover you keep it level yourself. With 45 m/s and high collective, holding S loops the OH-6 in about six seconds for a hundred-odd meters of height; hold W to point it straight down. Keep the rotor loaded. Control comes from the rotor's thrust, so with the collective down, or pushing over into weightlessness, the stick does far less, and an inverted rotor drives the helicopter toward the ground. Press M again in any attitude to hand back to the assisted cyclic, which rolls the helicopter upright and levels it. On the ground both modes behave as assisted.

Bendy Small Airliner: the generic 39-meter twin uses the same airplane controls, with slower responses and a lower load-factor limit than the Mustang. Its two independently named engines use the jet thrust model, calibrated to a representative Mach 0.78 cruise. It is a fictional aircraft. The flight deck has an animated yoke; its display markings are decorative, while live flight readings come from the HUD. Board at the forward entry point. Its larger footprint needs substantially more runway and clearance.

Osprey and Harrier: use J to select vertical thrust (the parked Osprey starts there), allow the nacelles/nozzles to reach 90°, start the engine and increase power smoothly. W/S, A/D and Z/C provide powered pitch, roll and yaw control in a hover. Transition toward forward thrust gradually while gaining airspeed; the nacelles take 12 seconds for full travel and Harrier nozzles take 3. These are simplified powered-lift dynamics, with finite travel, vertical thrust, engine-dependent hover authority and airspeed blending. They do not simulate a real conversion corridor, transmission cross-shaft, vortex-ring state, hot-gas ingestion or a certified nozzle schedule. Fixed landing gear remains down regardless of G. Cargo aircraft have larger clearance and runway requirements.

Cockpit needles show airspeed, altitude, heading, vertical speed and RPM; the artificial horizon banks with the aircraft. The HUD supplies precise knot/feet/feet-per-minute readings, AGL height, g load, power, fuel remaining, engine/gear/flap state, stall, buffet, low-rotor-RPM, low-fuel and greyout alerts and terrain waiting status. It distinguishes KTAS from equivalent airspeed (KEAS), shows local Mach and afterburner percentage, and flags airframe/surface overspeed and developed departures. KEAS is not calibrated indicated airspeed. Propellers, both helicopter rotors, controls, gear, flaps, ailerons, elevators and rudder animate from simulation state. A rotor turning too fast for a display to sample fades from blades into a translucent disc, so a propeller at full power cannot alias into looking stopped; the hub stays solid, and the disc's size comes from the model (see the blur details below). The Mustang's gear takes 12 seconds: its inner wheel doors open, each main leg swings inboard into a well in the wing root, the tail wheel folds forward into the fuselage, and the doors close behind them. Its flaps take 13 seconds to run down to 50°.

Collisions and breakable sections ​

Aircraft contacts apply impulses at the point of impact, including angular response, friction and a small rebound. A wingtip strike can turn the aircraft while it keeps moving; a wreck continues to fall, tumble and slide. Terrain is tested at the airframe probes as well as at the landing origin, so a banked wing can hit the runway before the wheels or fuselage.

The Mustang has detachable wings, tail surfaces and propeller; the OH-6 has separate main rotor, tail rotor and tail sections; the small airliner has detachable wings (with their engines) and tail. Every animated rotor, propeller and fan in the aircraft catalog has its own collision disc and breakable joint. Strong impacts or repeated loaded scrapes consume joint integrity. Separation removes the section's collision probes, reduces lift/control authority and can disable its attached engines. An asymmetric wing loss produces a rolling moment. Detached geometry retains its own velocity and spin, then falls, bounces and slows against terrain and resident obstacles. Debris expires after 20 simulation seconds; the missing section stays missing. R repairs the aircraft and clears debris. Losing both wings switches the fuselage to ballistic wreck motion, disabling thrust and flight controls. Ground and obstacle contact dissipates wreck spin as well as sliding motion, so the fuselage settles after impact; airborne wrecks continue to fall and tumble. Other aircraft retain their existing airframe probes alongside their independent rotor parts; additional wing, tail and gear separation requires authored section bindings.

Rotors collide across their complete swept disc, including its interior and the spaces between the old tip probes. The obstacle adapter clips triangles to the disc's thickness and tests the radial boundary: geometry above or below a horizontal rotor clears it. Both rotors on tandem helicopters and both Osprey proprotors are independent; the latter follow the actual nacelle conversion position. Blade speed contributes to joint damage, so hovering beside a post can break a spinning rotor even when the hub is stationary. Propeller loss disables its engine; tail-rotor loss removes anti-torque authority and produces yaw. These conservative swept volumes remain active when stopped, regardless of visible blade phase.

For custom models, spec.collisionParts replaces collisionProbes. Every section declares a unique id, a role (body, leftWing, rightWing, tail, rotor, tailRotor, gear or engine), local probe centers and sphere radius, a section center, massFraction, and GLB nodes. Add breakSpeed in m/s for a breakable joint and engines for engines carried by that section. Keep a non-detachable body and at least 20% of the mass. Optional fragments selects triangles from shared static detail meshes using a model-space bounding box, so markings follow a wing. disc replaces a section's sphere probes with a model-space center, unit normal, radius, halfThickness and rotor node from visual.rotors. Its optional tilt hinge (pivot, unit axis, angle) follows thrustVectorPosition. A parent part id makes a rotor separate when its supporting wing or tail breaks, with no duplicate geometry or debris. Detached rotors inherit their shaft spin. Terrain uses deterministic samples of the disc interior, rim and lowest point; arbitrary height fields are not exact triangle meshes.

These are gameplay approximations with authored joint strengths, not a structural engineering or accident-reconstruction model. Detached pieces use sphere collision proxies; mesh deformation, fire, debris-to-debris contacts and impulse transfer into other vehicles are not simulated. The obstacle adapter uses oriented boxes for other cars and body-center spheres for other aircraft.

Hosts provide AircraftEnvironment.contacts(probes, entity) with world-space contact points, outward normals and penetration depths. aircraftObstacleContacts from client/aircraft adapts a collision tree, cars and other aircraft to this contract; the Earth view and world explorer use it. The legacy canOccupy callback remains supported with a simple recoil because it supplies no contact normal. aircraftState.damage and debris are serializable and survive keyframes; crashed means damage requiring recovery and no longer freezes motion.

Reuse in another experience ​

All 54 aircraft are registered in the molen.entities content pack, with their type documents and models. npx molen pack fetch https://molen.dev/packs/index.json molen.entities downloads it and lists it in your project.json packs, and the CLI then resolves the types; in a browser, open it with openPack from @bendyline/molen-pack and pass createPackSet([pack]).assetProvider() as the client's asset provider. The entity type IDs and glTF refs are molen.entities.aircraft.p51d, molen.entities.aircraft.oh6 and molen.entities.aircraft.airliner. Fly them in World Explorer to see the finished integration.

These are not kernel presets. Each type document contains the concrete aircraft's mass and center of gravity, engine and thrust geometry, wing or rotor geometry, control response, lift/drag or rotor-force coefficients, landing limits, collision probes, GLB reference, animation-node bindings, seats, and behavior scripts. Molen supplies only the generic airplane and helicopter algorithms.

js
import { installAircraft, flyAircraft } from '@bendyline/molen-kernel/aircraft';
import { mountEntity, unmountEntity } from '@bendyline/molen-kernel/vehicles';

export function setup(world) {
  const ground = { groundHeight: (x, z) => 0 };
  installAircraft(world, ground);
  world.registerCommand('board', () => mountEntity(world, 'pilot', 'mustang'));
  world.registerCommand('fly', (_w, command) => flyAircraft(world, 'pilot', command.payload));
  world.registerCommand('exit', () => unmountEntity(world, 'pilot', ground));
}

Declare the commands and spawn the pilot and aircraft in your scene, using the type registry. Aircraft, AircraftInput, AircraftState, aircraftMounts, initialAircraftState and stepAircraft are exported by kernel/aircraft; serializable spec shapes are in schema, while concrete values live in the external type documents. The aircraft capability installs the same seat follower as cars, once per world. Mounted actors bypass walking physics. Only the occupied pilot seat can submit flight intent.

The render half is @bendyline/molen-client/aircraft: createAircraftVisual(loadedGlb, spec) takes ownership of a loaded GLB and animates the nodes named by spec.visual from aircraft state, and aircraftCameraPose(transform, spec, options) returns the cockpit or chase pose from the same VehicleCameraOptions that @bendyline/molen-client/vehicles exports. The gear and flaps follow aircraftState.gearPosition and flapPosition as they travel. spec.visual.animation adds exterior moving parts as model-signal bindings, with keyframed curves so one gear position can sequence doors and legs.

Exposed airplane propellers fade from individual blades into a translucent, soft-edged disk between 20 and 60 rad/s (about 190–570 RPM). The disk follows actual shaft speed, including independent engines and spool-down, so blades cannot appear frozen at normal operating RPM. Its size and radial colors come from the blade geometry and materials; separate central hubs stay solid. This render-only effect needs no model changes and works with WebGL and WebGPU. Fading blades use transparent copies of their materials, listed in userData.materialVariants: a preparing renderer builds them on request, and the blades stay solid until they are built rather than stalling the frame the engine starts. Every other rotor (helicopter main and tail rotors, and fans a jet model binds as rotors) blurs between 35 and 78 rad/s instead: its blades fade into a faint disc with a slightly darker tip ring, sized from the model, and its hub stays solid.

For powered lift, declare spec.poweredLift with positive transitTime, controlFadeSpeed, pitchAuthority, rollAuthority, yawAuthority and damping, and mark the participating forward-facing engine installations vectored: true. aircraftInput.thrustVector is 0–1; aircraftState.thrustVectorPosition is its actual actuator position. The model signal thrustVector follows that position, so visuals and forces remain synchronized. Thrust rotates from local +Z to +Y; off-center engines generate moments. Hover controls require available engine thrust and fade with axial airspeed. spec.airplane.fixedGear keeps fixed undercarriage extended independently of the pilot's selection.

The deterministic airplane solver is a six-degree-of-freedom rigid body. The transform's quaternion is the attitude, with no pitch or bank stops, so loops, rolls, inverted flight and spins follow from the forces; aircraftState.yaw, pitch and roll report that attitude (roll is ±π inverted). Forces are lift, induced/profile/gear/flap drag, side force, propeller thrust or jet thrust and gravity at the center of mass, from wind-relative airflow and air density. Moments are angle-of-attack (pitch) and weathercock (yaw) stability, roll, pitch and yaw damping, dihedral effect, roll from yaw rate, inertia coupling, asymmetric thrust, and, scaled by propellerEffects, propeller torque, P-factor and slipstream yaw, and gyroscopic precession. The airframe turns about its center of mass in flight and about its wheels on the ground.

Stall depends on wing incidence, including camber, rather than a fixed true-airspeed cutoff. Separated flow progressively loses lift and control authority, adds drag, breaks the nose toward attached flow, and loses roll damping so yaw drops a wing. Lift remains perpendicular to airflow. Elevator and rudder retain limited propwash authority at low speed. Throttle controls shaft power for propellers and dry/reheat thrust for jets, with a transient RPM spool limit.

Propulsion, altitude and performance ​

All 54 shipped aircraft have separate performance profiles. engine.propulsion: 'propeller' uses shaft power, propeller efficiency and an altitude lapse, with ratedDensityRatio representing supercharging or flat rating. 'jet' uses dryThrust in newtons, density lapse and a Mach-dependent ram term. afterburnerThrust is total augmented thrust per engine. The last 15% of throttle commands reheat by default (afterburnerDetent: 0.85); it takes 0.6 seconds to light fully after the engine reaches operating RPM. Engine failure or cutoff extinguishes it. Ordinary turbofans and the Harrier have no afterburner. Omitting propulsion retains legacy constant-power behavior.

The atmosphere has standard temperature lapse layers, including the tropopause; sound speed therefore changes with altitude. Wind-relative TAS drives forces; equivalentAirspeed is TAS * sqrt(density / 1.225) and mach uses local sound speed. criticalMach and waveDrag add a continuous transonic drag rise. Ground effect reduces induced drag near the surface. maxMach, maxEquivalentAirspeed, gearLimitSpeed and flapLimitSpeed set overspeed alerts; they do not impose a velocity cap or silently break the airframe. Surface limits are EAS approximations, not exact POH calibrated-airspeed limits. Flap input can be a boolean or a fraction from 0 to 1, allowing intermediate settings through commands.

The F-14 profile has an empirical high-alpha departure model: directional stability fades, rudder/elevator authority is blanked, aileron response can reverse, and yaw autorotation can sustain a flat spin. A symmetric stall does not receive an arbitrary spin direction. The torque-free angular integrator preserves rotational energy through rapid rotations. NASA's F-14 model research, especially printed pages 126–127, supports these mechanisms; it does not supply a validated F-14D coefficient set. This model does not reproduce the F-14A's TF30 compressor stalls, the later digital flight-control system, or automatic variable wing sweep aerodynamics.

Helicopters keep an assisted collective and, unless direct cyclic is selected, an assisted cyclic. An actuator-disc power budget limits lift by installed shaft power, induced power, rotor profile losses and parasitic drag power; increasing payload cannot create extra engine power. Their calibrated parasitic drag, density-dependent lift, ground effect and translational lift are supplemented by optional vortex-ring lift loss in powered, slow descent and retreating-blade lift loss above an authored equivalent speed. These are qualitative approximations, not blade-element models. Powered-lift conversion has the separate limitations described above.

In forward flight the tail fin weathervanes the nose into the relative wind, so banking with the cyclic turns the nose along with the track rather than crabbing. The nose aligns at helicopter.directionalStability × airspeed / length rad/s per radian of sideslip (default 1; 0 turns it off). In a full-cyclic turn without pedal the OH-6's nose trails its track by about 4° at 25 m/s and about 1° at 50 m/s; right pedal coordinates the turn. The effect fades out below about a fifth of translationalLiftSpeed, where the tail sits in the rotor wake, so in a hover the pedals alone set the heading and a strong wind slowly turns the nose into it. Pedal authority does not change, so at cruise speed the pedals hold only a few degrees of sideslip against the fin: turn with the cyclic. Drag is the same in every direction, so a sideslip adds no side force.

Direct cyclic ​

aircraftInput.cyclicMode selects the helicopter cyclic. assisted (the default) commands a tilt of cyclicTilt × stick, bounded by maxTilt, that springs back to level, and keeps the attitude as Euler angles. direct commands body pitch and roll rates and integrates the attitude as a quaternion, as the airplanes do, so loops, rolls and vertical dives are possible:

  • Full stick gives helicopter.cyclicRate rad/s (default cyclicResponse / 4, 1 rad/s in the OH-6) with the rotor carrying the weight, reached with the rotor's damping (cyclicDamping). Released, the rates die out and the attitude holds. There is no self-levelling, speed stability or pitch weathervaning, so it flies as a rate-command, attitude-hold helicopter, not one that drifts by itself.
  • Control power scales with rotor thrust over weight, clamped to 0..1.5. The share set by helicopter.hubStiffness (0..1, default 0.25) comes from the blade hinges and remains at zero g; the rest fades as the rotor unloads. Mast bumping in a teetering rotor is not modelled.
  • The rotor's heave damping, vortex ring, autorotation and climb power act on the climb or descent through the disc, and translational lift, retreating-blade stall and parasite drag act on the flow across it. With the disc level these are the vertical and horizontal airspeed, exactly as in the assisted model; with the disc vertical in a dive, the whole descent runs across the disc. Rotor thrust cannot reverse, so an inverted rotor pushes toward the ground.
  • The tail-fin weathervane works in the fuselage's own frame, so a helicopter banked past 90° sideslips nose-first toward the ground. Pedals command a yaw rate the tail rotor reaches in about an eighth of a second.

On the skids both modes behave as assisted. Switching back to assisted in an unusual attitude does not snap: beyond maxTilt the limit lets the tilt shrink but not grow, and the cyclic's spring flies the helicopter back to level, rolling it upright from inverted in about a second and a half.

Autorotation ​

With its engine out in flight a helicopter's rotor freewheels, and its speed follows an energy balance instead of running down: the rotor holds helicopter.rotorInertiaTime seconds of hover power at full speed (default 2), spends it on the lift the collective asks for and on its own drag, and gets power back from the air it descends through. That rising air also meets the blades at a steeper angle, as more collective would (about a third of the lever at 10 m/s), so the collective goes down and the descent settles at a steady rate: the OH-6 comes down at about 10 m/s at 50 knots with the collective nearly closed and the rotor at full speed. Pulling the collective near the ground spends rotor speed on a cushion, a second or two of it; a heavy rotor (the UH-1H's 3.5 s) forgives a late or early pull, a light one (the R44's 1.6 s, the OH-6's 1.5 s) does not. Held too high, the collective drags the rotor down and the lift with it. Rotor speed never exceeds its governed value. On the ground the rotor runs down as before, and a restart in flight spools it back up. This needs powerLimitedRotor, which every shipped helicopter has. It is a momentum-theory approximation for learning the shape of the manoeuvre, not a blade-element model: there is no blade stall at low rotor speed and no height-velocity curve.

Headless fleet experiments ​

In the engine repository, build the packages before running the graphics-free harness:

sh
pnpm aircraft:bench --flight --check --out=.artifacts/aircraft-performance.json
pnpm aircraft:bench --id=f-14d --json

The harness uses the production kernel. It solves steady lift/thrust/drag balance, sweeps five altitudes, and runs three-minute controlled flights from 85% of each reference speed. It reports multiple equilibrium branches rather than assuming a supersonic branch can always be reached. The fleet unit suite also checks a withheld DA42 cruise point, F-22 dry supercruise, dirty configuration, hot air, uniform-wind invariance and timestep convergence. Kernel tests exercise spin symmetry, energy conservation, engine failures and reheat transients.

Reference conditions and provenance live in the performance ledger. Published cruise, maximum and operating speeds are different quantities. Where a source does not specify weight, altitude or throttle, the test condition is explicitly estimated. Some aircraft still have engineering-estimate anchors. Passing a fitted anchor establishes internal consistency, not independent real-world validation. All polar, lapse and high-alpha coefficients remain approximations. Stores, a center of gravity that moves as fuel burns, detailed engine maps, icing, fatigue, load-induced structural failures and certified flight-control laws are not modeled.

Fuel and weight ​

An aircraft with a spec.fuel block carries fuel: capacity is the usable load in kg, and spec.mass is the aircraft with full tanks. aircraftState.fuel starts full and burns with the power in use, the aircraft flies lighter as it goes (it climbs and turns a little better on empty tanks), and when the tanks are dry every engine stops: an airplane becomes a glider and a helicopter autorotates. A propeller or rotor engine burns by the shaft work it delivers (engine.fuelConsumption in kg per joule; default 7.5e-8 with a manual mixture, about 0.27 kg/kWh, and 9.5e-8 otherwise), a jet by its thrust (kg per newton-second; default 2e-5), and afterburnerFuelConsumption (default 5.4e-5, per newton of total thrust at full reheat) is why the afterburner is for moments: an F-16 that flies over half an hour at military power empties its tanks in about eight minutes with the burner lit. Engines never burn less than an idle flow. All 54 shipped aircraft carry fuel, sized by class as a share of their mass (13–17% for propeller aircraft, 22% for airliners and transports, 28% for fighters and small jets, 14% for helicopters): estimates, not flight-manual capacities. Recovering (R) starts a fresh aircraft with full tanks, and so does boarding one that is parked: the Earth view and the world explorer call refuelAircraft(world, id), which fills the tanks of an aircraft standing on the ground with its engines stopped. Without a fuel block, fuel is unlimited and the mass constant, as before.

aircraftFuelFlow(engine, engineState) from kernel/aircraft returns an engine's burn in kg/s for a fuel-flow gauge or a range estimate.

Flight assistance is limited to the pitch axis, so a keyboard can fly it. The stick moves an elevator (deflecting at pitchResponse per second and springing back four times faster) that adds up to pitchAuthority radians of angle of attack to a trim angle; the airframe's short-period dynamics (pitchFrequency, pitchDamping) fly toward it. Trim follows the angle of attack that keeps the flight path straight at autoTrim per second (0 leaves it fixed, like a real stick-fixed airplane), is captured at liftoff, and never exceeds the stall. Full stick stops at maxLoadFactor / minLoadFactor g at high speed. Ailerons command a roll rate (rollAuthority) against roll damping (rollResponse). The rudder is a yaw moment (rudderAuthority) against directionalStability and yawDamping; yaw damping acts on half the turn rate, so turns need little rudder while dihedral (dihedralEffect) still levels the wings slowly hands-off. Rates are given at controlAuthoritySpeed and scale with dynamic pressure.

On the ground a steerable tailwheel (groundSteerSpeed) and tire side grip (groundTrackRate) hold the rolling direction to the nose, sharing the load with the wing: as lift builds the tires let go, so crosswind weathervaning and propeller swing grow through the takeoff roll and drift persists after touchdown. The gear holds the wings level and the nose at its resting attitude until the elevator lifts it, up to maxGroundPitch.

Landing gear ​

The gear works by the weight on it. Wheel brakes (brakeDeceleration) and rolling drag scale with the share of the weight the wheels carry, from a fifth with the wing flying to all of it at a walk, so braking right after touchdown does little until the airplane has slowed, and braking tips it forward on its struts: a nosewheel airplane dips its nose, a taildragger lifts its tail. Struts and tires give back part of a firm touchdown: gearRebound (default 0.45) of the sink speed beyond a gentle 0.6 m/s, so a greased landing stays down and a firm one skips, further the more of its weight the wing still carries. airplane.tailwheel: true puts the main wheels ahead of the center of mass: touching down on them with the tail still up pitches the nose up, into more lift and a bigger bounce, where a nosewheel airplane pitches down onto its nose gear and stays. The Mustang, Beaver, Porter, Beech 18 and DC-3 are taildraggers. A sink rate beyond hardLandingSpeed is still damage, not a bounce. There are no individual struts or tires: the airframe does not sink on its gear, and there is no ground loop.

Buffet and the pilot under g ​

aircraftState.buffet (0–1) rises from 0.07 rad (4°) before the stall angle to 1 at the stall and stays there in separated flow, scaled down where the air is too slow to shake anything. It is a cue, not a force: the flight path is unchanged. aircraftCameraPose takes shake: { amount, time } and shakes the seated view by it (the Earth view and the world explorer pass the buffet), and the world explorer's HUD warns.

aircraftState.greyout and redout (0–1) are the pilot's accumulated strain. Above airplane.pilotGTolerance (default 4.5 g, or 6.5 g where maxLoadFactor is 7.5 or more: a g-suit), greyout builds at a twentieth of the excess g per second, so 9 g in a fighter dims the view after about three seconds and takes it away in eight; a g below the tolerance and it recovers in four. Below -1.5 g, redout builds a sixth of the excess per second. The controls keep working throughout: this is what the pilot sees, for a host to draw (the world explorer narrows the view to a tunnel, then darkens it, and tints it red), not a loss of consciousness. view.vehicleStatus() reports buffet, greyout, redout, and fuel with fuelCapacity.

The pilot's body in the seat ​

PilotMotion from @bendyline/molen-client/aircraft moves the cockpit camera the way a load moves someone strapped into the seat. Like the buffet shake it is a cue for the view: it reads the aircraft's motion and never changes the flight.

  • Heave. In a pull the eye sinks into the seat and the chin drops; unloaded, the pilot floats up against the straps.
  • Surge. Thrust presses the pilot into the seat back; braking throws them forward onto the straps and nods the head.
  • Sway. A skid, or a turn on the ground, throws them to the outside and tilts the head with the body.
  • Lag. The head is left behind for a moment when a roll, pitch or yaw starts quickly.
  • Horizon lean. In a bank the head tilts toward the horizon, as pilots do.
  • Bracing. The body gives way when a load arrives, then the pilot recovers part of the travel over about a second, and is left leaning the other way for a moment when the load comes off.

What the pilot feels is the specific force in the seat's own axes: the aircraft's acceleration less gravity, which is 1 g straight up through the seat when parked or in level flight. The model takes it from the change in the aircraft's velocity between simulation ticks, so it works for every airplane and helicopter, on the ground and in the air, with no change to the flight model. The body is three damped springs driven by how far that load is from 1 g up, and the head three more. It runs in simulation time: a paused world holds the pilot still.

ts
import {
  aircraftCameraPose,
  PilotMotion,
  pilotMotionSample,
} from '@bendyline/molen-client/aircraft';

const pilot = new PilotMotion();

// Each frame, with the flown aircraft's transform and aircraftState:
const motion = pilot.update(pilotMotionSample(world.tick * world.dt, transform, state));
const pose = aircraftCameraPose(transform, spec, { view: 'cockpit', motion });

Call update in every view, so the body is already settled when the cockpit view returns, and reset() when the pilot changes aircraft. A teleport or a respawn is recognized (the aircraft moved farther than its speed carries it) and starts the pilot settled in the seat; an impact is felt as a jolt. Chase views ignore motion. pilot.load is the load last felt, in g, as [left, up, forward], for a HUD.

The defaults are sized to be felt more than seen. Flown through the flight model: a 6 g pull in the P-51D lowers the eye 3 cm, presses it a centimeter back and drops the chin 1.5°; full brakes throw the pilot nearly 3 cm forward, half of which they recover as they brace; a 60° bank tilts the head 3°. pilot.tuning holds every number and is live, so a host can adjust it while flying:

TuningDefaultMeaning
enabledtrueThe switch: off, the eye stays at the authored pilotEye.
intensity1Scales every displacement and rotation before its limit.
maxLoad12Loads beyond this many g on an axis are clipped: an impact jolts, it does not launch.
braceTime1.2Seconds the pilot takes to brace against a sustained load.
heave, surge, swayOne body axis each: travel (meters per g), limit (meters, [negative, positive], approached softly), frequency (Hz), damping (ratio) and brace (share of a sustained load recovered, 0–1).
head.nod0.006Chin drop per g above 1, radians.
head.surgeNod0.04Chin drop per g of deceleration, radians. Pressed back, the head meets the headrest.
head.swayTilt0.05Head roll per g of sideways load, radians.
head.lag0.004Radians of lag per rad/s² of airframe angular acceleration.
head.horizonLean0.12Radians of tilt per radian of bank at small angles; it peaks at 45° and is gone at knife-edge and inverted.
head.limit0.1Largest head rotation about one axis, radians, approached softly.
head.neck0.12Height of the eyes above the neck's pivot, meters: a tilted head also moves the eye.
head.frequency, head.damping2.4, 0.6The head's spring.

new PilotMotion(false) or pilot.configure(false) switches the whole effect off; pilot.configure({ heave: { travel: 0.012 } }) changes the fields it names. In an Earth view the effect is on by default: mount with pilotMotion: false (or a partial tuning), and call view.setPilotMotion(...) to change it while flying. World Explorer has a "Pilot feels g" checkbox; ?pilotMotion=0 starts with it off and ?pilotMotion=3 exaggerates it threefold to show what moves.

NOTE

An Earth view's cockpit camera keeps a level horizon, so the head's roll (the horizon lean and the lag of a roll) does not show there; the eye's travel and the nod do. Hosts that apply the pose's rotation, as World Explorer does, show all of it.

The gear and flaps travel rather than switch. aircraftInput.gear and flaps select a position, and aircraftState.gearPosition and flapPosition (0 up, 1 down) move toward it over airplane.gearTransitTime seconds for a full gear cycle, doors included, and flapTransitTime for full flap travel. Gear drag, flap lift and flap drag scale with the positions. A weight-on-wheels lock holds the gear still on the ground, so selecting it up before takeoff raises it once the wheels leave the runway. Touching down before the gear locks down is a belly landing, which counts as a crash. Both times default to 0, which switches instantly as before, and a state without positions starts at the selection.

Each engine's propellerRotation (default clockwise seen from the cockpit, the left-turning case) and propellerInertia set the direction and size of the propeller effects; airplane.propellerEffects scales them from 0 (none, the default) to 1. The shipped Mustang uses 0.2, enough to feel on the takeoff roll and at climb power; raise it toward 1 for the full handful. rollInertia, pitchInertia and yawInertia set the moments of inertia. airplane.stallTransitionAngle sets the separation transition width (radians, default 0.12). stallDrag is the broadside separated-flow coefficient, scaled by separation and sin(alpha)^2. The legacy stallSpeed tuning reference no longer triggers aerodynamic stall. Wing position remains metadata rather than a distributed lift model.

levelFlightAngleOfAttack(spec, airspeed, density?) returns the angle of attack that carries an airplane's weight. Start an airplane in flight with that as its pitch and pitchTrim (the Earth view's airborne launch does) and it holds level flight hands-off.

Wind and turbulence ​

Aircraft feel the weather's wind field, not only its mean windVelocity: a shear profile with height above ground, turbulence carried downwind, gusts along the wind, and slope flow that lifts air up windward hillsides and sinks it, rougher, in the lee (see Weather). The airplane samples it at its center of mass and both wingtips, so uneven gusts across the span roll it; the helicopter samples across its rotor disc. The field is a function of the weather, the position and simulation time, so replays and keyframes reproduce every bump. installAircraft hands the solver the world clock; callers of stepAircraft pass time in the environment. An explicit uniform wind override turns the structure off.

In an Earth view ​

mountEarthView flies the same aircraft without a practice airfield: view.setMode('fly') puts the viewer in a P-51D already airborne over the current view, and { aircraft: 'molen.entities.aircraft.oh6' } picks the helicopter. view.vehicleStatus() reports airspeed, altitude, vertical speed, attitude, power and engine/gear/flap state for a HUD, and view.recover() restarts the flight above an impact. See Earth view. Hosts composing their own view use EarthAircraft from @bendyline/molen-earth/client: it spawns any aircraft type into the vehicles' ECS world, on the ground or with airborne: { speed, power }, boards and releases the pilot, applies EarthPilotControls and draws the models. To start from a real runway, ask view.airfields for one and spawn at its threshold placement; see Airfields.

Engine sound ​

The P-51D carries an audioSource that plays aircraft.engine.piston, a Rolls-Royce Merlin recording. The OH-6 plays aircraft.engine.helicopter. Both take pitch and gain from aircraftState.rpm: they are silent until I starts the engine, and spool up and down with it. The OH-6 also leans a little on aircraftInput.power, since its governed rotor holds rpm while the collective changes load. Any host that plays audio from the entity world hears them with no extra code; see Sound and music.

Multiple engines and engine failures ​

An airplane can keep the existing spec.engine (implicitly named main), or replace it with a nonempty spec.engines array. Supply exactly one form. Every engine has a unique id, local position, thrustAxis, shaft power in watts, and its own RPM/spool configuration. Power and thrust limits are per engine; splitting one engine into two without changing total power or static thrust means halving each engine's power and thrust cap. Optional engine propellerEfficiency, maxThrust and minPropellerSpeed override the shared airplane values.

For example, derive a synthetic twin from an existing single-engine airplane spec:

ts
const { engine, ...airframe } = singleEngineSpec;
if (!engine || !airframe.airplane) throw new Error('Expected a single-engine airplane');
const twinSpec = {
  ...airframe,
  engines: [
    { ...engine, id: 'left', position: [2.5, 1, 1], power: engine.power / 2,
      maxThrust: airframe.airplane.maxThrust / 2 },
    { ...engine, id: 'right', position: [-2.5, 1, 1], power: engine.power / 2,
      maxThrust: airframe.airplane.maxThrust / 2 },
  ],
  visual: {
    ...airframe.visual,
    rotors: [
      { node: 'left-propeller', engine: 'left', axis: 'z', multiplier: 1 },
      { node: 'right-propeller', engine: 'right', axis: 'z', multiplier: 1 },
    ],
  },
};

Positions are meters from the aircraft's landing-contact origin, with +Z forward, +Y up and +X to the pilot's left. The solver sums each engine's force and computes its yaw moment from (position - centerOfMass) × thrust. A failed left engine therefore leaves the right engine yawing the nose left. Rudder can counter the yaw; cutting the remaining engine removes the powered asymmetry. Greater lateral separation produces a larger moment. airplane.yawInertia sets yaw inertia in kg m² (default mass * (span² + length²) / 12). The thrust moment joins the airframe's other yaw moments in aircraftState.yawRate, against weathercock stability and yaw damping in the air and tire grip on the ground.

The normal throttle and engine switch still control the whole bank. Optional aircraftInput.engines entries override individual throttles or switches; omitted fields inherit the common controls. The common engine: false always shuts every engine down. In a host setup:

js
import { flyAircraft, setAircraftEngineFailed } from '@bendyline/molen-kernel/aircraft';

flyAircraft(world, 'pilot', {
  power: 0.8, engine: true, pitch: 0, roll: 0, yaw: 0,
  gear: false, flaps: false, brake: false,
  engines: { left: { power: 0.6 }, right: { enabled: true } },
});
setAircraftEngineFailed(world, 'twin', 'left');        // latch a failure
setAircraftEngineFailed(world, 'twin', 'left', false); // explicit repair

setAircraftEngineFailed returns false for an unknown aircraft or engine. A failure immediately removes powered thrust and lets that propeller spool down; pilot throttle/switch input cannot repair it. Failure triggers belong to the experience (for example a damage or training command). The world explorer supplies common and individual engine controls; failure scenarios are authored through this API, without automatic random failures.

aircraftState.engines[id] stores rpm, rotorAngle, failed and current thrust in newtons. The solver initializes missing engine state from the legacy RPM/phase, then the per-engine state is authoritative. The aggregate rpm is the maximum across engines, and aggregate rotorAngle follows the first engine. Set visual.rotors[].engine to animate independent propellers; omitted bindings retain the common phase. Body rates, trim, all engine state and input overrides survive keyframes/replay and pause at terrain gaps. Boarding and exit checks consider every engine.

This extension models thrust imbalance and, for vectored engines, pitch and roll moments from the thrust line. Feathering, windmilling drag and a calibrated minimum-control-speed envelope are not included; propeller torque, P-factor and precession come from propellerEffects above. Helicopters continue to use one engine driving the shared rotor; multiple turbines feeding a common gearbox require a different shaft-power model and are not represented by independent propeller engines.

Helicopter forces include rotor spool, collective lift, cyclic tilt, ground effect, translational lift, air drag and assisted yaw; the helicopter keeps the assisted model, in which cyclic commands a disc tilt bounded by maxTilt, and gusts across the disc tip it. State includes velocity, attitude/rates, rotor phase and controls for checkpoint/replay. Translational lift uses air-relative horizontal speed, so wind and forward motion give consistent results. Collision sampling is at least 120 Hz and at most one meter of translation per substep. Unknown terrain pauses at the last known position and resumes when support is available.

Hosts can supply groundHeight, wind and contacts(probes, entity) (or the legacy canOccupy(transform, spec, entity)). The world view checks nearby resident geometry, the airfield, cars and other aircraft. Cars and exits also check conservative aircraft bounds. Imported collision hulls are available for hosts that need a different collision solver. Without either obstacle callback, the kernel only collides with terrain. Do not add a second physics body that also writes the aircraft transform.

This is a game flight model with recognizable polygonal aircraft, not a full aircraft systems simulation or a calibrated replica of any airplane's handling. Rotor blade-element aerodynamics, a quantitatively validated spin model, fuel tanks and their selection, a moving center of gravity, automatic engine damage, detailed avionics and weapons are outside this implementation. Primary cockpit controls operate the simulated systems as described below; switches for unsupported systems remain decorative. Collision uses coarse airframe probes and resident world geometry; it does not model deformation or distant unloaded obstacles.

Clickable cockpits ​

Earth views and the world explorer enable pointer controls while occupying the cockpit. Drag a yoke or cyclic sideways to bank and down to pull up; release it to center. Pedals drag sideways and also center on release. Drag a throttle or collective upward to increase its retained setting. Modeled gear selectors toggle on click; flap and thrust-vector levers accept intermediate positions. Solid panel geometry blocks clicks behind it. Dragging empty space still looks around.

All 54 bundled cockpits have physical controls for their supported systems, including engine master switches, individual engine switches and throttles for airplanes with named engine banks, parking brakes, and applicable gear, flap and nozzle controls. Supplemental labeled modules fill gaps in the original models; their layout approximates the aircraft rather than reproducing every real switch. The Cessna 172's existing master rocker and flap selector are directly operable. Moving common power (including =/− or the modeled PWR ALL handle) synchronizes all throttle levers while preserving individual engine cutoffs, mixtures and propeller settings. A throttle indicates commanded power; shaft RPM follows the simulation's spool response. Retractable airplane gear is locked on the ground. Helicopters retain the existing shared engine/gearbox model and collective. Manual-mixture aircraft have operable mixture controls, and aircraft with manual propeller governors have operable propeller RPM controls. Fuel selectors, avionics and other unmodeled systems remain decorative.

Mixture and propeller governors ​

AircraftInputData.mixture and .propeller are retained 0–1 selections, both defaulting to 1. The same fields in engines[id] override the common selections independently. A common adjustment synchronizes only its own control, preserving throttle, cutoff and the other engine settings. Drag the modeled mixture or propeller lever upward to increase its setting.

An engine with mixtureControl: true uses a reduced fuel/air model: 0 cuts fuel immediately; 1 is full rich. At reduced intake-air density a lower setting can recover power, while excessive leaning or enrichment reduces combustion, thrust and available shaft power. The existing ratedDensityRatio approximates boosted intake air before leaning becomes necessary. Mixture cutoff spools the engine down without latching a failure; restoring mixture can restart it when the engine master is on. This assisted restart does not model a starter or ignition sequence.

propellerControl: { minRpm: 0.6 } enables a constant-speed governor: the lever selects between 60% and 100% of rated RPM. It does not directly set blade angle. At sufficient power the governor holds selected RPM; at low power the fine-pitch stop permits RPM to fall. Reduced selected RPM limits shaft power in the torque-limited approximation and lowers the static thrust cap. RPM, propeller rotation, torque and thrust all follow these inputs. This follows the distinction between throttle, mixture and governed RPM in the FAA engine-controls overview.

These are estimated simulation curves, not aircraft performance tables or operating procedures. There is no EGT/CHT, detonation, feathering, reverse thrust or blade-element model, and leaning does not change the fuel burn. Fixed-pitch Cessna 172S and Cherokee aircraft expose mixture without a propeller lever; the DA42 and PC-12 NGX retain automatic scheduling. Turboprops have no piston mixture. Combined condition levers used for propeller RPM currently cover the governed range; engine cutoff remains a separate switch. The R44's mixture affects the shared piston/rotor power model without adding a propeller control.

Per-engine aircraftState.engines[id].combustion reports effectiveness (0–1), and shaftPower reports delivered watts. Model signals expose these as engines.<id>.combustion and .shaftPowerW; .mixture and .propeller are commanded lever positions. The live cockpit review shows these settings alongside RPM and shaft power so cutoff and independent engine effects are visible.

Hosts pass the camera to visual.updateView(camera) each frame (in the coordinates of visual.object.position). The cabin, the interior's nodes, is drawn only within three times the aircraft's length or span of it (at least 60 m): cockpits held most of an aircraft's draw calls and as many again in the shadow pass, yet from farther away they are a few pixels behind the canopy. Boarded and chase views are always near enough, but within the cabin a part too small to see from the camera (an angular radius under 0.002 rad, a few pixels at 1080p) leaves the frame: from a chase camera a P-51's 415 cockpit meshes were a quarter of a takeoff's draws. That culling uses the part's render layers, so the visible that bindings and damage set is never overridden. A flight-controls group (the generated cockpit controls) counts as cabin too. Earth views and the world explorer also prepare an aircraft's shaders before its model joins the scene.

Double-sided transparent materials (canopies, windscreens, instrument covers) draw in one pass: three otherwise draws each such pane twice and builds a program before each face, every frame. Glass casts no sun shadow: a mesh whose materials all blend at less than full opacity, or whose name contains canopy or bubble. Three's shadow pass draws a pane as solid, so a windscreen shaded its whole cockpit.

For the aircraft a view follows (flown or watched), hosts also pass renderer.shadowTexelSize to visual.updateShadows(texel) each frame, and undefined for every other aircraft. Over a wide view the sun's shadow map coarsens (on High, 0.2 m texels 100 m above the ground, 1.6 m in cruise at 2,500 ft). It then cannot resolve the aircraft's own canopy frame and seat, and their shadows on the cockpit jumped from frame to frame as the aircraft crossed the map's texel grid. Coarser than 0.15 m, the aircraft casts no sun shadow; at 0.12 m or finer it casts again. It still receives shadows from terrain, buildings and clouds. The Earth view and the world explorer do this for the mounted aircraft.

createAircraftVisual exposes cockpit, a mesh picker and control inventory derived from the interior's authored primary-input bindings and glTF node extras.aircraftControl metadata. An AircraftControlNode declares a supported action, optional engine ID, and optional rest-relative motion (property, axis, scale, optional offset). Switches and selectors animate their commands; gear, flaps and engine RPM still follow the simulation's transit/spool response. Separate throttle levers are associated with engine positions from pilot-left to pilot-right; duplicated collective/thrust levers remain linked. bindAircraftCockpitPointer from @bendyline/molen-client/aircraft binds a canvas, camera and active pilot session. The HTML companion panel is opt-in with companionPanel: true, for accessibility or older models with incomplete geometry. Call its update() each frame and dispose() on teardown. Hosts apply changes with applyAircraftControl, submit the result through flyAircraft, and mix AircraftPointerAxes with their keyboard/gamepad inputs. Session release must clear transient axes. The binder cancels drags on exit, view change, blur and pointer cancellation; it does not write simulation components directly.

In the engine repository, build the client and kernel, then run a local live review of all 54 bundled aircraft:

sh
pnpm --filter @bendyline/molen-examples-world-explorer exec vite --config ../../packages/entities/scripts/cockpit-controls-vite.mjs

Open http://127.0.0.1:4322/packages/entities/scripts/cockpit-controls.html. The review runs the real aircraft solver, displays commanded power beside actual RPM, and offers parked, airborne and exterior views.

Reproducible review ​

The source brief, generator, provenance and verification notes are in the engine repository, in the copyable P-51 source bundle and OH-6 source bundle. content/entities/scenes/aircraft.scene.json there is the neutral apron scene. The browser flight scenario is examples/world-explorer/test/visual/aircraft.play.json.

packages/kernel/test/aircraft-performance.test.ts exercises level acceleration, part-throttle power, configuration drag, stall recovery from either bank direction, coordinated turns, unpowered energy loss, wind equivalence and 30/60/120 Hz consistency. packages/kernel/test/aircraft-dynamics.test.ts covers full rolls, loops and the load-factor limit, flight-path hold, trimmed launches, propeller swing and crosswind on the takeoff roll, and turbulence that matches across host rates and keyframes. Current fleet calibration targets and their evidence are recorded in the performance ledger above. The test pilot's altitude hold is a harness feature, not a player control or a certified performance chart.

packages/kernel/test/aircraft-engines.test.ts covers symmetric two/four-engine layouts, mirrored engine failures, counter-rudder, thrust moment arms, independent switches/spool, explicit repair, terrain rollback, exit safety, keyframe restoration and 30/60/120 Hz consistency.

Exterior mechanisms use the snapshot-owned graduated actuator system. Canopies, hooks and speed brakes accept fractional targets through aircraftInput.actuators; aircraftState.actuators holds actual travel. Ordinary mechanisms reverse immediately from their current position. Speed-brake drag follows deployment. Retractable helicopter gear uses helicopter.fixedGear: false and gearTransitTime; skids remain fixed by default. The supplied aircraft expose only fitted equipment. Helicopter blade release is a gameplay escape effect, triggered by the latched eject actuator, and removes rotor lift after release.

50 guides · 44 schema formats · 51 API entry points · 11 samples. API, CLI and schema pages are generated from the shipped build.