Standard aircraft structure
| This article or section contains out-of-date information
Please help improve this article by updating it. There may be additional information on the talk page. |
To help provide a more consistent experience for end users, please use Release:Aircraft Selection Criteria as a guide to prepare aircraft for inclusion in the base package, especially if you are hoping for your aircraft to become part of the default distribution, such as the c172p for example.
Standard Aircraft Folder Structure
The majority of cleanly structured aircraft share (more or less) a pretty similar folder layout.
While the suggested structure may seem overly verbose, using this or a similar structure for your own work ensures that your aircraft is pretty intuitively organized and that key components are kept in distinct places (and can be easily identified), so that future maintenance is simplified because of the self-documenting nature of the underlying file hierarchy.
Please note: While the following folder layout has merely advisory character, it can be considered a product of "convention by evolution": As aircraft emulations in FlightGear are getting more and more complex, it is also getting more complicated to maintain an overview of aircraft components and their implementation files, including their mutual relationships and purposes.
Furthermore, having aircraft authors organize their aircraft this way, also ensures that future contributors can more easily find, borrow and understand certain code snippets from existing work, so that they don't have to waste time trying to understand the purpose of the various files included.
Multiplayer Notes
Only few aircraft have a specific multiplayer model, so the feature only helps with some aircraft. There is one thing I'd like to see added to the top-level directory tree for each aircraft. That is an MPModel directory, which would contain a simplified version of the model for AI/MP use. I think the MP version should be made by the original model builder, and it should be included in the original model package.
The reason I'd like to see this is I usually remove all models from my Aircraft directory except the ones I'm working on. This is to prevent periodic freezing of my sim session on MP when someone logs in with a heavy model. I'd like to see their airplane though, but not in its full form, and not replaced with a blue glider (or some other one-off substitue). I used to keep my own stable of MP versions of many models, but it became too unwieldy to maintain. It would be easier if I could set an XML element in preferences.xml to use the MP version of a model rather than the full version, or get a blue glider if no MP version exists.
Note that I don't consider turning some features off on a full model to be sufficient for making an MP model. The really lagging thing is the loading of textures, so I modified the livery exchange for the model (which is needed to send the correct livery over MP) to use a low-res version of the texture. So it's not the full blown 2048x2048 texture but a light weight 512x512 texture.
Many (or most/all?) AI models ignore liveries. They could still support it though - it really depends on what is coded in the AI model's animation code. An AI aircraft could support all the very same features as the real model. But obviously they only make really sense, when they are omitting a few features compared to the full-blown original. But it's up to the author to decide what to omit/simplify for the lightweight version.
An additional AI Model for AI Scenario use is helpful too, especially tail-draggers need some additional animations to work properly (e.g. lift the tail while accelerating).
If you use some low detail impostor for some objects at a distance, make sure you use the same texture as the "original" high poly version. Loading textures is the most expensive operation currently in FG (you need to unpack the png, generate the mipmaps on the fly then upload the uncompressed texture+mipmaps to the gpu.). This texture loading is the cause of the freezes everyone notices when some "detailed" aircraft joins MP.
I think the Model complexity needs to be reduced via the Model itself. E.g put all 3d Cockpit models into a seperate XML File and have a range animation (suggested by Anders) to load it only if sitting in the cockpit. Usable for gears too. Livery select over Multiplayer can reduce lag too, by loading a low res texture instead of the hi res default one (see the F4U for an example).
Structure
- MPModel - for multiplayer models [1] [2] [3]
Dialogs - for aircraft-specific dialog resources(if you load your dialogs manually)- gui/dialogs - for aircraft-specific dialog resources (if you use dialog-show for opening your dialogs)
- Docs - for aircraft-specific documentation
- Engines - for various different engines supported by the FDMs (possibly beneath FDM folder?)
- Huds - for aircraft-specific HUDs
- Models - for 3D models
- Instruments - for aircraft-specific 3D instruments
- Liveries - for aircraft-specific livery textures
- Nasal - for aircraft-specific Nasal scripts
- Panels - for 2D cockpit panels
- Instruments - for aircraft specific 2D instruments
- Sounds - for aircraft-specific sounds
- Splashs - for aircraft-specific splash screens
- Systems - for aircraft-specific system modelling files (such as the electrical system and autopilot)
- Tutorials - aircraft-specific tutorials (i.e. cold startup, approach etc.)
- Resources - for all sorts of aircraft specific development resources that may be required by other developers to continue development of an aircraft (i.e. data, images, artwork etc) but that isn't officially included in any of the other folders because it isn't yet used. That is, such "resource" folders could/should be automatically excluded from the script that is currently used to create the default base package for distribution.
Recommended set of Standard Files to be provided
Additionally, all aircraft are recommended to have files such as the following included (possibly in a directory named "contrib"?):
- limits.xml - XML file configuring aircraft specific flight regime limits, i.e. to provide crash detection parameters
- AUTHORS.txt - list original authors and contributors, including their work
- CHANGELOG.txt - list recent changes to the aircraft
- README.txt - general information about aircraft
- HELP.txt - Help-related information
- FEATURES.txt - summary of supported features in plaintext
- TODO.txt - things that yet need to be done
- FILES.txt - a description of all relevant files and their purposes
- LICENSE.txt - detailing licensing and distribution
- LAYOUT.txt - file detailing layout of folder (i.e. contents of this paragraph)
- thumbnail.jpg - thumbnail image of aircraft for use by GUI/web frontends (standard size 171x128 for fgfs thumbnails )
- thumbnail.txt - optional file containing description being displayed on the web as the thumbnail's caption
Also, providing such a set of standard files describing your work in detail, makes it possible for arbitrary web and gui frontends to optionally provide very detailed information about the progress of your work, so that automated scripts could be used to compile comprehensive summaries for all base package aircraft providing such files.