@fboes/aerofly-custom-missions 1.2.2 → 1.2.3

package/src/dto/AeroflyMissionCheckpoint.ts

@@ -0,0 +1,235 @@
+import { AeroflyConfigFileSet } from "./AeroflyConfigFileSet.js";
+import { feetPerMeter } from "./AeroflyMission.js";
+
+/**
+ * Types of checkpoints. Required are usually "origin", "departure_runway" at the start and "destination_runway", "destination" at the end.
+ */
+export type AeroflyMissionCheckpointType =
+    | "origin"
+    | "departure_runway"
+    | "departure"
+    | "waypoint"
+    | "arrival"
+    | "approach"
+    | "destination_runway"
+    | "destination";
+
+/**
+ * @class
+ * A single way point for the given flight plan
+ *
+ * The purpose of this class is to collect data needed for Aerofly FS4's
+ * `custom_missions_user.tmc` flight plan file format, and export the structure
+ * for this file via the `toString()` method.
+ */
+
+export class AeroflyMissionCheckpoint {
+    /**
+     * @property {"origin"|"departure_runway"|"departure"|"waypoint"|"arrival"|"approach"|"destination_runway"|"destination"} type of checkpoint, like "departure_runway"
+     */
+    type: AeroflyMissionCheckpointType;
+
+    /**
+     * @property {string} name ICAO code for airport, runway designator, navaid
+     *    designator, fix name, or custom name
+     */
+    name: string;
+
+    /**
+     * @property {number} longitude easting, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -180..180
+     */
+    longitude: number;
+
+    /**
+     * @property {number} latitude northing, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -90..90
+     */
+    latitude: number;
+
+    /**
+     * @property {number} altitude The height in meters above or below the WGS
+     *    84 reference ellipsoid
+     */
+    altitude: number;
+
+    /**
+     * @property {?boolean} altitudeConstraint The altitude given in `altitude`
+     *    will be interpreted as mandatory flight plan altitude instead of
+     *    suggestion.
+     */
+    altitudeConstraint: boolean | null;
+
+    /**
+     * @property {?number} direction of runway, in degree
+     */
+    direction: number | null;
+
+    /**
+     * @property {?number} slope of runway
+     */
+    slope: number | null;
+
+    /**
+     * @property {?number} length of runway, in meters
+     */
+    length: number | null;
+
+    /**
+     * @property {?number} frequency of runways or navigational aids, in Hz; multiply by 1000 for kHz, 1_000_000 for MHz
+     */
+    frequency: number | null;
+
+    /**
+     * @property {?boolean} flyOver if waypoint is meant to be flown over
+     */
+    flyOver: boolean | null;
+
+    /**
+     * @param {string} name ICAO code for airport, runway designator, navaid
+     *    designator, fix name, or custom name
+     * @param {"origin"|"departure_runway"|"departure"|"waypoint"|"arrival"|"approach"|"destination_runway"|"destination"} type Type of checkpoint, like "departure_runway"
+     * @param {number} longitude easting, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -180..180
+     * @param {number} latitude northing, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -90..90
+     * @param {object} additionalAttributes allows to set additional attributes on creation
+     * @param {number} [additionalAttributes.altitude] The height in meters above or below the WGS
+     *    84 reference ellipsoid
+     * @param {?number} [additionalAttributes.altitude_feet] The height in feet above or below the WGS
+     *    84 reference ellipsoid. Will overwrite altitude
+     * @param {number} [additionalAttributes.altitudeConstraint] The altitude given in `altitude`
+     *    will be interpreted as mandatory flight plan altitude instead of
+     *    suggestion.
+     * @param {boolean} [additionalAttributes.direction] of runway, in degree
+     * @param {?number} [additionalAttributes.slope] of runway
+     * @param {?number} [additionalAttributes.length] of runway, in meters
+     * @param {?number} [additionalAttributes.length_feet] of runway, in feet. Will overwrite length
+     * @param {?number} [additionalAttributes.frequency] of runways or navigational aids, in Hz; multiply by 1000 for kHz, 1_000_000 for MHz
+     * @param {?boolean} [additionalAttributes.flyOver] if waypoint is meant to be flown over
+     */
+    constructor(
+        name: string,
+        type: AeroflyMissionCheckpointType,
+        longitude: number,
+        latitude: number,
+        {
+            altitude = 0,
+            altitude_feet = null,
+            altitudeConstraint = null,
+            direction = null,
+            slope = null,
+            length = null,
+            length_feet = null,
+            frequency = null,
+            flyOver = null,
+        }: {
+            altitude?: number;
+            altitude_feet?: number | null;
+            altitudeConstraint?: boolean | null;
+            direction?: number | null;
+            slope?: number | null;
+            length?: number | null;
+            length_feet?: number | null;
+            frequency?: number | null;
+            flyOver?: boolean | null;
+        } = {},
+    ) {
+        this.type = type;
+        this.name = name;
+        this.longitude = longitude;
+        this.latitude = latitude;
+        this.altitude = altitude;
+        this.altitudeConstraint = altitudeConstraint;
+        this.direction = direction;
+        this.slope = slope;
+        this.length = length;
+        this.frequency = frequency;
+        this.flyOver = flyOver;
+
+        if (altitude_feet) {
+            this.altitude_feet = altitude_feet;
+        }
+        if (length_feet) {
+            this.length_feet = length_feet;
+        }
+    }
+
+    /**
+     * @param {number} altitude_feet
+     */
+    set altitude_feet(altitude_feet: number) {
+        this.altitude = altitude_feet / feetPerMeter;
+    }
+
+    /**
+     * @returns {number} altitude_feet
+     */
+    get altitude_feet(): number {
+        return this.altitude * feetPerMeter;
+    }
+
+    /**
+     * @param {number} length_feet
+     */
+    set length_feet(length_feet: number) {
+        this.length = length_feet / feetPerMeter;
+    }
+
+    /**
+     * @returns {number} length_feet
+     */
+    get length_feet(): number {
+        return (this.length ?? 0) * feetPerMeter;
+    }
+
+    /**
+     * @returns {string}
+     */
+    get frequency_string(): string {
+        if (!this.frequency) {
+            return "None";
+        }
+        if (this.frequency > 1000000) {
+            return String(this.frequency / 1000000) + " MHz";
+        }
+        if (this.frequency > 1000) {
+            return String(this.frequency / 1000) + " kHz";
+        }
+
+        return String(this.frequency) + " Hz";
+    }
+
+    /**
+     * @param {number} index if used in an array will se the array index
+     * @returns {string} to use in Aerofly FS4's `custom_missions_user.tmc`
+     */
+    toString(index: number = 0): string {
+        const fileSet = new AeroflyConfigFileSet(5, "tmmission_checkpoint", "element", String(index))
+            .push("string8u", "type", this.type)
+            .push("string8u", "name", this.name)
+            .push("vector2_float64", "lon_lat", [this.longitude, this.latitude])
+            .push("float64", "altitude", this.altitude, `${Math.ceil(this.altitude_feet)} ft`)
+            .push("float64", "direction", this.direction ?? (index === 0 ? -1 : 0))
+            .push("float64", "slope", this.slope ?? 0);
+
+        if (this.altitudeConstraint !== null) {
+            fileSet.push("bool", "alt_cst", this.altitudeConstraint);
+        }
+        if (this.length) {
+            fileSet.push("float64", "length", this.length ?? 0, `${Math.floor(this.length_feet)} ft`);
+        }
+        if (this.frequency) {
+            fileSet.push("float64", "frequency", this.frequency ?? 0, `${this.frequency_string}`);
+        }
+        if (this.flyOver !== null) {
+            fileSet.push("bool", "fly_over", this.flyOver);
+        }
+
+        return fileSet.toString();
+    }
+}

