This RFC proposes new features to the apt.dat format for X-Plane 10.50 to support the X-Plane Scenery Gateway and static aircraft spawning. It consists of two parts: one for static spawning and one for airport identifiers.
This RFC is not a general call for feature requests for the apt.dat format – it aims to solve two specific problems.
Part 1: Static Aircraft Spawning and Aircraft Metrics
In order to make ramp positions more suitable to both AI and static aircraft, the apt.dat 1050 file format includes extra meta-data on parking spots and ATC taxi routes.
Clearance Widths on Taxi Edges
Clearances for aircraft are described using the standard ICAO category codes for aircraft, A-F. Roughly speaking the coding is:
| Wheel Base | Wing Span | Category |
|---|---|---|
| 4.5m | 15m | A |
| 6m | 24m | B |
| 9m | 36m | C |
| 14m | 52m | D |
| 14m | 65m | E |
| 16m | 80m | F |
Both parking spots and ATC taxi route (that are not runways) gain a new maximum ICAO category, describing the largest aircraft that can safely operate on this ATC taxi route or parking spot.
For ATC taxi route edges, this is accomplished with 6 new type tokens: where taxiway edges (record type 1202) could normally be one of “runway” or “taxiway”, new “sized” taxiways are permitted: taxiway_A, taxiway_B, taxiway_C, taxiway_D, taxiway_E, taxiway_F. Edges corresponding to runways do not need sizes because X-Plane can determine the runway width from the actual runway (type 100) record.
Ramp Starts
Additional metadata is included in a new 1301 record, which follows the 1300 (new ramp start) record.
The 1301 record consists of an ICAO width code, an operations type code and zero or more space separated 3-letter airline codes, e.g.
1301 icao_width operations_type [airlines] 1301 C airline AAL SWA UAL
The ICAO width must be one of: A, B, C, D, E, F
The operations type must be one of: none, general_aviation, airline, cargo, military
Additional Equipment Classes
A new equipment class is introduced, “fighters” – it is allowed anywhere that the original five equipment classes (heavy, jets, turboprops, props and helos) are allowed.
Clearance Widths
For ramp starts, this is accomplished by allowing a size flag (A, B, C, D, E, or F) to be included in a new extended ramp start (type 1301) record.
Ramp Operation Types
Ramps gain a new field: “operations type,” indicating what kind of AI or static aircraft appear there. Can be set to: none, general_aviation, airline, cargo, military.
Airline Sets
A ramp start may optionally tagged with a set of valid 3-letter ICAO airline codes, which must be entered as capital letters.
Part 2: Airport Identification Meta-Data
Historically, the apt.dat file provided a single identifier field, sometimes referred to as an ICAO identifier. This identifier was a mandatory primary key for the airport, and therefore if an ICAO code did not exist for an airport, some non-ICAO code had to be made up and stuffed in this field. For US airports, typically an FAA code was used, and for non-US airports, there was no clear standard. Recently the X-Plane Scenery Gateway project designed a fixed rule-set to create non-conflicting synthetic identifiers by extending the field beyond four characters.
Finding an airport by identifier can thus be challenging; if the identifier is synthetic, searching by an IATA code or a local authority code will not work.
This extension aims to solve this problem by separating the primary airport identifier key (whose goals are uniqueness and stability) from other meta-data keys aimed at airport discovery (e.g. to aid search).
Going forward, the airport identifier referred to in the type 1, 16 or 17 record is known as an airport identifier, and is required to be a globally unique identifier for a particular real-world airport. The identifier can be synthetic or match a real world authority, but it cannot be ambiguous, and it cannot be omitted.
Each airport may have zero or more meta-data records, record code 1302, which is defined as
1302 key value
For example:
1302 icao_id KBOS 1302 faa_id BOS 1302 iata_id BOS
A key may not appear more than once per airport amongst all 1302 records. Keys must not contain white space or commas but values may.
The legal semantics of a given key (e.g. global uniqueness, accepted character set) is defined on a per-key basis; the only guarantees of the file format itself are file-valid (UTF8) characters, no white space or commas in keys, no newlines in keys or values, and no repeating keys. No key is mandatory. An empty key is illegal. Only officially defined, supported, conforming, and non-empty keys are allowed.
For the purposes of the initial specification, the following keys are being officially defined:
| Key Name | Explanation | Example | |
|---|---|---|---|
| icao_id | ICAO airport identifier code | EDDF | |
| faa_id | FAA airport identifier (“LID”) | MA52 | |
| iata_id | IATA airport code | FRA | |
| city_id | City name | Boston | |
| country_id | Country name | United States | |
| region_id | State/Province/Region | Massachusetts |
Can ICAO aircraft code also reflect aircraft weight? many taxiways or aprons have weight limits listed on charts as opposed to ICAO aircraft code restrictions.
It’s stated above that Ramp Start operations type can only be one value. I can see people trying to work around this restrictions for parking areas where GA, Cargo, Military or Airlines may share space.
Since the file format allows for any unicode character, which codepoints are considered whitespace? For reference, here’s a list of potential candidates: http://www.fileformat.info/info/unicode/category/Zs/list.htm
For parsing separate fields, only ASCII spaces and tabs.
Airport meta-data has been requested for my apps, therefore I’m looking forward to the new extensions.
These extensions appear to be solid an plausible to me. Good Work!
Reading about the newly introduced Equipment Class “fighters” reminds me of a long existing problem of the Equipment Class itself: The defined Classes are well and fine (by the way, is this one not missing: “Super_Heavy”[A380]?).
However, it is not possible to block an explicit Aircraft Type for operation on this runway.
A good example is EDDF, where 25R/07L is certified for landing only. For turbulence and/or noise reasons the following A/C types are not permitted to operate this rwy: A380, 747, Md11.
We could try to solve this by allowing the above 6 categories (based on wing span) to be used as a parameter, but this will NOT solve the above described definition of restriction (The 777 has a greater wing span than the MD11, but is allowed on this runway)!
Thus, a possibility to block certain A/C Type(s!) would eliminate this problem once and for all. Any kind of A/C-combinations on a given runway will then be possible!
For parking, A380 is covered by size F, rather than a new aircraft class. “Heavy” goes back to the original file format, and is sort of weird…it’s a weight class and not an aircraft type.
The current tech isn’t really detailed enough to handle noise abatement procedures, which can get very, very specific.
Right! “Heavy” is a weight class. And covers the WHOLE set. Within this set let’s pick the 747. Currently its not possible to define the 747 as a “not allowed aircraft” for a particular runway, although other heavys are permitted.
With this possibility you could -based on the current logic of the ATC Rules- define a refined, complex, what you call, “procedure” (wether this is based on noise-abatement or whatever reason) wich is indeed “very, very specific”.
Similary you might run into this trap with parking. Not all gates at a given airport are able to handle A380 (wich is again only an example) although the physical size of the gate seems sufficient. As you can see, noise abatement (runways) is not the only thing that causes exceptions for blocking certain A/C types. With a bit of humor: We programmers go alert instantly, when it comes to “unhandled exceptions” 😉
“The current tech isn’t really detailed enough to handle noise abatement procedures, which can get very, very specific.”
Does that mean, the static models will also used for AI Traffic in future? I thought it is only used to populate ramps???
At a minimum, I think we’re going to try to avoid putting live AI planes into spots that they don’t fit within due to ICAO code. So this gives us a way to say “no A380 at this spot”. For live AI planes, we can determine their ICAO size class because we have the real aircraft.
This system promises to be a major step forward, I’m really looking forward to playing around with it. However some questions cross my mind:
1) I miss an operations type for “emergency services” like police aviation, air medical services or aerial firefighting. Some airport parking positions are exclusive to such aircraft.
2) Is it possible to allow ramp starts to spawn only static aircraft or the users aircraft but no AI traffic?
3) What is the difference between “heavy jet” and “jet”? Isn’t the “heavy jet” equipment class redundant once the new ICAO aircraft category code system has arrived?
4) No glider aircraft equipment class to spawn some static gliders at small airfields?
Greetings Peter
In what way might 3rd party plugins that parse the apt.dat for airport data be affected, Ben? Are the format changes going to be legacy friendly….in other words, will existing apt.dat files for custom scenery need to be updated?
That depends on how the parser is written – we’ve tried to be minimally invasive, but:
– The major version of the file is changed, so there’s that.
– Meta-data and ramp extra data are all entirely new record codes – they can be skipped.
– The enum sets for equipment class and taxiway vs runway on edges have new enums, so programs that read these and can’t cope with the new enums will not be able to function.
So it sounds like existing apt.dat files with the legacy header will still be read by X-Plane — they just won’t have the extra data. The functionality that uses the metadata will not have anything to play with, but the essential data that we’re currently getting from apt.dat will be read by the sim. Plugin parsers will need to be cognizant of the record code they’re reading, instead of assuming that the next record type after A is B, so to speak (which would be a bad practice anyway). Thanks, Ben.
Correct. X-Plane will continue to support all past apt.dat files that it reads now, which I think is the 850 and 1000 variant. (There might be an 810 parser in there – I’d have to look, but that’s well beyond the compatibility range we try to maintain.)
We will be forward-converting gateway airports on export – this means the gateway data is unchanged but gateway airports will appear to be forward converted to get some static aircraft in; when a gateway airport is uploaded with new 1050 data, we won’t auto-upgrade it on export anymore.
One problem is there is no data for file date in the apt.dat. Parsing apt.dats? Parse first “Custom Scenery/scenery_packs.ini” to get the hierarchy, then parse each apt.dat file found in Custom Scenery in that order, ignoring duplicates when they appear, then parse Resources/default scenery/default apt dat/Earth nav data/apt.dat, ignoring again any airports you’ve already parsed. Use a coroutine or another thread to not freeze the sim. Find some method of figuring out when anything has changed in Custom Scenery as there’s no file date on the _packs.ini file too.
I really hope some switch will be introduce to get rid of AI static when user has third part traffic plugins working or maybe providing a dataref for occupied gates at airports within a certain range from user’s position. In this case external plugin could parse the free gates to use them for their traffic.
And, not strictly connected with static planes, I hope you can change ATC lines colour in WED because now it’s really hard to draw new taxiways when photoreal background or other polys are visible.
There will be a switch to turn off static aircraft, e.g. for flying online with VATSIM. For WED issues, please file a WED bug. No more WED commentary here please; this RFC is for the apt.dat format only!
I’m so glad you’re doing this.
-It would be a great advantage (and little work) to have at least one of [icao_id, iata_id, faa_id], and all of [city_id, country_id, region_id] consistently available, so what about making this mandatory?
-Regarding country_id…how about specifing ISO 3-letter country codes instead of letting these be arbitrarily defined by the author (so you don’t get America, USA, U.S.A, United States, United States of America)?
-Maybe I missed it, but will the airport GUID will always be taken care of by Scenery Gateway?
That’s a little bit tricky…how can we guarantee the existence of data fields that do not yet exist? There may also be airports for which there is no IATA, ICA, or FAA ID, e.g. a small non-US strip.
I agree that it would be useful to have a machine-readable country code and not just a human-readable one; although we really need the human-readable ones to be consistent too.
I’ not sure what you mean by “the airport GUID will always be taken care of by Scenery Gateway?”.
Not trying to hijack the thread but I’ve run into this situation on several occasions. There are quite a few airports in the world that have both land and water runways. Is there any possibility of adding a “W” designator for water runways? and also convince the ATC engine NOT to direct land based aircraft to the water runways?.
Please file a bug including an airport and repro steps where ATC lands you in the water.
Where would the W designator go? The UI?
One more thing: what about diacritics in airport names? My apps do support them, but due to lack of use in apt.dat this is currently only relevant for custom scenery. Wouldn’t it be time to enter the 21st century and make diacritics a reality? I’d voluteer to edit the ED** domain.
I think we want to promote the file format, or at least parts of it, to UTF8. I’ll confer with Robin.
Well the problem is, it currently already includes UTF8, see for example ‘EDAU’ and numerous other entries. My importer, however, prints it out garbled because [NSString stringWithContentsOfFile:encoding:error:] doesn’t recognize it as NSUTF8StringEncoding and therefore I have to fallback to ASCII. But maybe that’s a different problem.
I’ve identified at least two entries that make NSUTF8StringEncoding stumble: SLTJ and TFFR.
Please file a bug on the gateway bug reporter against any airport ID where the airport name is either:
1. not valid UTF8 or
2. contains incorrect diacritical marks or junk characters.
I haven’t seen that happen in awhile, but it’s most likely because I made a separate apt.dat file for the water sealanes.
I’ll test it again with the sealanes included in the same apt.dat file as the runways.
I’m not sure what you mean as far as where the W should go. Airports like Juneau Alaska have their runways designated as 8-26 and 8W-26W. When I try to name a runway 8W (for example) WED throws a fit and won’t allow that naming protocol.
Oh, I understand – you are proposing FAA sealane naming conventions.
That’s correct. I’m afraid that my command of the English language is somewhat limited.
I’ve seen several,airports that that have two parallel land runways and also have a third parallel water sealane so it would make sense to allow the FAA “W” designation to be allowed in X-Plane
What is the airport identifier of a US airport that is like this as an example?
Here are some examples.
Check out PAFA (Fairbanks Intl).
http://155.178.201.160/d-tpp/1606/01234AD.PDF
PAJN (Juneau Intl)
http://155.178.201.160/d-tpp/1606/01191AD.PDF
And PHNL (Honolulu Intl)
http://155.178.201.160/d-tpp/1606/00754AD.PDF
PAJN: 8/26; 8W/26W
Hello.
This new format, is final?
My plugin does not work with new format.
It’s very close to final. If your add-on doesn’t work with it, it’s relatively unlikely that a future tweak to the format will make this better; we’ve already done everything we can to minimize the impact on older parsers. Please email me directly to discuss this.