Documentation / Cheatsheet

Cheatsheet

Everything on one page, for a reader who has already read the rest. No teaching, no explanation: the keys, the options, the elements, and the calls.

Keys

Without a keyboard

Drawn on a machine that takes touches and has no pointer that can hover: a phone or a tablet, never a laptop with a touchscreen. Menus were always worked by pointer, so only the flight controls are added.

Tilt is what those machines open in, and it takes the four attitude pads off the glass. FLY BY TILT in the control settings overrules that either way, so a tablet with a keyboard can ask for the device and a phone can ask to be left alone. Whatever angle the device is held at when a flight starts is level for it, and a reset levels it again. Seven degrees either side of level is nothing, and TILT DEADZONE offers two positions either side of those seven. Refused, or on a device with no gyroscope, the pads stay and the flight is flown from them: a sensor that reports no angles at all is no reading rather than a device held level. The pads take the bottom corners, so the attitude indicator moves to the top left of the screen, the readouts drop below it and the chart it now shares that top with, and the control list comes off.

A pad is 44 pixels square, which is both the smallest a control under a thumb should be and what lets two clusters and the padding either side of them fit the 320 pixel screen a phone is narrowest at.

The pads take a fixed band off the bottom whatever the screen, so a short one has less left between them and the instruments above. Below 541 pixels of height - which is every phone held sideways - the readouts are drawn compact and drop THROTTLE and CAMERA, the two you are not flying on - and on a screen 640 pixels or narrower that starts at 657 instead, because a narrow one has the objective card under the readouts as well as the pads under both. Shorter again and they move into the band between the two clusters of pads, with the AUDIO MUTED line going up beside the attitude indicator rather than staying under it. The objective card, which is what carries the breakdown of a landing, is lifted clear of the pads on any screen narrow enough for them to cross it; on a screen short and wide enough for the readouts to be in that middle band it is hung from the top of the same lane instead, because the band is where the readouts now are. The two are placed against each other rather than each against the pads, so neither is drawn over the other at any size a phone comes in.

Bounded to the room the readouts leave, the card holds what it says in flight and not a landing read off it, which is five lines more. So the readouts stand down for as long as a breakdown is up and the card takes the column - on the screens the two are in one column on. An aircraft stopped on a strip reads zero knots, zero feet a minute and the strip's own elevation, which is everything the breakdown says and nothing it does not, so of the two wanting that column it is the stack that gives way. From 680 pixels of width, on a screen tall enough to keep the readouts in their own corner, the card's left edge is past their right edge and the two never meet, so there the stack stays up and the card is bounded to the screen rather than to anything above it. A screen short enough to have put the readouts in the middle lane is the exception at any width, because the card is hung in that same lane and the two are back in one column.

On the shortest screen a browser leaves, 320 by 460, there are 108 pixels between the chart and the pads for both of them, so the stack keeps the airspeed and the altitude and the card keeps its stage and its objective. What the card has no room for comes off rather than being cut through: the bound is written in the card's own rows, so every line on it is either read whole or not drawn at all.

Flight numbers

The start state

Radio group: START OFF FLYING (default) or RUNWAY TAKEOFF. Checkbox: RUNWAY, forced on and disabled under RUNWAY TAKEOFF. Pitch is derived, never set.

Every row in the table above but START CAMERA can be typed into as well as stepped: a digit starts the figure, Enter takes it, Backspace erases a character, and Esc, the mouse, walking the cursor to another row, or stepping the row with A/D gives up. The figure goes through the validator the stepping goes through, so one between two steps is refused and the row says what is allowed - 0 KTS TO 200 KTS BY 5. A character the figure has no room for is turned down and leaves what is typed where it is. A row that steps through a list holds no figure to type, which is why the view is the one left out.

Options

Everything above is stored in localStorage and reopens with the next session.

Control settings

The CONTROL SETTINGS entry, on the start screen and in the pause menu. Stored under a key of its own, so how a pilot flies outlives which world they flew.