package/src/dto/AeroflyMissionConditions.ts

@@ -0,0 +1,196 @@
+import { AeroflyConfigFileSet } from "./AeroflyConfigFileSet.js";
+import { meterPerStatuteMile } from "./AeroflyMission.js";
+import { AeroflyMissionConditionsCloud } from "./AeroflyMissionConditionsCloud.js";
+
+/**
+ * Weather data for wind
+ * @property direction in degree
+ * @property speed in kts
+ * @property gusts in kts
+ */
+export type AeroflyMissionConditionsWind = {
+    direction: number;
+    speed: number;
+    gusts: number;
+};
+
+/**
+ * @class
+ * Time and weather data for the given flight plan
+ *
+ * The purpose of this class is to collect data needed for Aerofly FS4's
+ * `custom_missions_user.tmc` flight plan file format, and export the structure
+ * for this file via the `toString()` method.
+ */
+export class AeroflyMissionConditions {
+    /**
+     * @property {Date} time of flight plan. Relevant is the UTC part, so
+     *    consider setting this date in UTC.
+     */
+    time: Date;
+
+    /**
+     * @property {object} wind state
+     */
+    wind: AeroflyMissionConditionsWind;
+
+    /**
+     * @property {number} 0..1, percentage
+     */
+    turbulenceStrength: number;
+
+    /**
+     * @property {number} 0..1, percentage
+     */
+    thermalStrength: number;
+
+    /**
+     * @property {number} visibility in meters
+     */
+    visibility: number;
+
+    /**
+     * @property {AeroflyMissionConditionsCloud[]} clouds for the whole flight
+     */
+    clouds: AeroflyMissionConditionsCloud[] = [];
+
+    /**
+     * @param {object} additionalAttributes allows to set additional attributes on creation
+     * @param {Date} [additionalAttributes.time]  of flight plan. Relevant is the UTC part, so
+     *    consider setting this date in UTC.
+     * @param {{direction: number, speed: number, gusts: number}} [additionalAttributes.wind] state
+     * @param {number} [additionalAttributes.turbulenceStrength] 0..1, percentage
+     * @param {number} [additionalAttributes.thermalStrength] 0..1, percentage
+     * @param {number} [additionalAttributes.visibility] in meters
+     * @param {?number} [additionalAttributes.visibility_sm] in statute miles, will overwrite visibility
+     * @param {?number} [additionalAttributes.temperature] in °C, will overwrite thermalStrength
+     * @param {AeroflyMissionConditionsCloud[]} [additionalAttributes.clouds] for the whole flight
+     */
+    constructor({
+        time = new Date(),
+        wind = {
+            direction: 0,
+            speed: 0,
+            gusts: 0,
+        },
+        turbulenceStrength = 0,
+        thermalStrength = 0,
+        visibility = 25_000,
+        visibility_sm = null,
+        temperature = null,
+        clouds = [],
+    }: {
+        time?: Date;
+        wind?: {
+            direction: number;
+            speed: number;
+            gusts: number;
+        };
+        turbulenceStrength?: number;
+        thermalStrength?: number;
+        visibility?: number;
+        visibility_sm?: number | null;
+        temperature?: number | null;
+        clouds?: AeroflyMissionConditionsCloud[];
+    } = {}) {
+        this.time = time;
+        this.wind = wind;
+        this.turbulenceStrength = turbulenceStrength;
+        this.thermalStrength = thermalStrength;
+        this.visibility = visibility;
+        this.clouds = clouds;
+
+        if (visibility_sm) {
+            this.visibility_sm = visibility_sm;
+        }
+        if (temperature) {
+            this.temperature = temperature;
+        }
+    }
+
+    /**
+     * @returns {number} the Aerofly value for UTC hours + minutes/60 + seconds/3600. Ignores milliseconds ;)
+     */
+    get time_hours(): number {
+        return this.time.getUTCHours() + this.time.getUTCMinutes() / 60 + this.time.getUTCSeconds() / 3600;
+    }
+
+    /**
+     * @returns {string} Time representation like "20:15:00"
+     */
+    get time_presentational(): string {
+        return [this.time.getUTCHours(), this.time.getUTCMinutes(), this.time.getUTCSeconds()]
+            .map((t) => {
+                return String(t).padStart(2, "0");
+            })
+            .join(":");
+    }
+
+    /**
+     * @param {number} visibility_sm `this.visibility` in statute miles instead of meters
+     */
+    set visibility_sm(visibility_sm: number) {
+        this.visibility = visibility_sm * meterPerStatuteMile;
+    }
+
+    /**
+     * @returns {number} `this.visibility` in statute miles instead of meters
+     */
+    get visibility_sm(): number {
+        return this.visibility / meterPerStatuteMile;
+    }
+
+    /**
+     * Will set `this.thermalStrength`
+     * @param {number} temperature in °C
+     */
+    set temperature(temperature: number) {
+        // Range from -15°C to 35°C
+        this.thermalStrength = Math.max(0, (temperature + 15) / 50) ** 2;
+    }
+
+    /**
+     * @returns {number} in °C
+     */
+    get temperature(): number {
+        return Math.sqrt(this.thermalStrength) * 50 - 15;
+    }
+
+    /**
+     * @returns {string}
+     */
+    getCloudsString(): string {
+        return this.clouds
+            .map((c: AeroflyMissionConditionsCloud, index: number): string => {
+                return c.toString(index);
+            })
+            .join("\n");
+    }
+
+    /**
+     * @returns {string} to use in Aerofly FS4's `custom_missions_user.tmc`
+     */
+    toString(): string {
+        if (this.clouds.length < 1) {
+            this.clouds = [new AeroflyMissionConditionsCloud(0, 0)];
+        }
+
+        return new AeroflyConfigFileSet(4, "tmmission_conditions", "conditions")
+            .pushRaw(
+                new AeroflyConfigFileSet(5, "tm_time_utc", "time")
+                    .push("int32", "time_year", this.time.getUTCFullYear())
+                    .push("int32", "time_month", this.time.getUTCMonth() + 1)
+                    .push("int32", "time_day", this.time.getUTCDate())
+                    .push("float64", "time_hours", this.time_hours, `${this.time_presentational} UTC`)
+                    .toString(),
+            )
+            .push("float64", "wind_direction", this.wind.direction)
+            .push("float64", "wind_speed", this.wind.speed, "kts")
+            .push("float64", "wind_gusts", this.wind.gusts, "kts")
+            .push("float64", "turbulence_strength", this.turbulenceStrength)
+            .push("float64", "thermal_strength", this.thermalStrength, `${this.temperature} °C`)
+            .push("float64", "visibility", this.visibility, `${this.visibility_sm} SM`)
+            .pushRaw(this.getCloudsString())
+            .toString();
+    }
+}

