Using the Library System

= The Power of the X-Plane Library System = by Cristiano Maggi Revision History 5/21/06					Initial Draft

This tutorial provides an introduction to working with X-Plane's library system. It will cover:


 * How to understand library files and analyze the default scenery
 * How to replace the X-Plane default objects
 * How to provide additional objects for more variety.
 * How to customize the look of X-Plane for only one region of the Earth
 * How to customize some of the objects found around an airport.

How to Read a Library.txt File
X-Plane 8 introduced a new way to manage the objects and other artwork used in scenery: the library system. The library system allows one scenery package to give its artwork and objects to another.

The global scenery is designed to be modular, so the X-Plane default scenery ships with two separated parts: some default scenery packages contain DSFs for the entire world. But objects and other artwork are stored in other packages and are linked to those DSFs by means of libraries. This modularity permits updating or expanding the default set of objects and other artwork without creating brand new global scenery DSFs.

Let's take a look inside the libraries' layout to better understand the way they work. Here are some typical library.txt files--you can find them in Resources/default scenery/800 objects (1) or Resources/default scenery/820 us objects (2).


 * [[Image:library_1.jpg|thumb|alt= | ]]


 * [[Image:library_2.jpg|thumb|alt= | ]]

The look of the two libraries is slightly different, but they work in exactly the same way.


 * 1)  =  Any line beginning with this symbol will be ignored by the sim, so it's used to add comments, to separate kinds of objects just for keep things in order or to keep in place information not yet implemented.

Any line of the library, then, has this same structure, divided in three blocks:
 * 1) The first part just contains the command "EXPORT", it tells the sim that the object in this scenery package may be used in ANY scenery package.
 * 2) The second part is a "virtual path".  This is the name of the object that other DSFs can use to refer to this object.  It is an "official" name for an object.  When DSF files are generated, our DSF creation tool has a list of all of the "virtual paths" for the objects we will use; every object placed is referred to by a virtual path.
 * 3) The last part of each line is the most personalizable section: it's the REAL path aiming to the position where 3d objects are stored in the scenery package folder hierarchy.


 * [[Image:library_3.jpg|thumb|alt= | ]]

The very first line of this example section of the library can, then, be read and interpreted as follows:


 * Mr. X-Plane, please, when you find inside ANY DSF file a "virtual path" with these characteristics: "/lib/global8/us/town_sq_200_200r.obj", simply pick up the object named "com_200_200_1.obj" which is stored in the folder "commercial" you will find in the same folder as this library.

One more thing to note: we can have multiple real paths for one virtual path. When this happens, X-Plane will randomly use one of the many object choices randomly, increasing the variety of the scenery. (This technique is allowed for OBJects and FACades, but not beaches, terrain, forests or roads.)

Breaking the Code
A virtual path can be any name, decided by the author of the DSF. But in the case of the global scenery, they follow a structured format that makes it possible to understand how they are used. Let's consider town_sq_200_200r.obj:
 * /lib/global8/us/ means that this is a library object for the "global8" scenery (our internal name for the global DSFs) and the object will be used for the US set. We have two sets of objects, one for the US and one for the rest of the world.  (Because the raw data for the US is very different from the rest of the world, two distinct object sets are needed.

By decoding this pattern, you can understand how the virtual names relate to an objects usage in the scenery. For example, you will see where we mapped commercial buildings to some terrain but not others.
 * town_sq refers to the type of terrain that this object will appear on top of. Terrain is catagorized as SQuare or IRRegular based on the shape of the roads in the underlying texture.
 * 200_200 refers to the size of the object; this object needs to be approximatel 200 meters in width and 200 meters deep. If the object is larger than this, then it may collide with other objects or roads. If the object is smaller than 200 by 200 meters, that's okay, but it will not be packed into the scenery as tightly as possible.
 * r means the object is only placed directly along roads. Typically objects are either "r" (meaning only along roads), "f" (fill, meaning only inside blocks but not on roads, good for trees) or "a" (all, meaning the object could be along roads or in the interior).

Most objects are automatically placed filler, but some are based on real-world obstacles and thus must match a certain height. Objects that have a fixed height are referred to as obstacles, because usually they represent things that planes should not hit. For example, here is an obstacle path:
 * /lib/global8/us/feat_Building_50_40_600r550.obj


 * feat means that this is an explicitly placed feature (an obstacle). Building is the type of feature.  Radio towers, smoke stack and other specific types are specifically described this way.
 * 50_40 is the footprint in meters, just like before.
 * 600 is the maximum height of any building. In other words, no buildings in the default scenery are more than 600m tall.
 * r has the same meaning as above - the building must be along a road.
 * 550 is the height of this particular building. So here this is the virtual path for a building that is 550 meters tall.

If you look at the library files you will see a whole series of building features, running a range of heights from 50 to 600 meters.

So what are all of the virtual paths?
It turns out if you look in the library.txt file of the "820 us object placeholders" package, you will see a huge list of object, all mapped to "blank.obj" like this: EXPORT /lib/global8/us/ind_irr_60_30r.obj blank.obj EXPORT /lib/global8/us/ind_irr_60_60r.obj blank.obj EXPORT /lib/global8/us/ind_irr_90_30r.obj blank.obj EXPORT /lib/global8/us/ind_sq_100_60r.obj blank.obj EXPORT /lib/global8/us/ind_sq_200_100r.obj blank.obj EXPORT /lib/global8/us/ind_sq_200_200r.obj blank.obj

What on earth is that all about? Well, there are two things you must know about X-Plane: The "us object placeholders" scenery package is an emergency backup package. While most US objects come from the "820 us objects" scenery package, there are a few virtual paths that this package does not yet have artwork for. The lower priority "820 us objects placeholders" package maps all objects to blank. This way there is always at least one object for each virtual path. (The placeholders package is generated by our tools automatically, so we know it is not missing any virtual paths.
 * 1) If an object is EXPORTed from two libraries, the higher priority library is used.
 * 2) X-Plane must have an object for every virtual path used in a DSF.