DIRECTIONAL points the key where the aircraft goes; INVERTED points it where a stick would. Each axis is set on its own, and both spellings of an input turn over together. TILT READS AXES carries those two settings through to a device flown by tilting it; off, the device is the aircraft. FLY BY TILT says which machines are flown by tilt at all - WITH NO KEYS is the machine's own answer and the two others overrule it, and what the row holds is what was asked for rather than what the sensor granted. TILT DEADZONE is how far the device is turned before it asks for anything. FULL ROTATION off clamps the nose short of the vertical and the wings at half a turn; on, either angle crosses the limit and comes round the other side, so a loop and a barrel roll carry on.

A key row waits for a key once it is chosen. A key another row holds is refused and the row says which row holds it; a key the game reads for itself is refused the same way and the row says what the key already does, as P IS PAUSE; Esc is the way out of the wait; Delete leaves RESET FLIGHT on no key at all, which is the only row allowed to be on none. The map is stored under a key of its own, and the reference list is written from it. Control settings is the page.

Worlds

Five more are built for the modes and kept out of the panel: OPEN COUNTRY, LOOP VALLEY, BACK COUNTRY, CANYON REACH and SURVEY COUNTRY.

Under the worlds, LOAD ENVIRONMENT… opens a saved environment file, whose world joins the list under its own name and is flown, and SAVE ENVIRONMENT… writes the world as it would be flown to <name>.pilot-matter.json. A refused file says why and changes nothing. The browser keeps the last world loaded across a reload. Neither row is offered while a game mode runs.

Elements

Pipeline order: landforms, ground cover, water, cuts and built things, snow, runway last.

Builder canvas

A canvas carries the tools that work down the left and its own control list in the corner. ACCEPT AND EXIT and Esc are the one way out, back to whichever menu opened the builder, and both ask first; Backspace leaves the picker but not a canvas. Once a build has been kept, L opens straight onto it with no picker; choosing another world in the settings lets go of it, and the picker is back.

The control list

What a canvas's own list reads, in its corner, line by line - the tool a line is for in brackets.

Down the right is the dock: SELECTION MODE, the camera written out as fields to read and type into, or the edit in hand with ACCEPT and CANCEL under it. Only its fields scroll, and the wheel over it scrolls them. A figure's field has its own up and down inside it, a press each - a tenth for a fraction from 0 to 1, a fiftieth of the range otherwise - and ten with Shift; ↑/↓ in the field do the same, and Page Up/Page Down are always ten. A switch or a choice keeps its ‹ ›, and a click on its reading steps it on, round to the first. In Select the camera stays on top: beneath it is the placement picked, under SELECTED and its name, or with nothing picked each of the world's own elements under WORLD:, folded until its heading is pressed. A value changed there changes every one of that element across the world, and YES on leaving keeps it.

The two questions open on YES; the arrows cross to NO and CANCEL, and CANCEL, Esc or a press off the panel calls the question off with nothing changed - the edit still in hand, the tool still the one it was, the canvas still open. YES on ACCEPT EDITS keeps the edit and stays, so keeping work never doubles as leaving; YES on SAVE AND EXIT MODE keeps what was built as the world flown and leaves. Choosing another tool with an edit in hand asks ACCEPT EDITS first.

In Select, the placement under the pointer is outlined in white and the one picked, or dropped and in hand, in blue. A press that travels more than a few pixels orbits and picks nothing. A pick changed on the dock asks ACCEPT EDITS before it is let go; one left as it was asks nothing.

The lasso's panel is its tools in the art's rows, and DESELECT while something is selected. The selection is a dashed white line on the ground that stays across tool changes until DESELECT drops it. A mountain dropped inside it is cut at its edge, and a click outside it drops nothing. A selection is not an edit, so leaving with one asks only whether to save.

Triangle, Star and Polygon stand on the press and reach to the pointer, turned the way it went. NUMBER OF SIDES, NUMBER OF POINTS, STAR RATIO and a rounded box's CORNER reshape the selection the tool drew, where it stands. Curved Polygon runs a smooth curve through the points clicked and round the loop; Curved Polyline runs it through them and closes straight back to the start. The key held at the press says how a shape meets the selection, and holds to the end of the shape: Shift adds it, Alt cuts it out, and neither keeps only the ground inside both. A shape that leaves no ground selected drops the selection. Shift pressed once a drag is under way squares the box or rounds the ellipse instead, so the one key does both.

