flight3dplugin

A fixed-wing aeroplane as forces and moments, with a stalling lift polar, drawn from its model.

#Putting it in a scene

List it after loader and before render3d. The scene's sim lists the flight3d kind from #plugins/flight3d/flight3d.sim.ts, and every plane is one flight3d row. The browser half draws every row of the kinds listed, from the loader model its plane names. A child scene inherits world.flight3d from the manager scene.

"world": {
  "loader": { "assets": { "camel": { "type": "model", "url": "/games/mygame/assets/camel.glb", "preload": true } } },
  "flight3d": {
    "gravity": 9.81,
    "air": { "density": 1.225, "scaleHeight": 8500, "calm": 1 },
    "materials": { "engineDensity": 40, "wingDensity": 8, "structureDrag": 0.002 },
    "planes": {
      "camel": {
        "airframe": {…},
        "gear": { "wheels": [{ "at": [-0.8, -1.1, -0.3], "radius": 0.35, "spring": 60000, "damper": 4000, "roll": 0.03, "grip": 0.9, "brake": true, "steer": 0 }],
                  "brakeGrip": 0.5, "sink": 4, "touch": [[0, 1.2, 0.4]], "retract": 0, "drag": 0.1 },
        "look": { "model": "camel", "spin": 120, "airbrake": 0.6, "gear": 1.2 }
      }
    },
    "overspeed": 1.2,
    "sweep": 5,
    "mods": { "ground": "terrain3d" }
  }
},
"prefabs": {
  "flight3d": { "type": "camel", "pos": [0, 300, 0], "rot": [0, 0, 0, 1], "vel": [0, 0, -40], "spin": [0, 0, 0],
                "pitch": 0, "roll": 0, "yaw": 0, "throttle": 0.6, "throttling": 0, "airbrake": 0, "brake": 0, "gear": 1, "gearDown": true }
}

World space is x and z across the ground and y up, in metres. The plane's body frame has +X along the right wing, +Y up and −Z along the nose.

#Properties

Read from world.flight3d.

.gravity : number

m/s², downward.

.air : { density, scaleHeight, calm }

density is kg/m³ at y = 0. scaleHeight is metres: the density at height y is density · exp(−y / scaleHeight). calm is the speed in m/s below which there is no relative wind to fly on.

.materials : { engineDensity, wingDensity, structureDrag }

What an airframe's mass is priced from. engineDensity is newtons of thrust per kg of engine, wingDensity is kg per m² of wing, and structureDrag is m² of drag area per kg of structure. A plane's mass is structureMass + maxThrust / engineDensity + wingArea · wingDensity, and its structure casts a drag area of structureMass · structureDrag, so structure is never free.

.planes : { [name]: { airframe, gear, look } }

The planes there are, by name. airframe is the sheet, what was bought, with no mass on it, since the mass is the parts'. gear is its wheels and what else of it may touch the ground. look says how the page draws it.

.overspeed : number

The cap on speed, as a multiple of the sheet's top speed at y = 0. A dive rides the cap, with the direction untouched, instead of chattering on it.

.sweep : number

Metres. The path a step flies is checked against the ground this often along it, so a plane at 300 m/s cannot pass through a ridge between two steps.

.mods : { ground }

The plugin that provides the ground (see Mods).

.kinds : string[]

The kinds whose rows are planes. ["flight3d"] when left out. A game whose seat flies its own player row lists player here, and that kind's rule flies the row with step, so a page that runs the scene ahead draws the seat's plane from its copy.

The airframe sheet

Every key is required. Angles are radians. Stability derivatives are written in the aviation frame, x forward, y right, z down, with rates p (roll right), q (nose up) and r (nose right), and keep a textbook's signs.

gear

Only gear locked down (gear 1) has wheels. Below that the plane meets the ground on its touch points, and a landing with the gear up is a crash. A plane also crashes when a wheel is pressed in past its radius, and when the path its centre flies in a step meets the ground. A crashed plane lies where it hit.

look

