Library.txt files are text files that sit directly inside a scenery package and tell X-Plane how to use the objects and other graphic resources in other parts of the flight simulator. Without a library.txt file a scenery package’s contents are used for its own DSF and ENV files, but with a library.txt file a scenery package can replace the models and artwork from other parts of the simulator.
Library files work by mapping virtual paths to files in the scenery package. One virtual path can be mapped to multiple graphic resources; in many cases X-Plane will randomly pick between the choices to create more scenery variety.
A region is any set of 1×1 DSF or ENV file locations; regions are specified as a series of rectangles along latitude and longitude lines. The union of all such rectangles forms a region.
Scenery packages are prioritized alphabetically within the Custom Scenery folder (all custom packagse have priority over the default scenery which is in Resources/Default scenery). Within a scenery package, all objects have equal priority, but objects that are not regionalized must be first.
Objects and facades can be mapped to virtual paths multiple times. X-Plane will randomly pick among the definitions to increase variety. However other artwork types (terrain, beaches, roads, etc.) cannot be multiply mapped.
Library.txt files consist of a 3-line header, followed by commands. The first line is A or I – this code traditionally indicates line endings but is actually ignored by X-Plane. The second line is the file version number (currently 800) and the third line is “LIBRARY”.
A 800 LIBRARY
Library commands are interpretted from the top of the file down. This means that:
- Regions must be defined before their rects can be defined.
- Regions must be defined before they are used.
EXPORT <virtual path> <real path>
The export command maps the object from the current scenery package with the given real path (relative to the scenery package) to a virtual path.
If multiple export commands are provided within a scenery package for the same virtual path and the resource type supports multiple definitions, X-Plane picks randomly amongst all of the given definitions.
The use of an EXPORT command within a scenery package blocks out definitions of the virtual path from lower priority scenery package; EXPORT effectively replaces artwork.
You can use an object in your scenery package without putting it in a library. If an object is not in a library, it will not be used by any other package.
Note: The on-disk paths given in all EXPORT and related lines must come from within your own scenery pack. Paths outside your scenery pack (e.g., ../some-other-scenery-pack/myobject.obj) are not supported.
EXPORT_RATIO <quantity> <virtual path> <real path>
The export ratio command is just like the EXPORT command, except that the object is interleaved with other objects at a given ratio. (The implicit radio of regular “EXPORT” objects is 1.) You can use this command to control the mix of objects.
EXPORT_EXTEND <virtual path> <real path>
New To X-Plane 820: the EXPORT_EXTEND command works just like the EXPORT command except it does not inhibit the placement of objects from lower priority packages. These objects will be randomly mixed with objects from other packages. If another package of higher priority then uses EXPORT, it will block the EXPORT_EXTEND command. In other words, EXPORT_EXTEND merges with lower-priority packages, but the highest priority package has the choice to merge or replace.
New To X-Plane 840: The REGION_DEFINE command begins defining a region. All following REGION_RECT commands will add to this region. You must define a region before you can use it.
Warning: region names are currently global. For this reason we recommend using a region name based on your package name and company, as well as the region itself.
REGION_RECT <w> <s> <e> <n>
New To X-Plane 840: The REGION_RECT command adds a rectangular set of DSFs to the region that is currently being defined. The region will end up as the union of all rectangles. Rectangles must include whole DSFs; partial DSFs cannot be specified.
The boundaries are inclusive; REGION_RECT -118 32 -117 33 would include four DSFs: +32-118.dsf, +32-117.dsf, +33-118.dsf, +33-117.dsf.
REGION_BITMAP <file name>
New in 850: Starting in X-Plane 850 you can list ta 360×180 gray-scale PNG file consisting of black and white pixels. Black pixels will be considered out of the region and white pixels in the region. This replaces any previously defined rects for the region and should generally be used on its own. The bottom left of the bitmap represents the south pole and the international dateline; the top right represents the north pole and international dateline.
New To X-Plane 840: The REGION command limits the EXPORT and EXPORT_EXTEND commands to only act in the named region. Before the first REGION command, objects are exported to the entire world. REGION limits objects placed in DSFs, but not objects placed by X-Plane.
EXPORT_EXCLUDE <virtual path> <real path>
New to X-Plane 850: The EXPORT_EXCLUDE command maps a file to the library just like the export command, but also excludes any export definitions in lower priority packs and below this export in this scenery pack.
Export-exclude is useful because it only “exports and blocks” lower priority definitions if its region requirement is met. This lets you define an export_exclude “override” in a scenery pack with a region, and then follow it with a world-wide export. The higher priority export_exclude directive will block out the world-wide case if and only if you are in the region. This lets you make a multi-region library in a single scenery pack.
EXPORT_BACKUP <virtual path> <real path>
New to X-Plane 860: The EXPORT_BACKUP command maps a file to the library just like the export command, except the particular file is treated as the lowest priority when finding artwork for a given virtual path.
The intention of this command is to allow a scenery package to provide minimal artwork for its DSFs while using other package’s artwork even if that other package isn’t hgiher priority. In other words, this maps a file as the artwork of last resort.