Grass, Sand, Water and Snow are one tool, each with its own panel from the moment it is chosen: DENSITY, the stamp - BUILD HEIGHT, BUILD WIDTH and CORNER RADIUS, in screen pixels - and COLOR LIGHT and COLOR DARK. A drag lays the stamp swept whole along the way it went, laid at the size it is on the screen where it was pressed, and the strokes drawn before ACCEPT are one batch: DENSITY and the colours change all of it at once, and the stamp only the strokes still to come. At a density below 1 the stroke breaks into clumps with ground between them - pools, for water. Grass and sand lie on all the ground under a stroke, whatever its height, shaded light on its low ground and dark on its high. Water is cut into the ground at its stroke's lowest bank, so it lies level across the stroke and runs down with the ground along it - a stream down a slope, a pond in a hollow - pale at its banks and dark in its middle; the sea's level stays where it was. Snow settles on any ground the stroke crosses, thin and shadowed at its edges and white down its middle, and stays off faces too steep to hold it. The batch carries the gumball: the centre moves it, the squares stretch it and the arc turns it. With a selection live the batch is clipped to it, and a stroke that reaches none of it lays nothing. The next batch starts where the panel was left.

Insert Runway's panel is its templates as cards: BASIC RUNWAY, and COMMERCIAL, longer and wider with a dashed centreline. Choosing a card arms the tool, and the template's outline follows the pointer over the ground; a click places it lined up with the view to the nearest ten degrees, its strip levelled to the ground it lands on. HEADING, LENGTH and WIDTH turn and size it, as the gumball's arc and squares do, and its centre moves it; a click with it in hand puts it down there instead, and another card turns it into that template where it stands. A strip is kept wholly on the canvas. The two airports join the cards once their aprons and buildings can be drawn. A flight that starts on a runway starts on the last one placed.

Free Paint's panel is the artwork's three groups. COLOR SELECTION is eight swatches, a strip of every hue in four bands - whole, then at 75, 50 and 25 percent on white - the eye dropper, and HEX INPUT, which reads out the colour and takes one typed as #RRGGBB or #RGB. BRUSH SELECTION is TIP, round or square, and EDGE, hard or soft, under DEFAULT, which is lit while the brush is the one the tool starts with - hard, round and 25 pixels - and puts it back. BRUSH PROPERTIES is OPACITY as a percentage, SIZE in pixels with a slider, and BLEND. A drag is shown on the ground as the region it will cover, in the paint's colour, and lays a colour and no height: at TINT the stroke takes the colour's hue at the ground's own lightness, so a painted slope keeps its light and shade and black or white is the ground's own grey, and at NORMAL it lays the colour as it is. The strokes before ACCEPT are one batch, as a cover's are: the colour, opacity and blend change all of it, and the brush only the strokes still to come. The eye dropper, pressed, makes the next click on the ground take the colour there; Esc puts it down.

Erase's panel is TARGET - ALL, or one element - STRENGTH as a percentage, and the paint brush's TIP, EDGE and SIZE. A drag, shown in red as it is drawn, takes away what was laid before it under the stroke - a preset's mountain as readily as a stroke of grass laid a minute ago - leaving the ground as it was without it rather than painting over it; at a strength below whole it thins what it takes. ALL takes every element but a runway: a strip is taken only when RUNWAY is the target, and then whole, wherever the stroke reaches it. Water erased is dry ground, even under the sea's level. Alt held at the press, drawn in green, puts back: as the first stroke of a batch it hands back what the batches before it took, and within a batch it cuts the stroke out of the batch, so an overshoot is put right before ACCEPT. Something laid after a batch is not touched by it.

While something is selected, every tool's panel carries DESELECT beside its own answers - Mountain's, before a drop, is its heading over DESELECT alone - and a right click on the selection opens a small popup carrying it at the pointer. A press anywhere off the popup, or Esc, shuts it and drops nothing.