package/src/dto/AeroflyMissionConditionsCloud.ts

@@ -0,0 +1,100 @@
+import { feetPerMeter } from "./AeroflyMission.js";
+
+/**
+ * Cloud coverage codes
+ */
+export type AeroflyMissionConditionsCloudCoverCode = "CLR" | "FEW" | "SCT" | "BKN" | "OVC";
+
+/**
+ * @class
+ * A cloud layer for the current flight plan's weather data
+ *
+ * The purpose of this class is to collect data needed for Aerofly FS4's
+ * `custom_missions_user.tmc` flight plan file format, and export the structure
+ * for this file via the `toString()` method.
+ */
+export class AeroflyMissionConditionsCloud {
+    /**
+     * @property {number} cover 0..1, percentage
+     */
+    cover: number;
+
+    /**
+     * @property {number} base altitude in meters AGL
+     */
+    base: number;
+
+    /**
+     * @param {number} cover 0..1, percentage
+     * @param {number} base altitude in meters AGL
+     */
+    constructor(cover: number, base: number) {
+        this.cover = cover;
+        this.base = base;
+    }
+
+    /**
+     * @param {number} cover 0..1, percentage
+     * @param {number} base_feet altitude, but in feet AGL instead of meters AGL
+     * @returns {AeroflyMissionConditionsCloud}
+     */
+    static createInFeet(cover: number, base_feet: number): AeroflyMissionConditionsCloud {
+        return new AeroflyMissionConditionsCloud(cover, base_feet / feetPerMeter);
+    }
+
+    /**
+     * @param {number} base_feet `this.base` in feet instead of meters
+     */
+    set base_feet(base_feet: number) {
+        this.base = base_feet / feetPerMeter;
+    }
+
+    /**
+     * @returns {number} `this.base` in feet instead of meters
+     */
+    get base_feet(): number {
+        return this.base * feetPerMeter;
+    }
+
+    /**
+     * @returns {string} Cloud coverage as text representation like "OVC" for `this.cover`
+     */
+    get cover_code(): AeroflyMissionConditionsCloudCoverCode {
+        if (this.cover < 1 / 8) {
+            return "CLR";
+        } else if (this.cover <= 2 / 8) {
+            return "FEW";
+        } else if (this.cover <= 4 / 8) {
+            return "SCT";
+        } else if (this.cover <= 7 / 8) {
+            return "BKN";
+        }
+        return "OVC";
+    }
+
+    /**
+     * @param {number} index if used in an array will se the array index
+     * @returns {string} to use in Aerofly FS4's `custom_missions_user.tmc`
+     */
+    toString(index: number = 0): string {
+        const getIndexString = (index: number) => {
+            switch (index) {
+                case 0:
+                    return "cloud";
+                case 1:
+                    return "cirrus";
+                case 2:
+                    return "cumulus_mediocris";
+                default:
+                    return "more_clouds";
+            }
+        };
+
+        const indexString = getIndexString(index);
+        const comment = index > 1 ? "//" : "";
+
+        return `\
+                    ${comment}<[float64][${indexString}_cover][${this.cover ?? 0}]> // ${this.cover_code}
+                    ${comment}<[float64][${indexString}_base][${this.base}]> // ${this.base_feet} ft AGL`;
+    }
+}

