Marginal X-Plane Scenery Tutorials Library

Using and creating a scenery library

Overview

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:

OverlayEditor

	Run the program that you downloaded to install OverlayEditor. Choose Start » All Programs » OverlayEditor
	Open the folder that you downloaded and drag the OverlayEditor application to your Applications folder. If you're using MacOS 10.3 then download and install wxPython 2.5.3. Double-click on the OverlayEditor application.
	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:

• Press the "New" button:

• Type in Test package and press OK.

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.

• Press the Objects menu to see the names of the scenery libraries that are available to you. A fresh copy of X-Plane 8.40 comes with these libraries:

Later versions of X-Plane ship with more libraries.

• Choose the global8 library.

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

• Choose the first object from the list - in X-Plane 8.40 this is /lib/global8/us/feat_Building_50_40_600r100.

OverlayEditor shows you a preview of the object:

You can place this object in your test scenery package:

• Press the "Add" button

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

• Press the key to zoom in:

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.

• In Explorer or Finder navigate to your X-Plane Custom Scenery folder.
• Make a new folder for your scenery library inside the Custom Scenery folder; lets call it Test library .

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

Download:

VAhangars.zip

• Copy the files from this archive into the Test library folder that you just made.

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:

• Create a file called library.txt inside the Test library folder.
• Open library.txt in a text editor application (eg Notepad or TextEdit) and add the following three lines:

A
800
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.

• Add the following two lines to library.txt:

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

• Save library.txt. (If your text editor gives you the option, make sure that you save it as a plain text file).

That's it!

Now to see if it worked:

• Press the "Reload" button in OverlayEditor to make it notice our new library:

• Press the Objects menu. You should see our new test library listed. Select it:

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

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:

Download:

screenshot.zip

• Copy the file VAhangar_open.jpg to your Test library folder.

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.

© 2006 Jonathan Harris