The model is in the body frame, with a node for each moving part on its hinge, its local axes turned so the hinge is the axis it turns about. Each frame every part is turned from its pose in the model by the angle on the row. Every mesh casts and takes shadows, with its material dressed by render3d.

The row

A rule writes type when it makes the plane, and the stick, throttling, airbrake, brake and gearDown. The plugin writes the rest. How fast the plane flies, its angle of attack, its sideslip and how stalled it is are not on the row. They follow from vel and rot, and windAngles and aero hand them to whatever shows them.

#Methods

From #plugins/flight3d/flight3d.sim.ts. f is world.flight3d. A Quat is [x, y, z, w] and a Vec3 is [x, y, z].

step( p, f, dt, ground? ) : Aero

Steps a plane's row p once, in place, over ground, a function (x, z) => height. With none, the plane has nothing to touch or hit. The surfaces move toward the stick, the lever moves, the forces and moments of the air, the engine and the gear are worked out, the angular velocity and then the attitude are stepped, and then the velocity and then the position, semi-implicitly, which keeps a circling turn from spiralling out at a fixed step. Returns the flight picture of the step.

aero( p, stick, f, airframe, dt ) : Aero

The whole flight picture for one step, without stepping anything, so that a HUD, a panel or a test can read it. stick is { pitch, roll, yaw, airbrake }. airframe is a priced sheet. It returns aoa, slip, speed, qd (dynamic pressure), cl, cd, lift, drag, side, thrust and weight (newtons), stall (0 attached, 1 fully separated), surfaces ({ aileron, elevator, rudder } after moving toward the stick), force (world, newtons) and torque (body, N·m).

windAngles( p, air ) : { aoa, slip, speed }

Speed in m/s, angle of attack in radians (air from below is positive) and sideslip in radians (velocity to the right is positive), from the plane's vel and rot. Below the calm speed both angles are 0.

price( sheet, materials ) : Airframe

A sheet priced: the sheet plus its mass and structureDragArea, both derived. airframeOf(f, type) is plane type's airframe, priced, and modelOf(f, type) is its catalogue entry. massOf(sheet, materials) and dragShadowOf(sheet, materials) are the two numbers alone.

topSpeed( airframe, rho ) : number

The top speed in m/s where full thrust meets parasite drag at density rho. For a jet it is √(thrust / k), and for a propeller past propSpeed it is ∛(thrust · propSpeed / k), where k is half the density times the total parasite drag area, wingArea · cd0 plus the structure's.

stallSpeed( airframe, gravity, rho ) : number

The speed in m/s below which the wing cannot hold the plane up in level flight at density rho.

thrustOf( sheet, throttle, rho, rho0, speed ) : number

Thrust in newtons at a lever, an air density (of rho0 at y = 0) and a speed.

densityAt( air, y ) : number

The air's density at height y.

contact( p, gear, ground ) : { force, torque, press, crash }

What the ground does to a plane on its gear this step: the force (world) and moment (body) of every wheel pressed into it, how far each is pressed, and whether it has crashed. It steps nothing.

impact( ground, a, b, sweep ) : Vec3 | undefined

Where the path from a to b first meets the ground, checked every sweep metres along it and at its end, or undefined when it stays above.

normalOf( ground, x, z ) : Vec3

The ground's unit normal under x, z, its slope read off ground itself 0.5 m either side.

groundOf( w ) : ((x, z) => number) | undefined

The scene's ground, off its ground mod, as a height under x, z. Undefined when the scene names none.

rotate( q, v ) / unrotate( q, v ) : Vec3

A vector turned by the attitude q, body to world, and a world vector in the body frame.

fromHeading( heading ) / fromAttitude( heading, pitch ) : Quat

Attitudes for placing a plane. fromHeading is wings level with the nose heading radians clockwise from −Z seen from above. fromAttitude also puts the nose pitch radians up from level.

noseOf( heading ) : Vec3

The nose's direction for a heading, as fromHeading turns it.

#Mods

Name them in world.flight3d.mods.

• terrain3d
  ground: ground(w, x, z) hands back the height of the ground under a world x, z. With no ground mod the plane flies over nothing, never touches down and never crashes.

#In the guide