package/src/dto/AeroflyMissionTargetPlane.ts

@@ -0,0 +1,56 @@
+import { AeroflyConfigFileSet } from "./AeroflyConfigFileSet.js";
+
+/**
+ * @class
+ * A target plane which the aircraft needs to cross.
+ */
+export class AeroflyMissionTargetPlane {
+    /**
+     * @property {number} longitude easting, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -180..180
+     */
+    longitude: number;
+
+    /**
+     * @property {number} latitude northing, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -90..90
+     */
+    latitude: number;
+
+    /**
+     * @property {number} dir in degree
+     */
+    dir: number;
+
+    /**
+     * @property {string} name of property
+     */
+    name: string;
+
+    /**
+     *
+     * @param {number} longitude easting, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -180..180
+     * @param {number}latitude northing, using the World Geodetic
+     *    System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units
+     *    of decimal degrees; -90..90
+     * @param {number} dir in degree
+     * @param {string} name of property
+     */
+    constructor(longitude: number, latitude: number, dir: number, name: string = "finish") {
+        this.longitude = longitude;
+        this.latitude = latitude;
+        this.dir = dir;
+        this.name = name;
+    }
+
+    toString(): string {
+        return new AeroflyConfigFileSet(4, "tmmission_target_plane", this.name)
+            .push("vector2_float64", "lon_lat", [this.longitude, this.latitude])
+            .push("float64", "direction", this.dir)
+            .toString();
+    }
+}