What this means is that you can read the "820 us objects placeholders" library.txt file and learn the names of every virtual path that X-Pane needs for the global scenery! This is like a "master list" for all virtual paths.

Replacing X-Plane artwork using custom scenery packages
Example: library_1.zip

Okay so you are dying to customize the look of the sim...but how? I cannot stress this enough:
 * You do not need to edit, modify or replace the default scenery packages to customize how X-Plane looks.
 * You do not need to copy any of the contents of the default scenery packages to customize how X-Plane looks.

With libraries, you can fully replace only the objects you want to customize using a custom scenery package!

All you need to do to replace an object in X-Plane is:
 * Make a custom scenery package with a new OBJ and PNG in it.
 * Make a library.txt file directly inside that custom scenery package.
 * Use EXPORT commands with the same virtual path as the default scenery, but using the real path of your object.

That's it! X-Plane will now load your objects instead of the default ones. This is an example to see how the structure of your scenery package could be:


 * [[Image:library_$.jpg|thumb|alt= | ]]

The library.txt file would read: A 800 LIBRARY EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobject1.obj EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobject2.obj EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobject3.obj EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobject4.obj

This custom scenery folder would now replace the object /lib/global8/us/town_sq_200_200r.obj with one of your four objects.

As already stated, the scenery folder name can be any you prefer and the objects folder name, too. We suggest to store both objects and textures in the same folder; this is the place where most 3d applications are expecting to find them.

Have it your way
The last part of an EXPORT line, the "real path" can be customized completely. You have the freedom to arrange your custom scenery package any way you'd like.


 * 1. You can use the same object names for your objects as we did. X-Plane will use the objects from your custom scenery package.   EXAMPLE:

EXPORT /lib/global8/us/town_sq_200_200r.obj    commercial:com_200_200_1.obj EXPORT /lib/global8/us/town_sq_200_200r.obj    commercial:com_200_200_2.obj
 * 2. You can make up your own names for objects in your own folder. The scheme is up to you.   EXAMPLE:

EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobject1.obj EXPORT /lib/global8/us/town_sq_200_200r.obj     myfolder:myobject2.obj EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobject3.obj EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobject4.obj .......... EXPORT /lib/global8/us/town_sq_200_200r.obj    myfolder:myobjectxxx.obj
 * 3. You can use this power to organize your work in whatever way helps you work. For example, you can create a brand new "category" within your package to organize your objects.   EXAMPLE:

EXPORT /lib/global8/us/in_sq_90_30r.obj    gas_stations_folder:gas_station_1.obj EXPORT /lib/global8/us/in_sq_90_30r.obj   gas_stations_folder:gas_station_2.obj
 * 1) GAS STATIONS
 * 1) GAS STATIONS

In other words, the virtual paths are fixed, but the real paths are up to you. Your library.txt file connects them.

Increasing variety of the default scenery
Example: library_2.zip

X-Plane ships with hundreds of objects as part of the default scenery. What if you want to add your own objects but you don't want to stop using these existing ones? Do you have to manually copy the objects into your package? Definitely not!

The EXPORT command tells X-Plane to use your objects instead of the default ones. But there is another command: EXPORT_EXTEND instructs the sim to use your object as an additional alternative rather than a replacement to the default set. X-Plane will randomly pick from among its multiple alternatives, increasing variety.

Look at these examples: in the first picture you can see the default look of the area, with buildings here and there:
 * [[Image:library_5.jpg|thumb|alt= | ]]

Next is the result of employing an EXPORT command: our object has been placed in any occurrence of the virtual path related to it. All the objects related to that virtual path have been replaced by our brand new one.


 * [[Image:library_6.jpg|thumb|alt= | ]]

