Library Creator XML

Applicable
MS Flight
FSXA
FSX
FS2004
FS2002

This is the user manual for Library Creator XML. This tool gives you a graphical user interface to create an object library with the Fs2004 XML format. In this user manual you can read how to install and use this tool.

Installation

If you have downloaded the installer version of Library Creator XML, all you have to do is run this installer. This will make sure all files are installed for you. If you have downloaded the zip file version, you need to unzip its contents to a folder of your choice.

To compile the library BGLComp is used. It is possible that you need to install MSXML4 before BGLComp will work correctly, but most of you will already have BGLComp working (because you are already using GMax).

The interface

When you start Library Creator XML for the first time you will get a screen as shown below. As you can see most buttons are greyed out at that moment, because these options are not valid. You need to make a new library first or you could open an existing library XML.

Making a new library

If you want to make a new library project you need to select the option "New XML" from the "File" menu (or you could press Ctrl-N). This will bring up a default Windows file dialog where you need to select the name and location of the XML file for the library.

Warning: if you select an existing file at this point it will be overwritten.

After you have selected the XML filename, you will get a second screen that will ask you to add the first MDL object(s) to your library. These objects will then be added to your library and the GUID is generated random((If you prefer to use your own GUID you can always change it manual after the first object, this will be described later on)).

Your new library, with a first object added, should now look like this:

Opening a existing library

If you do not want to create a new library, you can also open an old XML library file, to change the current objects in it or to add new ones. To do this you need to select "Open XML" from the "File" menu (or you could press Ctrl-O). This will bring up a default Windows file dialog, where you can select the XML file you want to open. Once it is loaded all current objects are listed on the screen.

In the File menu you will also find the 8 latest XML files that you have loaded listed at the bottom. You can use these to quickly reload one of them.

Adding an object

Once you have created a new library or opened an existing one, you can start adding new objects to it. To do this you need to press the "add new object" button. This will bring up a Windows file dialog, where you can select the MDL file(s) you want to add. Once you have selected the files they will be added to the end of the object list. The GUID of the previous object will automatically be increased. If the new GUID already exists in your library it will be increased again till a valid one is found. This is only important if you don't have a logical order of the GUIDs. If the object is already included in your library (this is checked by the full filename, including the path, so if you have a MDL file with the same name, but in a different folder, it is not a problem) it will not be added again and you will see that nothing has happened to your library.

The figure below shows how the screen could look after you have added a new object.

If you want to add multiple objects to your library at once, you can select them all at the same time in the file dialog. Hold down the Ctrl key to select additional MDL files. The figure below shows how the screen could look like after you have added multiple MDL files to your library.

Removing an object

If you want to remove an object from the library you simply select it in the list view. The details, filename and GUID, will then be shown in the boxes at the bottom. If you now select the "remove object" button the object will be removed from the library. At this moment the object is not yet removed from the XML file, that is done once you save the XML file.

Changing an object

Once you have selected an object in the list view, you will see that the details, the filename and GUID, are shown in the boxes at the bottom. You can now change this information if you want.

If you want to change the GUID of an object, you can type the new GUID in the boxes. Because the maximum length for each part of the GUID is eight characters, you are not allowed to enter more. If you enter an invalid GUID you will also get a warning, a valid GUID can only use the hexadecimal characters (this means only the characters 0 till 9 and A till F are allowed, so you can NOT use G till Z). Once you have entered the new GUID you want you can press the "change" button and the GUID will be updated in the list view.

If you want to change the MDL file, for example because you want to replace the object at a certain GUID with a new one, you can press the "change" button next to the MDL file name. This will bring up the selection windows again and you can select the new MDL file there.

Copying a GUID

When you have selected an object in the list, its GUID will be displayed in the boxes at the bottom. Next to these GUID boxes you will also find a button named "copy". When you press this button the GUID of the currently selected object will be copied to the clipboard. This means you can then paste it into another program, for example your text editor with XML code or into SceneGenX where you are placing the object.

Saving the XML file

To be sure that all changes you have made to your library file are also stored you need to select "Save XML" from the "File" menu (or you could also press Ctrl-S). This will save all objects as shown in the list view into the XML file for the library((If you have opened a XML file made by GMax that also contains some placement code, this code is not lost after saving with Library Creator XML.)). Without saving all the changes you made will not be stored.

Compiling the BGL

The last step is to generate the BGL file for your library. To do this you need to select "Compile BGL" from the "File" menu (or you can press Ctrl-B). You will then get a Windows dialog screen asking you where you want to save the BGL file. The location you enter here is remembered for this specific library XML file, so that the next time you compile it will be used as the default location.

Once you have selected the location of the BGL file, a compile log, as shown in the figure below, will be shown during the compilations. Any errors that occur during the compilation will show here.

Advanced options

Preferences

You can set a few preferences in Library Creator XML. If you select "Preferences" from the "Options" menu you will get a screen where you can enter them. The options dialog looks like this:

With the option relative path you can determine if the filenames of your MDL files are defined with an absolute or a relative path. For normal operations absolute paths are sufficient, but if you are working on the same library with a team of scenery designers using relative paths can be a good option. This way you can share your XML file with other designers and as long as they use the same folder structure for the XML and MDL files they will also be able to compile it (although the absolute path will probably be different).

The second option is to generate an EZ-Scenery TXT file together with your library BGL when you compile the library. This TXT file is used to display the names of your MDL files in EZ-Scenery instead of the GUIDs. The MDL filenames will be used to name the objects. This option is useful if you are using EZ-Scenery to place your objects or if you want to share your library with people who do so.

SBuilder export

If you are using SBuilder, you might want to add the objects of your library to the objects list of SBuilder. With the option "SBuilder object list" from the "Export" menu, you can create a text file that contains the definition of your objects in the SBuilder objects list format. If you copy the contents of this file into the objects.txt file of SBuilder, you can select them in SBuilder.

Rwy12 export

If you want to use your object library in the Rwy12 Object Placer tool, you will have to make a special XML file for Rwy12 as well. This file defines the pictures used for the objects, as well as the description of the library itself. You can also let Library Creator XML create this XML file for you. To do this you need to select "Rwy12 XML file" from the "Export" menu. This will give you a dialog as shown below:

First you should enter the filename of your Rwy12 XML file. The first time you will have to enter it manual, but after that the Rwy12 path has been saved and Library Creator XML will automatically give you a suggested name. This name is the same as the name of your library, but with the prefix add_ added

The second option you need to enter is the folder name for the images. You don't have to enter the full path, only the folder name inside the Rwy12\img folder. By default the image folder is given the same name as your library XML file.

The last option is the description of your library. This is shown in Rwy12, in the dropdown list where you select the library to use.

If no images exist in the image folder, a blank image (with the text "No image available" written on it) will be copied to the folder. It will have the same name as the MDL object. So if you want to add images for your library, you only need to replace the JPG files with the proper images. No editing of the Rwy12 XML file is required.

API/SCM export

With the options "API macros" and "SCM macros" in the "Export" menu you can create API or SCM macros to call your library objects. These macros will be placed in the same folder as your XML source file.

One big warning. It is strongly advised to place your objects with XML commands, instead of using the obsolete API/SCM macros. Only if you have an airport fully designed with the old tools like FSSC or Airport for Windows, it could be useful to use macros to place your newly designed objects (until you have redone the airport in XML code of course).

Feedback and support

If you have questions, comments or suggestions about Library Creator XML you can reach us either by email or through the forums of FsDeveloper.com.

Thanks to

Nick Whittome for his ideas, suggestions and testing, which has helped a lot shaping this tool into this final form.
Erwin Horjus for his suggestions and help in implementing the features that allow multiple users to work on the same library easier. And also for evaluating the manual.
Bill Sieffert and Iain Gallacher for bringing the important GUID problem to my attention.
Stephen Legg for his testing of the Rwy12 functionality
All other users who gave me feedback to improve the tool.

Version history

v1.03 18/02/2006

Fixed a few bugs within the relative path option
Mass add folder button removed, you can now select multiple files at once in the select file dialog
Option added to create a EZ-Scenery TXT file with your BGL file, this file allows users of EZ-Scenery to see the name of the objects in your library

v1.02 22/10/2005

BGL location remember for each XML library file
8 last opened files remembered and shown in file menu
Problems while editing an object fixed

v1.01 14/04/2005

Random GUID now calculated by GuidGen function of Microsft
Auto updater functionality removed due to problems

v1.00 14/03/2005

Compilation process improved, including a compile log to show errors
SBuilder export functionality added
Rwy12 export functionality added
API/SCM export functionality added
Auto updater functionality added
Preferences can now be set from the tool

v0.14 beta 08/08/2004

Bug solved that caused an endless loop when saving a file that contains a comment.

v0.13 beta 01/08/2004

Option added to use relative instead of absolute paths to store the MDL files (useful when you want to share the source with other people).
Option added to specify a folder where the BGL files must be placed.
Library open when the program exited, will be opened again at startup.

v0.12 beta 02/06/2004

Problem with not random first GUID solved.

v0.11 beta 18/03/2004

Note: The documentation has not yet been updated
Compilation of the BGL changed, should solve the reported runtime errors
Button added to copy the GUID to the clipboard, so you can paste it into an XML code or SceneGenX.
The created XML file is now readable, not all commands are printed on one line.

v0.10 beta 24/02/2004

First beta release.

Users license

This software program is distributed without charge to other scenery designers, redistribution of the original ZIP file is allowed. You are NOT allowed to sell this software program or ask money for its distribution. Libraries created with this software program can be used in commercial scenery projects if you wish.

The copyright and any intellectual property relating to this program remain the property of the author.

The software distributed in this way may represent work in progress, and bears no warranty, either expressed or implied.