File Format Specification Archives

Airport Data (apt.dat) 12.00 File Format Specification

Revision History

20 Dec 2023     Minor addtion of options and values added by 11.30 through 12.00
7 Nov 2022      Minor corrections for  X-Plane 12 early access.
1 May 2022      Add row codes 1402, 1501 for custom service trucks & jetways

16 Nov 2021     Spec created, based upon most recent apt.dat 11.30 spec.
                Add new surface types for runways, taxiways, helipads.
                Add property extensions for runway markings and lights.
                New row code 1500 for moving jetways.
16 Nov 2021     Updated new lines styles added in 11.30, correct wording in row code 21 name field
11 Apr 2019     Updated with new COM frequency capabilities added in 11.30.
14 Feb 2018     Minor corrections to Definition of Data fields
25 Jan 2017     Spec created, based upon prior apt.dat 1050 spec.

Applicability

This specification (APT.DAT 1200) is supported in X-Plane 12.00 and later and by WorldEditor 2.5 and later. The prior specification for airport data was APT.DAT 1130, which is recommended for X-Plane 11.30+.

This spec is an extension to 1130 – all features in 1130 are fully supported.

Support for Deprecated File Formats

The deprecated file specifications (APT.DAT 1050, 1000) are still supported. A dwindling quantity of custom airport data exists only in this format. So airports defined according to these specifications can be included in a file otherwise complying with the most recent specification.

Overview & Scope

This specification defines core airport data for X-Plane. This includes the locations of runways, taxiway and apron pavement, basic airport ‘furniture’ (VASI/PAPIs, windsocks, light beacons and taxiway signage) and communications frequencies. It also includes attributes for each of these features to fully describe them (eg. it includes runway surface type, runway markings, taxiway lighting and markings, approach lighting, taxiway sign text, etc).

This specification (1200) introduces new surface types, extensions for runway markings & lights, and new row codes.

This specification does not include scenery objects (such as buildings, static aeroplanes or underlying terrain textures).

Basic concepts

Latitudes and longitudes are described in a decimal notation (eg. 20.12345678) up to 8 decimal places.
- A latitude of 50 degrees 30 minutes south would be defined as -50.50000000
North latitudes and east longitudes are positive. South latitudes and west longitudes are negative.
All headings are referenced to true north (not magnetic north).

File Characteristics

The apt.dat files are plain text files:

Fields in the data can be separated by one or more white space characters (space, tab).
- By default, the files are generated so that columns of data are consistently aligned, but this is not required.
Blank rows are permitted and are helpful to differentiate between airports.
Comments are permitted and are indicated by “#” as the first two characters of a row.

File Structure

It is recommended that all airports be created in WorldEditor (“WED”). This will ensure that all structural requirements listed here for airport data are met. WED version 2.5 is required to support all the features in this spec.

In common with most other X-Plane data file specification, header rows of data define the origin of a particular copy of a file, and define the file specification version. The file specification may be followed by a reference to a sequential release data cycle and build number for the data, and a version information message:

I
1000 Version – written by WorldEditor 2.5.0r2

Each row of data has a numeric ‘row code’ as its first field, to define its content.

The top level of this hierarchy defines an individual airport, defined by an airport header row (a row code of ‘1’, ‘16’ or ‘17’).
Subsequent rows define elements of an airport:
- Runways (including helipads) follow the airport header row (one row per runway).
- Pavement (taxiway/apron) definitions have a header row followed by an ordered list of nodes that define its boundaries:
  - Each pavement definition must each have a single boundary with no overlaps with itself.
  - Nodes on this outer boundary must be defined in a counter-clockwise direction.
  - Boundaries must be terminated with a node with a row code ‘113’ or ‘114’.
  - Pavement definitions may overlap with another pavement chunk. But this is not recommended – instead consider precise alignment of adjacent features by ‘snapping’ nodes to identical locations in World Editor (WED).
    - A pavement definition can never overlap with itself.
      - The sequencing of the pavement definitions is the layering in which they will be rendered in X-Plane, top-down. So the last piece of pavement in the file will be rendered underneath any others with which it overlaps.
      - Holes can be defined for pavement (through which the underlying terrain texture will show):
        
        Hole boundaries should follow the termination of the pavement definition in which the hole occurs (starting with a row type ‘111’ or ‘112’).
        
        Hole boundaries are defined in a clockwise direction (ie, opposite direction to the boundary nodes).
        
        Hole boundaries must form a closed loop (ie. must terminate with a row code ‘113’ or ‘114’).
        
        Each pavement definition can have zero, one or multiple hole boundaries.
        
        Hole boundaries must be contained within the outer boundary of the pavement definition.
        
        Holes cannot overlap each other.
        
        After creating a hole boundary, it can be ‘filled’ with a new pavement chunk (probably using a different surface type).
        
        Linear features also have a header row followed by an ordered list of nodes that define the line:
        
        Linear features can be closed loops (terminating in a node of type ‘113’ or ‘114’) or just strings (terminating with ‘115’ or ‘116’).
        
        An airport boundary is defined with nodes in a counter-clockwise direction. A boundary can contain holes (see above) and must form a closed loop (terminating in a node of type ‘113’ or ‘114’).
        
        Airport traffic flows have a header row (row code ‘1000’) followed by multiple rows that define rules of multiple classes (time, wind direction, ceiling, visibility, runway in use, VFR traffic pattern) that indicated that a flow should be used (wind rules, minimum ceiling rules, visibility rules, time rules, and operations rules).
        
        A flow is acceptable if any rule of a class is acceptable, or if there are no rules of a given class. So to permit a flow with no time restrictions, simply exclude any traffic time rules (row code ‘1004’).
        
        Rules use ‘or’ logic. For example, a flow may have two wind rules (row code ‘1001’) – one for slight winds very generally aligned with a runway, and one with strong winds only if they are almost exactly with the runway.
        
        A flow will be used only if all its rule classes are ‘passed’.
        
        The flows are evaluated in sequence. The first flow to ‘pass’ will be used. So, the most specific-but-useful rule should be listed first (eg. parallel VFR approaches on a clear, calm day) and the most general (but least useful) rules should be listed last (eg. a single ILS cat III approach to a single runway).
        
        If the rules prevent any defined flow from being ‘passed’ then X-Plane’s AI engine will create a flow.
        
        ‘Runway in use’ rules (row code 1100) are also evaluated in sequence. The first ‘runway in use’ rule to ‘pass’ will be used for the parent flow. So rules should be listed in preferential sequence.
        
        Airport taxi routes & networks begin with a row code ‘1200’ and are defined by a set of nodes (row code ‘1201’) and ‘edges’ (the taxi routing) that connect two nodes (row code ‘1202’):
        
        Nodes can be defined as ‘init’ (a point at which X-Plane will try to start a taxi route), ‘end’ (where X-Plane will try to end a taxi route), or ‘both’. ‘junc’ can also be used for junctions between taxi routes.
        
        Edges must specify an allowed width, sizes A-E, and may be followed by multiple rows (row code ‘1204) defining an ‘active zone’ ‘for that parent edge (eg. if the edge conflicts with arrival or departure runways, or an ILS-critical area).
        
        Taxi routings begin or end at ramp locations (row code ‘1300’), which are also available as startup-locations in X-Plane. These locations may not be directly connected to the taxi route network – X-Plane’s ATC engine will calculate how to direct an airplane between the taxi route network and each location.
        
        Ground truck route edges (row code ‘1206’), parking locations (row code ‘1400’), and destinations (row code ‘1401’) are included under row code header ‘1200’ for taxi networks.
        
        Other airport features are defined with one row for each feature.

The file is terminated by a ‘99’:

Row Codes

Each row of data begins with an integer code that defines the type of data:

Row Code	Meaning	Comment

1	Land airport header
16	Seaplane base header
17	Heliport header

100	Runway
101	Water runway
102	Helipad

110	Pavement (taxiway or ramp) header	Must form a closed loop
120	Linear feature (painted line or light string) header	Can form closed loop or simple string
130	Airport boundary header	Must form a closed loop

111	Node	All nodes can also include a “style” (line or lights)
112	Node with Bezier control point	Bezier control points define smooth curves
113	Node with implicit close of loop	Implied join to first node in chain
114	Node with Bezier control point, with implicit close of loop	Implied join to first node in chain
115	Node terminating a string (no close loop)	No “styles” used
116	Node with Bezier control point, terminating a string (no close loop)	No “styles” used

14	Airport viewpoint	One or none for each airport
15	Aeroplane startup location	* Convert these to new row code 1300 *
18	Airport light beacon	One or none for each airport
19	Windsock	Zero, one or many for each airport
20	Taxiway sign (inc. runway distance-remaining signs)	Zero, one or many for each airport
21	Lighting object (VASI, PAPI, Wig-Wag, etc.)	Zero, one or many for each airport

1000	Airport traffic flow	Zero, one or many for an airport. Used if following rules met (rules of same type use ‘or’ logic, rules of a different type use ‘and’ logic). First flow to pass all rules is used.
1001	Traffic flow wind rule	Zero, one or many for a flow. Multiple rules use ‘or’ logic.
1002	Traffic flow minimum ceiling rule	Zero or one rule for each flow
1003	Traffic flow minimum visibility rule	Zero or one rule for each flow
1004	Traffic flow time rule	Zero, one or many for a flow. Multiple rules use ‘or’ logic.
1100	Runway-in-use arrival/departure constraints, 10kHz frequency resolution	First constraint met is used. Sequence matters!
1110	Runway-in-use arrival/departure constraints, 1kHz frequency resolution	Alternate option to row code 1100.
1101	VFR traffic pattern	Zero or one pattern for each traffic flow

1200	Header indicating that taxi route network data follows
1201	Taxi route network node	Sequencing must be 0 based, ascending by ID. Must be part of one or more edges.
1202	Taxi route network edge	Must connect two nodes
1204	Taxi route edge active zone	Can refer to up to 4 runway ends
1205	Taxi route edge control	Replaces 1203
1206	Taxi route edge	Ground vehicles only

1300	Start up location (deprecates code 15)	Not explicitly connected to taxi route network
1301	Start up location metadata	Consists of an ICAO width code, an operations type code and zero or more space separated 3-letter airline codes
1302	Airport identification metadata	Zero, one or many for each airport

1400	Truck Parking Location	Not explicitly connected to taxi route network
1401	Truck Destination Location	Must not allow car pile ups due to bad one way designs
1402	Custom Truck Objects	Overrides objects used in last preceeding 1500 rowcode

1050 –1056	8.33kHz communication frequencies (11.30+)	Zero, one or many for each airport
50 – 56	Legacy 25kHz communication frequencies	Zero, one or many for each airport. Ignored if row codes 1050-1056 exist.

1500	Active jetway
1502	Custom Jetway Objects	Overrides objects used in last preceeding 1500 rowcode

Example Data

Here is some example data for KBFI. It is not real and is very incomplete, but it illustrates examples of most types of data found in an apt.dat file. This data includes an airport header, runway, water runway, helipad, PAPI, taxiway definition, painted line, viewpoint, startup location, light beacon, windsock, taxiway sign and an ATC communications frequency:

1 21 1 0 KBFI Boeing Field King Co Intl

100 29.87 1 0 0.15 0 2 1 13L 47.53801700 -122.30746100 73.15 0.00 2 0 0 1 31R 47.52919200 -122.30000000 110.95 0.00 2 0 0 1

101 49 1 08 35.04420900 -106.59855700 26 35.04420911 -106.59855711

102 H1 47.53918248 -122.30722302 2.00 10.06 10.06 1 0 0 0.25 0

21 47.53666659 -122.30585255 2 150.28 3.30 13L PAPI-2L

110 1 0.25 150.29 A2 Exit

111 47.53770968 -122.30849802

111 47.53742819 -122.30825844 3

112 47.53752190 -122.30826710 47.53757385 -122.30824831 3 102

114 47.53768630 -122.30834929 47.53768690 -122.30838150 3 102

120 Line B1

111 47.53969864 -122.31276189 51

111 47.53977825 -122.31255145 1

115 47.54002296 -122.31189878

14 47.52917900 -122.30434900 100 0 ATC Tower

15 47.52926674 -122.29919589 304.16 A8 Run Up

18 47.52920400 -122.30412800 1 BCN

19 47.53900921 -122.30868700 1 WS

20 47.54099177 -122.31031317 235.71 0 2 {@L}A1{@R}31R-13L

50 12775 ATIS

Here is some example data for KSEA showing the 1000 version traffic flow and taxi route data:

1000 Calm and South flow

1001 KSEA 000 359 5

1001 KSEA 070 250 999

1002 KSEA 0

1003 KSEA 0

1004 0000 2400

1100 16C 11920 arrivals jets|turboprops|props 160340 161161 Arrival 16C

1100 16R 11920 arrivals jets|turboprops|props 341159 161161 Arrival 16R

1100 16L 11920 arrivals heavy 000359 161161 Arrival Heavy Jets

1101 16R right

1200

1201 47.46360812 -122.30613338 both 5416 A_stop

1202 5258 5266 twoway taxiway B

1204 ils 34R

1300 47.43931757 -122.29806851 88.78 gate jets|turboprops A10

Here is some example data for KSEA showing the 1050 metadata and 1100 ground truck additions:

1302 city Seattle

1302 country United States

1302 datum_lat 47.449888889

1302 datum_lon -122.311777778

1302 faa_code SEA

1302 iata_code SEA

1302 icao_code KSEA

1206 107 11 twoway C

1300 47.44158755 -122.30116873 44.78 gate jets A3

1301 D airline dal

1400 47.44374472 -122.30463464 88.1 baggage_train 3 Svc Baggage

1401 47.44103438 -122.30382493 0.0 baggage_train Luggage Train Destination South 2

Definition of Data Fields

Each column in each row code is defined below, using the example data from KBFI & KSEA shown above. Note that:

Some row codes store data in an identical specification, and these have been grouped together in the table below.
The specification aims to be consistent. For example, the format or latitudes and longitudes is always the same, and all headings/orientations are defined as true (not magnetic) degrees.

Row	Meaning	Comment
		Explanation	Valid values

1	Land airport header	Row codes 1, 16 and 17 share a common format (see below)
16	Seaplane base header	Row codes 1, 16 and 17 share a common format (see below)
17	Heliport header	Row codes 1, 16 and 17 share a common format (see below)
	1	Row code for an airport, seaplane base or heliport	1, 16 or 17
	21	Elevation of airport in feet above mean sea level (AMSL)
	1	Deprecated. Use default value (“0”)	Use 0
	0	Deprecated. Use default value (“0”)	Use 0
	KBFI	Airport Identifier. X-Plane internal use only, not used for user-facing functions, NOT used to determine the “ICAO code” by X-Plane >10.45.. See rowcode 1302. Use X + local identifier to create fictional on not Sceney gateway coordinates ID’s.	Maximum seven characters. Must be unique and all upper case.
	Boeing Field King Co …	Airport name. May contain spaces.	Text string (up to 40 characters)

100	Land Runway
	100	Row code for a land runway (the most common)	100
	29.87	Width of runway in metres	Two decimal places recommended. Must be >= 1.00
	1	Code defining the surface type (concrete, asphalt, etc)	Integer value for a Surface Type Code (see below)
	206
(= 2x 100 + 6)	Code defining a runway shoulder surface type + 100x width of each shoulder in whole meters.	See Surface Type Code below – all asphalt and concrete styles supported.
If the number is >100, the 100-digit (and optionally 1000-digit) define the width of the shoulder in meters.
If the number is <100 (i.e. only the surface code), width is same as X-Plane 11, scaling with runway tpe and width, some 3-5 meters.
	0.15	Runway smoothness (not used by X-Plane yet)	0.00 (smooth) to 1.00 (very rough). Default is 0.25
	0	Runway centre-line lights	0=no centerline lights, 1=centre line lights
	2	Runway edge lighting (also implies threshold lights)	0=no edge lights, 2=medium intensity edge lights
	1	Auto-generate distance-remaining signs (turn off if created manually)	0=no auto signs, 1=auto-generate signs
	The following fields are repeated for each end of the runway
	13L	Runway number (eg. “31R”, “02”). Leading zeros are required.	Two to three characters. Leading zero’s are printed, if present.
Valid suffixes: “L”, “R”, “C” (visible in markings on paved surfaces)
Suffixes “W”, “S” and “T” are valid, but never printed.
	47.53801700	Latitude of runway end (on runway centerline) in decimal degrees	Eight decimal places supported
	-122.30746100	Longitude of runway end (on runway centerline) in decimal degrees	Eight decimal places supported
	73.15	Length of displaced threshold in metres (this is included in implied runway length)A displaced threshold will always be inside (between) the two runway ends	Two decimal places (metres). Default is 0.00
	0.00	Length of overrun/blast-pad in metres (not included in implied runway length)	Two decimal places (metres). Default is 0.00
	2	Code for runway markings (Visual, non-precision, precision)	Integer value for Runway Marking Code (see below)
	0	Code for approach lighting for this runway end	Integer value for Approach Lighting Code (see below)
	0	Flag for runway touchdown zone (TDZ) lighting	0=no TDZ lighting, 1=TDZ lighting
	1	Code for Runway End Identifier Lights (REIL)	0=no REIL, 1=omni-directional REIL, 2=unidirectional REIL,

101	Water runway
	101	Row code for a water runway	101
	49	Width of runway in metres	Two decimal places recommended. Must be >= 1.00
	1	Flag for perimeter buoys	0=no buoys, 1=render buoys
	The following fields are repeated for each end of the water runway
	08v	Runway number. Not rendered in X-Plane (it’s on water!)	Valid suffixes “W” (or blank)
	35.04420911	Latitude of runway end (on runway centerline) in decimal degrees	Eight decimal places supported
	-106.59855711	Longitude of runway end (on runway centerline) in decimal degrees	Eight decimal places supported

