Using and creating a scenery library


This mini-tutorial shows you how to use scenery libraries and how to create your own. It is assumed that you already know how to make a scenery package.

What are scenery libraries?

Scenery libraries are a good way to share scenery objects with other scenery package authors.

Scenery libraries are similar to normal scenery packages in that they live in the Custom Scenery folder and they contain scenery objects, bitmaps, and other scenery types like facades, forests etc.

Scenery libraries differ from normal scenery packages in that they don't by themselves cause X-Plane to draw any scenery; instead they provide a collection of scenery objects that can be used in scenery packages.

When a scenery package author wants to use an object from a scenery library they don't copy the object into their package - they just refer to it in the library. Of course this does mean that anyone that downloads the scenery package also needs to download the scenery libraries that it uses.

Using the built-in X-Plane scenery libraries

X-Plane ships with a number of scenery libraries already included. We'll use the OverlayEditor application to explore them. Make sure that you have the latest version:

Download: DownloadOverlayEditor

Windows Run the program that you downloaded to install OverlayEditor.
Choose Start » All Programs » OverlayEditor

Mac OS X Open the folder that you downloaded and drag the OverlayEditor application to your Applications folder.
If you're using MacOS 10.7 or later download, open and install wxPython Cocoa. If you're using MacOS 10.8 or later will need to (temporarily) allow applications downloaded from “Anywhere” under  → System Preferences → Security & Privacy before installing it.
Double-click on the OverlayEditor application.

Linux Install the package that you downloaded.
Choose Graphics » OverlayEditor from your Gnome or KDE applications menu (or just type overlayeditor in a terminal).

The first time that you start OverlayEditor it prompts you to locate the X-Plane folder:
  • Navigate to X-Plane's top-level folder (ie the folder which contains the X-Plane, Plane-Maker etc applications).

Make a new test scenery package:

New button

At the top right of the OverlayEditor window there is a pull-down menu titled Objects. There aren't any objects in our new scenery package, so the list below this menu is blank.

Scenery libraries

Later versions of X-Plane ship with more libraries.

The list on the right of the OverlayEditor window now shows all the objects in the global8 library.

OverlayEditor shows you a preview of the object:


You can place this object in your test scenery package:

Add button

You'll need to zoom in to see the object clearly:


The object isn't actually copied into your Test package folder. Instead, your test scenery package now "depends" on the built-in X-Plane global8 library.

All of the scenery objects in the global8 library and in the other libraries are available for you to use in your scenery packages. The built-in X-Plane scenery libraries contain many useful objects, but there's a lot missing too - eg hangars, static planes, ground traffic etc. Browse through the objects in the global8 and in the other libraries to see what's available.

Note that if you publish a scenery package that depends on a scenery library that you've downloaded or that you've created yourself, then people that download your scenery package will also need to download the scenery libraries that your scenery package depends on.

Also note that later versions of X-Plane ship with more extensive libraries than earlier versions, so you you should always design using the earliest version of X-Plane that you want your scenery package to work with.

Creating a scenery library

You can collect scenery objects together into a library and so share the objects across multiple scenery packages. You can also publish your scenery library so that other scenery package authors can use your scenery objects.

We'll use the hangar objects from the Hangar tutorial to populate our library:


So far, this is just like adding objects to a normal scenery package. Now for the extra step that turns this folder into a library:


Now we need to "advertise" our scenery library and the objects that it provides to the rest of the world.

First we need to decide on a name for our scenery library. The library name doesn't have to be the same as the folder name; we'll just call our library test.

Next we need to think about a naming scheme for the objects that we advertise. (There are only two objects in our test library so we don't really need to do this, but it's good practice in general). Our objects are hangars, so we'll collect them under the category hangars.

There are two object files, VAhangar.obj and VAhangar_open.obj in our library folder. Those are rather terse names; we'll advertise these objects with more descriptive names, say Virgin_closed.obj and Virgin_open.obj.

We put the library name, category (if any) and object name together separated by the / symbol. So the full names under which we'll advertise the objects are test/hangars/Virgin_closed.obj and test/hangars/Virgin_open.obj.

The mechanism for "advertising" objects is really simple; just add lines to library.txt consisting of the word EXPORT, followed by the advertised name, followed by the real file name or path. (Note that this means that you can't have any spaces in the "advertised" name). Users of our scenery library will see the "advertised" names and not the real file names and paths.

EXPORT test/hangars/Virgin_closed.obj VAhangar.obj
EXPORT test/hangars/Virgin_open.obj   VAhangar_open.obj

That's it!

Now to see if it worked:

Reload button
Scenery libraries

Our two objects are listed under the names that we advertised. You can now use them in a scenery package:

Test library

The preview picture that OverlayEditor generates for a library object doesn't always show the best features of the object (and OverlayEditor can't generate any preview pictures for facades or forests). If you select our test/hangars/Virgin_open object you'll see this:


We can supply a better preview picture. Preview pictures must:

  1. Live in the same folder as the real object file.
  2. Be in JPEG format, with a .jpg extension.
  3. Have the same file name as the real object file name (note: not the "advertised" name). OverlayEditor will also look for a file named screenshot.jpg.
  4. Can be any size - OverlayEditor will resize preview pictures to fit in the preview window. 300x300 pixels is a reasonable size.

Here's a screenshot of our VAhangar_open.obj object, taken at night in X-Plane:


OverlayEditor will now show this preview picture when you select the test/hangars/Virgin_open object:


Note that X-Plane ignores the preview picture; the preview picture is just to help you (or any other user of your scenery library) to find useful objects.

Publishing a scenery library

Publishing a scenery library is as simple as creating a .zip file that contains the library folder and uploading this .zip file for other people to download. Other authors can then use your objects in their scenery packages.

If you upgrade a scenery library that you have already published you should be careful never to change or remove any of the "advertised" names, otherwise you might break other authors' scenery packages that depend on your library. It's OK to upgrade the real objects to make them look better, as long as they look broadly similar to the old versions.