Extrude's panel, EXTRUDE SHAPE, is its seven shapes - Rectangle, Circle, Triangle, Polygon, Star, Polyline and Polycurve, drawn as the lasso's are - the chosen shape's own fields, and one button that reads off the stage the extrusion is at. Drawing, it is EXTRUDE, greyed until the region covers some ground: shapes drawn are one region, filled red over the canvas and not yet ground - Shift adds a shape, Alt cuts one out, and with a selection live the selection is the region, drawn solid red, so EXTRUDE is ready on arrival and a shape is drawn within it. EXTRUDE levels the region to its ground's mean and raises it, flat on top and walled at its edge, with HEIGHT and FLATTEN on the panel and the gumball's blue arrow pulling it up or down - shown red on the overlay as it is pulled, and the ground drawn when it is let go. EDIT EXTRUSION puts the gumball away for TOP COLOR, WALL COLOR and BLEND: a click on the top or the wall points the panel at that surface's colour and BLEND, outlined red - the top round its rim, the wall at its foot and its head - and a click off the extrusion points it at all three again. Each colour row carries the eye dropper, which fills that row. APPLY comes back keeping what was changed, and BACK comes back with the surfaces as they were. At TINT, the default, each surface takes its colour's hue at the lightness of the ground it stands on, so a wall shades down a hillside the way the hillside does, and the wall fades to the ground's own colour at its foot; at NORMAL the two colours are laid as they are. Picking another shape keeps the extrusion lifted, asking nothing, and draws the next with it.

A pan from inside any tool - Shift and the right button held - moves the view and nothing else: the tool waits, the cursor grabs, the brush and a runway's outline are put away, and letting go puts the tool back as it was, with a shape half drawn still being drawn and nothing committed or asked about.

Insert Runway offers BASIC AIRPORT and COMMERCIAL AIRPORT too: a strip with an apron painted in its grey beside it and buildings standing beyond the apron, each kept at its distance from the paving as the strip is widened, and picked as one by any part of it.

Shift with a press on a spinner is a coarse step - ten points on a row read as a percentage, 100% to 110% to 120%, and ten steps on any other row - and Shift with an arrow in the element editor is the same.

What is in hand carries the gumball, in the art's colours: red east, green north, blue up. The white centre moves it over the ground, the red and green arrows slide it along one axis, the blue arrow makes a mountain taller rather than lifting it, the dot on each axis spreads it and the tick stands it taller or lower. A handle moves nothing until it has been dragged further than a click, and holds to the same bounds the dock's rows do.

Builder settings

The builder's own preferences, opened by the gear on the palette's band or O on a canvas, and by the BUILDER SETTINGS row on the game's settings. BACK, Esc, Backspace or O returns to whichever opened it. Stored under a key of its own, and read by the editor alone: the same placements build the same ground whatever was set here while they were built.

The four under AUTO ACCEPT are when a draft is kept without being asked about. WHEN DRAWING AGAIN: the next press that draws - a stroke begun, a mountain dropped, a runway placed, a shape begun over a lifted extrusion - keeps the draft in hand and starts a new one, joined to the stroke kept just before it when nothing about it changed, so a batch is still one placement; nothing is kept when a stroke is let go of, so the stroke just drawn can still be changed or cancelled. WHEN LEAVING: the way out keeps it and asks only SAVE AND EXIT MODE. WHEN CHANGING TOOL: another tool keeps it rather than asking ACCEPT EDITS. With ALL on the three read on and do not step; off, they are what they were. A pan never keeps anything. CAMERA SPEED scales the orbit, the pan and the wheel's zoom together.

Opened over a canvas the screen is modal and the live tool waits under it: nothing is kept or dropped, the draft is the draft when it closes, and a setting changed there applies from the next press.

Element editor

The world being flown as the elements it was assembled from. Enter opens an element onto its ranges; A/D step the range under the cursor. L opens the builder, which carries these rows now: in Select with nothing picked, each element is a WORLD: section on the dock.