Now let's use the new EXPORT_EXTEND command instead of the EXPORT command. Our object overrides the default randomly, increasing variety:


 * [[Image:library_7.jpg|thumb|alt= | ]]

As you can easily imagine the EXPORT_EXTEND command is a powerful way to let you customize the default scenery, adding all the custom objects you like. Here is an example where all the virtual paths that the default library dedicates to commercials were EXPORT_EXTENDed to a set of custom objects of different shapes and colors:


 * [[Image:library_8.jpg|thumb|alt= | ]]

Of course it's really important that you remember to assign to each virtual path objects with dimensions equivalent or smaller than those of the placeholder, or you will probably have collisions between your objects and the nearby roads and scenery.

Other important information you need to build your custom objects set: objects are expected to have their center at 0,0 and have their street-facing wall facing "north", e.g. with the negative Z axis as a normal.

It is not necessary to include the size of objects in the real file names as part of your custom scenery. The default object packages are named this way to help us keep track of our work; the example shown here uses a slightly different scheme. These naming schemes are simply for our own sanity to easily keep track of approximately how big each object is. X-Plane will accept any name for your custom objects as long as the virtual paths match.

Regionalization: Customizing X-Plane's look for one area
Example: library_3.zip

Example: library_4.zip

I think you can guess what we mean by regionalization: you can limit the geographical areas where objects will be used. Those areas are defined by latitude and longitude rectangles. Note that you can only define whole number boundaries, you can't create a library object that is only used for a fraction of a DSF. (This technique is meant for making a whole region have localized architecture, not for trying to replace the skyscraper on the corner of 43rd and Lexington in NYC. Use overlay DSFs with exclusion zones to replace individual landmarks.)

The syntax in your library.txt must be something like this:
 * [[Image:library_9.jpg|thumb|alt= | ]]


 * REGION_DEFINE is the command to give your region a new and unique name.
 * REGION_RECT is the command to determine the boundaries of your area. The boundaries are inclusive, so you have to put in the first two fields the coordinates of the southwest-most DSF you want to be interested by your objects, and in the other two fields the coordinates of the northeast-most one. In the example we defined an area of one DSF only, so the coordinates are the same.
 * REGION finally you determine where your objects assignment start.

One warning: the EXTEND command replaces objects from other packages, but not your own. So if you make a custom library where some objects are used everywhere and others are only used in a region, then within that region bothsets of objects will be used!

Here is the result of our regionalization in X-Plane, no custom yellow objects outside the defined region:
 * [[Image:library_10.jpg|thumb|alt= | ]]

Unfortunately due to a bug in X-Plane, if you need to define two different regions using the EXPORT command to replace objects completely, you will instead need to make two complete packages, each one with its own library inside and its own instructions for regionalization as shown above. (If you just want to extend the default scenery, you can make one package with multiple regions.)

Here is an example:
 * [[Image:library_11.jpg|thumb|alt= | ]]

In this way you will really separate your architectural differences from one area to the other:


 * [[Image:library_12.jpg|thumb|alt= | ]]

Sim objects: Customizing localizers, VORs, etc.
Example: library_5.zip

X-Plane uses the library system for more than just the objects in the global scenery DSFs. X-Plane uses the library system for all objects shown in X-Plane! This means that you can customize any object in the sim.

Note: as of X-Plane 8.50 you cannot regionalize or use multiple variants for objects that are placed by X-Plane rather than a DSF.

The default scenery package "sim objects" contains many of the default objects that X-Plane uses for navaids, etc. The library.txt file from this package will show you the virtual paths for these objects.

In the following example we put a custom microwave tower at the place of the Glideslope antenna, to make the substitution more evident, certainly not to make pilots have mobile phone calls while they land... that substitution will involve ALL airports with a Glideslope antenna object.


 * [[Image:library_13.jpg|thumb|alt= | ]]

The naming convention for virtual paths is simpler with sim objects; the objects are simply named, without their dimensions.

Conclusion: World domination
Example: library_6.zip

The teachers' pet suddenly stands up raising his hand: "But... there is a default package whose name is "820 world objects placeholder"... do you mean that this folder's library.txt file contains the virtual paths for objects all over the world and that we can already have 3D everywhere if we provide a set of objects together with their own library?"

Suspense... YES! You can have 3-d objects all over the world. Just make a library file with those virtual paths and build objects respecting the placeholders' dimensions, all the rules described above will apply, regionalization too. You will be able to build your own Chinese set of objects and place them only in China, but don't expect to have the same look you got in the USA: outside of the States the roads' database is quite poor and we had to put huge placeholders based on landuse rules inside DSFs; you should try to build objects depicting whole blocks, not only one building at a time. Good luck!


 * [[Image:library_14.jpg|thumb|alt= | ]]