The X-Plane Library System

Revision History 11/17/05 - Initial Draft.

X-Plane 8 and 9 use the library system to locate the bitmaps, models, and other graphic resources. You can use the library system to replace virtually any part of the artwork for the new global scenery.

Libraries and Scenery Packages
Any X-Plane scenery package can be a library. To be a library, a scenery package must have a text file called "library.txt" directly inside it. This text file contains a list of all of the resources the library shares with X-Plane.

X-Plane scenery packages can be in either the Custom Scenery folder or the Default Scenery folder. The Custom Scenery folder is for add-on scenery packages that are installed by the user; the Default Scenery folder is for the scenery packages that come from Laminar Research and are installed with the simulator.

''Note: The X-Plane updater/installer will sometimes upgrade the default scenery packages that come with the sim. It will not alter custom scenery packages. For this reason, all add-ons should be placed in the Custom Scenery folder!''

The library.txt file maps a file path for a resource inside the package to a virtual path that scenery can use. File paths are the actual locations of the objects on disk. Virtual paths are used by the DSFs that need artwork.

How X-Plane Locates Objects, Terrain, and other Graphic Resources
As X-Plane loads scenery, it must locate each object, terrain definition, etc. First X-Plane looks in each scenery package, in alphabetical order, first in custom scenery, then in the default scenery folder. If X-Plane finds a virtual path in a library.txt file in a package, it uses the object or terrain in that package located by the file path that is associated with it.

If X-Plane cannot find the object as a virtual path in any library, it then looks in the scenery package the DSF is located in for an actual file. A few things to note about this:
 * X-Plane will only look in a scenery package other than the one a DSF lives in for files in the library.txt. It does not actually look at the files in the package, only the library.txt file.  So if you do not include a library.txt file, no other package will use your objects/terrains, etc.
 * X-Plane matches virtual paths, not real file paths, when looking up files in the library. This means you can name your customized artwork anything you want--you only need to match virtual paths.
 * Because you can map any virtual path to any file path in your library.txt file, you can use one object or terrain for many virtual path entries without having to duplicate the actual files.
 * You can also map one virtual path to multiple file paths. For objects, X-Plane	will randomly pick one of the objects, to provide more variation.

Organization of the Default Global Scenery Graphic Resources
The graphic resources for X-Plane's global scenery are divided into a few scenery packages based on their type. There is no requirement that the artwork be divide up this way (all graphics could be in one package, or each object could even be in its own package); we chose this system because it makes it easy for us to manage our files.

The current folders are: What matters is the virtual paths in the library.txt files. Very important:
 * 820 Beaches
 * 820 Roads
 * 820 US Objects (objects used in the US)
 * 820 US Object Placeholders (blank placeholders for any US objects we have not yet provided artwork for)
 * 820 World Object Placeholders (blank placeholders for any non-US objects we have not yet provided artwork for)
 * 820 World Terrain (all of the terrain textures and .ter files)

The scenery package names DO NOT MATTER! You can rename any of these folders and X-Plane will continue to use their contents, because it is only looking at the virtual paths in the library.txt file.

Note: actually, US objects must occur alphabetically before US Object Placeholders so that the real objects are found before the stubs.

Customizing Objects
You can customize the objects used in the global scenery. The virtual paths for the objects in the global scenery are named by their size and the terrain they are used with. The size can be thought of as a maximum limit as you make objects; this is how much space the scenery-creation tools reserved for each object.

There are two separate sets of objects for the global scenery - one for the US and one for the rest of the world. Because the US has much higher road density, the US objects are all relatively small. World objects are much larger.

The global scenery objects are not meant to be one building-each. For example, a 200x30 meter object in the US can be 7 houses next to each other, a shopping mall with a parking lot, or one large building.

Customizing Terrain Textures
You can customize the terrain textures for X-Plane. This is done by providing new "terrain info" (.ter) files. If you do not provide .ter files, X-Plane will not use your textures. X-Plane loads your .ter files and from there will pick a PNG in your package. If you override a .ter file, you must provide all of the textures for that .ter file in your package.

Night lighting is not automatic for scenery; you must provide a TEXTURE_LIT line in your .ter file to enable night lighting. The lit texture may have any name; I recommend using the _LIT suffix for clarity, but any name will work.

Some day X-Plane may feature seasonal textures; when this happens, the TEXTURE_LIT command will allow one .ter with multiple daytime seasonal textures to share a single night lighting map.

Customizing Roads
X-Plane currently only uses one road .net file for all road types (one .net file defines many road types). This means you must include all of the textures and objects you for your entire set of roads.

Customizing Beaches
All X-Plane beaches exist in one image file and are referenced via one .bch file. So you must provide all beach definitions if you are going to provide any.