From bd9a7705bcbb693d779ae6f0dd590edef757c999 Mon Sep 17 00:00:00 2001 From: "Nabeel S." <99736+nabeelio@users.noreply.github.com> Date: Tue, 17 Nov 2026 12:13:06 -0600 Subject: [PATCH 1/7] feat(settings): accept the phase-consensus threshold keys Adds the go-around/approach consensus and nearby-lookup keys the client validates, and the general-aviation class selector. --- src/types/settings.schema.json | 64 ++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/src/types/settings.schema.json b/src/types/settings.schema.json index 1721d48..e24bced 100644 --- a/src/types/settings.schema.json +++ b/src/types/settings.schema.json @@ -42,9 +42,9 @@ } }, "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" @@ -284,6 +284,66 @@ "type": "number", "minimum": 0, "maximum": 7200 + }, + "goAroundClimbSeconds": { + "description": "Go-around consensus: the window (s) the climbing vote's mean vertical speed is averaged over.", + "type": "number", + "minimum": 1, + "maximum": 30 + }, + "goAroundSustainSec": { + "description": "Go-around consensus: how long (s) each counted vote must hold true.", + "type": "number", + "minimum": 0, + "maximum": 30 + }, + "goAroundFieldCeilingFt": { + "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": 100, + "maximum": 10000 + }, + "goAroundMinGainFt": { + "description": "Go-around consensus: the barometric gain (ft) from the low point that is always required.", + "type": "number", + "minimum": 0, + "maximum": 2000 + }, + "goAroundN1RisePct": { + "description": "Go-around consensus: N1 points above the trailing baseline (the lowest N1 over goAroundThrustBaselineSeconds) that cast the thrust vote.", + "type": "number", + "minimum": 1, + "maximum": 100 + }, + "goAroundThrottleRisePct": { + "description": "Go-around consensus: throttle points above the trailing baseline (the lowest throttle over goAroundThrustBaselineSeconds) that cast the thrust vote.", + "type": "number", + "minimum": 1, + "maximum": 100 + }, + "goAroundThrustBaselineSeconds": { + "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": 1, + "maximum": 60 + }, + "approachDescentFpm": { + "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", + "minimum": 50, + "maximum": 3000 + }, + "nearbyLookupCeilingAglFt": { + "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 nearbyLookupDescentCeilingAglFt.", + "type": "number", + "minimum": 0, + "maximum": 10000 + }, + "nearbyLookupDescentCeilingAglFt": { + "description": "Approach candidates: a sustained descent starts a nearby-airport lookup only below this AGL (ft).", + "type": "number", + "minimum": 0, + "maximum": 50000 } } } From 9dd071cf8390c5bb9491e0e5b7861a6b808b4bad Mon Sep 17 00:00:00 2001 From: "Nabeel S." <99736+nabeelio@users.noreply.github.com> Date: Tue, 17 Nov 2026 12:35:22 -0600 Subject: [PATCH 2/7] feat(settings): accept the nearby lookup range --- src/types/settings.schema.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/types/settings.schema.json b/src/types/settings.schema.json index e24bced..9514461 100644 --- a/src/types/settings.schema.json +++ b/src/types/settings.schema.json @@ -344,6 +344,12 @@ "type": "number", "minimum": 0, "maximum": 50000 + }, + "nearbyLookupRangeNm": { + "description": "Approach candidates: the airborne lookup takes the nearest airport with runways within this range (NM).", + "type": "number", + "minimum": 1, + "maximum": 50 } } } From 7d3404ec1fd8ebf7a0543e9a7c06c94b4cc27237 Mon Sep 17 00:00:00 2001 From: "Nabeel S." <99736+nabeelio@users.noreply.github.com> Date: Tue, 17 Nov 2026 14:39:52 -0600 Subject: [PATCH 3/7] docs(schema): add default values as reference --- src/types/settings.schema.json | 44 +++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/src/types/settings.schema.json b/src/types/settings.schema.json index 9514461..fbb5e3f 100644 --- a/src/types/settings.schema.json +++ b/src/types/settings.schema.json @@ -98,214 +98,250 @@ "taxiInMaxKt": { "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": { "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": { "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.", "type": "number", + "default": 300, "minimum": 10, "maximum": 5000 }, "goAroundClimbGainFt": { "description": "Height gained (ft) above the approach low point that declares a go-around.", "type": "number", + "default": 300, "minimum": 10, "maximum": 5000 }, "goAroundGsKt": { "description": "Minimum ground speed (kt) during the climb for it to count as a go-around.", "type": "number", + "default": 80, "minimum": 1, "maximum": 300 }, "goAroundVsFpm": { "description": "Minimum vertical speed (fpm) during the climb for it to count as a go-around.", "type": "number", + "default": 300, "minimum": 1, "maximum": 10000 }, "arrivalAirborneAglFt": { "description": "AGL (ft) below which the arrival segment of a flight begins in landing analysis.", "type": "number", + "default": 500, "minimum": 10, "maximum": 10000 }, "circuitLiftoffSeconds": { "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 }, "circuitLiftoffAglFt": { "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": 1000 }, "circuitStopKt": { "description": "Ground speed (kt) below which a landing roll is considered stopped, ending the circuit.", "type": "number", + "default": 10, "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" + "type": "boolean", + "default": true }, "circuitRollMinKt": { "description": "Ground speed (kt) floor for a roll attempt. Kept above takeoffRunwayKt so an expedited runway exit after over-slowing does not qualify.", "type": "number", + "default": 50, "minimum": 1, "maximum": 200 }, "circuitRollAccelKt": { "description": "Ground speed gain (kt) over circuitRollWindowSeconds that declares a roll attempt.", "type": "number", + "default": 20, "minimum": 1, "maximum": 100 }, "circuitRollWindowSeconds": { "description": "Sim-clock window (s) over which circuitRollAccelKt is measured; needs at least three samples, and a gap over two seconds resets it.", "type": "number", + "default": 5, "minimum": 1, "maximum": 60 }, "circuitRollHeadingToleranceDeg": { "description": "Heading drift (deg) allowed during the roll window for it to still count as a roll on the runway.", "type": "number", + "default": 20, "minimum": 0, "maximum": 180 }, "departureAfterReverserPenalty": { "description": "Points taken off the landing category (0-100) when the aircraft departs again after reversers were used.", "type": "number", + "default": 25, "minimum": 0, "maximum": 100 }, "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.", "type": "number", + "default": -200, "minimum": -5000, "maximum": 5000 }, "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 }, "contactLandedSec": { "description": "Empirical. Contact held this long (s) means the aircraft is on the ground.", "type": "number", + "default": 1, "minimum": 0.1, "maximum": 10 }, "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", + "default": 0.25, "minimum": 0.05, "maximum": 5 }, "airborneGainFt": { "description": "Empirical. Radio-altitude gain (ft) over the ground baseline needed together with the dwell.", "type": "number", + "default": 0.8, "minimum": 0, "maximum": 50 }, "airborneGainTimeoutSec": { "description": "On-ground false this long (s) enters Airborne whatever the gain (sloped runway, unusable radio altitude).", "type": "number", + "default": 1, "minimum": 0.1, "maximum": 10 }, "bounceMinGainFt": { "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 }, "bounceMinAirborneSec": { "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 }, "bounceMaxSec": { "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": 300 }, "holdSec": { "description": "Touchdown values (rate, g, wheels) become final this long (s) after the contact. Equals the touchdown-g window.", "type": "number", + "default": 2, "minimum": 0.5, "maximum": 10 }, "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 }, "heliLiftoffSec": { "description": "Helicopter departure: airborne at least this long (s).", "type": "number", + "default": 2, "minimum": 0.1, "maximum": 60 }, "heliLiftoffAglFt": { "description": "Helicopter departure: at least this much gain (ft) over the ground baseline.", "type": "number", + "default": 10, "minimum": 0, "maximum": 500 }, "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 }, "goAroundClimbSeconds": { "description": "Go-around consensus: the window (s) the climbing vote's mean vertical speed is averaged over.", "type": "number", + "default": 3, "minimum": 1, "maximum": 30 }, "goAroundSustainSec": { "description": "Go-around consensus: how long (s) each counted vote must hold true.", "type": "number", + "default": 1, "minimum": 0, "maximum": 30 }, "goAroundFieldCeilingFt": { "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", + "default": 1000, "minimum": 100, "maximum": 10000 }, "goAroundMinGainFt": { "description": "Go-around consensus: the barometric gain (ft) from the low point that is always required.", "type": "number", + "default": 100, "minimum": 0, "maximum": 2000 }, @@ -318,36 +354,42 @@ "goAroundThrottleRisePct": { "description": "Go-around consensus: throttle points above the trailing baseline (the lowest throttle over goAroundThrustBaselineSeconds) that cast the thrust vote.", "type": "number", + "default": 20, "minimum": 1, "maximum": 100 }, "goAroundThrustBaselineSeconds": { "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", + "default": 15, "minimum": 1, "maximum": 60 }, "approachDescentFpm": { "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 }, "nearbyLookupCeilingAglFt": { "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 nearbyLookupDescentCeilingAglFt.", "type": "number", + "default": 3000, "minimum": 0, "maximum": 10000 }, "nearbyLookupDescentCeilingAglFt": { "description": "Approach candidates: a sustained descent starts a nearby-airport lookup only below this AGL (ft).", "type": "number", + "default": 10000, "minimum": 0, "maximum": 50000 }, "nearbyLookupRangeNm": { "description": "Approach candidates: the airborne lookup takes the nearest airport with runways within this range (NM).", "type": "number", + "default": 10, "minimum": 1, "maximum": 50 } From 894c9b402771f449308b44c5bf20f905e305a3b0 Mon Sep 17 00:00:00 2001 From: "Nabeel S." <99736+nabeelio@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:37:34 -0600 Subject: [PATCH 4/7] feat(schema): add nearbyLookupApproachRangeNm --- src/types/settings.schema.json | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/types/settings.schema.json b/src/types/settings.schema.json index fbb5e3f..6570186 100644 --- a/src/types/settings.schema.json +++ b/src/types/settings.schema.json @@ -392,6 +392,13 @@ "default": 10, "minimum": 1, "maximum": 50 + }, + "nearbyLookupApproachRangeNm": { + "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 } } } From 0b3cbe82888ce8036bcc4b6cca30092e60541e29 Mon Sep 17 00:00:00 2001 From: "Nabeel S." <99736+nabeelio@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:22:56 -0600 Subject: [PATCH 5/7] fix(schema): thrust baseline default 30 s --- src/types/settings.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/settings.schema.json b/src/types/settings.schema.json index 6570186..fbbd937 100644 --- a/src/types/settings.schema.json +++ b/src/types/settings.schema.json @@ -361,7 +361,7 @@ "goAroundThrustBaselineSeconds": { "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", - "default": 15, + "default": 30, "minimum": 1, "maximum": 60 }, From 5b96a2418ff6d6fdbc25c2e4494ef548531eaffd Mon Sep 17 00:00:00 2001 From: "Nabeel S." <99736+nabeelio@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:12:28 -0600 Subject: [PATCH 6/7] feat(settings): overrides-only artifact The full threshold set now lives in the client. settings.json carries only the class overrides, grouped by flight phase (version 2), from .json or .jsonc sources. Adds the airline settings/thresholds.jsonc template to the zip. --- README.md | 190 +++++-- gulpfile.mjs | 104 ++-- package-lock.json | 8 + package.json | 1 + src/package.json | 3 + src/settings/defaults.json | 34 -- src/settings/overrides/general-aviation.jsonc | 7 + src/settings/overrides/helicopter.json | 6 - src/settings/overrides/helicopter.jsonc | 11 + src/settings/thresholds.jsonc | 18 + src/types/settings.schema.json | 486 ++++++++++-------- 11 files changed, 524 insertions(+), 344 deletions(-) delete mode 100644 src/settings/defaults.json create mode 100644 src/settings/overrides/general-aviation.jsonc delete mode 100644 src/settings/overrides/helicopter.json create mode 100644 src/settings/overrides/helicopter.jsonc create mode 100644 src/settings/thresholds.jsonc diff --git a/README.md b/README.md index ed65b25..c5b73d6 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 `thresholds` 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/thresholds.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/thresholds.jsonc` - the airline template. It ships in the zip + as `settings/thresholds.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/thresholds.jsonc` in its own config zip, with the +same shape: + +```jsonc filename="settings/thresholds.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..5ecf7a9 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 `thresholds` namespace, this + * artifact, then the airline's own settings/thresholds.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/thresholds.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 + '/thresholds.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/thresholds.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/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/settings/thresholds.jsonc b/src/settings/thresholds.jsonc new file mode 100644 index 0000000..7da0462 --- /dev/null +++ b/src/settings/thresholds.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/types/settings.schema.json b/src/types/settings.schema.json index fbbd937..78fa9ea 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/thresholds.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 thresholds 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": { @@ -44,181 +63,110 @@ "class": { "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", "general-aviation"] + "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.", - "type": "number", - "default": 300, - "minimum": 10, - "maximum": 5000 - }, - "goAroundClimbGainFt": { - "description": "Height gained (ft) above the approach low point that declares a go-around.", - "type": "number", - "default": 300, - "minimum": 10, - "maximum": 5000 - }, - "goAroundGsKt": { - "description": "Minimum ground speed (kt) during the climb for it to count as a go-around.", - "type": "number", - "default": 80, - "minimum": 1, - "maximum": 300 - }, - "goAroundVsFpm": { - "description": "Minimum vertical speed (fpm) during the climb for it to count as a go-around.", - "type": "number", - "default": 300, - "minimum": 1, - "maximum": 10000 - }, - "arrivalAirborneAglFt": { - "description": "AGL (ft) below which the arrival segment of a flight begins in landing analysis.", - "type": "number", - "default": 500, - "minimum": 10, - "maximum": 10000 - }, - "circuitLiftoffSeconds": { - "description": "Seconds the aircraft must stay airborne after a touchdown for the lift-off to count as a new circuit.", + "heliLiftoffSec": { + "description": "Helicopter departure: airborne at least this long (s).", "type": "number", - "default": 3, - "minimum": 0, + "default": 2, + "minimum": 0.1, "maximum": 60 }, - "circuitLiftoffAglFt": { - "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": 1000 - }, - "circuitStopKt": { - "description": "Ground speed (kt) below which a landing roll is considered stopped, ending the circuit.", + "heliLiftoffAglFt": { + "description": "Helicopter departure: at least this much gain (ft) over the ground baseline.", "type": "number", "default": 10, "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", - "default": true - }, - "circuitRollMinKt": { - "description": "Ground speed (kt) floor for a roll attempt. Kept above takeoffRunwayKt so an expedited runway exit after over-slowing does not qualify.", - "type": "number", - "default": 50, - "minimum": 1, - "maximum": 200 - }, - "circuitRollAccelKt": { - "description": "Ground speed gain (kt) over circuitRollWindowSeconds that declares a roll attempt.", - "type": "number", - "default": 20, - "minimum": 1, - "maximum": 100 - }, - "circuitRollWindowSeconds": { - "description": "Sim-clock window (s) over which circuitRollAccelKt is measured; needs at least three samples, and a gap over two seconds resets it.", - "type": "number", - "default": 5, - "minimum": 1, - "maximum": 60 - }, - "circuitRollHeadingToleranceDeg": { - "description": "Heading drift (deg) allowed during the roll window for it to still count as a roll on the runway.", - "type": "number", - "default": 20, - "minimum": 0, - "maximum": 180 - }, - "departureAfterReverserPenalty": { - "description": "Points taken off the landing category (0-100) when the aircraft departs again after reversers were used.", - "type": "number", - "default": 25, - "minimum": 0, - "maximum": 100 - }, - "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.", + "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": -200, - "minimum": -5000, - "maximum": 5000 - }, + "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", @@ -233,6 +181,13 @@ "minimum": 0.1, "maximum": 10 }, + "holdSec": { + "description": "Touchdown values (rate, g, wheels) become final this long (s) after the contact. Equals the touchdown-g window.", + "type": "number", + "default": 2, + "minimum": 0.5, + "maximum": 10 + }, "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", @@ -254,34 +209,6 @@ "minimum": 0.1, "maximum": 10 }, - "bounceMinGainFt": { - "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 - }, - "bounceMinAirborneSec": { - "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 - }, - "bounceMaxSec": { - "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": 300 - }, - "holdSec": { - "description": "Touchdown values (rate, g, wheels) become final this long (s) after the contact. Equals the touchdown-g window.", - "type": "number", - "default": 2, - "minimum": 0.5, - "maximum": 10 - }, "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", @@ -296,104 +223,211 @@ "minimum": 0.05, "maximum": 10 }, - "heliLiftoffSec": { - "description": "Helicopter departure: airborne at least this long (s).", + "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 + }, + "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": 60 + "maximum": 30 }, - "heliLiftoffAglFt": { - "description": "Helicopter departure: at least this much gain (ft) over the ground baseline.", + "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": 10, - "minimum": 0, - "maximum": 500 + "default": 20, + "minimum": 1, + "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 }, - "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.", + "vsFpm": { + "description": "Minimum vertical speed (fpm) during the climb for it to count as a go-around.", "type": "number", - "default": 600, - "minimum": 0, - "maximum": 7200 + "default": 300, + "minimum": 1, + "maximum": 10000 }, - "goAroundClimbSeconds": { + "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": 30 }, - "goAroundSustainSec": { + "sustainSec": { "description": "Go-around consensus: how long (s) each counted vote must hold true.", "type": "number", "default": 1, "minimum": 0, "maximum": 30 }, - "goAroundFieldCeilingFt": { + "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", "default": 1000, "minimum": 100, "maximum": 10000 }, - "goAroundMinGainFt": { + "minGainFt": { "description": "Go-around consensus: the barometric gain (ft) from the low point that is always required.", "type": "number", "default": 100, "minimum": 0, "maximum": 2000 }, - "goAroundN1RisePct": { - "description": "Go-around consensus: N1 points above the trailing baseline (the lowest N1 over goAroundThrustBaselineSeconds) that cast the thrust vote.", + "n1RisePct": { + "description": "Go-around consensus: N1 points above the trailing baseline (the lowest N1 over goAround.thrustBaselineSeconds) that cast the thrust vote.", "type": "number", + "default": 10, "minimum": 1, "maximum": 100 }, - "goAroundThrottleRisePct": { - "description": "Go-around consensus: throttle points above the trailing baseline (the lowest throttle over goAroundThrustBaselineSeconds) that cast the thrust vote.", + "throttleRisePct": { + "description": "Go-around consensus: throttle points above the trailing baseline (the lowest throttle over goAround.thrustBaselineSeconds) that cast the thrust vote.", "type": "number", "default": 20, "minimum": 1, "maximum": 100 }, - "goAroundThrustBaselineSeconds": { + "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", "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 }, - "approachDescentFpm": { - "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.", + "liftoffAglFt": { + "description": "AGL (ft) the aircraft must reach after a touchdown for the lift-off to count as a new circuit.", "type": "number", - "default": 300, - "minimum": 50, - "maximum": 3000 + "default": 50, + "minimum": 0, + "maximum": 1000 + }, + "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", + "default": -200, + "minimum": -5000, + "maximum": 5000 + }, + "stopKt": { + "description": "Ground speed (kt) below which a landing roll is considered stopped, ending the circuit.", + "type": "number", + "default": 10, + "minimum": 0, + "maximum": 100 + }, + "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 + }, + "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": 200 + }, + "rollAccelKt": { + "description": "Ground speed gain (kt) over circuit.rollWindowSeconds that declares a roll attempt.", + "type": "number", + "default": 20, + "minimum": 1, + "maximum": 100 + }, + "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", + "default": 5, + "minimum": 1, + "maximum": 60 + }, + "rollHeadingToleranceDeg": { + "description": "Heading drift (deg) allowed during the roll window for it to still count as a roll on the runway.", + "type": "number", + "default": 20, + "minimum": 0, + "maximum": 180 }, - "nearbyLookupCeilingAglFt": { - "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 nearbyLookupDescentCeilingAglFt.", + "departureAfterReverserPenalty": { + "description": "Points taken off the landing category (0-100) when the aircraft departs again after reversers were used.", + "type": "number", + "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 }, - "nearbyLookupDescentCeilingAglFt": { + "descentCeilingAglFt": { "description": "Approach candidates: a sustained descent starts a nearby-airport lookup only below this AGL (ft).", "type": "number", "default": 10000, "minimum": 0, "maximum": 50000 }, - "nearbyLookupRangeNm": { + "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 }, - "nearbyLookupApproachRangeNm": { + "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, @@ -401,6 +435,36 @@ "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" + } + } } } } From 91f66e15e6401b69e2a073619698fea27b762dd5 Mon Sep 17 00:00:00 2001 From: "Nabeel S." <99736+nabeelio@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:49:47 -0600 Subject: [PATCH 7/7] refactor(settings): rename airline layer to flight --- README.md | 12 ++++++------ gulpfile.mjs | 10 +++++----- src/settings/{thresholds.jsonc => flight.jsonc} | 0 src/types/settings.schema.json | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) rename src/settings/{thresholds.jsonc => flight.jsonc} (100%) diff --git a/README.md b/README.md index c5b73d6..9919438 100644 --- a/README.md +++ b/README.md @@ -425,13 +425,13 @@ so a change takes effect on the next flight without a client release. Last one wins, key by key: 1. **Client built-in values** - every key (the Keys table below). -2. **Replane `thresholds` namespace** - global tuning, `{}` until something is +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/thresholds.jsonc` (or `.json`)** in its config +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. @@ -439,8 +439,8 @@ Last one wins, key by key: - `src/settings/overrides/*.json` or `*.jsonc` - one class override per file: a selector plus only the keys it changes. -- `src/settings/thresholds.jsonc` - the airline template. It ships in the zip - as `settings/thresholds.jsonc` and changes nothing until an airline adds +- `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 @@ -563,10 +563,10 @@ the ones it should beat. ### Airline tuning -An airline edits `settings/thresholds.jsonc` in its own config zip, with the +An airline edits `settings/flight.jsonc` in its own config zip, with the same shape: -```jsonc filename="settings/thresholds.jsonc" +```jsonc filename="settings/flight.jsonc" { "version": 2, "values": { "phases": { "taxiIn": { "maxKt": 30 } } }, diff --git a/gulpfile.mjs b/gulpfile.mjs index 5ecf7a9..c327a29 100644 --- a/gulpfile.mjs +++ b/gulpfile.mjs @@ -203,8 +203,8 @@ function buildAircraftConfigsTask(done) { * * 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 `thresholds` namespace, this - * artifact, then the airline's own settings/thresholds.json[c] from its config + * winning: its compiled-in defaults, the Replane `flight` namespace, this + * artifact, then the airline's own settings/flight.json[c] from its config * zip. * * artifacts/settings.json carries the aircraft-class overrides. Same publishing @@ -217,7 +217,7 @@ function buildAircraftConfigsTask(done) { * plain JSON (version 2), so the published file never depends on a * comment-tolerant reader. * - * src/settings/thresholds.jsonc is the airline template: it is copied into + * 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. * @@ -229,7 +229,7 @@ function buildAircraftConfigsTask(done) { function buildSettingsTask(done) { const dir = paths.src + '/settings' const overridesDir = dir + '/overrides' - const templateFile = dir + '/thresholds.jsonc' + 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 @@ -330,7 +330,7 @@ function buildSettingsTask(done) { ) fs.mkdirSync(paths.out + '/settings', { recursive: true }) - fs.copyFileSync(templateFile, paths.out + '/settings/thresholds.jsonc') + fs.copyFileSync(templateFile, paths.out + '/settings/flight.jsonc') console.log(`settings.json: version 2, ${overrides.length} overrides`) done() diff --git a/src/settings/thresholds.jsonc b/src/settings/flight.jsonc similarity index 100% rename from src/settings/thresholds.jsonc rename to src/settings/flight.jsonc diff --git a/src/types/settings.schema.json b/src/types/settings.schema.json index 78fa9ea..fb40d3c 100644 --- a/src/types/settings.schema.json +++ b/src/types/settings.schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://get.acars.link/configs/settings.schema.json", "title": "vmsacars flight thresholds", - "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/thresholds.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 thresholds namespace, this artifact, then the airline file.", + "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": [