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:
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 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 of the default set of objects and other artwork without creating brand new global scenery DSFs.
Let's take a look inside the libraries' scheme to better understand the way they work. Here are some typical library.txt files - you can find the in Resources/default scenery/800 objects (1) or Resources/default scenery/820 us objects (2).
The look of the two libraries is slightly different, but they work in exactly the same way.
# = 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 informations not yet implemented.
Any line of the library, then, has this same structure, divided in three blocks:
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.
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.
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.
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 into the folder "commercial" you will find in the same folder of 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.)
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:
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 bulidings to some terrain but not others.
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
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.
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.
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.
Okay so you are dying to customize the look of the sim...but how? I cannot stress this enough:
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:
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:
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.
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.
You can use the same object names for your objects as we did. X-Plane will use the objects from your custom scenery package.
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
You can make up your own names for objects in your own folder. The scheme is up to you.
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
You can use this power to organize your work in whatever way helps you work. For example, you can create a brand new "catagory" within your package to organize your objects.
######################################################## ### GAS STATIONS ######################################################## 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
In other wordrs, the virtual paths are fixed, but the real paths are up to you. Your library.txt file connects them.
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:
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.
Now let's use the new EXPORT_EXTEND command instead of the EXPORT command. Our object overrides the default randomly, increasing variety:
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 colours:
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 informations 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 scenrey. 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.
I think you can guess what we mean with 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:
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:
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:
In this way you will really separate your architectural differences from one area to the other:
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 cannnot 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.
The naming convention for virtual paths is simpler with sim objects; the objects are simply named, without their dimensions.
The teachers' pet suddently 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?"
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!