A gated range is a pair of bounds that only sometimes applies, for a footprint an element otherwise works out for itself. The switch opens OFF, where the element draws what it always drew, and moves in one press rather than by a fiftieth. Its bounds stay listed either way, so a range can be set up before it is turned on. The mountain's LENGTH and WIDTH are the two: off, a peak is the round bump RADIUS and GIRTH arrive at; on, its footprint is the one it was asked for.

One press moves a fiftieth of what the range allows, rounded to 1, 2, or 5 times a power of ten. A range can be typed into instead: a digit starts the figure, Enter takes it and draws the ground again, and the figure is read in the units the row reads in - 150 at a gradient end is 150%. A figure outside the declared bounds is refused and the row says what they are. RESTORE THE PRESET puts every range back. Edits belong to the world they were made on and are not stored between sessions. Not available while a game mode is being played: a mode brings its own ground.

Game modes

Gate colours: green is the one the course is waiting on, amber is still to come, dim is behind you. A crash restarts the stage.

A circuit is five legs - TAKEOFF, CLIMB OUT, DOWNWIND, BASE, FINAL - each marked on how near its heading and its height it was held, and finished by the landing rather than by crossing the threshold. The landing closes FINAL too, so the arrival reports the approach's mark and the circuit's together. A mast stands at the three turns in open air; the other two are the ends of the strip, which is drawn there already. A canyon run counts a cut only when it is crossed inside the walls and under the beam; over the top is not a way through, and there is no floor. A survey counts a shot only with the aircraft inside the height, the range and the heading the brief asked for - the range is drawn as two circles on the ground, the other two are written on the card.

With no engine - a dead stick, or a cargo run out of budget - the nose sets the airspeed instead of the lever: nose down buys speed with height, nose up spends that speed for a slower descent, and a level glide reaches about twelve times the height it spends. A cargo run writes what is left of its budget where the time to beat goes, and only an open throttle spends it.

Gates are laid over from the second stage on, and closed up one way across as they are - a round hoop is the same hoop at every angle, so a gate that has to be flown at the angle it was laid at is wider along its span than it is tall.

Approach guidance is withdrawn the same way: an extended centreline of eight marks running 3200 units back down the approach and a bar across the threshold on stage one, the bar alone on stage two, and nothing from stage three on. Both are laid off the threshold the stage opens you out from.

The whole course is drawn on the minimap the moment the stage is laid out, in the same three colours. A gate past the edge of the square the chart covers is held hollow at that edge. The other two modes with something to fly to are drawn the same way: a route's strips in the order they are landed at, and a search's marker on its own.

Best times are kept per stage per mode in localStorage. The clock runs from the moment a stage is laid out to the moment its objective is met, and a stage restarted is timed from nothing.

A mode can also be opened straight from the address, at any stage it has:

http://localhost:8080/index.html?mode=cargo-run&stage=2

The stage is the one on the card - STAGE 2 OF 3 is stage=2. A request that cannot be met opens nothing and writes the reason to the console rather than opening the nearest stage instead. This is for reaching a stage without flying the stages before it, which is the only way an automated check can read a mode's later stages.

API

import { createPilot, createEnvironment, createTiledEnvironment } from './js/api/index.js';

createPilot({ scene, camera, aircraft, anchor, terrain, keymap, flight })
    .update(dt)          // returns { airspeed, altitude, verticalSpeed, heading, throttle }

createEnvironment({ environment, runway })
    .group               // one detachable Object3D
    .applyDepth(scene)   // the sky and the fog, without the ground
    .attach(aircraft)    // throws with every gap in the contract
    .register(mesh, { x, z })
    .runways[0]
    .setEnvironment(id)
    .setDaylight(phase)  // 0 to 1
    .updateWater(dt, phase)

createTiledEnvironment({ environment, tiles, size })
    .sampleHeight(x, z)  // answered by whichever square the point is over

import { validateAircraftContract, TELEMETRY_FIELDS, API_VERSION } from './js/api/contract.js';

validateAircraftContract(aircraft)   // every gap at once, or []

Commands

Photo names

pilot-matter-YYYYMMDD-HHMMSS.png, for example pilot-matter-20260824-050709.png.