102	Helipad
	102	Row code for a helipad	101
	H1	Designator for a helipad. Must be unique at an airport.	Usually “H” suffixed by an integer (eg. “H1”, “H3”)
	47.53918248	Latitude of helipad centre in decimal degrees	Eight decimal places supported
	-122.30722302	Longitude of helipad centre in decimal degrees	Eight decimal places supported
	2.00	Orientation (true heading) of helipad in degrees	Two decimal places recommended
	10.06	Helipad length in metres	Two decimal places recommended (metres), must be >=1.00
	10.06	Helipad width in metres	Two decimal places recommended (metres), must be >= 1.00
	1	Helipad surface code	Integer value for a Surface Type Code (see below)
	0	Helipad markings	0 (other values not yet supported)
	0	Code defining a helipad shoulder surface type	0=no shoulder, 1=asphalt shoulder, 2=concrete shoulder
	0.25	Helipad smoothness (not used by X-Plane yet)	0.00 (smooth) to 1.00 (very rough). Default is 0.25
	0	Helipad edge lighting	0=no edge lights, 1=yellow edge lights

110	Pavement (taxiways)	Defines an arbitrary pavement shape
	110	Row code for a pavement chunk header (must be followed by a set of nodes)	110
	1	Code defining the surface type (concrete, asphalt, etc)	Integer value for a Surface Type Code (see below)
	0.25	Runway smoothness (not used by X-Plane yet)	0.00 (smooth) to 1.00 (very rough). Default is 0.25
	150.29	Orientation (true degrees) of pavement texture ‘grain’	Two decimal places recommended
	A2 Exit	Description of pavement chunk (not used by X-Plane)	Text string

120	Linear feature	Painted surface markings & light strings
130	Airport boundary	Boundary for future terrain ‘flattening’
	120	Row code for a linear feature or airport boundary	120 or 130
	Line B1	Description of feature or boundary (not used by X-Plane)	Text string

111	Node	Node (plain)
112	Node	Node with Bezier control point
113	Node	Node (close loop), to close boundary
114	Node	Node (close loop) with Bezier control point
115	Node	Node (end) to terminate a line
116	Node	Node (end) with Bezier control point
	112	Row code for a node. First node must follow an appropriate header row	111 thru 116
	47.53752190	[All nodes] Latitude of node in decimal degrees	Eight decimal places supported
	-122.30826710	[All nodes] Longitude of node in decimal degrees	Eight decimal places supported
	47.53757385	[112, 114, 116 only] Latitude of Bezier control point in decimal degrees	Eight decimal places supported. Ignore for 111, 113, 115
	-122.30824831	[112, 114, 116 only] Latitude of Bezier control point in decimal degrees	Eight decimal places supported. Ignore for 111, 113, 115
	3	[Not for 115 or 116] Code for painted line type on line segment starting at this node	Integer Line Type Code (see below). Not for 115 or 116
	102	[Not for 115 or 116] Code for lighting on line segment starting at this node	Integer Line Type Code (see below). Not for 115 or 116

14	Viewpoint	Maximum of one viewpoint for each airport
	14	Row code for a viewpoint	14
	47.52917900	Latitude of viewpoint in decimal degrees	Eight decimal places supported
	-122.30434900	Longitude of viewpoint in decimal degrees	Eight decimal places supported
	100	Height (in feet) of viewpoint above ground level	Integer
	0	Code deprecated. Use ‘0’	0
	ATC Tower	Name of viewpoint (not used by X-Plane)	Descriptive text string (optional)

15	Startup location	Startup locations for airplanes at an airport	Should be converted to new row code 1300
	15	Row code for a startup location	15
	47.52926674	Latitude of startup location in decimal degrees	Eight decimal places supported
	-122.29919589	Longitude of startup location in decimal degrees	Eight decimal places supported
	304.16	Heading (true) of an aeroplane when positioned at startup location	Two decimal places recommended
	A6 Run Up	Name of startup location (list will be displayed in X-Plane for each airport)	Short descriptive text string – ten characters or less

18	Light beacon	Maximum of one beacon for each airport
	18	Row code for an airport light beacon	18
	47.52920400	Latitude of beacon in decimal degrees	Eight decimal places supported
	-122.30412800	Longitude of beacon in decimal degrees	Eight decimal places supported
	1	Code for type of light beacon. Determines colors of beacon.	Integer Beacon Type Code (see below)
	BCN	Name of viewpoint (not used by X-Plane)	Descriptive text string (optional)

19	Windsock	Multiple windsocks permitted for each airport
	19	Row code for a windsock	19
	47.53900921	Latitude of windsock in decimal degrees	Eight decimal places supported
	-122.30868700	Longitude of windsock in decimal degrees	Eight decimal places supported
	1	Flag for windsock lighting	0=unlit, 1=illuminated
	WS	Name of viewpoint (not used by X-Plane)	Descriptive text string (optional)

20	Signs	Taxiway signs or runway distance-remaining signs
	20	Row code for a sign	20
	47.54099177	Latitude of sign in decimal degrees	Eight decimal places supported
	-122.31031317	Longitude of sign in decimal degrees	Eight decimal places supported
	235.71	Orientation of sign in true degrees (heading of someone looking at sign’s front)	Two decimal places recommended
	0	Reserved for future use. Ignore.	0
	2	Code for sign size	Integer Sign Size Code (see below)
	{@L}A1{@R}31R-13L	Text to be rendered on sign front and/or back	Text string formatted by Sign Text Definition (see below)

21	Lighting objects	VASI, PAPI, wig-wags, etc.
	21	Row code for a lighting object	21
	47.53666659	Latitude of lighting object in decimal degrees	Eight decimal places supported
	-122.30585255	Longitude of lighting object in decimal degrees	Eight decimal places supported
	2	Code for type of lighting object	Integer Lighting Object Code (see below)
	150.28	Orientation of lighting object in true degrees (looking toward object)	Two decimal places recommended
	3.30	Visual glideslope angle in degrees	Two decimal places. 0.00 if not required. Default is 3.00
	PAPI-2L	Name of lighting object (not used by X-Plane]	Short text string (optional)

1000	Traffic flow	Arrival and departure traffic flows
	1000	Row code for an arrival/departure traffic flow	1000
	Calm and south flows	Traffic flow name	Descriptive name (max 50 characters)

1001	Traffic flow wind rule	Zero or multiple wind rules permitted per flow
	1001	Row code for a traffic flow wind rule	1001
	KSEA	METAR reporting station (may be a remote airport, eg KSEA for KBFI)	ICAO code, up to 7 characters
	000	Wind direction minimum (magnetic)	000 – 359
	359	Wind direction maximum (magnetic)	000 – 359
	5	Maximum wind speed. Use 999 for ‘all’ wind speeds.	0 – 999

1002	Traffic flow ceiling rule	Zero or one ceiling rule permitted per flow
	1002	Row code for a traffic flow ceiling rule	1002
	KSEA	METAR reporting station (may be a remote airport, eg KSEA for KBFI)	ICAO code, up to 7 characters
	0	Minimum reported ceiling in feet AGL at reporting station	Positive integer

1003	Traffic flow visibility rule	Zero or one visibility rule permitted per flow
	1003	Row code for a traffic flow visibility rule	1003
	KSEA	METAR reporting station (may be a remote airport, eg KSEA for KBFI)	ICAO code, up to 7 characters
	0	Minimum reported visibility in statute miles	Float (eg. “1.5”)

1004	Traffic time rule	Zero or multiple time rules permitted per flow
	1004	Row code for a traffic flow time rule	1004
	0000	UTC time from which rule is valid	0000 – 2400
	2400	UTC time at which rule ends	0000 – 2400

