diff --git a/README.md b/README.md index ed65b25..9919438 100644 --- a/README.md +++ b/README.md @@ -414,95 +414,171 @@ everything else alone. ## Flight Thresholds (`settings.json`) The client decides when a takeoff roll has started, when a landing roll has -stopped, when a climb is a go-around, and so on, from a handful of numeric -thresholds. Those live in `src/settings/` and are published on their own, like -the aircraft configs, as `configs/settings-latest.json`. The client downloads -it from `acars.settings_url`, resolves one set of values when a flight starts -and freezes it for that flight, so a change here takes effect on the next -flight without a client release. When the file cannot be fetched, the client -falls back to a bundled copy of `defaults.json`. +stopped, when a climb is a go-around, and so on, from a set of numeric +thresholds. The full set of values is compiled into the client. Everything +else is a sparse layer that lists only the keys it changes. When a flight +starts, the client resolves one set of values and freezes it for that flight, +so a change takes effect on the next flight without a client release. + +### Layers + +Last one wins, key by key: + +1. **Client built-in values** - every key (the Keys table below). +2. **Replane `flight` namespace** - global tuning, `{}` until something is + tuned. +3. **This repo's `settings.json`** - the aircraft-class overrides, published on + their own like the aircraft configs, as `configs/settings-latest.json`, and + downloaded from `acars.settings_url`. When it cannot be fetched, the client + uses its own copy of the class overrides. +4. **The airline's `settings/flight.jsonc` (or `.json`)** in its config + zip, found through `config.settings.path` in the zip's `package.json`. + Airlines tune thresholds here. ### Layout -- `src/settings/defaults.json` - every key, with the value that applies to any - aircraft nothing else matches. -- `src/settings/overrides/*.json` - one override per file: a selector plus - only the keys it changes. -- `src/types/settings.schema.json` - the JSON schema. Every key's meaning and - allowed range is documented there, and the build validates the source files - against it. +- `src/settings/overrides/*.json` or `*.jsonc` - one class override per file: + a selector plus only the keys it changes. +- `src/settings/flight.jsonc` - the airline template. It ships in the zip + as `settings/flight.jsonc` and changes nothing until an airline adds + values to it. +- `src/types/settings.schema.json` - the JSON schema. Every key's meaning, + built-in value and allowed range is documented there, and the build + validates every source file against it. -The build (`npm run build`) assembles them into `artifacts/settings.json`: +Comments and trailing commas are allowed in the sources, so give each file a +short comment. The build (`npm run build`) parses them, validates them and +writes plain JSON (version 2) to `artifacts/settings.json`: -```json +```jsonc { - "version": 1, - "defaults": { "taxiInMaxKt": 35, "takeoffRunwayKt": 40, "...": 0 }, + "version": 2, "overrides": [ - { "class": "helicopter", "values": { "circuitRollEnabled": false } }, - { "icao": ["C172", "C152", "PA28"], "values": { "circuitLiftoffAglFt": 30 } } + { "class": "general-aviation", "values": { "phases": { "approach": { "descentFpm": 150 } } } }, + { "class": "helicopter", "values": { "phases": { "approach": { "descentFpm": 150 }, "circuit": { "rollEnabled": false } } } } ] } ``` -### Precedence +Every layer document has the same shape. `version` is required and must be 2; +`values` (applies to every aircraft) and `overrides` are both optional. + +### Groups + +| Group | What it covers | +|---|---| +| `phases.taxiIn` | When the aircraft counts as taxiing in after landing | +| `phases.takeoff` | Takeoff roll start, and the helicopter lift-off confirmation | +| `phases.approach` | The sustained descent that starts the Approach phase | +| `phases.landed` | Touchdown plausibility and ground-contact detection | +| `phases.landed.bounce` | When a hop after touchdown counts as a bounce | +| `phases.goAround` | The go-around consensus votes | +| `phases.circuit` | Multiple landings: lift-off, roll and stop detection for touch-and-go circuits | +| `airportLookup` | When and how far the nearby-airport lookup searches for an approach field | +| `recording` | Raw-telemetry capture policy | + +The `phases` groups are named after the client's flight phases (`PirepState`), +`goAround` after its go-around event. -Resolution is `defaults` <- `class` overrides <- `icao` overrides, merged -key-by-key. The client starts from `defaults`, applies every matching `class` -override in file order, then every matching `icao` override in file order. -Each layer only replaces the keys it lists, so an override that sets one key -leaves all the others at the lower layer's value. If two overrides for the same -layer set the same key, the one whose file sorts later wins. +### Precedence inside one document -With the example above, a C172 ends up with `circuitLiftoffAglFt` 30, and a -PA28 with the same key at 30 but every other key from `defaults`. Any -helicopter gets `circuitRollEnabled` false and everything else from `defaults`. +`values` <- `class` overrides <- `icao` overrides, merged key-by-key: every +matching `class` override in file order, then every matching `icao` override in +file order. Each layer only replaces the keys it lists. If two overrides for the +same layer set the same key, the one later in the file (or whose file sorts +later) wins. ### Keys -| Key | Default | What it does | +The built-in value is the one compiled into the client; every layer only +changes it. + +| Key | Built-in | What it does | |---|---|---| -| `taxiInMaxKt` | 35 | Ground speed (kt) below which the aircraft is taxiing in after landing | -| `takeoffRunwayKt` | 40 | Ground speed (kt) that starts the takeoff roll on a known runway | -| `takeoffAnywhereKt` | 80 | Ground speed (kt) that starts the takeoff roll anywhere | -| `goAroundAglFt` | 300 | AGL (ft) the approach must be below before a climb can be a go-around | -| `goAroundClimbGainFt` | 300 | Height gained (ft) above the approach low point that declares a go-around | -| `goAroundGsKt` | 80 | Minimum ground speed (kt) during the climb for a go-around | -| `goAroundVsFpm` | 300 | Minimum vertical speed (fpm) during the climb for a go-around | -| `arrivalAirborneAglFt` | 500 | AGL (ft) below which the arrival segment begins in landing analysis | -| `circuitLiftoffSeconds` | 3 | Seconds airborne after a touchdown for the lift-off to start a new circuit | -| `circuitLiftoffAglFt` | 50 | AGL (ft) reached after a touchdown for the lift-off to start a new circuit | -| `circuitStopKt` | 10 | Ground speed (kt) below which a landing roll is stopped | -| `circuitRollEnabled` | `true` | Whether a re-acceleration on the runway can start a new circuit (`false` for helicopters) | -| `circuitRollMinKt` | 50 | Ground speed (kt) floor for a roll attempt; above `takeoffRunwayKt` on purpose so an expedited runway exit does not qualify | -| `circuitRollAccelKt` | 20 | Ground speed gain (kt) over `circuitRollWindowSeconds` that declares a roll attempt | -| `circuitRollWindowSeconds` | 5 | Sim-clock window (s) for `circuitRollAccelKt`; at least 3 samples, a gap over 2 s resets it | -| `circuitRollHeadingToleranceDeg` | 20 | Heading drift (deg) allowed during the roll window | -| `departureAfterReverserPenalty` | 25 | Points off the landing category (0-100) when the aircraft departs again after using reversers | -| `circuitLiftoffMinVsFpm` | -200 | Mean VS (fpm) over the lift-off window must be at or above this for a circuit lift-off to confirm; a fall off an obstacle is not a departure | -| `touchdownMaxRadioAltFt` | 100 | On-ground sample with radio altitude above this (ft) and no gear contact is not a touchdown; unknown telemetry stays plausible | +| `phases.taxiIn.maxKt` | 35 | Ground speed (kt) below which the aircraft is taxiing in after landing | +| `phases.takeoff.runwayKt` | 40 | Ground speed (kt) that starts the takeoff roll on a known runway | +| `phases.takeoff.anywhereKt` | 80 | Ground speed (kt) that starts the takeoff roll anywhere | +| `phases.takeoff.heliLiftoffSec` | 2 | Helicopter departure: airborne at least this long (s) | +| `phases.takeoff.heliLiftoffAglFt` | 10 | Helicopter departure: gain (ft) over the ground baseline | +| `phases.approach.descentFpm` | 300 | Sustained descent rate (fpm, positive) that starts the Approach phase | +| `phases.landed.touchdownMaxRadioAltFt` | 100 | On-ground sample with radio altitude above this (ft) and no gear contact is not a touchdown; unknown telemetry stays plausible | +| `phases.landed.contactLandedSec` | 1 | Contact held this long (s) means the aircraft is on the ground | +| `phases.landed.holdSec` | 2 | Touchdown values become final this long (s) after the contact | +| `phases.landed.airborneDwellSec` | 0.25 | On-ground false this long (s), with the gain, means airborne | +| `phases.landed.airborneGainFt` | 0.8 | Radio-altitude gain (ft) needed together with the dwell | +| `phases.landed.airborneGainTimeoutSec` | 1 | On-ground false this long (s) means airborne whatever the gain | +| `phases.landed.sinkRateWindowSec` | 1 | Touchdown sink rate is the mean vertical speed over this window (s) | +| `phases.landed.oneWheelSec` | 0.5 | One main wheel down this long (s) before the other marks a one-wheel touchdown | +| `phases.landed.bounce.minGainFt` | 2 | A hop after touchdown that rises at least this much (ft) is a bounce | +| `phases.landed.bounce.minAirborneSec` | 1 | A hop after touchdown airborne at least this long (s) is a bounce | +| `phases.landed.bounce.maxSec` | 20 | A span this long (s) is an extended float; ground held this long closes bounce attribution | +| `phases.goAround.climbGainFt` | 300 | Barometric climb (ft) above the approach low point that casts the gain vote | +| `phases.goAround.vsFpm` | 300 | Mean vertical speed (fpm) that casts the climbing vote | +| `phases.goAround.climbSeconds` | 3 | Window (s) the climbing vote is averaged over | +| `phases.goAround.sustainSec` | 1 | How long (s) each counted vote must hold | +| `phases.goAround.fieldCeilingFt` | 1000 | The low point must be at most this far (ft) above the field | +| `phases.goAround.minGainFt` | 100 | Barometric gain (ft) from the low point that is always required | +| `phases.goAround.n1RisePct` | 10 | N1 points above the trailing baseline that cast the thrust vote | +| `phases.goAround.throttleRisePct` | 20 | Throttle points above the trailing baseline that cast the thrust vote | +| `phases.goAround.thrustBaselineSeconds` | 30 | Trailing window (s) whose lowest N1 and throttle are the thrust baseline | +| `phases.circuit.liftoffSeconds` | 3 | Seconds airborne after a touchdown for the lift-off to start a new circuit | +| `phases.circuit.liftoffAglFt` | 50 | AGL (ft) reached after a touchdown for the lift-off to start a new circuit | +| `phases.circuit.liftoffMinVsFpm` | -200 | Mean VS (fpm) over the lift-off window must be at or above this; a fall off an obstacle is not a departure | +| `phases.circuit.stopKt` | 10 | Ground speed (kt) below which a landing roll is stopped | +| `phases.circuit.rollEnabled` | `true` | Whether a re-acceleration on the runway can start a new circuit (`false` for helicopters) | +| `phases.circuit.rollMinKt` | 50 | Ground speed (kt) floor for a roll attempt; above `phases.takeoff.runwayKt` on purpose so an expedited runway exit does not qualify | +| `phases.circuit.rollAccelKt` | 20 | Ground speed gain (kt) over `phases.circuit.rollWindowSeconds` that declares a roll attempt | +| `phases.circuit.rollWindowSeconds` | 5 | Sim-clock window (s) for `phases.circuit.rollAccelKt`; at least 3 samples, a gap over 2 s resets it | +| `phases.circuit.rollHeadingToleranceDeg` | 20 | Heading drift (deg) allowed during the roll window | +| `phases.circuit.departureAfterReverserPenalty` | 25 | Points off the landing category (0-100) when the aircraft departs again after using reversers | +| `airportLookup.ceilingAglFt` | 3000 | At or below this AGL (ft) a nearby-airport lookup may start | +| `airportLookup.descentCeilingAglFt` | 10000 | A sustained descent starts a lookup only below this AGL (ft) | +| `airportLookup.rangeNm` | 10 | The lookup takes the nearest airport with runways within this range (NM) | +| `airportLookup.approachRangeNm` | 20 | Range (NM) once the Approach phase has started | +| `recording.lowFullRateMaxSec` | 600 | Full-rate recording below 2,000 ft AGL lasts at most this long (s) per low leg | ### Adding an override Create one file under `src/settings/overrides/`. It needs `values` and at least one selector: -- `class` - `fixed-wing` or `helicopter`. +- `class` - `fixed-wing`, `helicopter` or `general-aviation`. - `icao` - a list of ICAO type designators. Matching ignores case. -```json filename="src/settings/overrides/light-singles.json" +```jsonc filename="src/settings/overrides/light-singles.jsonc" +// Light singles fly a tighter, lower circuit. { "icao": ["C172", "C152", "PA28"], "values": { - "circuitLiftoffAglFt": 30 + "phases": { "circuit": { "liftoffAglFt": 30 } } } } ``` -Only list the keys you are changing. The build rejects a key that is not in -the schema, a value outside its range, and an override with no selector, so -run `npm run build` before opening a pull request. Files are applied in -filename order, so name a file so it sorts after the ones it should beat. +Only list the keys you are changing, nested in their groups. The build rejects +a group or key that is not in the schema, a value outside its range and an +override with no selector, so run `npm run build` before opening a pull +request. Files are applied in filename order, so name a file so it sorts after +the ones it should beat. + +### Airline tuning + +An airline edits `settings/flight.jsonc` in its own config zip, with the +same shape: + +```jsonc filename="settings/flight.jsonc" +{ + "version": 2, + "values": { "phases": { "taxiIn": { "maxKt": 30 } } }, + "overrides": [ + { "icao": ["C172"], "values": { "phases": { "approach": { "descentFpm": 200 } } } } + ] +} +``` + +A file that does not parse is skipped whole and logged. An unknown key is +logged and ignored; a value outside its range is logged and reverts to the +built-in value. --- diff --git a/gulpfile.mjs b/gulpfile.mjs index 224d01c..c327a29 100644 --- a/gulpfile.mjs +++ b/gulpfile.mjs @@ -1,5 +1,6 @@ import dotconfig from '@dotenvx/dotenvx' import Ajv from 'ajv' +import { parse as parseJsonc, printParseErrorCode } from 'jsonc-parser' import { deleteSync as del } from 'del' import fs from 'fs' import { dest, series, src, watch } from 'gulp' @@ -198,59 +199,72 @@ function buildAircraftConfigsTask(done) { } /** - * Builds the flight-thresholds settings document into one JSON artifact. + * Builds the flight-thresholds artifact and the airline thresholds template. * - * Same publishing story as aircraft.json: the client downloads this file on - * its own (acars.settings_url), so it is written to artifacts/ and not into - * dist/. The source is split so an override is one small file: defaults.json - * holds every key, and each overrides/*.json is one selector plus the keys it - * changes. Overrides are concatenated in filename order, which is also the - * order the client applies them in, so a filename is the only ordering knob. + * The full set of threshold values lives in the client; everything here is a + * sparse layer that lists only what it changes. The client applies, last one + * winning: its compiled-in defaults, the Replane `flight` namespace, this + * artifact, then the airline's own settings/flight.json[c] from its config + * zip. * - * Everything is validated against src/types/settings.schema.json before it is - * written. A typo here reaches every client within a release cycle, so an - * unknown key, an out-of-range value or a selector-less override fails the - * build rather than shipping. + * artifacts/settings.json carries the aircraft-class overrides. Same publishing + * story as aircraft.json: the client downloads it on its own + * (acars.settings_url), so it is written to artifacts/ and not into dist/. Each + * src/settings/overrides/*.json or *.jsonc is one selector plus the keys it + * changes; they are concatenated in filename order, which is also the order the + * client applies them in, so a filename is the only ordering knob. The sources + * may carry comments (parsed with jsonc-parser); the artifact is written as + * plain JSON (version 2), so the published file never depends on a + * comment-tolerant reader. + * + * src/settings/flight.jsonc is the airline template: it is copied into + * dist/settings/ for the zip (package.json points config.settings.path at it), + * where an airline adds its own tuning. + * + * Everything is validated against src/types/settings.schema.json first. A typo + * here reaches every client within a release cycle, so an unknown group or key, + * an out-of-range value or a selector-less override fails the build rather than + * shipping. */ function buildSettingsTask(done) { const dir = paths.src + '/settings' const overridesDir = dir + '/overrides' + const templateFile = dir + '/flight.jsonc' const schemaFile = paths.src + '/types/settings.schema.json' // strictRequired is the one strict check we drop: the override selector rule - // is "icao or class" spelled as an anyOf of bare `required` branches, and that - // check wants the properties re-declared inside every branch. + // is "icao or class" spelled as an anyOf of bare `required` branches, and + // that check wants the properties re-declared inside every such schema. const ajv = new Ajv({ allErrors: true, strict: true, strictRequired: false }) const schema = JSON.parse(fs.readFileSync(schemaFile, 'utf8')) const validateDocument = ajv.compile(schema) - // Sub-schemas for the source files, so an error names the file it came from - // instead of an index into the assembled artifact. - const validateDefaults = ajv.compile({ $ref: `${schema.$id}#/definitions/values` }) + // Sub-schema for one override source, so an error names the file it came + // from instead of an index into the assembled artifact. const validateOverride = ajv.compile({ $ref: `${schema.$id}#/definitions/override` }) const fail = (file, message) => { done(new Error(`${file}: ${message}`)) } - const read = (file) => JSON.parse(fs.readFileSync(file, 'utf8')) - const describe = (errors) => ajv.errorsText(errors, { separator: '; ' }) - - let defaults - const defaultsFile = dir + '/defaults.json' - try { - defaults = read(defaultsFile) - } catch (err) { - fail(defaultsFile, err.message) + // jsonc-parser is fault tolerant: it returns a best-effort value and reports + // problems through `errors`, so any error at all is treated as a broken file. + const read = (file) => { + const errors = [] + const value = parseJsonc(fs.readFileSync(file, 'utf8'), errors, { + allowTrailingComma: true, + disallowComments: false, + }) + + if (errors.length > 0) { + const { error, offset } = errors[0] + throw new Error(`${printParseErrorCode(error)} at offset ${offset}`) + } - return + return value } - if (!validateDefaults(defaults)) { - fail(defaultsFile, describe(validateDefaults.errors)) - - return - } + const describe = (errors) => ajv.errorsText(errors, { separator: '; ' }) const overrides = [] const overrideFiles = fs.existsSync(overridesDir) @@ -258,7 +272,7 @@ function buildSettingsTask(done) { : [] for (const file of overrideFiles) { - if (!file.endsWith('.json')) { + if (!file.endsWith('.json') && !file.endsWith('.jsonc')) { continue } @@ -281,7 +295,7 @@ function buildSettingsTask(done) { overrides.push(override) } - const document = { version: 1, defaults, overrides } + const document = { version: 2, overrides } // Belt and braces: the pieces were valid, so the whole must be too. If this // ever trips, the schema and this task have drifted apart. @@ -291,6 +305,23 @@ function buildSettingsTask(done) { return } + // The airline template ships in the zip as-is, comments included: the + // client's reader accepts JSONC for the airline file. + let template + try { + template = read(templateFile) + } catch (err) { + fail(templateFile, err.message) + + return + } + + if (!validateDocument(template)) { + fail(templateFile, describe(validateDocument.errors)) + + return + } + fs.mkdirSync(paths.artifacts, { recursive: true }) fs.writeFileSync( paths.artifacts + '/settings.json', @@ -298,9 +329,10 @@ function buildSettingsTask(done) { 'utf8', ) - console.log( - `settings.json: ${Object.keys(defaults).length} defaults, ${overrides.length} overrides`, - ) + fs.mkdirSync(paths.out + '/settings', { recursive: true }) + fs.copyFileSync(templateFile, paths.out + '/settings/flight.jsonc') + + console.log(`settings.json: version 2, ${overrides.length} overrides`) done() } diff --git a/package-lock.json b/package-lock.json index e0e9d5d..33ff876 100644 --- a/package-lock.json +++ b/package-lock.json @@ -26,6 +26,7 @@ "gulp-typescript": "^6.0.0-alpha.1", "gulp-zip": "^6.1.0", "gulplog": "^2.2.0", + "jsonc-parser": "^3.3.1", "merge2": "^1.4.1", "prettier": "^3.3.3", "typescript": "^5.5.4" @@ -3534,6 +3535,13 @@ "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==", "dev": true }, + "node_modules/jsonc-parser": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz", + "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==", + "dev": true, + "license": "MIT" + }, "node_modules/keyv": { "version": "4.5.4", "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz", diff --git a/package.json b/package.json index c526287..38fb621 100644 --- a/package.json +++ b/package.json @@ -39,6 +39,7 @@ "gulp-typescript": "^6.0.0-alpha.1", "gulp-zip": "^6.1.0", "gulplog": "^2.2.0", + "jsonc-parser": "^3.3.1", "merge2": "^1.4.1", "prettier": "^3.3.3", "typescript": "^5.5.4" diff --git a/src/package.json b/src/package.json index aea85d5..2df05c9 100644 --- a/src/package.json +++ b/src/package.json @@ -14,6 +14,9 @@ }, "sounds": { "path": "sounds" + }, + "settings": { + "path": "settings" } } } diff --git a/src/settings/defaults.json b/src/settings/defaults.json deleted file mode 100644 index 8573bdf..0000000 --- a/src/settings/defaults.json +++ /dev/null @@ -1,34 +0,0 @@ -{ - "taxiInMaxKt": 35, - "takeoffRunwayKt": 40, - "takeoffAnywhereKt": 80, - "goAroundAglFt": 300, - "goAroundClimbGainFt": 300, - "goAroundGsKt": 80, - "goAroundVsFpm": 300, - "arrivalAirborneAglFt": 500, - "circuitLiftoffSeconds": 3, - "circuitLiftoffAglFt": 50, - "circuitStopKt": 10, - "circuitRollEnabled": true, - "circuitRollMinKt": 50, - "circuitRollAccelKt": 20, - "circuitRollWindowSeconds": 5, - "circuitRollHeadingToleranceDeg": 20, - "departureAfterReverserPenalty": 25, - "circuitLiftoffMinVsFpm": -200, - "touchdownMaxRadioAltFt": 100, - "contactLandedSec": 1.0, - "airborneDwellSec": 0.25, - "airborneGainFt": 0.8, - "airborneGainTimeoutSec": 1.0, - "bounceMinGainFt": 2.0, - "bounceMinAirborneSec": 1.0, - "bounceMaxSec": 20.0, - "holdSec": 2.0, - "sinkRateWindowSec": 1.0, - "oneWheelSec": 0.5, - "heliLiftoffSec": 2.0, - "heliLiftoffAglFt": 10.0, - "lowFullRateMaxSec": 600.0 -} diff --git a/src/settings/flight.jsonc b/src/settings/flight.jsonc new file mode 100644 index 0000000..7da0462 --- /dev/null +++ b/src/settings/flight.jsonc @@ -0,0 +1,18 @@ +// Airline flight-thresholds layer (version 2). Optional, and applied last, over the client's +// built-in defaults and the vmsacars class overrides, so anything set here wins. +// +// List only what you change; every key you leave out keeps its built-in value. The keys, their +// ranges and their built-in values are in types/settings.schema.json of the acars-config repo. +// +// "values" applies to every aircraft. +// "overrides" applies to the aircraft a selector matches: "class" (fixed-wing, helicopter, +// general-aviation) and/or "icao" (a list of type designators). +// +// Example: +// "values": { "phases": { "taxiIn": { "maxKt": 30 } } }, +// "overrides": [ +// { "icao": ["C172"], "values": { "phases": { "approach": { "descentFpm": 200 } } } } +// ] +{ + "version": 2 +} diff --git a/src/settings/overrides/general-aviation.jsonc b/src/settings/overrides/general-aviation.jsonc new file mode 100644 index 0000000..46da40d --- /dev/null +++ b/src/settings/overrides/general-aviation.jsonc @@ -0,0 +1,7 @@ +// Light aircraft descend in the pattern at 150-500 fpm; the jet value would hold their Approach back. +{ + "class": "general-aviation", + "values": { + "phases": { "approach": { "descentFpm": 150 } } + } +} diff --git a/src/settings/overrides/helicopter.json b/src/settings/overrides/helicopter.json deleted file mode 100644 index adcca27..0000000 --- a/src/settings/overrides/helicopter.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "class": "helicopter", - "values": { - "circuitRollEnabled": false - } -} diff --git a/src/settings/overrides/helicopter.jsonc b/src/settings/overrides/helicopter.jsonc new file mode 100644 index 0000000..eac1d48 --- /dev/null +++ b/src/settings/overrides/helicopter.jsonc @@ -0,0 +1,11 @@ +// Helicopters do not roll for takeoff, so a re-acceleration on the ground never starts a new circuit, +// and they descend in the pattern slower than the jet approach threshold. +{ + "class": "helicopter", + "values": { + "phases": { + "approach": { "descentFpm": 150 }, + "circuit": { "rollEnabled": false } + } + } +} diff --git a/src/types/settings.schema.json b/src/types/settings.schema.json index 1721d48..fb40d3c 100644 --- a/src/types/settings.schema.json +++ b/src/types/settings.schema.json @@ -2,33 +2,52 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://get.acars.link/configs/settings.schema.json", "title": "vmsacars flight thresholds", - "description": "The built artifacts/settings.json: the flight-phase and landing-analysis thresholds the client resolves once per flight. defaults applies to every aircraft; each override layers its values on top when its selector matches (class overrides first, then icao overrides, each in file order). Also used to validate src/settings/defaults.json (against #/definitions/values) and every src/settings/overrides/*.json (against #/definitions/override) at build time.", + "description": "A sparse flight-thresholds layer document (version 2). The full set of values lives in the client; every document lists only what it changes, grouped by flight phase (PirepState names, with goAround and circuit under phases) and feature. Used for the published artifacts/settings.json (the aircraft-class overrides, built from src/settings/overrides/*.json[c]) and for an airline's settings/flight.json[c] in its config zip. values applies to every aircraft; each override layers its values on top when its selector matches (class overrides first, then icao overrides, each in file order). The client applies, last one winning: its compiled-in defaults, the Replane flight namespace, this artifact, then the airline file.", "type": "object", "additionalProperties": false, - "required": ["version", "defaults", "overrides"], + "required": [ + "version" + ], "properties": { "version": { - "description": "Document format version. The client rejects anything other than 1.", + "description": "Document format version. The client accepts only 2 (grouped keys); version 1 (flat keys) never shipped.", "type": "integer", - "const": 1 + "const": 2 }, - "defaults": { + "values": { "$ref": "#/definitions/values" }, "overrides": { "type": "array", - "items": { "$ref": "#/definitions/override" } + "items": { + "$ref": "#/definitions/override" + } + }, + "$schema": { + "type": "string" } }, "definitions": { "override": { - "description": "One override document. Needs at least one selector; values lists only the keys it changes.", + "description": "One override document. Needs at least one selector; values uses the same groups as defaults and lists only the keys it changes.", "type": "object", "additionalProperties": false, - "required": ["values"], + "required": [ + "values" + ], "anyOf": [ - { "type": "object", "required": ["icao"] }, - { "type": "object", "required": ["class"] } + { + "type": "object", + "required": [ + "icao" + ] + }, + { + "type": "object", + "required": [ + "class" + ] + } ], "properties": { "icao": { @@ -42,250 +61,410 @@ } }, "class": { - "description": "Aircraft class this override applies to.", + "description": "Aircraft class this override applies to. A general-aviation aircraft is also fixed-wing: general-aviation overrides apply after the fixed-wing ones.", "type": "string", - "enum": ["fixed-wing", "helicopter"] + "enum": [ + "fixed-wing", + "helicopter", + "general-aviation" + ] }, "values": { - "$ref": "#/definitions/partialValues" + "$ref": "#/definitions/values" } } }, - "values": { - "description": "The complete threshold set. Every key is required here; this is the shape of defaults.", + "phases": { + "description": "Flight phases, one group per PirepState (camelCase).", "type": "object", - "allOf": [{ "$ref": "#/definitions/partialValues" }], - "required": [ - "taxiInMaxKt", - "takeoffRunwayKt", - "takeoffAnywhereKt", - "goAroundAglFt", - "goAroundClimbGainFt", - "goAroundGsKt", - "goAroundVsFpm", - "arrivalAirborneAglFt", - "circuitLiftoffSeconds", - "circuitLiftoffAglFt", - "circuitStopKt", - "circuitRollEnabled", - "circuitRollMinKt", - "circuitRollAccelKt", - "circuitRollWindowSeconds", - "circuitRollHeadingToleranceDeg", - "departureAfterReverserPenalty", - "circuitLiftoffMinVsFpm", - "touchdownMaxRadioAltFt", - "contactLandedSec", - "airborneDwellSec", - "airborneGainFt", - "airborneGainTimeoutSec", - "bounceMinGainFt", - "bounceMinAirborneSec", - "bounceMaxSec", - "holdSec", - "sinkRateWindowSec", - "oneWheelSec", - "heliLiftoffSec", - "heliLiftoffAglFt", - "lowFullRateMaxSec" - ] + "additionalProperties": false, + "properties": { + "taxiIn": { + "$ref": "#/definitions/taxiIn" + }, + "takeoff": { + "$ref": "#/definitions/takeoff" + }, + "approach": { + "$ref": "#/definitions/approach" + }, + "landed": { + "$ref": "#/definitions/landed" + }, + "goAround": { + "$ref": "#/definitions/goAround" + }, + "circuit": { + "$ref": "#/definitions/circuit" + } + } }, - "partialValues": { - "description": "Any subset of the threshold keys. Unknown keys are rejected so a typo cannot silently fall through to the default.", + "taxiIn": { + "description": "Taxi-in (PirepState.TaxiIn): when the aircraft counts as taxiing in after landing.", "type": "object", "additionalProperties": false, "properties": { - "taxiInMaxKt": { + "maxKt": { "description": "Ground speed (kt) below which the aircraft is considered to be taxiing in after landing.", "type": "number", + "default": 35, "minimum": 1, "maximum": 100 - }, - "takeoffRunwayKt": { + } + } + }, + "takeoff": { + "description": "Takeoff (PirepState.Takeoff): the takeoff roll start, and the helicopter lift-off confirmation.", + "type": "object", + "additionalProperties": false, + "properties": { + "runwayKt": { "description": "Ground speed (kt) that starts the takeoff roll when the aircraft is on a known runway.", "type": "number", + "default": 40, "minimum": 1, "maximum": 200 }, - "takeoffAnywhereKt": { + "anywhereKt": { "description": "Ground speed (kt) that starts the takeoff roll anywhere, runway known or not.", "type": "number", + "default": 80, "minimum": 1, "maximum": 300 }, - "goAroundAglFt": { - "description": "Absolute AGL (ft) the aircraft must be below on approach before a climb can count as a go-around.", + "heliLiftoffSec": { + "description": "Helicopter departure: airborne at least this long (s).", "type": "number", - "minimum": 10, - "maximum": 5000 + "default": 2, + "minimum": 0.1, + "maximum": 60 }, - "goAroundClimbGainFt": { - "description": "Height gained (ft) above the approach low point that declares a go-around.", + "heliLiftoffAglFt": { + "description": "Helicopter departure: at least this much gain (ft) over the ground baseline.", "type": "number", - "minimum": 10, - "maximum": 5000 + "default": 10, + "minimum": 0, + "maximum": 500 + } + } + }, + "approach": { + "description": "Approach (PirepState.Approach): the sustained descent that moves InitialClimb or Enroute to Approach.", + "type": "object", + "additionalProperties": false, + "properties": { + "descentFpm": { + "description": "Approach consensus: the sustained descent rate (fpm, positive) that moves InitialClimb or Enroute to Approach (mean VS over 5 s at or below minus this). Set per class: light aircraft and helicopters descend slower than jets.", + "type": "number", + "default": 300, + "minimum": 50, + "maximum": 3000 + } + } + }, + "landed": { + "description": "Landed (PirepState.Landed): touchdown plausibility and the ground-contact tracker.", + "type": "object", + "additionalProperties": false, + "properties": { + "touchdownMaxRadioAltFt": { + "description": "An on-ground sample with a valid radio altitude above this (ft) and no gear contact is not a touchdown. Rejects building or obstacle strikes the sim reports as ground contact. Unknown radio altitude or gear data always counts as plausible.", + "type": "number", + "default": 100, + "minimum": 0, + "maximum": 2500 }, - "goAroundGsKt": { - "description": "Minimum ground speed (kt) during the climb for it to count as a go-around.", + "contactLandedSec": { + "description": "Empirical. Contact held this long (s) means the aircraft is on the ground.", "type": "number", - "minimum": 1, - "maximum": 300 + "default": 1, + "minimum": 0.1, + "maximum": 10 }, - "goAroundVsFpm": { - "description": "Minimum vertical speed (fpm) during the climb for it to count as a go-around.", + "holdSec": { + "description": "Touchdown values (rate, g, wheels) become final this long (s) after the contact. Equals the touchdown-g window.", "type": "number", - "minimum": 1, - "maximum": 10000 + "default": 2, + "minimum": 0.5, + "maximum": 10 }, - "arrivalAirborneAglFt": { - "description": "AGL (ft) below which the arrival segment of a flight begins in landing analysis.", + "airborneDwellSec": { + "description": "Empirical. On-ground false this long (s), with the gain, enters Airborne. Measured from the lift-off edge to the re-contact edge.", "type": "number", - "minimum": 10, - "maximum": 10000 + "default": 0.25, + "minimum": 0.05, + "maximum": 5 }, - "circuitLiftoffSeconds": { - "description": "Seconds the aircraft must stay airborne after a touchdown for the lift-off to count as a new circuit.", + "airborneGainFt": { + "description": "Empirical. Radio-altitude gain (ft) over the ground baseline needed together with the dwell.", "type": "number", + "default": 0.8, "minimum": 0, - "maximum": 60 + "maximum": 50 }, - "circuitLiftoffAglFt": { - "description": "AGL (ft) the aircraft must reach after a touchdown for the lift-off to count as a new circuit.", + "airborneGainTimeoutSec": { + "description": "On-ground false this long (s) enters Airborne whatever the gain (sloped runway, unusable radio altitude).", "type": "number", - "minimum": 0, - "maximum": 1000 + "default": 1, + "minimum": 0.1, + "maximum": 10 }, - "circuitStopKt": { - "description": "Ground speed (kt) below which a landing roll is considered stopped, ending the circuit.", + "sinkRateWindowSec": { + "description": "Empirical. Touchdown sink rate is the mean vertical speed over this window (s) ending at the last airborne sample before contact.", + "type": "number", + "default": 1, + "minimum": 0.1, + "maximum": 10 + }, + "oneWheelSec": { + "description": "Empirical. One main wheel stable-down this long (s) before the other marks a one-wheel touchdown.", + "type": "number", + "default": 0.5, + "minimum": 0.05, + "maximum": 10 + }, + "bounce": { + "$ref": "#/definitions/bounce" + } + } + }, + "bounce": { + "description": "Bounce attribution after a touchdown.", + "type": "object", + "additionalProperties": false, + "properties": { + "minGainFt": { + "description": "Empirical. A span after touchdown that rises at least this much (ft) is a bounce, not a rollout hop.", "type": "number", + "default": 2, "minimum": 0, "maximum": 100 }, - "circuitRollEnabled": { - "description": "Whether a re-acceleration on the runway (a touch-and-go roll) can start a new circuit. Off for helicopters.", - "type": "boolean" + "minAirborneSec": { + "description": "Empirical. A span after touchdown airborne at least this long (s) is a bounce, not a rollout hop.", + "type": "number", + "default": 1, + "minimum": 0.1, + "maximum": 30 }, - "circuitRollMinKt": { - "description": "Ground speed (kt) floor for a roll attempt. Kept above takeoffRunwayKt so an expedited runway exit after over-slowing does not qualify.", + "maxSec": { + "description": "Empirical. A span this long (s) without a departure is an extended float; the ground held this long closes bounce attribution.", "type": "number", + "default": 20, "minimum": 1, - "maximum": 200 + "maximum": 300 + } + } + }, + "goAround": { + "description": "Go-around consensus (EventType.GoAround): the votes that declare a go-around.", + "type": "object", + "additionalProperties": false, + "properties": { + "climbGainFt": { + "description": "Height gained (ft) above the approach low point that declares a go-around.", + "type": "number", + "default": 300, + "minimum": 10, + "maximum": 5000 }, - "circuitRollAccelKt": { - "description": "Ground speed gain (kt) over circuitRollWindowSeconds that declares a roll attempt.", + "vsFpm": { + "description": "Minimum vertical speed (fpm) during the climb for it to count as a go-around.", "type": "number", + "default": 300, "minimum": 1, - "maximum": 100 + "maximum": 10000 }, - "circuitRollWindowSeconds": { - "description": "Sim-clock window (s) over which circuitRollAccelKt is measured; needs at least three samples, and a gap over two seconds resets it.", + "climbSeconds": { + "description": "Go-around consensus: the window (s) the climbing vote's mean vertical speed is averaged over.", "type": "number", + "default": 3, "minimum": 1, - "maximum": 60 + "maximum": 30 }, - "circuitRollHeadingToleranceDeg": { - "description": "Heading drift (deg) allowed during the roll window for it to still count as a roll on the runway.", + "sustainSec": { + "description": "Go-around consensus: how long (s) each counted vote must hold true.", "type": "number", + "default": 1, "minimum": 0, - "maximum": 180 + "maximum": 30 }, - "departureAfterReverserPenalty": { - "description": "Points taken off the landing category (0-100) when the aircraft departs again after reversers were used.", + "fieldCeilingFt": { + "description": "Go-around consensus: the episode's low point must be at most this far (ft) above the approach target's elevation, or this high by AGL when no elevation is known.", "type": "number", - "minimum": 0, - "maximum": 100 + "default": 1000, + "minimum": 100, + "maximum": 10000 }, - "circuitLiftoffMinVsFpm": { - "description": "Mean vertical speed (fpm) over the circuitLiftoffSeconds window must be at or above this for a lift-off to confirm. Stops a fall off an obstacle (AGL rising while VS is deeply negative) from counting as a departure.", + "minGainFt": { + "description": "Go-around consensus: the barometric gain (ft) from the low point that is always required.", "type": "number", - "minimum": -5000, - "maximum": 5000 + "default": 100, + "minimum": 0, + "maximum": 2000 }, - "touchdownMaxRadioAltFt": { - "description": "An on-ground sample with a valid radio altitude above this (ft) and no gear contact is not a touchdown. Rejects building or obstacle strikes the sim reports as ground contact. Unknown radio altitude or gear data always counts as plausible.", + "n1RisePct": { + "description": "Go-around consensus: N1 points above the trailing baseline (the lowest N1 over goAround.thrustBaselineSeconds) that cast the thrust vote.", "type": "number", - "minimum": 0, - "maximum": 2500 + "default": 10, + "minimum": 1, + "maximum": 100 }, - "contactLandedSec": { - "description": "Empirical. Contact held this long (s) means the aircraft is on the ground.", + "throttleRisePct": { + "description": "Go-around consensus: throttle points above the trailing baseline (the lowest throttle over goAround.thrustBaselineSeconds) that cast the thrust vote.", "type": "number", - "minimum": 0.1, - "maximum": 10 + "default": 20, + "minimum": 1, + "maximum": 100 }, - "airborneDwellSec": { - "description": "Empirical. On-ground false this long (s), with the gain, enters Airborne. Measured from the lift-off edge to the re-contact edge.", + "thrustBaselineSeconds": { + "description": "Go-around consensus: the trailing window (s, pause-adjusted) whose lowest N1 and throttle are the thrust vote's baseline, so only a fresh advance counts.", "type": "number", - "minimum": 0.05, - "maximum": 5 + "default": 30, + "minimum": 1, + "maximum": 60 + } + } + }, + "circuit": { + "description": "Multiple landings: lift-off, roll and stop detection for touch-and-go circuits.", + "type": "object", + "additionalProperties": false, + "properties": { + "liftoffSeconds": { + "description": "Seconds the aircraft must stay airborne after a touchdown for the lift-off to count as a new circuit.", + "type": "number", + "default": 3, + "minimum": 0, + "maximum": 60 }, - "airborneGainFt": { - "description": "Empirical. Radio-altitude gain (ft) over the ground baseline needed together with the dwell.", + "liftoffAglFt": { + "description": "AGL (ft) the aircraft must reach after a touchdown for the lift-off to count as a new circuit.", "type": "number", + "default": 50, "minimum": 0, - "maximum": 50 + "maximum": 1000 }, - "airborneGainTimeoutSec": { - "description": "On-ground false this long (s) enters Airborne whatever the gain (sloped runway, unusable radio altitude).", + "liftoffMinVsFpm": { + "description": "Mean vertical speed (fpm) over the circuit.liftoffSeconds window must be at or above this for a lift-off to confirm. Stops a fall off an obstacle (AGL rising while VS is deeply negative) from counting as a departure.", "type": "number", - "minimum": 0.1, - "maximum": 10 + "default": -200, + "minimum": -5000, + "maximum": 5000 }, - "bounceMinGainFt": { - "description": "Empirical. A span after touchdown that rises at least this much (ft) is a bounce, not a rollout hop.", + "stopKt": { + "description": "Ground speed (kt) below which a landing roll is considered stopped, ending the circuit.", "type": "number", + "default": 10, "minimum": 0, "maximum": 100 }, - "bounceMinAirborneSec": { - "description": "Empirical. A span after touchdown airborne at least this long (s) is a bounce, not a rollout hop.", - "type": "number", - "minimum": 0.1, - "maximum": 30 + "rollEnabled": { + "description": "Whether a re-acceleration on the runway (a touch-and-go roll) can start a new circuit. Off for helicopters.", + "type": "boolean", + "default": true }, - "bounceMaxSec": { - "description": "Empirical. A span this long (s) without a departure is an extended float; the ground held this long closes bounce attribution.", + "rollMinKt": { + "description": "Ground speed (kt) floor for a roll attempt. Kept above phases.takeoff.runwayKt so an expedited runway exit after over-slowing does not qualify.", "type": "number", + "default": 50, "minimum": 1, - "maximum": 300 + "maximum": 200 }, - "holdSec": { - "description": "Touchdown values (rate, g, wheels) become final this long (s) after the contact. Equals the touchdown-g window.", + "rollAccelKt": { + "description": "Ground speed gain (kt) over circuit.rollWindowSeconds that declares a roll attempt.", "type": "number", - "minimum": 0.5, - "maximum": 10 + "default": 20, + "minimum": 1, + "maximum": 100 }, - "sinkRateWindowSec": { - "description": "Empirical. Touchdown sink rate is the mean vertical speed over this window (s) ending at the last airborne sample before contact.", + "rollWindowSeconds": { + "description": "Sim-clock window (s) over which circuit.rollAccelKt is measured; needs at least three samples, and a gap over two seconds resets it.", "type": "number", - "minimum": 0.1, - "maximum": 10 + "default": 5, + "minimum": 1, + "maximum": 60 }, - "oneWheelSec": { - "description": "Empirical. One main wheel stable-down this long (s) before the other marks a one-wheel touchdown.", + "rollHeadingToleranceDeg": { + "description": "Heading drift (deg) allowed during the roll window for it to still count as a roll on the runway.", "type": "number", - "minimum": 0.05, - "maximum": 10 + "default": 20, + "minimum": 0, + "maximum": 180 }, - "heliLiftoffSec": { - "description": "Helicopter departure: airborne at least this long (s).", + "departureAfterReverserPenalty": { + "description": "Points taken off the landing category (0-100) when the aircraft departs again after reversers were used.", "type": "number", - "minimum": 0.1, - "maximum": 60 + "default": 25, + "minimum": 0, + "maximum": 100 + } + } + }, + "airportLookup": { + "description": "Approach candidates: when and how far the background nearby-airport lookup searches.", + "type": "object", + "additionalProperties": false, + "properties": { + "ceilingAglFt": { + "description": "Approach candidates: at or below this AGL (ft) a background nearby-airport lookup may start. Above it a lookup starts only on gear-down or a sustained descent below airportLookup.descentCeilingAglFt.", + "type": "number", + "default": 3000, + "minimum": 0, + "maximum": 10000 }, - "heliLiftoffAglFt": { - "description": "Helicopter departure: at least this much gain (ft) over the ground baseline.", + "descentCeilingAglFt": { + "description": "Approach candidates: a sustained descent starts a nearby-airport lookup only below this AGL (ft).", "type": "number", + "default": 10000, "minimum": 0, - "maximum": 500 + "maximum": 50000 + }, + "rangeNm": { + "description": "Approach candidates: the airborne lookup takes the nearest airport with runways within this range (NM).", + "type": "number", + "default": 10, + "minimum": 1, + "maximum": 50 }, + "approachRangeNm": { + "description": "Approach candidates: once in the Approach phase, the airborne lookup widens to the 10 nearest airports with runways within this range (NM).", + "type": "number", + "default": 20, + "minimum": 1, + "maximum": 50 + } + } + }, + "recording": { + "description": "Raw-telemetry capture policy.", + "type": "object", + "additionalProperties": false, + "properties": { "lowFullRateMaxSec": { "description": "Capture policy: full-rate recording below 2,000 ft AGL lasts at most this long (s) per low leg, then drops to 4 Hz.", "type": "number", + "default": 600, "minimum": 0, "maximum": 7200 } } + }, + "values": { + "description": "A sparse layer of thresholds: any subset of the groups and keys. The full set of values lives in the client; each key's \"default\" here is that compiled-in value, for reference.", + "type": "object", + "additionalProperties": false, + "properties": { + "phases": { + "$ref": "#/definitions/phases" + }, + "airportLookup": { + "$ref": "#/definitions/airportLookup" + }, + "recording": { + "$ref": "#/definitions/recording" + } + } } } }