package/src/dto/AeroflyMissionsList.ts

@@ -0,0 +1,36 @@
+import { AeroflyMission } from "./AeroflyMission.js";
+
+/**
+ * @class
+ * A list of flight plans.
+ *
+ * The purpose of this class is to collect data needed for Aerofly FS4's
+ * `custom_missions_user.tmc` flight plan file format, and export the structure
+ * for this file via the `toString()` method.
+ */
+export class AeroflyMissionsList {
+    /**
+     * @property {AeroflyMission[]} missions in this mission list
+     */
+    missions: AeroflyMission[];
+
+    /**
+     * @param {AeroflyMission[]} missions in this mission list
+     */
+    constructor(missions: AeroflyMission[] = []) {
+        this.missions = missions;
+    }
+
+    /**
+     * @returns {string} to use in Aerofly FS4's `custom_missions_user.tmc`
+     */
+    toString(): string {
+        const separator = "\n// -----------------------------------------------------------------------------\n";
+        return `\
+<[file][][]
+    <[tmmissions_list][][]
+        <[list_tmmission_definition][missions][]${separator + this.missions.join(separator) + separator}        >
+    >
+>`;
+    }
+}

package/src/index.test.ts

@@ -1,14 +1,12 @@
-import {
-    AeroflyConfigFileSet,
-    AeroflyMissionsList,
-    AeroflyMission,
-    AeroflyMissionConditions,
-    AeroflyMissionConditionsCloud,
-    AeroflyMissionCheckpoint,
-    AeroflyLocalizedText,
-    AeroflyMissionTargetPlane,
-} from "./index.js";
 import { strict as assert } from "node:assert";
+import { AeroflyConfigFileSet } from "./dto/AeroflyConfigFileSet.js";
+import { AeroflyLocalizedText } from "./index.js";
+import { AeroflyMission } from "./index.js";
+import { AeroflyMissionCheckpoint } from "./index.js";
+import { AeroflyMissionConditions } from "./index.js";
+import { AeroflyMissionConditionsCloud } from "./index.js";
+import { AeroflyMissionsList } from "./index.js";
+import { AeroflyMissionTargetPlane } from "./index.js";
 
 const assertValidAeroflyStructure = (aeroflyString: string): void => {
     const openingBrackets = aeroflyString.match(/</g);