1100	Runway-in-use rule	Multiple rules for each flow. First to ‘pass’ is used
	1100	Row code for a runway-in-use rule	1100
	34C	Runway end identifier	Two to three characters. Valid suffixes: “L”, “R” or “C” (or blank)
	11920	Arrival or departure frequency	Five digit integer, rounded DOWN where necessary. 10kHz resolution only.
	arrivals	Rule type (arrivals, departures)	Pipe separated list (“
	jets	turboprops	Airplane types to which rule applies
	181359	On course heading range ((ie. first leg of flight plan for departures, last leg for arrivals)	000000 – 359359
	341341	Initial ATC assigned departure heading range. Not used for arrivals.	000000 – 359359
	Arrival 34C	Rule name	Descriptive name (max 50 characters)

1110	Runway-in-use rule	Replaces 1100 row code, supports 8.33kHz radio frequencies. Multiple rules for each flow. First to ‘pass’ is used.
	1110	Row code for a runway-in-use rule	1110
	34C	Runway end identifier	Two to three characters. Valid suffixes: “L”, “R” or “C” (or blank)
	118325	Arrival or departure frequency	Six digit integer, rounded DOWN where necessary, 1kHz resolution
	arrivals	Rule type (arrivals, departures)	Pipe separated list (“
	jets	turboprops	Airplane types to which rule applies
	181359	On course heading range ((ie. first leg of flight plan for departures, last leg for arrivals)	000000 – 359359
	341341	Initial ATC assigned departure heading range. Not used for arrivals.	000000 – 359359
	Arrival 34C	Rule name	Descriptive name (max 50 characters)

1101	VFR pattern rule	Zero or one VFR pattern rule permitted per flow
	1101	Row code for a VFR traffic pattern	1101
	34L	Runway end identifier	Two to three characters. Valid suffixes: “L”, “R” or “C” (or blank)
	left	VFR traffic pattern direction	“left” or “right”

1200	Taxi routing network	(for readability only)

1201	Taxi routing node	All nodes must be used in at least one edge
	1201	Row code for taxi routing network node	1201
	47.53752190	Latitude of node in decimal degrees	Eight decimal places supported
	-122.30826710	Longitude of node in decimal degrees	Eight decimal places supported
	both	Usage of node in network (begin or end a taxi path, or both)	“dest”, “init”, “both” or “junc”
	5416	Node identifier (defined in 0 based sequence, ascending)	Integer. Must be unique within scope of an airport.
	A_start	Node name. Not currently used.	String (max 16 characters)

1202	Taxi routing edge	Segment in taxi routing network
	1202	Row code for taxi routing network edge	1202
	5416	Node identifier for start of edge	Integer. Must refer to valid node (row code ‘1201’)
	5417	Node identifier for end of edge	Integer. Must refer to valid node (row code ‘1201’)
	twoway	Edge can be used in both directions	“twoway” or “oneway”
	taxiway_a	Edge ATC restrictions. If “runway” a clearance is needed from ATC. If “taxiway_a” the trailing single letter denotes maximum wingspan for aircraft routed on that taxiway.	“runway” or
”taxiway_”
with = a	b	c	d
	A	Taxiway identifier. Used to build ATC taxi clearances (eg. “.. .taxi via A, T, Q”)	String. Taxiway or runway identifier (eg. “A” or “16L/34R”)

1204	Edge active zone	Identifies an edge as in a runway active zone.
	1204	Row code for an edge entering a runway active zone	1204
	arrival	Active zone classification	“arrival” or “departure” or “ils”
	16L,16C	Runway(s) to which active zone refers	Comma-separated list up to 4 runway identifies

1206	Taxi routing edge (ground vehicles)	Segment in taxi routing network (ground vehicles only)
	1206	(See 1202)	(See 1202)
	107	(See 1202)	(See 1202)
	11	(See 1202)	(See 1202)
	twoway	(See 1202)	(See 1202)

1300	Start up location	Start or end point for aircraft. Not linked to taxi routing network by edges (row code 1202)
	1300	Row code for taxi route start/end point	1300
	47.44158755	Latitude of location in decimal degrees	Eight decimal places supported
	-122.30116873	Longitude of location in decimal degrees	Eight decimal places supported
	44.78	Heading (true) of airplane positioned at this location	Decimal degrees, true heading
	gate	Type of location	“gate”, “hangar”, “misc” or “tie-down”
	jets	Airplane types that can use this location	Pipe-separated list (“
	A3	Unique name of location	Text string, must be unique within a single airport

1301	Row Code	For ramp start metadata
	1301		1301
	d	ICAO width code	A, B, C, D, E, F
	airline	Operation type	none, general_aviation, airline, cargo, military
	dal	Airline permitted to use this ramp	3-letter airline codes (AAL, SWA, etc)

1302	Row Code	Airport metadata
	1302	row code	Takes zero, any or all applicable Key_values
	icao_id	key_value for ICAO code	icao_id, faa_id, iata_id, city_id, country_id, region_id, local_id, local_authorithy, transition_alt_,_ transition_level, gui_3d, is_oilrig, allows_circuits
	KSEA	ICAO for airport	Unique identifier up to 7 characters long

1400	Truck Parking
	1400	row code
	47.44374472	Latitude of location in decimal degrees	Eight decimal places supported
	-122.30463464	Longitude of location in decimal degrees	Eight decimal places supported
	88.1	Heading (true) of the OBJ positioned at this location	Decimal degrees
	baggage_train	type string	baggage_loader, baggage_train, crew_car, crew_ferrari, crew_limo, pushback, fuel_liners, fuel_jets, fuel_props, food, gpu
	3		0 to 10 if type is baggage_train, 0 if not
	Svc Baggage	Name of parking	Text string

1401	Truck Destination
	1401	row code
	47.44103438	Latitude of location in decimal degrees	Eight decimal places supported
	-122.30382493	Longitude of location in decimal degrees	Eight decimal places supported
	0.0	Heading (true) of the positioned at this location	Decimal Degrees, true heading
	baggage_train	Truck types allowed to end up at this destination	Pipe separated list (“
	Luggage Train Destination South 2	Name of Truck Destination	Text string
1402	Custom service truck
	myLib/myCrewCar.obj	vpath to custom object to replace default object for vehicle in in last 1400 row code preceding this	If vpath is not defined, this rowcode is silently ignored and the last preceeding 1400 record keeps using the default vehicle.

1050	ATC – Recorded	AWOS, ASOS or ATIS
1051	ATC – Unicom	Unicom (US), CTAF (US), Radio (UK)
1052	ATC – CLD	Clearance Delivery
1053	ATC – GND	Ground
1054	ATC – TWR	Tower
1055	ATC – APP	Approach
1056	ATC – DEP	Departure
	1052	Row code for ATC COM Frequency	Supercedes row codes 50-56.
	128730	Frequency in kHz, 833kHz capable radio channels only	118000 – 135995
	ATIS	Descriptive name (displayed on X-Plane charts)	Short text string (10 characters or less recommended)

50	ATC – Recorded	AWOS, ASOS or ATIS
51	ATC – Unicom	Unicom (US), CTAF (US), Radio (UK)
52	ATC – CLD	Clearance Delivery
53	ATC – GND	Ground
54	ATC – TWR	Tower
55	ATC – APP	Approach
56	ATC – DEP	Departure
	51	Row code for an ATC COM frequency	50 thru 56 (see above)
	12775	Frequency in MHz x 100 (eg. use “12322” for 123.225MHz)	Five digit integer, rounded DOWN where necessary
	ATIS	Descriptive name (displayed on X-Plane charts)	Short text string (recommend less than 10 characters)

1500	Active jetway
	46.512345	Latitude of location in decimal degrees	Location of base of telescoping jetway tunnel
	-123.00345	Longitude of location in decimal degrees
	42.0	Heading of parked tunnel	Decimal Degrees, true heading
	0	Jetway style code	0 = light color, solid (metal) sidewalls
1= light color, glass side walls
2 = dark color, solid (metal) sidewalls
3 = dark color, glass side walls
	2	Jetway size code	0 = tunnel length 11 – 23m
1 = tunnel length 14 – 29m
2 = tunnel length 17 – 38m
3 = tunnel length 20 – 47m
	0	Do not use or change	not used, in X-Plane 12.00
	17.5	Parked tunnel length	In meters, must be within the extension capabilities according to the size code
	127.3	Parked cabin heading	True north heading. Must be within the articulating capabilities of the jetway, which is from 0 to 90 degrees counter clockwise from the heading of the tunnel.
1501	Custom jetway
	myLib/myJWgate8.obj	vpath to custom cabin/tunnel object for replace LR default object in last 1500 row code preceeding this	If vpath is not defined, this rowcode is silently ignores and the – default cabin/tunnel object is used as for the last preceding 1500 record

Codes

Codes used to define airport data:

Codes	Comment
Code value	Code meaning	Code applicability
Surface Type Code	Surface type of runways or taxiways
1	Asphalt
2	Concrete
3	Turf or grass
4	Dirt (brown)
5	Gravel (grey)

12	Dry lakebed (eg. At KEDW)	Example: KEDW (Edwards AFB)
13	Water runways (do not use in XP10+, use rowcode for “sealane” instead)
14	Snow or ice	Poor friction. Runway markings cannot be added.
15	Transparent	Hard surface, but no texture/markings (use in custom scenery)

20-23	Light colored asphalt	Each “shade” of asphalt comes in 4 different subtypes differing in cracks, seams or dirt added to the base texture.The first subtype adds a moderate amount of seams, representing mid-aged asphalt that has not been repaired.
The 2nd subtype adds dark, patched cracks, indicative of older, but well maintained asphalt.
The 3rd subtype is “plain”, intended for manual additions of particular cracks & seams as a separate layer on top.
The 4th subtype adds more cracked and discolored areas, aka “worn, fair shape or not well maintained” asphalt.
1,24-26	Asphalt, comparable in brightness to XP11 asphalt
27-30	Darker colored asphalt
31-34	Very dark colored asphalt
35-38	Near black, ‘new’ looking asphalt

50-52	Light “new” looking concrete	Each “shade” of concrete comes in 3 different subtypes differing in cracks or dirt added to the base texture.The first subtype looks very uniform, has no cracks, representing very good shape asphalt.
The 2rd subtype is “dirty” looking, non-uniformly colored.
The 3rd subtype is “worn” with cracks developing in addition to non-uniform coloring.
2,53-54	Concrete, comparable in brightness to XP11 concrete
55-57	Dark concrete
Runway Marking Code	Markings on runway
0	No runway markings	Disused runways appear like taxiways
1	Visual markings
2	Non-precision approach markings
3	Precision approach markings
4	UK-style non-precision approach markings	UK uses distinctive touch-down zone markings
5	UK-style precision approach markings	UK uses distinctive touch-down zone markings
6	EASA style non-precision approach markings	EASA differs from FAA for location and number of distance marks on runway before/after touchdown zone bars
7	EASA style precision approach markings
Approach Lighting Code	Approach lighting systems
0	No approach lighting
1	ALSF-I
High intensity Approach Light System with sequenced flashing lights
2	ALSF-II
High intensity Approach Light System with sequenced Flashing lights
Red side bar lights (barettes) the last 1000’, that align with TDZ lighting.
3	Calvert
British – High intensity
4	Calvert ILS Cat II and Cat II
British – High intensity with red side bar lights (barettes) the last 1000’
Barettes align with TDZ lighting
5	SSALR
High intensity, Simplified Short Approach Light System
With Runway Alignment Indicator Lights (RAIL)
6	SSALF
High intensity, Simplified Short Approach Light System
With sequenced flashing lights
7	SALS
High intensity, Short Approach Light System
8	MALSR
Medium-intensity Approach Light System
With Runway Alignment Indicator Lights (RAIL)
9	MALSF
Medium-intensity Approach Light System with sequenced flashing lights
10	MALS
Medium-intensity Approach Light System
11	ODALS
Omni-directional approach light system
Flashing lights, not strobes, not sequenced
12	RAIL
Runway Alignment Indicator Lights
Sequenced strobes and green threshold lights, with no other approach lights
Line Type Code	Painted lines and light strings
	Note that for all linear features that involve runway entrance hold lines and associated lights (4, 5, 6, 103 & 104 below), the runway is assumed to be to the LEFT of the string and the taxiway to the RIGHT (looking along string from its first node)
0	Nothing.
1	Solid yellow line	Taxiway centre lines
2	Broken yellow line	Miscellaneous boundaries
3	Double solid yellow lines	Taxiway edge lines
4	Two broken yellow lines and two solid yellow lines. Broken line on left of string.	Runway hold positions
5	Broken yellow line with parallel solid yellow line. Broken line on left of string.	Other (non-runway) hold locations
6	Yellow cross-hatched line	ILS hold
7	Solid yellow line with broken yellow line on each side	Taxiway centerlines in runway safety zones
8	Widely separated, broken yellow line	Mark ‘lanes’ for queuing aeroplanes
9	Widely separated, broken double yellow line	Mark ‘lanes’ for queuing aeroplanes
51-59	Line types 1-9 above with a black border	Use on concrete surfaces for higher contrast

20	Solid white line	Roadway markings
21	White chequerboard pattern	Roadway markings
22	Broken white line	Roadway centreline
	Note that lights added to the edge boundary of a piece of pavement (or hole) will be placed off the edge of the pavement (about one meter).
101	Green embedded lights, bidirectional along string axis	Taxiway centrelines
102	Blue lights, omnidirectional	Taxiway edge
103	Closely spaced, embedded amber lights. Unidirectional to right of string	Hold lines
104	Closely spaced, pulsating embedded amber lights. Unidirectional to right of string	Runway hold lines
105	Alternating green and amber embedded lights, bidirectional along string axis	Centrelines in runway safety zones
106	Red lights, omnidirectional	Edge lights in dangerous/critical zones (eg. on bridges)
107	unidirectional steady green lights	Runway lead-off lights
108	unidirectional, alternating green and amber lights	Runway lead-off lights inside runway safety zones
Beacon Type Code	Airport light beacons
0	No beacon. Suppresses automatic creation of beacon by X-Plane.	Use a dummy airport lat/lon for the location.
1	White-green flashing	Civilian land airport
2	White-yellow flashing	Seaplane base
3	Green-yellow-white flashing	Heliport
4	White-white-green flashing	Military airport
Sign Size Code	Taxiway sign sizes & types
1	Small taxiway sign
2	Medium taxiway sign
3	Large taxiway sign
4	Large distance-remaining sign on runway edge	Alternatively, can be auto generated for a runway
5	Small distance-remaining sign on runway edge	Alternatively, can be auto generated for a runway
Lighting Object Code	Lighting objects
1	VASI	Location is centre point between the two VASI units
2	PAPI-4L (four-light) on left of runway	Left-handed: red indication appears first on right 2 lights
3	PAPI-4R (four light) on right of runway	Right-handed: red indication appears first on left 2 lights
4	Space Shuttle PAPI, 20 degree glidepath	Deprecated. Use normal PAPI with an appropriate angle.
5	Tri-colour VASI
6	Runway guard (“wig-wag”) lights	Pulsating double amber lights alongside runway entrances
7	APAPI L (two-light) on left of runway
8	APAPI R (two-light) on right of runway

Further Information

Resources are available for airport designers at the X-Plane Scenery Gateway at //gateway.x-plane.com/

X-Plane Airport Data (apt.dat) File Specification Page of 1200 Version, 1-May-2022

1 Comment

lights.txt File Format

The lights.txt file is a file of light names and directions for X-Plane’s rendering engine. It is absolutely not meant for editing by the user and we take no responsibility for crashes or the file being overwritten during updates.

It is an ASCII .txt file with a header and body.

All text including and after a ‘#’ is a comment. There are no leading or trailing whitespace allowed.

lights.txt Header

Similar to other Laminar Research file formats, the lights.txt header is as follows

NEWLINE (A)

VERSION (850)

LIGHT_SPECS

TEXTURE <filepath to texture file>

A header may have multiple TEXTURE files, currently one for close range and one for distant distances.

lights.txt Body

Each line of the body consists of a RECORD TYPE, a light name that may be shared with other records, and the contents of that RECORD TYPE.
Light names match “[A-Za-z0-9_]+” and represent only 1 light – no “my_test_light” representing a red spill and a blue strobe.
Each element of the line is separated by (usually 1) tab for readability. Spaces (please use 4) may be used but are strongly discouraged.
All light’s “front” face is to the south (0, 0, 1) – if you are standing south of a light, looking north you’ll see it. Parameters for DX, DY, and DZ can change this.

RECORD TYPEs

There are two record types: OVERLOAD or LIGHT_PARAM_DEF. A light_name must have at least 1 OVERLOAD and may have 1 LIGHT_PARAM_DEF. Records should be grouped by light_name, bounded by an empty line. A LIGHT_PARAM_DEF must precede all OVERLOADs.

OVERLOADs

OVERLOADS are in the form of <OVERLOAD TYPE> <light_name> <matching number of arguments for prototype>

Arguments may be

– a number (in decimal notation), convertible to a float
– a dataref or NOOP to replace DREF, no surrounding quotes
– a parameterization-argument: One of the parameters from the light’s LIGHT_PARAM_DEF. Can be in any order in the arguments list and be used multiple times in the arguments list as long as the light has a LIGHT_PARAM_DEF.

Overload Type | Order of arguments and likely parameters used (spacing for readability, not to indicate an altered start index)
---------------|--------------------------------------------------------------------------------------------------------------------
BILLBOARD_HW   | <R> <G> <B> <A> <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL> <DX> <DY> <DZ> <WIDTH> <FREQ> <PHASE> <AMP> <DAY>
BILLBOARD_SW   | <R> <G> <B> <A> <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL> <DX> <DY> <DZ> <WIDTH>                            <DREF>
SPILL_HW_DIR   | <R> <G> <B> <A> <SIZE>                               <DX> <DY> <DZ> <WIDTH>                      <DAY>
SPILL_HW_FLA   | <R> <G> <B> <A> <SIZE>                                                      <FREQ> <PHASE> <AMP> <DAY>
SPILL_SW       | <R> <G> <B> <A> <SIZE>                               <DX> <DY> <DZ> <WIDTH>                            <DREF>
SPILL_GND      |                 <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL>
SPILL_GND_REV  |                 <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL>

light_name has been omitted. (Although LIGHT_PARAM_DEF and an OVERLOADs params and arguments lists look like a function declarations and partially applied functions, the names are just for humans. The order used is what truly matters. To keep consistent, the format specifies our conventions.)

OVERLOAD Types

BILLBOARD_HW – A hardware accelerated billboard.
BILLBOARD_SW – A dataref driven billboard, NOOP may be used.
SPILL_GND, SPILL_GND_REV – old v8-style quads-on-the-ground light spill for runway lights.
SPILL_HW_DIR, SPILL_HW_FLA – hardware spill, directional’ or flashing. We can’t have both due to a lack of light params.
SPILL_SW – dataref driven spill, NOOP may be used

OVERLOAD Parametrization Restrictions

The following are tables of what columns of an OVERLOAD’s prototype are allowed to be parameterized. The column names are conventions only based on common uses of these columns. This is unrelated to the content and order of LIGHT_PARAM_DEFs or the overload’s argument.For example

A light has SIZE in the LIGHT_PARAM_DEF and a BILLBOARD_HW overload with “SIZE” 1st column (commonly known as the R column) and 1.24 in the 5th column (commonly known as the SIZE column). The common labels for the columns and their contents are meaningless.

OVERLOAD type	R	G	B	A	SIZE	CELL_SIZE	CELL_ROW	CELL_COL	DX	DY	DZ	WIDTH
BILLBOARD_HW	*	*	*	x	*	x	x	x	*	*	*	*

OVERLOAD type	FREQ	PHASE	AMP	DAY	DREF
BILLBOARD_HW (continued)	*	*	x	x	x

OVERLOAD type	R	G	B	A	SIZE	CELL_SIZE	CELL_ROW	CELL_COL	DX	DY	DZ	WIDTH	DREF
BILLBOARD_SW	*	*	*	*	*	x	x	x	*	*	*	*	x

OVERLOAD type	SIZE	CELL_SIZE	CELL_ROW	CELL_COL
SPILL_GND	*	x	x	x
SPILL_GND_REV	*	x	x	x

OVERLOAD type	R	G	B	A	SIZE	DX	DY	DZ	WIDTH	DAY
SPILL_HW_DIR	*	*	*	*	*	*	*	*	*	x

OVERLOAD type	R	G	B	A	SIZE	FREQ	PHASE	AMP	DAY
SPILL_HW_FLA	*	*	*	*	*	*	*	x	x

OVERLOAD type	R	G	B	A	SIZE	DX	DY	DZ	WIDTH	DREF
SPILL_SW	*	*	*	*	*	*	*	*	*	x

LIGHT_PARAM_DEFs

LIGHT_PARAM_DEFs are in the form of LIGHT_PARAM_DEF <light_name> <count greater than 0> <parameters list of count length>. Every parameter must be unique. A LIGHT_PARAM_DEF’s params list can be in any order but is strongly suggested to follow the order in each OVERLOAD type.

Regular Parameters

These are: R, G, B, A, SIZE, DX, DY, DZ, WIDTH, FREQ, PHASE, INDEX, and DIR_MAG. INDEX represents the index in the light’s dataref’s array. It is only used in airplane_ lights. DIR_MAG is only used in airplane_nav_left/right/tail_size to indicate it is using the “directional magnitude” method of calculating the WIDTH column, instead of the usual method.

Special “Hint” Parameters

Some parameters give clues to tools and X-Plane on what their values should be, despite being parameters. They can be used multiple times (by appending a '_' for each duplicate).

UNUSED: Replacement placeholder for deprecated parameters, commonly replaced with 0.
NEG_ONE, ZERO, ONE: Some light’s parameter’s only ever make sense to use a hard coded value like -1, 0, or 1. A prime example is airplane/generic/landing/taxi lights’ RGB parameters which are actually used for aiming the light, but the light should only ever be aimed at (0, 0, -1). Tools and X-Plane can use this metadata to avoid making artists know this obscure fact.

An example: old_light’s parameters list was once LIGHT_PARAM_DEF old_light 9 R G B A SIZE DX DY DZ WIDTH, but now is expressed as LIGHT_PARAM_DEF example_light 9 ZERO ZERO_ NEG_ONE UNUSED UNUSED_ DX DY DZ UNUSED__. This way tools and X-Plane knows only DX DY DZ matters anymore, and “each parameter is unique” is satisfied in an easy to read and parse way. Software can help the artist and user accordingly.

ARGUMENTS explained

R, G, B, A – The color tint applied to the light spill or billboard. Since light is additive, A is really just a master dimmer.
SIZE – The total size in meters for spill, or a ‘size constant’ for billboards you’ll have to play around with to get right.
CELL_SIZE, CELL_ROW, CELL_COL – A triplet of ints (size, row, column where 0,0 is the lower left) for billboards. Size is a power-of-two multiplier for cell size. Thus a double-size cell in the top right corner is 2 7 3 (because the 1024 x 512 texture can be divided into a 8 x 4 grid of 128×128 pixel cells).
DX, DY, DZ: Direction vector for directional billboards and spill lights – should be normalized
WIDTH: For billboards, a constant term between 0 and 1 that makes a billboard more omni directional the closer it gets to 1. For spill lights: cos(1/2 * view_angle).
FREQ, PHASE, AMP, DAY: Frequency, phase offset, amplitude, and day/night flag for flashing lights
DREF: For software lights, the dataref that “processes” the light.

NOTE: if a hardware or software billboard has negative size, then it is axial. In this case: the direction is the axis of rotation (the billboard hangs off in that
direction. The axis should be normalized. The ‘width’ parameter is used as a scaler, e.g. larger numbers are more focused.

More notes on frequency:

“frequency” of flashing in Hz ( number of flashes per second, 0.2 mean a flash every 5 seconds)
“Phase offset” in seconds (so you can make two flashing lights that don’t flash at the same time, this value controls how late the flashing pattern starts from light OFF
“amplitude” of the flash, flash is a triangle wave, but with amplitude 1.0 the lights pulse (going from 0 to 1 and back to 0)
but if you pick a huge amplitude like 10.0 x-plane will automatically subtract 9 (to keep the light from going crazy) the result is….a strobe!
if you set the amplitude to 0.5 then x-plane will add a bit so even at its DARKEST the light will still be 50% ON, so you can make some tricks with the amplitudeALEX SAYS: Flash amplitudes GREATER THAN 1000 now invoke a square-wave flash behaviour. The pulse width ratio is calculated as (amp – 1000)/1000 %.
In other words, every integer over 1000 represents one millicycle. E.g. amp = 1500 gives a pulse width of 50%, amp = 1020 gives a pulse width of 2% etc.
Amplitudes less than 1000 still invoke the existing “strobe” scheme.
parameter: “daytime vs night-time” ratio. if it is 1 the light will be ON during the day and night, if it is 0 light will be ON only at night.

3 Comments

Aircraft VR Configuration (_vrconfig.txt) File Format Specification

The _vrconfig.txt file is a text-based configuration file that customizes VR interactions for your aircraft.

VR Configurations are aircraft-specific which means each ACF requires its own configuration file. While VR Configurations are not required, they are strongly encouraged. Aircraft that do not have a VR Configuration will still load and still work, even with VR enabled, however, there will be no hotspots to make it easy for the user to get back into the pilot seat, and there will be no customization allowing the VR controllers to be used to their fullest potential.

The VR Configuration name needs to match the prefix of the ACF file, with _vrconfig.txt appended to the end. For example, to make a VR config for Cessna_172SP.acf, the file needs to be called Cessna_172SP_vrconfig.txt. This file must exist in the same directory as the ACF file.

The _vrconfig.txt file is a text file – Unix or Windows line endings are legal, blank lines are allowed after the header, and the character set should be UTF-8.

The header of the file should be

A
1100
VRCONFIG

followed by the directives listed below.

Hotspot Definitions

Hotspots are predefined locations that are used to precisely orient the VR user when selected. They are commonly used on the pilot and co-pilot seats so that users can quickly position themselves accurately in the seats.

Each hotspot block defines a single hotspot on or around the aircraft. You must use a matched pair of BEGIN_TELEPORT_HOTSPOT and END_TELEPORT_HOTSPOT. In this block you must have:

Exactly one Axis-Aligned-Bounding-Box (AABB)
Exactly one XYZ location
Exactly one Psi, Theta, and Phi orientation respectively.

Note: Unless the REF_POINT_ACF directive is set, all units are in Aircraft Coordinates – meters with the origin at the aircraft CG and the positive Z axis pointing aft. This is not the same as the English units used in Plane-Maker.

REF_POINT_ACF (V12 and later)

If this directive appears in the VRCONFIG, the hotspot location origin for AABB and PRESET_XYZ are no longer tied to the aircraft’s CG but instead moves to some offset from the aircraft’s authoring point in Plane-Maker. Typically artists will put the reference point of the aircraft at the tip of the nose or tail and it stays there throughout the aircraft’s existence. This makes it a more useful reference point for coordinates than the aircraft’s CG which might change as authors gather newer and more accurate data to model the aircraft.

There are two main uses of this directive. First, if the VRCONFIG is being done for the very first time, setting this directive tells the sim to just use the authoring point as the origin so it’ll never be tied to the CG. You can leave the Y/Z coordinates blank and the sim will assume you mean 0.0 0.0. The second main use is for VRCONFIGs that have already been done for an aircraft that is now having it’s CG moved. Rather than have to adjust every coordinate in the VRCONFIG, you can use this directive to tell the sim that the origin should be at the OLD CG’s location by telling it where the OLD CG was relative to the aircraft’s authoring point. For example, if the OLD CG was at a Y/Z of 3.28084ft/-6.56168ft (remember, PlaneMaker uses FEET for its units) then you could add REF_POINT_ACF 1.0 -2.0 (which is the old CG location, converted from feet to meters) as a directive to the VRCONFIG which will allow the CG to move but the reference point for the file to stay at the OLD CG.

BEGIN_TELEPORT_HOTSPOT

This begins the definition of a new teleport hotspot. All hotspot properties must be specified after this directive and before the matched END_TELEPORT_HOTSPOT directive. The legal types of hotspots are ‘SITTING’ and ‘STANDING’. A sitting hotspot places the user’s head at the XYZ location. A standing hotspot places the user’s feet at the XYZ location. The name property is useful for debugging purposes.

END_TELEPORT_HOTSPOT

This defines the end of a given teleport hotspot. Each hotspot must be “ended” before anything else in the file occurs, and before the file ends.

AABB

This adds an axis-aligned bounding box (in aircraft coordinates, that is +X = right, +Y = up, +Z = aft) in meters around the CG of the aircraft. When the teleport beam lands inside this box, if the user ends the teleport, this hotspot will be used to position the user.

PRESET_XYZ

This sets the location of the user to the location X, Y, Z in meters, relative to the default CG of the aircraft; X is right, Y is up, Z is aft. A sitting hotspot places the user’s head at the XYZ location. A standing hotspot places the user’s feet at the XYZ location.

PRESET_PSI <deg 0 – 360>

This sets the rotation orientation (rotating about the Y-axis) of the user’s view in degrees. 0 degrees is facing forward in the aircraft, 90 would look toward the right wing, 180 degrees would be looking back at the tail etc.

PRESET_THE <deg -90 – 90>

This sets the pitch orientation (rotating about the X-axis) of the user’s view in degrees. 0 degrees is level. 90 would look straight up at the sky. -90 would look down at the ground.

PRESET_PHI <deg -180 – 180>

This sets the tilt orientation (rotating about the Z-axis) of the user’s view in degrees. 0 degrees is upright. -90 would be like tilting their left ear to their shoulder. 90 would be like tilting their right ear to their shoulder.

Manipulator Customization

Some aircraft manipulators need more information than is currently available in the OBJ itself in order to function optimally with VR Controllers. The most common examples of these are knobs and switches. With a mouse, knobs usually move one detent for each click. With a VR controller, however, X-Plane needs to know how much rotation is necessary in order to move the knob to the next detent. For linear knobs like lighting rheostats, this can be a fraction of a degree. For more coarse knobs like a fuel selector, you may want to require 60 degrees of rotation. There are other reasons to specialize manipulators such as changing their behavior entirely. For example, if the default aircraft manipulator uses commands to increment something by single degrees, but you want a smoother feel to the knob, you may want to redefine the manipulator to use a dataref to increment by fractions of a degree.

It’s important to note that customizations done with this file ONLY affect VR controllers. They will not change mouse or joystick hardware functionality.

BEGIN_MANIP <cmnd1/dref1> <cmnd2/dref2>

This begins the manipulator block that defines the EXISTING aircraft OBJ manipulator to be customized. All manipulator properties must be specified AFTER this directive and before the matched END_MANIP directive. This line essentially contains the unique pieces of the OBJ manipulator for it to be looked up.

The manipulator type needs to match the type specified in the OBJ but without the ‘ATTR_manip_’. For example, if the OBJ has an ATTR_manip_command_axis, the type (for the purposes of this file) should be ‘command_axis’. The cmnd1/dref1 and cmnd2/dref2 should match those that exist in the OBJ manipulator definition. If the manipulator needs only one command/dataref, then cmnd2/dref2 can be omitted completely.

Lastly, to disambiguate two manipulators that have the exact same type and act on the same commands/datarefs, an optional tooltip can be used. This is common with Yoke manipulators since there are usually two yokes for the pilot and copilot and they typically act on the same datarefs. Again, if the tooltip is unnecessary to find a manipulator that is unambiguous and unique, it can be omitted completely.

The manipulator block will match only one manipulator – if more than one manipulator in the OBJ matches the specification, only one will be remapped; use more information (E.g. tooltips) when you need to remap manipulators that are otherwise ambiguous.

END_MANIP

This marks the end of a given manipulator block. Each manipulator block must be “ended” before anything else in the file occurs, and before the file ends.

ACTION axis_knob

This tells the VR system that this manipulator should be changed to an axis_knob manipulator and used instead of the original manipulator. This is useful if you want to act on the dataref instead of a command in VR mode to have finer control over the knob’s increment/decrement amounts. DX specifies the amount of change applied to the dataref for each action. Use DEG_PER_ACTION to set the amount of wrist rotation needed for an action to fire.

ACTION axis_switch_up_down (V12 and later)

This tells the VR system that this manipulator should be changed to an ATTR_manip_axis_switch_up_down manipulator and used instead of the original manipulator. This is useful if you want to act on a dataref instead of a command in VR mode to have finer control over the Up/Down switch’s increment/decrement amounts. DX specifies the amount of change applied to the dataref for each action. Use SWITCH_THRESHOLD to set the amount of wrist deflection/movement needed for an action to fire.

ACTION axis_switch_left_right (V12 and later)

See ACTION axis_switch_up_down for details. It’s exactly the same except in the horizontal direction.

ACTION drag_xy four_arrows

This tells the VR system that this manipulator should be changed to a drag_xy manipulator and used instead of the original manipulator. This is usually used to override the show/hide Yoke manipulator to instead make it behave as if the user has grabbed the yoke to begin using it.

ACTION command_axis (V12 and later)

This tells the VR system that this manipulator should be changed to an ATTR_manip_command_axis manipulator and used instead of the original manipulator. This is useful for mechanical things that have two states that you want to move through with a rest in between. For example, consider an elevator trim switch that’s spring loaded in the up and down positions so it always recenters. This manipulator coupled with a HOLD_MANIP flag will get you that behavior.

ACTION command_knob (V12 and later)

This tells the VR system that this manipulator should be changed to an ATTR_manip_command_knob manipulator and used instead of the original manipulator. This is useful if you want the mechanical thing to perform one command in a direction and another command if rotated in the opposite direction.

ACTION command_switch_up_down2 (V12 and later)

This tells the VR system that this manipulator should be changed to an ATTR_manip_command_switch_up_down2 manipulator and used instead of the original manipulator. This is useful if you have a single command that toggles rather than requiring two separate commands like ATTR_manip_command_switch_up_down.

ACTION command_switch_left_right2 (V12 and later)

This tells the VR system that this manipulator should be changed to an ATTR_manip_command_switch_left_right2 manipulator and used instead of the original manipulator. This is useful if you have a single command that toggles rather than requiring two separate commands like ATTR_manip_command_switch_left_right.

DEG_PER_ACTION

This tells the system how many degrees of wrist rotation is necessary before a knob manipulator will be acted upon. Another way of thinking about it is how far does the VR controller need to be rotated before the manipulator will fire as if the mouse was clicked once.

SWITCH_THRESHOLD

Similar to DEG_PER_ACTION for knobs, SWITCH_THRESHOLD tells the system how much wrist tilt or motion is necessary to trigger a command. This is useful for things dials like the vertical speed dial on an airliner. The angle in degrees tells the system how many degrees of tilt are necessary before triggering the command. The offset threshold in meters tells the system how much motion should exist before triggering the command. This allows the user to lift/lower their arm to operate the dial instead of tilting their wrist.

WRAP_MANIP

This tells the system that the knob manipulator should wrap. Examples of knobs that should wrap would include the course knob or heading bug. Examples of knobs that should not wrap are lighting knobs and volume controls.

HOLD_MANIP

This tells the system that the knob/switch manipulator should hold down commands continuously while it is not in motion. Without this, commands are issued once for each ‘click’ of the switch or knob; with this, a command is held until the knob/switch is released or moved again. Do not use this for manipulators that use datarefs. It is only intended for command manipulators.

Starter keys and spring-loaded knobs and switches often require the HOLD_MANIP directive as they will return to the off position when not held.

INVERT_MANIP (V12 and later)

This tells the system that the knob/switch manipulator should be inverted in the way it processes commands. For example, switches are expected to be UP in the ‘on’ position and DOWN in the ‘off’ position but some switches just aren’t modeled that way or the real switch is actually mounted upside down. With this flag, you can reverse the behavior to match real life without having to change the command order in the OBJ.

DISABLE_VISUALS (V12 and later)

This tells the system that it should not draw any kind of feedback visuals during manipulator use. Some manipulators such as axis manipulators visualize the axis while a user interacts with it. With this flag, that drawing will be disabled. This does not affect the drawing of the manipulator geometry BEFORE interaction.

JOYSTICK_MANIP

This tells the system that the manipulator is one that should be treated like a real-world joystick control (like those found on Airbuses and the CirrusJet). The data here will only become active if the user has enabled “Realistic” mode for their VR Yokes. The pitch and roll mins and maxes define the range of tilting motion in degrees of the VR controller that should be mapped to the full range of motion of the flight controls.

YOKE_MANIP_TRANSLATE

This tells the system that the manipulator is one that should be treated like a real-world yoke control (like those found on a Cessna 172) where the pitch axis is a translation axis that slides back and forth and the roll axis is a rotation one like a steering wheel that rotates about a centroid. The data here will only become active if the user has enabled “Realistic” mode for their VR Yokes.

Pitch min and max x,y,z are in OBJ units and define the axis of translation for pitch; they can be taken directly from the translation axis used to animate your yoke. The length of the vector between these points defines how far the yoke moves from full nose up to full nose down, and is typically aligned along the Z axis.

Roll centroid x,y,z are also in OBJ units and define the point at which the yoke rotates around. This point should be somewhere on the center of the yoke, and can be taken from the static translation that precedes your yoke’s roll animation.

The roll axis defines the axis about which the yoke rolls, and can be taken from the axis of your roll animation directly. This should be a unit vector, and will typically be about the Z axis.

The roll min and max angles define the maximum travel in either direction from the “level” point, and can be taken from the end key frames of your roll animation.

YOKE_MANIP_ROTATE

This tells the system that the manipulator is one that should be treated like a real-world flight stick (like those found in a fighter jet or SuperCub) where the pitch and roll axis are attached to a single stick that is attached to a mount point that can be rotated forward and back as well as left and right about two centroids (that can be co-located).

Pitch and roll centroid x,y,z are in OBJ units and define the centroids about which the pitch and roll axis rotates – you can take them from the static translation that precedes your animation.

Pitch and rolls axis x,y,z define the unit vectors of the rotation axes for pitch and roll; they should be unit vectors and can be taken directly from your pitch and roll animations. Typically the pitch axis will be the X axis and the roll axis will be the Z axis.

The pitch and roll min and max degrees define the maximum amount of rotation that can exist in either direction, for both pitch and roll.

Note that you can use YOKE_MANIP_ROTATE for both flight sticks (like a helicopter or fighter) or for airliner-style column yokes. In the flight stick case, the rotation centroid is at the floor pivot for both axes. For an airliner yoke, the pitch centroid is on the floor but the roll centroid is on the yoke itself.

We do not recommend using YOKE_MANIP_ROTATE for very small side sticks because they are hard to control in VR; prefer JOYSTICK_MANIP instead.

15 Comments

Flightplan files – v11 .fms file format

Flightplan files must be located in the Output/FMS plans/ directory.

The .fms file is a text file – Unix or Windows line endings are legal and the character set should be UTF-8. Spaces or tabs are allowed as whitespace.

The header of the file must be

I
1100 Version

Since this is a plain text file with no binary data, there’s no difference between ‘I’ or ‘A’ as the first line. The currently supported versions are 3 (legacy, not written but still loaded by X-Plane 11) and 1100 (current).

Next is the AIRAC cycle number of the cycle the file was created with. This line is mandatory as the third line of the file. It is given as a four-digit number:

CYCLE 1710

Next is the departure block, which can be either an airport or any named point in the X-Plane nav database. In case of an airport, the departure block will look like this

ADEP KGSO

optionally, the lines for departure runway, instrument departure and transition can follow:

DEPRWY RW14
SID TRSHA1
SIDTRANS BAWDS

If no departure procedure is part of the flightplan, the SID and SIDTRANS lines can be omitted. If the departure has no transitions, the SIDTRANS line can be omitted. If no departure procedures are available or no loading of a procedure desired, the DEPRWY line can be omitted.

If the flightplan starts at a point other than an airport the departure block looks like this:

DEP CTF

CTF in this case represents a VOR, more precise information on this point is then given in the enroute section of the flightplan.

Next is the destination block. It is similarly structured to the departure block and can include destination airport, runway, arrival, arrival transition, approach and approach transition:

ADES KRDU
DESRWY RW05L
STAR ALDAN1
STARTRANS ROA
APP I05L

If any off APP or STAR is set, the DESRWY is required! STAR and STARTRANS can be omitted if no arrival is desired. APP and APPTRANS can be omitted if no instrument approach is desired. APPTRANS is optional and can follow APP, just like STARTRANS is optional after the STAR. APPTRANS can be omitted if no transitions are available for the given approach or vector to final is desired.
An exception to the above rule is a circling approach with no runway, in which no DESRWY will be set. In this case, the loading of STARs prior to this approach is limited to STARs with non-empty trunk routes, as with no runway, no runway transition can be loaded.
The name of the approach must be given in the format of ARINC 424.18+, section 5.10. Examples: I26L, B08R, R29, V01L, N35, R35-Y, VDM, NDBB, LOCD, …

If the flightplan ends at a point other than an airport the destination block looks like this:

DES RDU

RDU in this case represents a VOR, more precise information on this point is then given in the enroute section of the flightplan.

Next is the enroute block of the flightplan. It starts with the number of enroute waypoints:

NUMENR 9

This is the number of waypoints in the flightplan that are NOT part of an instrument departure, arrival, transition, approach or missed approach. The waypoints listed can be either direct (DRCT) legs or via an ATS airway. The format is similar to the v3 flightplan, but adds a field for the via airway or other special rule of the waypoint.
Only track-to-fix legs are listed here. Note that any special leg types can be loaded as part of a published procedure, via the departure or destination block explained above.

A typical enroute block after the NUMENR field might look like this:

1 KCUB ADEP 4.000000 33.970470 -80.995247 
3 CTF DRCT 0.000000 34.650497 -80.274918 
11 NOMOE V155 0.000000 34.880920 -79.996437 
11 LILLS V155 0.000000 34.935440 -79.930206 
3 SDZ V155 0.000000 35.215481 -79.587936 
11 OCHOC V155 0.000000 35.402336 -79.361153 
11 MOATS V155 0.000000 35.621601 -79.092964 
3 RDU V155 0.000000 35.872520 -78.783340 
1 KRDU ADES 435.000000 35.877640 -78.787476

The first column is the type of waypoint, and corresponds to the first column in a v3 .fms file. It is 1 for airport, 2 for NDB, 3 for VOR, 11 for named fix and 28 for unnamed lat/lon waypoints.
The second column is the identifier of the waypoint, and corresponds to the second column in a v3 .fms file.
The third column is the via/special column. It can have the following values: ADEP/ADES for departure or destination airport of the flightplan, DRCT for a direct or random route leg to the waypoint, or the name of an airway or ATS route to the waypoint.
The fourth column is the required altitude in feet and corresponds to the third column in a v3 .fms file.
The fifth and six columns are the latitude and longitude of the waypoint, given in decimal degrees and correspond to the fourth and fifth column of a v3 .fms file.

Example

This is an example of a valid v11 flightplan .fms file:

I
1100 Version
CYCLE 1710 
ADEP KCUB 
DEPRWY RW13
ADES KRDU 
DESRWY RW05L 
APP I05L 
NUMENR 9 
1 KCUB ADEP 0.000000 33.970470 -80.995247 
3 CTF DRCT 0.000000 34.650497 -80.274918 
11 NOMOE V155 0.000000 34.880920 -79.996437 
11 LILLS V155 0.000000 34.935440 -79.930206 
3 SDZ V155 0.000000 35.215481 -79.587936 
11 OCHOC V155 0.000000 35.402336 -79.361153 
11 MOATS V155 0.000000 35.621601 -79.092964 
3 RDU V155 0.000000 35.872520 -78.783340 
1 KRDU ADES 435.000000 35.877640 -78.787476

Backward compatibility

X-Plane 11.10 can still load the following other, older formats of flightplans:

v3 .fms files, containing waypoints only but no airways or procedures, can be loaded into the GPS or FMS
.flp files, containing waypoints and airways, can be loaded by the airliner FMS
.fml files generated with the v11 FMS can be loaded by the airliner FMS

X-Plane 12 can read and write v11 .fms files.

Comments Off

Sound (.snd) File Format Specification

The .snd file is a text file – Unix or Windows line endings are legal, blank lines are allowed after the header, and the character set should be UTF-8.

The header of the file should be

A
1000
ACF_SOUNDS

Unlike some other X-Plane text file formats, the .snd file requires paired BEGIN and END directives for major subsections. Having a BEGIN directive without its matched END directive is an error.

Dataref Matching Conditions

Dataref-based trigger conditions use a simple logic language, of the form

<dataref> <operator> <constant value>, e.g.

sim/flightmodel2/engine/N1_percent[0] >= 12.5

The condition evaluates to true or false based on the comparison constant (see the list below). The conditions are evaluated every frame with the current dataref value and may then trigger FMOD events. Note that you can only compare with numbers, not strings.

Unlike normal datarefs, you can prefix the dataref with DELTA= or ABS_DELTA=. If you do this, the value in the condition is not the dataref itself, but its rate of change (per second). ABS_DELTA applies an absolute value.

For example, the condition

DELTA=sim/flightmodel2/engine/N1_percent[0] > 10

Would return true if N1 is growing at a rate of more than 10 per second. Using ABS_DELTA would cause the condition to also indicate true when N1 was falling by more than 10 per second.

DELTA and ABS_DELTA can be used to play sounds when a rate of change is detected in a dataref, even if the sim doesn’t provide a rate of change dataref directly. For example, the flaps, the flaps actual position is provided by X-Plane but their rate of movement is not. To correctly play a flap motor sound, DELTA is needed.

(Playing the sound based on the flap down command would be wrong: if the electrical system is broken, the flaps may not move even when the command is pressed. Thus the actual movement of the flaps should be the trigger for the sound, not the command.)

Constants Used In The File Format

Where datarefs can be compared, the valid comparison operators are:

< (less than)
<= (less than or equal)
== (equality)
!= (not equals)
>= (greater than or equal)
> (greater than)

The valid part names for aircraft attachments are:

engine – the sound is attached to the engine – index refers to the engine number.
tire – the sound is attached to a tire – index refers to the tire gear number.
cockpit – the sound is roughly in front of the pilot.

General Directives

These directives should appear at the beginning of the file.

REQUIRES_BANK <bank name>
This causes X-Plane to load the bank specified by name from the FMOD folder. This is needed for any bank you wish to use for this ACF other than the master bank.

DISABLE_LEGACY_ALERT_SOUNDS
New to X-Plane 11.30. Adding this to the SND file will prevent X-Plane from playing any legacy aircraft alert sounds and morse code.

REF_POINT_ACF <y_meters> <z_meters>
New to X-Plane 12.00. If this directive appears in the SND, the location origin for Sound Space’s AABB and SPHERE as well as the Sound Attachment’s VEH_XYZ are no longer tied to the aircraft’s CG but instead moves to some offset from the aircraft’s authoring point in PlaneMaker. Typically artists will put the reference point of the aircraft at the tip of the nose or tail and it stays there throughout the aircraft’s existence. This makes it a more useful reference point for coordinates than the aircraft’s CG which might change as authors gather newer and more accurate data to model the aircraft.

There are two main uses of this directive. First, if the SND is being done for the very first time, setting this directive tells the sim to just use the authoring point as the origin so it’ll never be tied to the CG. You can leave the Y/Z coordinates blank and the sim will assume you mean 0.0 0.0. The second main use is for SNDs that have already been done for an aircraft that is now having it’s CG moved. Rather than have to adjust every coordinate in the SND, you can use this directive to tell the sim that the origin should be at the OLD CG’s location by telling it where the OLD CG was relative to the aircraft’s authoring point. For example, if the OLD CG was at a Y/Z of 3.28084ft/-6.56168ft (remember, PlaneMaker uses FEET for its units) then you could add REF_POINT_ACF 1.0 -2.0 (which is the old CG location, converted from feet to meters) as a directive to the SND which will allow the CG to move but the reference point for the file to stay at the OLD CG.

Sound Attachment Directives

Each sound attachment block defines a single attached “sound” on the aircraft. You must use a matched pair of BEGIN_SOUND_ATTACHMENT and END_SOUND_ATTACHMENT. In this block you must have:

Exactly one of EVENT_NAME or SNAPSHOT_NAME to specify the FMOD object being played.
Exactly one of VEH_XYZ or VEH_PART to specify the FMOD object’s location in space.
At least one of the triggering methods (e.g. EVENT_xxx) so the FMOD object plays. This can be omitted, but then the FMOD event will never play.

Note: while all dataref triggers (start, end, cue) can be combined, only one command trigger can be used, and it cannot be combined with any dataref triggers.

BEGIN_SOUND_ATTACHMENT
This begins the definition of a new sound attachment. All sound attachment properties must be specified after this directive and before the matched END_SOUND_ATTACHMENT directive.

END_SOUND_ATTACHMENT
This defines the end of a given sound attachment. Each sound attachment must be “ended” before anything else in the file occurs, and before the file ends.

EVENT_NAME <fmod string name>
This defines an FMOD event (by string name) that this attachment plays.

SNAPSHOT_NAME <fmod string name>
This defines an FMOD snapshot (by string name) that this attachment plays. Snapshots change the mix while they are being “played” and stop taking effect when stopped.

VEH_XYZ <x> <y> <z>
This sets the location of your event to the location X,Y,Z in meters, relative to the default CG of the aircraft; X is right, Y is up, Z is aft.

VEH_THE <value>
This sets the orientation of your event, where <value> is the angle of PITCH (nose) up.

VEH_PSI <value>
This sets the orientation of your event, where <value> is the angle of YAW (heading) to the right.

VEH_PHI <value>
This sets the orientation of your event, where <value> is the angle of ROLL (bank) to the right.

Note: the order of application is first VEH_THE, then VEH_PSI then VEH_PHI (pitch, heading, roll).

VEH_PART <part_enum> <part_idx>
This attaches your sound to a specific part of the aircraft; where the aircraft can have multiple parts (e.g. engines) a zero-based index is used.

EVENT_ALLOWED_FOR_AI
If this directive exists, the sound is used when your aircraft is flown by the AI as well as the user; if it is omitted, the sound is for the user’s aircraft only. Do not attach internal cockpit sounds like switch clicks to the AI aircraft.

PARAM_DREF_IDX <dref_idx>
For sound parameters that use wild-cards for indices, e.g. sim/flightmodel2/engines/N1_percent[*] (or its equivalent sim.flightmodel2.engines.N1_percent[#] in X-Plane 12) this specifies the index to be used for this attached sound. This lets you make a single event for all engines and then vary the index to get correct match-up to the engine params of a particular engine in a multi-engine aircraft.

EVENT_START_COND <dref> <op> <value>
This causes the event to start playing when the listed dataref changes in relationship to the specified value.

EVENT_END_COND <dref> <op> <value>
This causes the event to stop playing when the condition becomes true.

EVENT_ALWAYS
This causes the event to always be played. Playing events costs CPU even if the event is not making sound, so only use this if you really need the event to always be playing. An example of an always-playing event might be a mix-automation event that is constantly adjusting your mix in response to datarefs.

For sounds that really stop (e.g. engine noise), use event conditions to completely stop the event (or allow it to end playing with cues) once appropriate.

CUE_TRIGGER_COND <dref> <op> <value>
This sets the conditions on which the “cue” is sent to FMOD for the given event, based on a dataref equation.

EVENT_CMND_DOWN <cmnd>
This causes the event to play when a command is pressed down. Since you can use only one command trigger per event, this is meant for a self-terminating sound like a switch clicking on the down press.

EVENT_CMND_UP <cmnd>
This causes the event to play when a command is released. Since you can use only one command trigger per event, this is meant for a self-terminating sound like a switch clicking when released.

EVENT_CMND_HOLD_STOP <cmnd>
This causes the event to be started when the command is pressed down, and stopped when the command is released. E.g. the event plays for the duration the command is pressed.

EVENT_CMND_HOLD_CUE <cmnd>
This causes the event to be started when the command is pressed down, and cued when the command is released; the intention is that the sound event can loop during the duration of the command and then cue an ending part when the command is released, followed by stopping itself.

EVENT_AUTO_END_FROM_START_COND
New to X-Plane 11.30. Added to a sound EVENT, this will cause the sound to stop whenever ANY of the Dataref start conditions are no longer true.

EVENT_POLYPHONIC
New to X-Plane 12.00. Added to a sound EVENT, this will prevent X-Plane from reusing the same event instance for the same event attachment, firing instead separate instances when the conditions are met. This is useful for rotary knobs or other rapid-firing events. Be sure to limit the amount of simultaneous instances that can be playing at the same time to prevent voice stealing.

Sound Space Definitions

X-Plane supports up to 64 3-d “sound spaces” defined in and near your aircraft. The intention is to mark internal regions of your aircraft so that X-Plane can provide datarefs showing camera location for mixing purposes.

Each sound space contains one or more volume primitives; the sound space is the union of the space covered by those volumes. Both disjoint and overlapping volumes are allowed. Where a soft blend-depth is used, it is based on the mathematical boundary of the union of the bounding volume.

BEGIN_SOUND_SPACE
This begins definition of a sound space. Sound spaces must be terminated with END_SOUND_SPACE before another one can be started or an event can be added, and sound spaces cannot be nested in sound attachments.

END_SOUND_SPACE
This terminates an existing sound space.

SOUND_INDEX <index>
This is a required directive (once inside each sound space) and defines the sound space’s index (0-63) in X-Plane; this is used to “publish” penetration ratios for that sound space.

BLEND_DEPTH <distance meters>
This defines a soft transition region starting at the mathematical edge of the volume and moving inward; the inside ratio dataref goes from 0 at the mathematical edge of the volume to 1.0 at “distance meters” inside.

SPHERE <center x> <center y> <center z> <radius>
This adds a sphere to the sound space, defined by location and radius in meters, referenced relative to the CG of the aircraft.

AABB <minx> <miny> <minz> <maxx> <maxy> <maxz>
This adds an axis-aligned bounding box (in aircraft coordinates, that is +X = right, +Y = up, +Z = aft) in meters around the CG of the aircraft.

15 Comments

Joystick Configuration (.joy) File Specification

In X-Plane 11, we added two new features aimed at making joystick configuration easy for users:

“image maps” that show you a picture of your joystick, with each of its buttons/axes labeled, and
detailed default configurations for joysticks.

Both are described in the .joy file corresponding to your joystick. These files are located in Resources/joystick configs/.

Creating a default joystick configuration file

The easiest way to create the default joystick configuration: plug in your joystick, configure it as you’d like, then hit the “Save as Default for [device]” button there on the joystick configuration screen.

That will output a .joy file wherever you’d like (recommended that you stick it in Resources/joystick configs/). You can confirm it worked by hitting the “Reset to Defaults for [device]” button and confirming that none of your axis or button assignments changes.

At this point, if you were to delete your preferences, when you plug in your joystick, you would see that your previous configuration gets loaded—your joystick would be instantly ready to use!

Creating an image map

Our image maps consist of two things:

a PNG image, which we’ve gotten clearance from a joystick manufacturer to distribute with the sim, and
information in the .joy file noting the pixel coordinates of that PNG image where buttons, axes, & hat switches should be labeled.

So, suppose we have an image that is 1,000 px on each side. If the very center of that image corresponds to a particular button, we’d put a line in the .joy file to the effect of “Button x should be labeled at position (500, 500).” (We’ll get to the actual syntax below.)

Unlike the default joystick configuration, we can’t auto-generate the image map. So, you’ll need to use an image editor to figure out where in the image each label for your buttons, axes, and hat switches should go. So, you’ll specify the coordinates for these things in pixels, with (0, 0) in the upper left of the image.

The easiest way I’ve found for getting these coordinates (if you don’t want to spend a zillion years in Photoshop hovering over portions of the images and noting the pixel coordinates in the Info tool) is to use an online image map generator. Here’s how that works:

Upload the image you want to work with.

Click the square or circle button.
Click within the image wherever you want to add an annotation. A new line will appear in the source at the bottom of the window, giving you the coordinates of that shape. We need only the first two (x, y) coordinates.
Continue clicking Add Area and noting the new coordinates until you’ve gotten everything you need.

See the “View” section of the following file format description for the syntax of the image map text.

Notes on the image files

X-Plane only supports .png images with an optional transparent background. While there are no official size limits, we recommend the image be no larger than 2000×2000 pixels to avoid impacting sim performance. X-Plane will also scale large images automatically while maintaining the image map coordinates you specify.

Nitty gritty: a sample .joy file, as of X-Plane 11.20

See examples of finished .joy files in X-Plane 11/Resources/joystick configs.

I
1100 version
JOY
# ^ The header; must be the first thing in the file, verbatim.

# Operating system(s) this file applies to.
# Windows, macOS, and Linux will index the axes differently, so a file
# that correctly configures your joystick on one platform is *not*
# guaranteed to work on the other. 
OS: Windows
# Other valid options:
# OS: Mac
# OS: Linux
# Zero or more device names (provided by the operating system, as seen in the UI) that this .joy file describes.
# (Note that you need at least one name or one ID, described below.)
# If more than one device is named, we're saying that *any* of those devices should be configured
# using the *same* defaults and the same image maps.
Name: [device name]

# Zero or more USB identifiers (vendor ID + product ID) that this .joy file describes.
# (Note that you need at least one ID or Name, described above.)
# If more than USB identifier is given, we'll use this .joy file to configure *any* of those devices.
# You can specify the IDs in either hex or decimal form.
# For instance, the following are equivalent:
#    ID: VID:0x046DPID:0xC214
#    ID: VID:1133PID:49684
# ...since hex 046D == 1133, and hex c214 == 49684.
ID: VID:[vendor ID]PID:[product ID]

# Optional: Specify the name X-Plane should display for the device in the user interface
# (if this is different from the name the operating system provides)
Display: [device name override]

# Zero or more view sections
# These will be presented in the UI, and you can select different views for the same device
# (e.g., you might have one looking at the front of the device, one looking at the back, 
# and a third looking at the throttle quadrant). Presumably you will annotate *different* 
# controls for each view.
View: [view name]
-----------------------------------------------------------------------
Image: [image_name.png]

# Then, within the view section, you can zero or more of the following:
#   - buttons
#   - hat switches
#   - axes
#   - axis groups

# Buttons are easy; just specify which button you're talking about, and where in the image you
# want the "dot" for that button positioned.
# Note that these (x, y) pixel coordinates---like all the coordinates that follow---use the top left as (0, 0).
Button [button index]: [x coordinate in the image] [y coordinate in the image]

# Buttons can also take an optional *label* to display in the UI, like this:
Button [button index] ([label for UI]): [x coordinate in the image] [y coordinate in the image]

# Axes, like buttons and hat switches, can take an optional label.
Axis [axis index]: [x coordinate] [y coordinate]
Axis [axis index] ([axis label]): [x coordinate] [y coordinate]

# In addition, axes can take an optional *axis direction*. This must be one of x, y, or z (lowercase).
# If you provide a direction, we'll use that letter when labeling the axis in the UI.
# So, the following are also valid axis labels:
Axis [axis index] ([x/y/z]): [x coordinate] [y coordinate]
Axis [axis index] ([axis label]; [x/y/z]): [x coordinate] [y coordinate]

# Finally, you can optionally group axes together in the UI.
# For instance, you probably don't want to display the x and y axes on your joystick separately.
Axis Group ([label for this group, displayed in the UI]): [1st axis index in this group] [2nd axis index]
Axis [index] ([x/y/z]): [x coordinate in the image] [y coordinate in the image]
Axis [index] ([x/y/z]): [x coordinate in the image] [y coordinate in the image]

# Zero or one assignment section
# This describes the default configuration for the device.
################################################################
# NOTE: 
# You almost certainly don't need to know the syntax for the
# assignments section, because you should be auto-generating
# it from an actual configuration (by hitting the 
# "Save as Default for [Device]" button in Settings > Joystick).
################################################################
Assignments:
------------------------------------------------------------------------

# Any number of axes, buttons, and hat switches.

Axis [axis index]: hidden
Axis [axis index]: [joy use]
Axis [axis index]: [joy use] reverse
Axis [axis index] Type: linear or centerable
Axis [axis index] Calibration: auto
#	Valid joy uses are:
#	 joy_use_none	joy_use_ptch	joy_use_roll
#	 joy_use_hdng	joy_use_thro	joy_use_coll
#	 joy_use_lbrk	joy_use_rbrk	joy_use_prop
#	 joy_use_mixt	joy_use_heat	joy_use_flap
#	 joy_use_vect	joy_use_swee	joy_use_sbrk
#	 joy_use_disp	joy_use_reverse	joy_use_elev_tr
#	 joy_use_ailn_tr	joy_use_rudd_tr	joy_use_thro1
#	 joy_use_thro2	joy_use_thro3	joy_use_thro4
#	 joy_use_prop1	joy_use_prop2	joy_use_prop3
#	 joy_use_prop4	joy_use_mixt1	joy_use_mixt2
#	 joy_use_mixt3	joy_use_mixt4	joy_use_reverse1
#	 joy_use_reverse2	joy_use_reverse3	joy_use_reverse4
#	 joy_use_gear	joy_use_tiller	joy_use_back_thro	joy_use_view_lr
#	 joy_use_view_ud	joy_use_view_zoom	joy_use_camera_lr
#	 joy_use_camera_ud	joy_use_camera_zoom	joy_use_gun_lr
#	 joy_use_gun_ud

Button [button number]: hidden
Button [button number]: [command path, like "sim/operation/quit"]
Hat Switch [hat switch number]: hidden
Hat Switch [hat switch number] Direction [hat switch direction]: [command path, like "sim/operation/quit"]
#	See X-Plane/Resources/plugins/Commands.txt for a complete list of commands

Coping with hardware eccentricities

“Phantom” buttons & axes

Sometimes, your USB hardware will report controls that don’t actually correspond to any physical axis, button, or hat switch. In that case, you can mark the control as “hidden” in the Assignments section (see examples above). Doing so will cause X-Plane to ignore that “phantom” control entirely, and not show it anywhere in the app.

(Normally, if you specify image mappings, but leave some axes, buttons, or hat switches out of all image mappings, X-Plane will add one final “view” called Other Controls to display them. Marking nonexistent controls as “hidden” can prevent this.)

Axes with limited range of motion

If your USB hardware reports a wider range of axis motion than the device is actually capable of sending, you may want to specify “relaxed” calibration in the header section. For instance, if you’re a custom cockpit builder, and your axis reports 16 bits of travel, but you only use 10 bits–during calibration, X-Plane may never recognize the range of motion as complete, although you know it is.

Calibration: Relaxed

This is not recommended if you have off-the-shelf hardware from a consumer hardware company like Saitek, Logitech, Thrustmaster, CH Products, etc.

Devices with more than one hat switch

Some devices come with multiple hat switch buttons. By default, X-Plane only recognizes one as a hat switch and the rest are considered separate buttons. You can group a set of 4 buttons into a virtual “hat switch,” which can make the button image mapping cleaner and easier to understand.

Specify the buttons to be grouped in up/right/down/left order, then associate your desired x/y image coordinates with the “up” button.

Hat Switch Group ([label for UI]): ["up" button index] ["right" button index] ["down" button index] ["left" button index] Button ["up" button index]: [x coordinate in the image] [y coordinate in the image]

Hat switches also take an optional label, so you can use either of the following:

Hat Switch [hat switch index]: [x coordinate in the image] [y coordinate in the image]

Hat Switch [hat switch index] ([label in the UI]): [x coordinate in the image] [y coordinate in the image]

Toggle switches: when a “button” isn’t a button

X-Plane 11.10 and greater support special configuration for joystick controls that send plain button presses to the sim, but which are conceptually not buttons.

Consider the Thrustmaster HOTAS Warthog:

It has a number of silver switches, which fall into three different categories:

Normal 2-position switches. When the switch is in one of these two positions, it sends a perpetually “held” button press, and while it’s in the other position, it sends no button press at all. The EAC on/off switch on the Warthog is an example of this.
Normal 3-position switches, which send no button press in the center position, but send a perpetual “hold” for two different buttons in the up and down states. The autopilot switch on the Warthog is an example.
Special 3-position switches which send a normal (momentary) button press in one direction (you have to keep holding the switch for it to continue sending the button press), no button press in the center, and a continuous button press when they “lock” into the third state. The engine toggles on the Warthog are like this: “ignition” is momentary, “normal” is center, and “motor” is the toggle-and-hold.

X-Plane 11.10 provides two .joy annotations to handle all three of the above cases: “momentary” and “virtual” buttons. When a button is marked as momentary, X-Plane will only run the associated command on the initial down-press, rather than running the command continuously for as long as the button is “down.” Likewise, “virtual” buttons are triggered when a “real” button (i.e., a button that you see in the UI when you have no .joy configuration file) is pressed or released—you pick which.

Here’s how it works in the above 3 cases:

The 2-position switch

This requires an immediate press-and-release when the “button” goes “down,” rather than firing the associated command continuously as long as the switch is in that state. Likewise, it requires a press-and-release when the “button” is “released (i.e., when the switch transitions to the “off” state).

The solution: mark the “button” as momentary, and create a new virtual button that fires on the release of the “button.” Example:

Button 15: Momentary
Virtual Button 100: Release Button 15

Note that this creates a new button at index 100—make sure you don’t actually have 100 physical buttons, or your newly created virtual button won’t work. In the rest of the file, you can refer to “Button 100” as though it were perfectly normal—you can map it to a view, assign a default command to it, etc.

The 3-position switch

This requires a single press-and-release when the two “buttons” are “pressed” initially, and it requires a separate command (for the center state) when either “button” is released.

The solution: mark the two “buttons” as momentary, and create a new virtual button that fires when either button is released. Example:

Button 12: Momentary
Button 13: Momentary
Virtual Button 105: Release Button 12, Release Button 13

The “special” 3-position switch

In this case, one of the button presses can actually be left alone—since it already behaves like a normal, momentary button, it doesn’t require any special configuration in the .joy file.

To cope with the “locked” button press, we need to once again mark it as momentary, and for the third state (which sends no button press at all), we need to create a virtual button that fires when either “button” is released. Example:

Button 18: Momentary
Virtual Button 105: Release Button 18, Release Button 31

Grouping switch “buttons”

In the case of our example Warthog above, all the states for one switch exist in the same space on the joystick. This can be problematic when you try to map two, three or even more of these switch states to very similar coordinates on your device image. The solution to this is a “Button Group:”

Button Group ([display name]): [button #] [button #]
Button # ([display name]): [x coordinate in the image] [y coordinate in the image]
Button # ([display name]): [x coordinate in the image] [y coordinate in the image]

You can specify the buttons to group together in any order. The first coordinates listed are used to position the image labels, but we recommend giving the same coordinates to all buttons in the group just for the sake of clarity.

Example:

Button Group (3-way Switch): 104 102 103
Button 102 (↑): 100 200
Button 104 (Center): 100 200
Button 103 (↓): 100 200

New capabilities in X-Plane 11.20

Group buttons and axes together

“Configuration Groups” allow you to group axes and buttons together. Note that X-Plane does not differentiate between configuration group types, so each must have a unique number. Example:

Configuration Group 2 ([display name]): Axis 2 3 Button 12

“Exclusive Configuration Group” is designed for hardware like the PS3 controller, where every button is also an axis. You specify the axis and the button, and the user has to choose in the UI which to use (and X-Plane will ignore the other). Example:

Exclusive Configuration Group 3 ([display name]): Axis 10 Button 4

New ways to use axes

Self-centering axes operating as linear axes

If you assign a self-centering axis to a linear axis assignment, we use the deltas from centered to move the throttle in that direction; a big movement from centered gives you a big jump in the axis position, etc.

For example, if you assign the Y of your X/Y stick to throttle, instead of the centered position always sticking your throttle at 50%, it instead leaves the throttle alone. You push the axis forward a bit, the throttle goes up (and remains there when you bring the axis back to center). Pull the axis back a bit and the throttle will go down. It requires some hint to us in the .joy file about the type of axis. A device with no .joy file at all will not work. To see it in action, you’ll need a .joy file with one of the following:

an explicit axis type line in the assignments section
a default assignment that would require a centered axis (pitch/roll/yaw/etc.)

Example:

Axis [axis index]: joy_use_roll
Axis [axis index] Type: centerable

Changing a device with no .joy file from pitch to something else can’t do it, because you may have accidentally set a linear slider to pitch at some point.

Axes operating as commands

In the .joy file, specify the axis type as either linear or centerable. Then, in the X-Plane axis usage dropdown choose “Custom commands” and you can assign some number of commands (based on the type of axis) to be fired as you move the stick:

Linear axes always have 2 configurable slots, self-centering axes always have 4.
You can assign up to that number of different commands to each slot.
The assignments in each slot get triggered when you move the axis into a certain range of the stick. (E.g., slot 1 on a linear axis is from about 0 to 50%, slot 2 is from 50 to 100%.)

Axes operating as hat switches

When you have a 2-axis group specified in the .joy file as described above, you’ll get a toggle in the UI next to the group’s name to choose “axis” or “hat switch” mode.

Handling VR controllers

“Reserved Configuration Groups” are specified the same way as the configuration groups as above, but the default config is all-or-nothing. This was designed for VR, where we want the stick+clicker to either all be for menu manipulation, or to totally disallow a partial menu manipulation config (i.e., you can’t set the X/Y to pitch & roll, but keep the clicker to be “menu enter”). Example:

Reserved Configuration Group 1 ([display name]): Axis 0 1 Button 3

Automatic calibration can be specified to bypass all calibration in X-Plane. All axes on the device must be specified as such. Example:

Axis 2 Calibration: auto

X-Plane also checks for and complains at you if you don’t have the required VR assignments (VR X/Y axes plus VR menu enter command) mapped to any VR controller.

New capabilities in X-Plane 12.00

Mark an axis as control-loaded for trim

If an axis is control-loaded instead of spring-entering, its “center” is decided by the control loading software rather than a fixed position. To keep X-Plane from adding trim onto the already trimmed position of the axis, mark an axis that centers itself by force feed back with the tag “ffb”, like so:

Axis [axis index]: [joy use] ffb

37 Comments

Navdata in X-Plane 11 and 12

One dataset to rule them all

In X-Plane 11 and later, one single database is used for all purposes of navigational data in the simulator. All items defined in this common database will be used for the scenery, the map, ATC, AI and the GPS/FMS and radio navigation avionics. In X-Plane 10, it was possible to have a discrepancy between what you saw in the X-Plane world and what was available for GPS navigation. This lack of data integrity is no longer possible. X-Plane 11 has a redesigned navdata hierarchy and new formats, that strongly enforce referential integrity and correctness. Note that the format is not backwards-compatible to any of the old datasets, X-Plane 11 will only load data in the X-Plane 11 format.

X-Plane 12 loads navdata conforming to the 11.50 or later spec, for supporting all features, navdata conforming to the 12 spec is preferred.

No more duplicate airport information

Furthermore, all data about airports and runways is taken from the apt.dat, which has been extended so it can carry information necessary for the avionics. Previously, a separate airports.txt was used to hold information like transition level, longest runway length, etc. Now all this information is taken from apt.dat, which uses the 1302 row code for key-value pairs, which can be edited in WED. The following key-value pairs are part of the apt.dat 1050 specification and are used in X-Plane 11:

region_code, this must specify the region according to ICAO document No 7910
datum_lat, datum_lon, those specify the location of the airport reference point (ARP) in decimal degrees, North and East positive
transition_alt, this must specify the transition altitude in feet
transition_level, this must specify the transition level in feet

Note that this data is already populated for most airports in the scenery gateway. If you find an airport with these values missing or incorrect, use WED 1.5 or later to add/edit these values and upload your change to the scenery gateway.

As of X-Plane 12, the airport data is located in $X-Plane/Global Scenery/Global Airports/Earth nav data/apt.dat and is the one and only source for both scenery and GPS data, so what you see is what you get.

Correct roles and regions, please

X-Plane 11 and 12 distinguish between global and terminal fixes and navaids. Terminal fixes and navaids must specify the arpt/heli ident of their terminal area, according to the 424.20 5.6 Airport/Heliport Identifier. All fixes and navaids must specify the region ICAO code according to the 424.20 5.14 ICAO code. Note especially the seven regions defined for the continental United States. See ICAO document No 7910 for details.
By classification into terminal vs global items and assigning the correct parent terminal area or ICAO region, each item in the database is addressable by a globally unique identifier. Only then it is possible to build the layered structure. X-Plane enforces integrity of this unique index, because it is needed to build the graph of the airway network.

Two supported formats

X-Plane 11 and 12 support two formats in which the global database can be provided:

ARINC 424 supplements 18 up to 20, with the exceptions noted in the FAA/Aeronautical Information Services CIFP Readme
XPNAV1100, 1150 and 1200, as explained further down

Sim-wide ARINC424 override

Professional customers with access to 424 master files can use them to override the X-Plane global database.

Upon sim start, X-Plane will examine the $X-Plane/Custom Data/ folder of its installation for a file named earth_424.dat . If this file is found, it will be interpreted according to the ARINC 424.18 standard with the FAA CIFP exceptions, and will be used to load the following information into X-Plane:

Fixes (EA and PC records)
Navaids (D, DB and PN records)
Airways (ER records)
Published Holdings (EP records)
Minimum Sector Altitude (PS records)
Minimum Off Route Altitudes (AS records)
ILS (PI records)
Markers (PM records)
Airport data (PA records)
Airport gate/parking locations (PB records)
Airport terminal procedures (PD, PE, PF records)
Airport runway information (PG records)
Path points (PP records)
GLS stations (PT records)
GBAS path points (PQ records)

After this file has been read, X-Plane will not load any other information from other text files. It is assumed that when the installation is provided with a global 424 file, no data of any other format needs to be loaded. In particular, X-Plane will then NOT load any of the files described in the following as “Global data”.

Global data

If no global 424 file is present, X-Plane will instead load files of the XPNAV1150/XPFIX1101/XPAWY1100/XPHOLD1140 format. These look superficially similar to the data files of previous versions, but they are fundamentally different in that referential integrity is required, and globally uniqueness with respect to type, code, and region code is enforced at load time. Full file format specifications are available below.

The layered hierarchy of global data

It is important to understand that rather than a full replacement of data, X-Plane 11 and 12 allow the data to be organized in layers with increasing priority, where higher priority data overrides the data from all layers below.

The base – what is shipped with X-Plane:

X-Plane 11/12 ships with a global base layer of data that enables IFR navigation world-wide. The data cycle represented by those files will remain the same over the lifetime of X-Plane 12.
These files are:

earth_fix.dat
earth_awy.dat
earth_nav.dat
earth_hold.dat
earth_mora.dat
earth_msa.dat
CIFP/#ICAO.dat (where #ICAO is each airport with instrument procedures)

they are located in $X-Plane/Resources/default data/ .
Starting with X-Plane 12, these files are also part of the default distribution:

Resources/default data/airspaces/airspace.txt (starting with X-Plane 12)
Resources/default scenery/1200 atc data/Earth nav data/atc.dat (starting with X-Plane 12)

The updated base – what is supplied by third-party providers

This layer is what advanced hobbyist users care about. They want updated data, because they want to fly online. Participation in the online networks usually requires fairly recent data. Aerosoft and Navigraph offer newest data by a monthly subscription. This data consists of the files:

earth_fix.dat
earth_awy.dat
earth_nav.dat
earth_hold.dat (starting with X-Plane 11.40)
earth_mora.dat (starting with X-Plane 11.50)
earth_msa.dat (starting with X-Plane 11.50)
CIFP/#ICAO.dat (where
is each airport with instrument procedures)
airspaces/airspace.txt (starting with X-Plane 12)
1200 atc data/Earth nav data/atc.dat (starting with X-Plane 12)

they must be located in $X-Plane/Custom Data/

These files completely replace the base layer of X-Plane. If these files are present, the X-Plane base layer is ignored. Note that because of the referential integrity, it is not possible to update just the earth_fix.dat and not the earth_awy.dat. Upon load, it is checked that all files are of the same cycle number. Mix-matching different cycles is not supported.

The updated approaches – what we get from the FAA for free

The FAACIFP file is an ARINC424.18 file provided by the Federal Aviation Administration free of charge and can be downloaded from their website.

In X-Plane 11/12, this file is used to replace P* records with the latest from the FAA. The following data is read from this file, and overrides data loaded from the global layer:

Terminal Fixes (PC records)
Terminal Navaids (D records where the 5.6 field is not empty, PN records)
ILS (PI records)
Markers (PM records)
Airport data (PA records)
Airport gate/parking locations (PB records)
Airport terminal procedures (PD, PE, PF records)
Airport runway information (PG records)
Path points (PP records)
GLS stations (PT records)
GBAS path points (PQ records)

The file

FAACIFP18

must be located in $X-Plane/Custom Data/

This file is not shipped with X-Plane but can be obtained from the FAA website free of charge.

Note that no enroute waypoints, VHF enroute navaids, or enroute airways are loaded from this file. These cannot be replaced safely as it would affect the referential integrity of the airway network.

Note that for integrity reasons, the cycle number of the FAA data must always match the cycle number of the underlying layer. Terminal procedures do reference waypoints out of the terminal area, therefore, the data source for global waypoints must be at the same cycle number.

Note also that when FAACIFP is in effect, terminal procedures are overridden on a per-airport basis. No attempt is made to mix-match terminal procedures from global data with those loaded from FAACIFP. As terminal procedures reference terminal waypoints, trying to build terminal procedures from global data with points loaded from FACCIFP could lead to unpredictable results. Therefore, once FAACIFP is in effect, Custom Data/CIFP/#ICAO.dat is overridden for each #ICAO with PD/PE/PF records in FAACIFP.

Hand-placed localizers – manual corrections

Starting with X-Plane 11.50, curated localizer data is only applied to a small number of airports. X-Plane is instead relying on the earth_nav.dat of the XPNAV1150 or newer variety for almost all airports. Such data is shipped with X-Plane 11.50 by default, and also available from Navigraph and Aerosoft. Please be sure to select “11.50 and later” as the data download format if you are on X-Plane 11.50 or later. Data made for X-Plane 11.41 or earlier will not assure 1000th-of-a-degree accuracy for localizers and can thus lead to ILS signals guiding the aircraft beside the runway.

With this data, we have currently identified 5 airports for which the necessary data quality is not assured. These will continue to be supplied from the X-Plane scenery gateway. The file

Custom Scenery/Global Airports/Earth nav data/earth_nav.dat (X-Plane 11)
Global Scenery/Global Airports/Earth nav data/earth_nav.dat (X-Plane 12)

contains these manual corrections for 5 airports. This number might increase if we find more airports with sub-par data quality.

User data – per-user overrides

The last layer is the user-defined layer.

These files are where all custom waypoints are saved. Whenever a custom waypoint is created (through the default FMS) it is saved in the user_fix.dat file, which overrides previously loaded information. The user_nav.dat can hold custom navaids, though there is no way in the X-Plane UI to create them directly.

The files

user_nav.dat
user_fix.dat

are located in $X-Plane/Custom Data/

and are non-existent in a default installation of X-Plane and not touched by the updater.

The user_fix.dat is first created once a pilot-defined waypoint was stored in the FMS. They are the highest layer and ensure user modifications are preserved even with updates from Aerosoft or Navigraph.

ONLY in these user_fix.dat/user_nav.dat can you add or edit the X-Plane world data without being at risk of breaking data integrity. So if you want to add custom fixes or navaids to X-Plane, this is the only safe place to do it.

Note that this does not work for deleting objects that were loaded in a lower layer. You can no longer delete a fix from the UI in a persistent way. If we’d allow for selective deletion of fixes or navaids, airways that might be referencing them would break.

From 424 to XPNAV1100

We provide a simple command line tool called convert424toxplane that is available free of charge. With this tool, data providers can convert 424.18+ files into navdata guaranteed to be compatible with X-Plane 12 and X-Plane mobile.

Do not try to create or edit XPNAV1100/XPFIX1100/XPAWY1100/XPHOLD1140 files by hand. While the format is reasonably human-readable, the data integrity assumptions that are inherent are easily overlooked. Always edit the data in a 424 file, using a tool like the ARINCDecoder v4.3, to ensure validity. Then export the data to X-Plane using the convert424toxplane command line tool.

PQ records are synthesized from the scenery

X-Plane supports tuning GBAS receivers to obtain GLS final approach course and glidepath information. If the Final Approach Segment for a GLS approach is not supplied in an ARINC424 PQ-record, the final approach segment is generated from the runway data in the scenery, with a TCH of 50 feet and a splay angle depending on runway length. This allows flying GLS approaches with ILS-like accuracy.

How do I make my own approach? No hand editing, please!

In the past, we have been asked how to edit existing procedures or create own, fictional procedures – maybe you want to prototype a future LPV approach into your own backyard airstrip?

Terminal Procedure description follows the coding rules laid out in ARINC 424.20, Attachment 5, “Path and terminator”. Correctly coding procedures obeying all those rules by hand is next to impossible, which is why industry tools have been developed to work with these files.

For X-Plane 10, no tools existed to design custom approaches, and attempts to hand-code them in text were extremely difficult and didn’t work most of the time.

With X-Plane 11/12, you have the full power of the ARINC424.18+ at your disposal. To evaluate, edit, or even design a new procedure, we strongly recommend the ARINCDecoder v4.3 program, which is an incredibly powerful tool.

Global Data Formats

The files are designed to be easily parsed, have low overhead (no XML!) and will look inherently familiar in structure if you’re familiar with the files for X-Plane 10 already. The file format changes to X-Plane 10 are clearly lined out at the beginning of each document.

Please consider the following file format specifications as a guide how to parse X-Plane 11/12 navdata, not to generate it (see warning above).

XPFIX1101: XP FIX1101 Spec
XPNAV1150: XP NAV1150 Spec
XPAWY1100: XP AWY1101 Spec
XPHOLD1140: XP HOLD1140 Spec
XPCIFP1101: XP CIFP1101 Spec
XPMSA1150: XP MSA1150 Spec
XPMORA1150: XP MORA150 Spec

Starting with X-Plane 12:

XPFIX1200: XP FIX1200 Spec
XPNAV1200: XP NAV1200 Spec
OpenAIR airspace files: This is not an X-Plane format. Kindly refer to the original documentation for WinPilot.

Comments Off

Autogen String (.ags) File Format Specification

An Autogen String art asset is an art definition to place a large number of tile-based scenery buildings around a polygonal shape. AG strings are designed to cover highly irregular shapes (including shapes with holes for lakes) in a “best-fill” manner.

The AG string contains:

A number of tile definitions – X-Plane picks from the tiles to place autogen.
Spelling and selection rules that specify which tiles are used under which use cases.
Global properties affecting use of the art asset.

Since the AG String is a type of autogen, all autogen directives may be used.

DSF Usage

Autogen strings are specified as a DSF polygon feature. The sequences of contours in the polygon are treated as independent poly-lines (e.g. 3 points in a contour sequence define two lines) such that:

The outermost winding is counterclockwise; holes in the polygon are clockwise.
No edges overlap, and every winding is fully closed (two adjacent windings share and duplicate a vertex).
Contours are ordered so that tile-spawning contours are first in the DSF.

The polygon parameter low 8 bits define the number of contours that have tiles attached to them. Contours are ordered so that the “tile-spawning” contours come first.

The polygon parameter high 8 bits are the height of any buildings within the AG element divided by four, for a maximum height of 1024 meters (in 4 meter increments).

Tiles are placed in the contour order from the DSF file; it is recommended to try to keep windings as close to a counter-clockwise circulation as possible.

AGString-Wide Properties

CREASING_ANGLE left-crease-degrees right-crease-degrees

The crease angle specifies how many degrees the boundary of the AG-polygon must turn for a vertex in the polygon boundary to be considered a “corner”. The assumption is that for very small angle changes, the poly-line is to be considered a single continuous side. The crease angle is a change in heading of the edge, first for left turns, then right turns. The default crease angle is 30 degrees for both.

FILL_LAYER layer-number

The fill layer directive specifies which layer of the .for file associated with this autogen is used to flood-fill the interior of the AG string with trees after tile placement completes. Trees are selected randomly from this layer.

HIDE_TILE

This directive causes the ground tiles to not be drawn at all. If you do not need ground tiles (e.g. the ground markings are accomplished via OBJ draped textures) then HIDE_TILE is much more efficient than using a 100% alpha clear ground tile.

SHARE_Y

Normally the elevation for buildings on the ground (for graded autogen buildings) is picked on a per-tile basis, using the GROUND_PT directive. If SHARE_Y is enabled, then for every atomic spelling of tiles that is placed, all graded buildings in the atomic spelling share the ground point of the first tile that is placed.

The intention of this directive is to let you model a single building across multiple tiles in parts and get the same vertical placement for all graded buildings.

Tile Specification Properties

These properties add additional per-tile data, specific to AG Strings, in addition to what is legal in all autogen.

TILE_ID id

This specifies the ID number of the next tile, for spelling purposes. If TILE_ID is omitted, tiles are assigned integers in file order starting from 0. TILE_ID is recommended to let authors understand which tile is which.

TILE left bottom right top

This defines a new tile, whose coordinates are specified in texture pixels. Annotations and markings must follow the tile they apply to.

STOP_PT s t

This defines a “stop-point” – that is, a barrier that may not be penetrated. When the tile is placed, it will be moved so that the stop point is within the DSF polygon; when a tile is placed, it will be slid so that it does not cover previously placed stop points.

If a tile cannot be placed without a stop point being out of bounds (e.g. the stop point would be in a lake) the tile is skipped. Use stop points to ensure that 3-d elements are not covered or under the road grid.

PIVOT_LEAD_PT s t

PIVOT_TRAIL_PT s t

The pivot lead and trail points define connection points when a 3-tile articulated corner is used. The three tiles will be placed so that, counterclockwise, the previous tile’s lead point will be co-located with the next tile’s trailing point and the angle change between the first and second tile is the same as the second and third tile.

Tile Selection Properties

The autogen string’s tiles are placed by:

Placing corner tiles in the DSF contour order, counter clockwise along each contour.
Placing edge tiles along the sides of the contours filling in space and
Placing “caps” at the end of each side to cover the last tile.

GROUP group-id tile-id [tile-id … [tile-id]]

Tiles may optionally be placed into groups for selection – each group defines one group with a set of tiles. A tile may be in zero, one, or many groups. Group IDs must be positive integers.

Corner Selection Properties

The corner selection properties specify that a tile may be used to fill in the corner of a polygon. Tiles can be used in more than one corner directive, or in corner and edge directives.

CORNER angle-min-degrees angle-max-degrees id1 [id2 id3]

This specifies that tile id1 (or the three-tile id1,id2,id3 triplet) form a corner, as long as the angle of the corner is within the degree range specified.

All angles are measured in degrees of turn when walking along the outside of the DSF contour; therefore a right turn (a reflex corner) is a positive turn. A simple square block has four turns of -90 each.

CORNER_LEN min-len1-meters max-len1-meters angle-min-degrees angle-max-degrees min-len2-meters max-len2-meters group-id tile-id1 [tile-id2 tile-id3]

This operates just like corner, but with additional restrictionss for selecting the tile: if group-id is not zero, the previous corner that was placed must be within group-id, or this corner must be first. Len1 and len2 specify ranges in meters that the previous and next edge must fit within. Thus CORNER_LEN gives the author more certainty about when a corner is used.

Note: the length of the side is measured as the length of a single line segment, even if the preceding contour has several small segments all below the crease angle. Thus CORNER_LEN will only work when the DSF polygon is made of a few large segments, not a long string of small angle changes.

CORNER_PAIR angle1-min-degrees angle1-max-degrees length-min-meters length-max-meters angle2-min-degrees angle2-max-degrees group-id tile-id1 [tile-id2 tile-id3]

CORNER_PAIR works like CORNER_LEN, except that it places two consecutive corners. The angles are for the first and second corner preceding counter clockwise, and the length is the length of the single side between them. Thus this lets authors place pairs of matched corners where they are close together in expected situations.

ATOMIC_SPELLING_CORNER min-len1-meters max-len1-meters angle-min-degrees angle-max-degrees min-len2-meters max-len2-meters group-id tile-id1 [tile-id2 tile-id3]

This works just like CORNER_LEN with one special behavior: tile placement is “atomic”. Atomic placement means that if not all three tiles can be placed, then no tiles are placed, and a different corner is tried.

The intention of atomic corners is to allow authors to build 3-tile articulated corners where the art assets do not look correct without all three tiles. In a normal corner, any one tile may be eliminated, e.g. due to a collision with an interior hole in the polygon. With an atomic corner, the entire corner acts as an indivisible atom – it is either entirely placed or entirely skipped.

CORNER_ORDER index1 index2 index3

This command can follow any corner directive that specifies 3 tiles and indicates the order that the tiles are placed. Normally the tiles are placed middle, preceding, trailing, but this order can be customized, e.g. if the order is 2 1 0 then trailing, middle, then preceding are used.

The placement order affects two things: the tiles overlap based on placement order – the first tile placed is on the bottom. Second, the first tile placed defines the ground point for shared_y autogen.

PRIORITY_MARKER_CORNER

This directive specifies a group of corners to be considered. All corners within the priority group have equal probability of appearing, but one will be tried first before a corner from a lower priority group is considered.

Edge Selection Properties

SPELLING tile-id1 [tile-id2 […tile-id-n]]

This specifies that a list of tiles (specified by ID) in order will be used to fill an edge. Once all corners are placed, X-Plane randomly selects spellings to fill the edges with the best fit it can find. Spellings allow you to select adjacency to control the randomization process.

An autogen element should contain spellings with a range of lengths to fit various sized edges.

ATOMIC_SPELLING length-min-meters length-max-meters group-id tile-id1 [tile-id2 […tile-id-n]]

An atomic spelling functions like a spelling with the following extra behavior:

The spelling is either entirely placed or discarded – individual tiles from the spelling don’t appear on their own due to collisions with other tiles.
The spelling is only considered if the previously placed tile is within group-id, this is the first spelling of the side, or the group-id is 0.
The length of the side (the single segment, not poly-line) is within len-meters.

Like atomic corners, the intention of atomic sides is to form multi-tile buildings that appear as a whole or not at all.

PRIORITY_MARKER

This defines a group of spellings that will be considered first (randomly within the group) before backup spellings are considered.

Cap Selection Properties

CAPS tile-id [tile-id [… tile-id]]

This marks a set of tile IDs as being eligible to be a cap. Caps are small tiles placed at the end of edges to cover the last tile placed. Caps are optional – if no cap is found, no cap is used. More than one CAPS directive may appear to specify caps.

Comments Off

Autogen Block (.agb) File Format Specification

Autogen blocks are autogen elements made up of a 2-d grid of adjacent tiles. AG Blocks are designed to tightly fill and pack rectangular areas, e.g. a city grid.

Unlike AG strings and points, the tiles in AG blocks are not specified individually, but rather by a 2-d grid. It is a requirement that the grid be built as a 2-d grid in the tile texture sheet. (The optimization is that for long strings of adjacent tiles, the entire set of tiles is drawn at once.)

An AG Block contains one or more grids; rules define which grid is used in which cases.

An AG block also contains spelling sets that indicate how the tiles in a given grid are included or removed from the grid. The relationship is many to many: any spelling set can reference any grid.

Slop and Anti-Slop

The majority of the size changes of an AGB are made by adding and removing tiles from the grid. However, the AGB also features resizable “slop” tiles that can be overlapped by their neighbors for the purpose of resizing the grid by small arbitrary distances.

Slop is defined by setting an entire row or column of the tile array as a ‘slop’ tile. A slop tile can be overlapped by its neighbor (to the right or above in the texture), and annotations that would be covered are dynamically removed if their point location is covered.

A slop tile can define “overlap” – the number of pixels of the slop zone that will be covered by the next tile over. This allows the next tile (which is on top of the slop tile) to contain a soft alpha edge that will always have the slop tile underneath it.

Thus the minimum size of a slop tile in an AGB is zero – it can be entirely compressed and serve as backing underneath the next tile. At its maximum stretch, the size of the tile is the tile size minus the overlap, since the next tile must start.

There is a second way to control alpha overlap: for any non-slop tile, an “anti-slop” parameter can be defined that causes this tile to be started some number of pixels to the left or below of its normal location, overlapping the previous tile. This can be used to make tiles with alpha edges that always overlap the previous tile.

DSF Usage

Autogen blocks in a DSF are specified by a four-point single-contour DSF polygon, counter-clockwise. Holes are not permitted. The upper 8 bits of the DSF parameter is the object height divided by four, and the lower 8 bits of the DSF parameter matches a particular spelling set.

The first segment of the AG block defines the orientation of the block. By convention, the bottom of the texture is aligned with this first side and forms the “S” or “H” axis.

Properties of the Entire .AGB

CROP 0|1

The crop directive defines whether tiles that go outside the DSF polygon are cut at the DSF polygon. The default behavior is false. Because the AGB can hang over the edge of the DSF polygon (when the DSF polygon is not a perfect rectangle), cropping can be useful to remove tile artifacts that cover other parts of the scenery like roads.

FLIP_180

Normally the first edge of the DSF polygon runs along the bottom of the AGB grid texture, with the left side of the directed polygon edge touching the AGB. When FLIP_180 is included, the first side of the DSF polygon runs along the top of the texture from right to left, flipping the entire AGB by 180 degrees.

Grid Specification and Properties

A sub-grid is a 2-d array of tiles specified together. The AGB contains one or more sub-grids.

SUB_GRID

This directive marks the beginning of a grid within the AGB. Unlike AGS and AGP files, all tiles are specified at once within the grid. Grids are numbered consecutively with the first grid having index 0. If the SUB_GRID directive is omitted, the first grid defined in the file is treated as GRID 0.

OVERLAP_H pixels

OVERLAP_V pixels

These directives define how many pixels of slop tiles must be overlapped by the next tile. Typically the tile following a slop tile will have alpha on the left edge; the overlap is the size of this alpha zone. Overlap ensures that the slop zone will not be stretched so much that there is no tile below the alpha.

These directives set a default slop – the SLOP_H/V directives let you override it on a per-tile basis.

ANTISLOP_H pixels

ANTISLOP_V pixels

These directives define the number of pixels of overlap that a non-slop tile will cover of the tile to the left or below them.

CUT_H pixels

CUT_V pixels

The CUT directives define the grid lines of the AG grid. For N h-cut lines there are N-1 horizontal tiles and for N v-cut lines, there are N-1 v-cut tiles. Properties defining the tiles (slop, anti-slop) must be defined after a cut directive but before the very last cut directives.

Cut directives must occur in increasing order of pixel grid line location. An AGB must have at least two cuts in each direction.

SLOP_H [pixels]

SLOP_V [pixels]

These define the preceding horizontal or vertical tile (whose left or bottom edge have just been defined with a cut directive) as a slop tile row or column. If pixels is included, it defines the amount of overlap that the next tile will cover the slop zone with; if it is omitted, the last OVERLAP_H/OVERLAP_V directive is used.

END_CUTS

This marks the end of the sub-grid definition; no more cuts or slop directives can occur until the next sub-grid.

Unlike AGS and AGP, annotations are placed on the entire grid – you do not need to tell X-Plane which tile an annotation is for. All annotations must occur after END_CUTS and before the next sub-grid.

EDGE_MIN left bottom right top

EDGE_BEST left bottom right top

EDGE_MAX left bottom right top

X-Plane aligns the tile grid to the DSF rectangle by aligning the bottom edge of the tile grid (or top for flip-180) with the first edge of the DSF polygon. The grid is then sized so that the DSF polygon goes through the tiles somewhere between EDGE_MAX and EDGE_MIN, as close to EDGE_BEST as possible. (In other words, in a perfectly rectangular DSF, EDGE_BEST is used, but if the DSF polygon is trapezoidal, then parts of it may come closer to edge min/max.

EDGE_MAX is the largest acceptable rectangle, e.g. it defines how far away from the center of the grid the DSF polygon can be; EDGE_MIN defines how close to the contents of the tiles the DSF boundary can get. When cropping is on, no content inside EDGE_MIN will ever be cropped.

GROUND_PT_FORMULA x-ratio x-delta y-ratio y-delta

When a tile contains the GROUND_PT_FORMULA directive, the point used to align graded objects with the ground is calculated using a formula based on the entire DSF boundary rectangle:

A blending weight is found between the four corners of the ideal square rectangel using x-ratio and y-ratio.
The location of the four corners are averaged using these blending ratios.
The x and y delta (in meters) are then applied, where X is a direction along the first DSF polygon side and Y is a direction perpendicular and counter clockwise from it.

The intention of this directive is that a number of tiles sharing parts of a common building can all use the same formula to achieve a common grading point somewhere within the AGB.

Note that since there are no tile directives, the tile that this directive applies to is based on the previous annotation that is placed. The intended use is to use this after the OBJ_GRADED directive that defines the object that needs special registration.

Spelling Set and Tile Selection Properties

The AGB also contains spelling sets. Each spelling set contains rules for how to use a grid (with tiles added and removed) and matching parameters for when it may be used. Note: if no spelling set matches the required situation, the first one in the AGB is used as a default.

SPELLING_SET param

This defines a new spelling set. The param value must match the low 8 bits of the DSF parameter. (This lets the DSF select variants on an AGB.) By convention, X-Plane scenery often uses these values:

HEIGHT_RANGE min-height-meters max-height-meters

WIDTH_RANGE min-width-meters max-width-meters

DEPTH_RANGE min-depth-meters max-depth-meters

These parameters require that the spelling set only be used when the width, height, or depth of the AGB is within certain metric ranges. The width is the shortest width across the DSF polygon along the direction of the first side; the depth is the shortest distance normal to it. The height is the metric height passed in the DSF parameter.

FREQUENCY ratio

This controls the relative frequency of this spelling set compared to others. When a random spelling set is picked from all spelling sets that match filtering criteria above, the relative frequencies weight the random drawing. The default weight is 1.0.

USE_GRID index

This indicates which grid to use with this spelling set, by zero-based index.

SPELLING_S col-index col-index […col-index]

SPELLING_T row-index row-index […row-index]

The spelling directives each define one spelling (of horizontal columns or vertical rows) that can be used to build real tile grids out of the grid for this spelling set. X-Plane will re-assemble the AGB grid from the columns and rows specified in the order specified.

You should include many spelling directives to provide spellings of different lengths to cover the entire size range the AGB spelling set is filtered to fulfill.

From a performance perspective, consecutively increasing non-anti-slop tiles are more efficient than arbitrary tiles because they can be drawn as a group.

DEFINE_SPELLING_S namecol-index col-index […col-index]

DEFINE_SPELLING_Trow-index row-index […row-index]

USE_SPELLING_S name

USE_SPELLING_t name

The define-spelling directives simply create a recallable name (within this .agb) for a given spelling column or row list. The USE_SPELLING directive with that name is the same as having a duplicate SPELLING_S or SPELLING_T directive with that set of tiles.

The use case for named spelling sets is when the same texture space is used to create a grid with the same cut lines and slop, with only the autogen annotations changing. In this case, it might be useful to simply have the exact same spellings for each grid.

Comments Off

Airport Data (apt.dat) 11.00 File Format Specification

REVISION HISTORY

16 Nov 2021	Updated new lines styles added in 11.30, correct wording in rowcode 21 name field.
11 April 2019	Updated with new COM frequency capabilities added in 11.30.
14 Feb 2018 Minor corrections to Definition of Data fields.
11 April 2017 Revised row code 1201.
18 Jan 2017 Spec created.

APPLICABILITY

This specification (APT.DAT 1100) is supported in X-Plane 11.00 and later and by WorldEditor 1.6b1 and later. The prior specification for airport data was APT.DAT 1050, which is recommended for X-Plane 10.50+. This spec is an extension to 1050 – all features in 1050 are fully supported.

SUPPORT FOR DEPRECATED FILE FORMATS

The deprecated file specification (APT.DAT 1050, 1000) is still supported. A dwindling quantity of custom airport data exists only in this format. So airports defined according to this specification can be included in a file otherwise complying with the APT.DAT 1100 specification.

The specification for APT.DAT 1050 is available to view here.

OVERVIEW & SCOPE

This specification (1100) introduces new service truck parking and destination features.

This specification does not include scenery objects (such as buildings, static aeroplanes or underlying terrain textures).

BASIC CONCEPTS

Latitudes and longitudes are described in a decimal notation (eg. 20.12345678) up to 8 decimal places.
- A latitude of 50 degrees 30 minutes south would be defined as -50.50000000
North latitudes and east longitudes are positive. South latitudes and west longitudes are negative.
All headings are referenced to true north (not magnetic north).

FILE CHARACTERISTICS

The apt.dat files are plain text files:

Fields in the data can be separated by one or more white space characters (space, tab).
- By default, the files are generated so that columns of data are consistently aligned, but this is not required.
Blank rows are permitted and are helpful to differentiate between airports.
Comments are permitted and are indicated by “#” as the first two characters of a row.

FILE STRUCTURE

It is recommended that all airports be created in WorldEditor (“WED”). This will ensure that all structural requirements listed here for airport data are met. WED version 1.6 is required to support the features in this spec.

I
1000 Version - data cycle 2012.03, build 20121054, metadata AptXP1000. Copyright © 2012, Robin A. Peel (robin@xsquawkbox.net)...

The complete copyright message must be left intact if you redistribute this data. The GNU GPL (general public License) under which this data is released is designed to encourage modifications, enhancements and redistribution, even in commercial derivative products.

Subsequent rows of data follow a hierarchical structure:

Each row of data has a numeric ‘row code’ as its first field, to define its content.
The top level of this hierarchy defines an individual airport, defined by an airport header row (a row code of ‘1’, ‘16’ or ‘17’).
Subsequent rows define elements of an airport:
- Runways (including helipads) follow the airport header row (one row per runway).
- Pavement (taxiway/apron) definitions have a header row followed by an ordered list of nodes that define its boundaries:
  - Each pavement definition must each have a single boundary with no overlaps with itself.
  - Nodes on this outer boundary must be defined in a counter-clockwise direction.
  - Boundaries must be terminated with a node with a row code ‘113’ or ‘114’.
  - Pavement definitions may overlap with another pavement chunk. But this is not recommended – instead consider precise alignment of adjacent features by ‘snapping’ nodes to identical locations in World Editor (WED).
    - A pavement definition can never overlap with itself.
  - The sequencing of the pavement definitions is the layering in which they will be rendered in X-Plane, top-down. So the last piece of pavement in the file will be rendered underneath any others with which it overlaps.
  - Holes can be defined for pavement (through which the underlying terrain texture will show):
    - Hole boundaries should follow the termination of the pavement definition in which the hole occurs (starting with a row type ‘111’ or ‘112’).
    - Hole boundaries are defined in a clockwise direction (ie, opposite direction to the boundary nodes).
    - Hole boundaries must form a closed loop (ie. must terminate with a row code ‘113’ or ‘114’).
    - Each pavement definition can have zero, one or multiple hole boundaries.
    - Hole boundaries must be contained within the outer boundary of the pavement definition.
    - Holes cannot overlap each other.
    - After creating a hole boundary, it can be ‘filled’ with a new pavement chunk (probably using a different surface type).
- Linear features also have a header row followed by an ordered list of nodes that define the line:
  - Linear features can be closed loops (terminating in a node of type ‘113’ or ‘114’) or just strings (terminating with ‘115’ or ‘116’).
- An airport boundary is defined with nodes in a counter-clockwise direction. A boundary can contain holes (see above) and must form a closed loop (terminating in a node of type ‘113’ or ‘114’).
- Airport traffic flows have a header row (row code ‘1000’) followed by multiple rows that define rules of multiple classes (time, wind direction, ceiling, visibility, runway in use, VFR traffic pattern) that indicated that a flow should be used (wind rules, minimum ceiling rules, visibility rules, time rules, and operations rules).
  - A flow is acceptable is any rule of a class is acceptable, or if there are no rules of a given class. So to permit a flow with no time restrictions, simple exclude any traffic time rules (row code ‘1004’).
  - Rules use ‘or’ logic. For example, a flow may have two wind rules (row code ‘1001’) – one for slight winds very generally aligned with a runway, and one with strong winds only if they are almost exactly with the runway.
  - A flow will be used only if all its rule classes are ‘passed’.
  - The flows are evaluated in sequence. The first flow to ‘pass’ will be used. So, the most specific-but-useful rule should be listed first (eg. parallel VFR approaches on a clear, calm day) and the most general (but least useful) rules should be listed last (eg. a single ILS cat III approach to a single runway).
  - If the rules prevent any defined flow from being ‘passed’ then the X-Plane’s AI engine will create a flow.
  - ‘Runway in use’ rules (row code 1100} are also evaluated in sequence. The first ‘runway in use’ rule to ‘pass’ will be used for the parent flow. So rules should be listed in preferential sequence.
- Airport taxi routes & networks begin with a row code ‘1200’ and are defined by a set of nodes (row code ‘1201’) and ‘edges’ (the taxi routing) that connect two nodes (row code ‘1202’):
  - Nodes can be defined as ‘init’ (a point at which X-Plane will try to start a taxi route), ‘end’ (where X-Plane will try to end a taxi route), or ‘both’. ‘junc’ can also be used for junctions between taxi routes.
  - Edges must specify an allowed width, sizes A-E, and may be followed by multiple rows (row code ‘1204) defining an ‘active zone’ ‘for that parent edge (eg. if the edge conflicts with arrival or departure runways, or an ILS-critical area).
  - Taxi routings begin or end at ramp locations (row code ‘1300’), which are also available as startup-locations in X-Plane. These locations may not be directly connected to the taxi route network – X-Plane’s ATC engine will calculate how to direct an airplane between the taxi route network and each location.
  - Ground truck route edges (row code ‘1206’), parking locations (row code ‘1400’), and destinations (row code ‘1401’) are included under row code header ‘1200’ for taxi networks.
- Other airport features are defined with one row for each feature.

The file is terminated by a ‘99’:

ROW CODES

Each row of data begins with an integer code that defines the type of data:

Row Code	Meaning	Comment
1	Land airport header
16	Seaplane base header
17	Heliport header
100	Runway
101	Water runway
102	Helipad
110	Pavement (taxiway or ramp) header	Must form a closed loop.
120	Linear feature (painted line or light string) header	Can form closed loop or simple string
130	Airport boundary header	Must form a closed loop
111	Node	All nodes can also include a “style” (line or lights)
112	Node with Bezier control point	Bezier control points define smooth curves
113	Node with implicit close of loop	Implied join to first node in chain
114	Node with Bezier control point, with implicit close of loop	Implied join to first node in chain
115	Node terminating a string (no close loop)	No “styles” used
116	Node with Bezier control point, terminating a string (no close loop)	No “styles” used
14	Airport viewpoint	One or none for each airport
15	Aeroplane startup location	* Convert these to new row code 1300 *
18	Airport light beacon	One or none for each airport
19	Windsock	Zero, one or many for each airport
20	Taxiway sign (inc. runway distance-remaining signs)	Zero, one or many for each airport
21	Lighting object (VASI, PAPI, Wig-Wag, etc.)	Zero, one or many for each airport
1000	Airport traffic flow	Zero, one or many for an airport. Used if following rules met (rules of same type use ‘or’ logic, rules of a different type use ‘and’ logic). First flow to pass all rules is used.
1001	Traffic flow wind rule	Zero, one or many for a flow. Multiple rules use ‘or’ logic.
1002	Traffic flow minimum ceiling rule	Zero or one rule for each flow
1003	Traffic flow minimum visibility rule	Zero or one rule for each flow
1004	Traffic flow time rule	Zero, one or many for a flow. Multiple rules use ‘or’ logic.
1100	Runway-in-use arrival/departure constraints, 10kHz frequency resolution	First constraint met is used. Sequence matters!
1110	Runway-in-use arrival/departure constraints, 1kHz frequency resolution	Alternate option to row code 1100
1101	VFR traffic pattern	Zero or one pattern for each traffic flow
1200	Header indicating that taxi route network data follows
1201	Taxi route network node	Sequencing must be 0 based, ascending by ID. Must be part of one or more edges.
1202	Taxi route network edge	Must connect two nodes. Also takes one of 6 sizes (A-F).
1204	Taxi route edge active zone	Can refer to up to 4 runway ends
1300	Airport location (deprecates code 15)	Not explicitly connected to taxi route network
1301	Ramp start metadata.	Includes width, operations type, equipment type, & airlines.
1302	Metadata records	Zero or many for each airport.
1400	Truck Parking Location	Not explicitly connected to taxi route network.
1401	Truck Destination Location	Not explicitly connected to taxi route network.
1050-1056	8.33kHz communication frequencies (11.30+)	Zero, one or many for each airport
50 – 56	Legacy 25kHz communication frequencies	Zero, one or many for each airport. Ignored if row codes 1050-1056 exist.

EXAMPLE DATA

Here is some example data for KBFI. It is not real and is very incomplete, but it illustrates examples of most types of data found in an apt.dat file. This data includes an airport header, runway, water runway, helipad, PAPI, taxiway definition, painted line, viewpoint, startup location, light beacon, windsock, taxiway sign and an ATC communications frequency:

1 21 1 0 KBFI Boeing Field King Co Intl
100 29.87 1 0 0.15 0 2 1 13L 47.53801700 -122.30746100 73.15 0.00 2 0 0 1 31R 47.52919200 -122.30000000 110.95 0.00 2 0 0 1
101 49 1 08 35.04420900 -106.59855700 26 35.04420911 -106.59855711
102 H1 47.53918248 -122.30722302 2.00 10.06 10.06 1 0 0 0.25 0
21 47.53666659 -122.30585255 2 150.28 3.30 13L PAPI-2L
110 1 0.25 150.29 A2 Exit
111 47.53770968 -122.30849802
111 47.53742819 -122.30825844 3
112 47.53752190 -122.30826710 47.53757385 -122.30824831 3 102
114 47.53768630 -122.30834929 47.53768690 -122.30838150 3 102
120 Line B1
111 47.53969864 -122.31276189 51
111 47.53977825 -122.31255145 1
115 47.54002296 -122.31189878
14 47.52917900 -122.30434900 100 0 ATC Tower
15 47.52926674 -122.29919589 304.16 A8 Run Up
18 47.52920400 -122.30412800 1 BCN
19 47.53900921 -122.30868700 1 WS
20 47.54099177 -122.31031317 235.71 0 2 {@L}A1{@R}31R-13L
50 12775 ATIS

Here is some example data for KSEA showing the new 1000 version traffic flow and taxi route data:

1000 Calm and South flow
1001 KSEA 000 359 5
1001 KSEA 070 250 999
1002 KSEA 0
1003 KSEA 0
1004 0000 2400
1100 16C 11920 arrivals jets|turboprops|props 160340 161161 Arrival 16C
1100 16R 11920 arrivals jets|turboprops|props 341159 161161 Arrival 16R
1100 16L 11920 arrivals heavy 000359 161161 Arrival Heavy Jets
1101 16R right
1200
1201 47.46360812 -122.30613338 both 5416 A_stop
1202 5258 5266 twoway taxiway B
1204 ils 34R
1300 47.43931757 -122.29806851 88.78 gate jets|turboprops A10

Here is some example data for KSEA showing the 1050 metadata and 1100 ground truck additions:

1000 Calm and South flow
1001 KSEA   000 359 5
1001 KSEA   070 250 999
1002 KSEA   0
1003 KSEA   0
1004 0000 2400
1100 16C 11920 arrivals jets|turboprops|props 160340 161161 Arrival 16C
1100 16R 11920 arrivals jets|turboprops|props 341159 161161 Arrival 16R
1100 16L 11920 arrivals heavy 000359 161161 Arrival Heavy Jets
1101 16R right
1200
1201  47.46360812 -122.30613338 both 5416 A_stop
1202 5258 5266 twoway taxiway B
1204 ils 34R
1300  47.43931757 -122.29806851  88.78 gate jets|turboprops A10

DEFINITION OF DATA FIELDS

For a complete table of example definitions, download the APT1100 Spec pdf document.

Comments Off

article_type: File Format Specification

Revision History

Applicability

Support for Deprecated File Formats

Overview & Scope

Basic concepts

File Characteristics

File Structure

Row Codes

Example Data

Definition of Data Fields

Codes

Further Information

lights.txt Header

lights.txt Body

RECORD TYPEs

OVERLOADs

OVERLOAD Types

OVERLOAD Parametrization Restrictions

LIGHT_PARAM_DEFs

Regular Parameters

Special “Hint” Parameters

ARGUMENTS explained

More notes on frequency:

Hotspot Definitions

REF_POINT_ACF (V12 and later)

BEGIN_TELEPORT_HOTSPOT

END_TELEPORT_HOTSPOT

AABB

PRESET_XYZ

PRESET_PSI <deg 0 – 360>

PRESET_THE <deg -90 – 90>

PRESET_PHI <deg -180 – 180>

Manipulator Customization

BEGIN_MANIP <cmnd1/dref1> <cmnd2/dref2>

END_MANIP

ACTION axis_knob

ACTION axis_switch_up_down (V12 and later)

ACTION axis_switch_left_right (V12 and later)

ACTION drag_xy four_arrows

ACTION command_axis (V12 and later)

ACTION command_knob (V12 and later)

ACTION command_switch_up_down2 (V12 and later)

ACTION command_switch_left_right2 (V12 and later)

DEG_PER_ACTION

SWITCH_THRESHOLD

WRAP_MANIP

HOLD_MANIP

INVERT_MANIP (V12 and later)

DISABLE_VISUALS (V12 and later)

JOYSTICK_MANIP

YOKE_MANIP_TRANSLATE

YOKE_MANIP_ROTATE

Example

Backward compatibility

Dataref Matching Conditions

Constants Used In The File Format

General Directives

Sound Attachment Directives

Sound Space Definitions

Creating a default joystick configuration file

Creating an image map

Notes on the image files

Nitty gritty: a sample .joy file, as of X-Plane 11.20

Coping with hardware eccentricities

“Phantom” buttons & axes

Axes with limited range of motion

Devices with more than one hat switch

Toggle switches: when a “button” isn’t a button

The 2-position switch

The 3-position switch

The “special” 3-position switch

Grouping switch “buttons”

New capabilities in X-Plane 11.20

Group buttons and axes together

New ways to use axes

Self-centering axes operating as linear axes

Axes operating as commands

Axes operating as hat switches

Handling VR controllers