Flight Initialization API

Flight Initialization API JSON structure

The initialization JSON is structured as an object containing various keys that define different aspects of the flight. The required keys differ depending on whether you're starting a new flight or updating an existing one.

Starting a New Flight

To start a new flight, you must provide:

• Aircraft specification via the aircraft key
• A start location key (exactly one of: runway_start, ramp_start, lle_ground_start, lle_air_start, or boat_start)

All other keys are optional and will use default values if omitted.

Updating an Ongoing Flight

When updating a flight, all keys are optional. Omitted keys leave the corresponding parameters unchanged. Note that you cannot change the start location or aircraft during an update – these require starting a new flight.

Aircraft Configuration

User Aircraft

"aircraft": {
    "path": "Aircraft/Laminar Research/Cessna 172SP/Cessna_172SP.acf",
    "livery": "old_style"
}

Required fields:

• path (string) – Path to .acf file relative to X-Plane root directory

Optional fields:

• livery (string) – Name of livery subdirectory in the aircraft's liveries folder

Start Location Keys

You must specify exactly one start location type. Having multiple start keys or no start key makes the specification invalid.

Runway Start

"runway_start": {
    "airport_id": "KBOS",
    "runway": "22L",
    "final_distance_in_nautical_miles": 3.5,
    "tow_type": "tug",
    "tow_aircraft": {
        "path": "Aircraft/Laminar Research/Cessna 172/C172.acf"
    }
}

Required fields:

• airport_id (string) – Valid X-Plane airport ID
• runway (string) – Runway ID at the specified airport

Optional fields:

• final_distance_in_nautical_miles (float) – If present, starts on final approach at this distance. Otherwise starts at runway threshold
• tow_type (string) – One of "tug", "winch", or "none" (default: "none")
• tow_aircraft (object) – Aircraft specification for tow plane. Required if tow_type is "tug"

Note: You cannot specify both final_distance_in_nautical_miles and tow_type simultaneously.

Ramp Start

"ramp_start": {
    "airport_id": "KBOS",
    "ramp": "B3"
}

Required fields:

• airport_id (string) – Valid X-Plane airport ID
• ramp (string) – Name of the ramp start location at the airport

Ground Start (Lat/Lon)

"lle_ground_start": {
    "latitude": 42.23492,
    "longitude": -72.18281,
    "heading_true": 310.1
}

Required fields:

• latitude (float) – Latitude in degrees (-90 to 90)
• longitude (float) – Longitude in degrees (-180 to 180)
• heading_true (float) – True heading in degrees (0 to 360)

Air Start (Lat/Lon)

"lle_air_start": {
    "latitude": 42.120,
    "longitude": -71.20,
    "elevation_in_meters": 310,
    "heading_true": 150.0,
    "speed_in_meters_per_second": 120,
    "pitch_in_degrees": 1.2
}

Required fields:

• latitude (float) – Latitude in degrees (-90 to 90)
• longitude (float) – Longitude in degrees (-180 to 180)
• elevation_in_meters (float) – Elevation MSL in meters
• heading_true (float) – True heading in degrees (0 to 360)
• One of the following two options to specify the speed
  • speed_in_meters_per_second (float)
  • speed_enum (string) – One of "short_field_approach", "normal_approach", or "cruise"

Optional fields:

• pitch_in_degrees (float) – Aircraft pitch (default: 0)

Boat Start

"boat_start": {
    "boat_name": "carrier",
    "start_position": "catapult_1",
    "boat_location": {
        "latitude": 42.293432,
        "longitude": -69.23423
    },
    "final_distance_in_nautical_miles": 1.5
}

Required fields:

• boat_name (string) – One of "carrier" or "frigate"

Optional fields:

• start_position (string) – One of "catapult_1", "catapult_2", "catapult_3", "catapult_4", or "deck". Required for carrier deck starts. Not allowed with final_distance_in_nautical_miles
• boat_location (object) – Latitude/longitude to relocate the boat
• final_distance_in_nautical_miles (float) – If present, starts on final approach

Weight and Balance

"weight": {
    "payload_weight_in_kilograms": [100, 200, 300, 400, 500, 600, 700, 800, 900],
    "fueltank_weight_in_kilograms": [100, 200, 300, 400, 500, 600, 700, 800, 900],
    "jato_weight_in_kilograms": 500,
    "slung_load": {
        "path_to_obj": "path/to/slung/load.obj",
        "weight_in_kilograms": 100
    },
    "jettisonable_weight_in_kilograms": 250,
    "shiftable_weight_in_kilograms": 75,
    "deice_holdover_time_in_minutes": 60,
    "oxygen_pressure_in_millibars": 3000,
    "deice_fluid_in_liters": 1500,
    "external_fueltank_weight_in_kilograms": [1000, 1000]
}

Required fields:

• payload_weight_in_kilograms (array) – Up to 9 payload station weights
• fueltank_weight_in_kilograms (array) – 1-9 fuel tank weights in kilograms

Optional fields:

• jato_weight_in_kilograms (float) – JATO system weight
• slung_load (object) – Slung load specification with weight_in_kilograms and path_to_obj
• jettisonable_weight_in_kilograms (float) – Jettisonable weight
• shiftable_weight_in_kilograms (float) – Shiftable weight for control
• deice_holdover_time_in_minutes (float)
• oxygen_pressure_in_millibars (float)
• deice_fluid_in_liters (float)
• external_fueltank_weight_in_kilograms (array) – External fuel tank weights

Engine Status

"engine_status": {
    "all_engines": {
        "running": true
    }
}

Required fields:

• all_engines.running (boolean) – Whether all engines should be running or not

Weapons

"weapons": [
    {
        "index": 0,
        "filename": "AIM7-Sparrow.wpn"
    },
    {
        "index": 1,
        "filename": "AIM9-Sidewinder.wpn"
    }
]

Array of weapon loadout specifications:

• index (integer) – Hardpoint index from Plane Maker
• filename (string) – Name of .wpn file (searches aircraft folder first, then global)

Failures

"failures": {
    "fix_everything": false,
    "mean_time_between_failures_in_hours": 5000.0,
    "operation_failures": [
        {
            "name": "fuel_water",
            "status": "fail_at_speed_in_knots",
            "value": 150.0
        },
        {
            "name": "inverter0",
            "status": "fail_at_altitude_in_feet",
            "value": 5000.0
        }
    ]
}

Optional fields:

• fix_everything (boolean) – Whether to fix all systems before applying new failures (default: true)
• mean_time_between_failures_in_hours (float) – MTBF for random failures (0 = disabled)
• operation_failures (array) – Array of specific failure configurations

Each failure object contains:

• name (string) – Failure system name
• status (string) – One of: "always_work", "fail_mean_time_in_hours", "fail_exact_time_in_hours", "fail_at_speed_in_knots", "fail_at_altitude_in_feet", "fail_at_command_trigger", "inoperative"
• value (float) – Required for time/speed/altitude failure types

AI Aircraft and Traffic

AI Aircraft

"ai_aircraft": [
    {
        "aircraft": {
            "path": "Aircraft/Laminar Research/Van's Aircraft RV-10/RV-10.acf"
        },
        "mission": "atc"
    },
    {
        "aircraft": {
            "path": "Aircraft/Laminar Research/F-4 Phantom II/F-4.acf"
        },
        "mission": "combat_team_red"
    }
]

Array of AI aircraft specifications:

• aircraft (object) – Aircraft specification (see User Aircraft)
• mission (string) – One of: "atc", "combat_team_red", "combat_team_blue", "combat_team_green", "combat_team_gold"

Formation Aircraft

"formation_aircraft": {
    "path": "Aircraft/Laminar Research/Cessna 172/C172.acf"
}

Specifies an AI aircraft for formation flying. Uses the same aircraft specification format.

Incursion

"incursion": {
    "aircraft": { 
        "path": "Aircraft/Laminar Research/Boeing 737-800/b738.acf" 
    },
    "type": "runway_incursion_arm"
}

Fields:

• aircraft (object) – Aircraft specification
• type (string) – One of: "flight_incursion", "runway_incursion_arm", "runway_incursion_execute", "clear_incursion"

Environment Configuration

Date and Time

If you want to specify date and time, exactly one time configuration method must be supplied:

System Time

"use_system_time": true

Local Time

"local_time": {
    "day_of_year": 100,
    "time_in_24_hours": 15.9
}

Required fields:

• day_of_year (integer) – Day of year (0 = January 1)
• time_in_24_hours (float) – Time of day in hours (e.g., 13.5 = 1:30 PM)

GMT Time

"gmt_time": {
    "day_of_year": 100,
    "time_in_24_hours": 15.9
}

Required fields:

• day_of_year (integer) – Day of year (0 = January 1)
• time_in_24_hours (float) – Time of day in hours (e.g., 13.5 = 1:30 PM)

Time Preset

"time_enum": "sunset"

Valid values: "day", "sunset", "evening", "night"

Weather

If you want to specify new weahter, exactly one weather configuration method must be provided:

Real Weather

"weather": "use_real_weather"

Weather Scenario

"weather": {
    "definition": "vfr_few_clouds",
    "vertical_speed_in_thermal_in_feet_per_minute": 250,
    "wave_height_in_meters": 2,
    "wave_direction_in_degrees": 200,
    "terrain_state": "dry",
    "variation_across_region_percentage": 100,
    "evolution_over_time_enum": "static"
}

Required fields:

• definition (string or object) – Preset name or custom weather definition (see below)
• vertical_speed_in_thermal_in_feet_per_minute (float)
• wave_height_in_meters (float)
• wave_direction_in_degrees (float) – True heading
• terrain_state (string) – See terrain states below
• variation_across_region_percentage (float)
• evolution_over_time_enum (string) – See evolution options below

Preset definitions:

• "vfr_few_clouds"
• "vfr_scattered"
• "vfr_broken"
• "marginal_vfr_overcast"
• "ifr_non_precision"
• "ifr_precision"
• "convective"
• "large_cell_thunderstorm"

Terrain states:

• "dry", "lightly_wet", "medium_wet", "very_wet"
• "lightly_puddly", "medium_puddly", "very_puddly"
• "lightly_snowy", "medium_snowy", "very_snowy"
• "lightly_icy", "medium_icy", "very_icy"
• "lightly_snowy_and_icy", "medium_snowy_and_icy", "very_snowy_and_icy"

Evolution options:

• "rapidly_improving", "improving", "gradually_improving"
• "static"
• "gradually_deteriorating", "deteriorating", "rapidly_deteriorating"

Custom Weather Definition

"weather": {
    "definition": {
        "latitude_in_degrees": 42.2342,
        "longitude_in_degrees": -72.342423,
        "elevation_in_meters": 500,
        "visibility_in_kilometers": 10,
        "temperature_in_degrees_celsius": 15,
        "altimeter_setting_in_hpa": 1013.25,
        "precipitation_ratio": 0.5,
        "clouds": [
            {
                "type": "cumulus",
                "cover_ratio": 0.2,
                "bases_in_feet_msl": 5000,
                "tops_in_feet_msl": 8000
            }
        ],
        "wind": [
            {
                "altitude_in_feet_msl": 3000,
                "speed_in_knots": 15,
                "direction_in_degrees_true": 260,
                "gust_increase_in_knots": 10,
                "shear_in_degrees": 30,
                "turbulence_ratio": 0.2
            }
        ]
    }
}

Required fields in definition:

• latitude_in_degrees (float)
• longitude_in_degrees (float)
• elevation_in_meters (float)
• visibility_in_kilometers (float)

Optional fields in definition:

• temperature_in_degrees_celsius (float) – Default: ISA (15°C at MSL)
• altimeter_setting_in_hpa (float) – Default: 1013.25
• precipitation_ratio (float) – 0 to 1 (default: 0)
• clouds (array) – Up to 3 cloud layers
• wind (array) – Up to 13 wind layers

Cloud layer fields:

• type (string) – "cirrus", "stratus", "cumulus", or "cumulunimbus"
• cover_ratio (float) – 0 to 1
• bases_in_feet_msl (float)
• tops_in_feet_msl (float)

Wind layer fields:

• altitude_in_feet_msl (float) – Required
• speed_in_knots (float) – Required
• direction_in_degrees_true (float) – Required
• gust_increase_in_knots (float) – Optional
• shear_in_degrees (float) – Optional
• turbulence_ratio (float) – 0 to 1, optional

Error Handling

The API returns specific error codes to help you handle different failure scenarios:

Error Codes

• xplm_Init_Success (0) – Operation completed successfully
• xplm_Init_Invalid (1) – Invalid JSON or validation rule violation
• xplm_Init_MissingAircraft (2) – Specified aircraft not found
• xplm_Init_MissingLivery (3) – Specified livery not found
• xplm_Init_MissingAirport (4) – Specified airport not found
• xplm_Init_MissingRamp (5) – Specified ramp start not found
• xplm_Init_MissingRunway (6) – Specified runway not found

When an error occurs, detailed diagnostic information is sent to the XPLMError callback (if installed) or to the log file. This information includes human-readable descriptions to aid debugging.

Examples

Here's a minimal example that starts the Boeing 737-800 at a ramp position at Portland International Airport:

{
    "ramp_start": {
        "airport_id": "KPDX",
        "ramp": "A1"
    },
    "aircraft": {
        "path": "Aircraft/Laminar Research/Boeing 737-800/b738.acf"
    }
}

This example uses only the required fields. The aircraft will be loaded with default fuel and payload, engines off, at the current system time and weather. You can add any of the optional configuration fields described above to customize the initialization further.

Here's a more completely specified flight starting at Boston Logan International Airport:

{
    "runway_start": {
        "airport_id": "KBOS",
        "runway": "22L"
    },
    "aircraft": {
        "path": "Aircraft/Laminar Research/Cessna 172SP/Cessna_172SP.acf",
        "livery": "default"
    },
    "weight": {
        "payload_weight_in_kilograms": [80, 80, 0, 0, 0, 0, 0, 0, 0],
        "fueltank_weight_in_kilograms": [50, 50, 0, 0, 0, 0, 0, 0, 0]
    },
    "engine_status": {
        "all_engines": {
            "running": true
        }
    },
    "local_time": {
        "day_of_year": 150,
        "time_in_24_hours": 14.5
    },
    "weather": {
        "definition": "vfr_scattered",
        "vertical_speed_in_thermal_in_feet_per_minute": 200,
        "wave_height_in_meters": 1.5,
        "wave_direction_in_degrees": 180,
        "terrain_state": "dry",
        "variation_across_region_percentage": 50,
        "evolution_over_time_enum": "static"
    }
}

Best Practices

• Validate your JSON – Use a JSON validator before passing data to the API
• Check return codes – Always check the XPLMInitResult return value
• Install an error callback – Register an XPLMError callback to receive detailed error messages
• Test with default aircraft – Start development with Laminar Research default aircraft to ensure proper configuration
• Handle missing resources gracefully – Be prepared for users who may not have certain aircraft or scenery installed
• Use appropriate units – Pay close attention to units in field names (meters vs feet, knots vs m/s, etc.)
• Start simple – Begin with minimal required fields and add complexity gradually