Revision History:
- 2023-01-25: Updated for X-Plane 1200 – seasonal export commands
- 2019-08-12: Updated For X-Plane 1110 – SEMI_DEPRECATED, PUBLIC <date> status keywords for WED
- 2013-07-23: Updated For X-Plane 1040 – REGION_DREF command
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 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 packages 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 1200) and the third line is “LIBRARY”.
A 1200 LIBRARY
Library commands are interpreted 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.
REGION_DEFINE <name>
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_ALL
REGION_ALL specifies the region being specified via REGION_DEFINE to contain the entire surface of the Earth. It is equivalent to REGION_RECT -180 -90 179 89
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.
REGION <name>
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 higher priority. In other words, this maps a file as the artwork of last resort.
New to X_Plane 1200: The path mapping can optionally depend on the season, by replacing the existing commands EXPORT, EXPORT RATIO, EXPORT_EXCLUDE and EXPORT_EXTEND by the following:
EXPORT_SEASON <seasons> <virtual path> <real path>
EXPORT_RATIO_SEASON <seasons> <quantity> <virtual path> <real path>
EXPORT_EXTEND_SEASON <seasons> <virtual path> <real path>
EXPORT_EXCLUDE_SEASON <seasons> <virtual path> <real path>
They function just as their obvious legacy counterparts, save for the added argument which is a whitespace free, comma separated list of one or more of “spr sum fal win”. Seasonal and legacy export commands are mutually exclusive for any one given virtual path. Sufficient seasonal export commands must be given to cover all four seasons.
REGION_DREF <dataref> <comparison> <value>
New to X-Plane 10.40: Define a region in a library pack, and X-Plane will only load those art assets when datarefs written into the library.txt file evaluate to true. Datarefs can come from the sim or a plugin; all six conditionals (< <= == != > >=) are available. If more than one REGION_DREF line is present, all must evaluate to true to use the region.
PUBLIC [date]
By default, all items in the library are public. You may explicitly mark them public by using this command. Also takes an optional date. Ex: PUBLIC 20170101
PRIVATE
This command is for Laminar Research internal use only. Once used, everything after it is private until PUBLIC is specified again.
DEPRECATED or SEMI_DEPRECATED
New in WED 1.7: Use of these commands will hide the item from the WED UI. Library items marked with the DEPRECATED command are already or will soon be removed and should not be used in scenery. SEMI_DEPRECATED is a weaker warning, used for items that will be removed further in the future. SEMI_DEPRECATED items will pass Gateway validation, while DEPRECATED ones will not.