Library Creator XML 2.0

From FSDeveloper Wiki

This is the user manual of Library Creator XML 2.0. This manual will explain what you can do with this tool and how you can use it. But it will also try to explain to you the basics of using object libraries.

Contents 1 What are object libraries and why use them? 2 Why use this tool? 3 How to use this tool 3.1 Installation 3.2 The GUI 3.3 Menus 3.3.1 File 3.3.2 Tools 3.3.3 Options 3.3.4 Help 3.4 Example 4 Feedback and support 5 Thanks to 6 Version history 7 Users license

[edit] What are object libraries and why use them?

The first thing you might wonder about is, what actually is an object library? Simply said an object library is a BGL file that contains a lot of different scenery objects that you can later use by picking them from that library. So after you have put the object in the library, it is not actually placed somewhere in the world yet. That is still something you need to do yourself as well.

But what are the advantages of having all your objects in a library?

• It is better for the performance, as the object does not have to be loaded multiple times. Each placement can just refer to the same object.
• The size of your BGL files will go down. If you would include your MDL object into each BGL file where you want to place the object, then the size of your BGL files would be a lot bigger than when you use a library.
• Having a collection (library) of objects makes it easier to reuse them later. So this will speed up your development as well.
• If you mix the MDL files and the object placement in one BGL file, these MDL objects will become geo-locked. This means they can only be placed near that origional placement and not anywhere in the world. Putting your objects in a library prevents this and makes sure you can use them everywhere you like.
• If you decide to update your object later on, you only have to update it in one place. Once the new object is in the library, all placement will automatically refer to this new version. Without you even having to recompile the placement itself.

There are also a few other technical terms that you need to be aware of when using object library. The first GUID, which stands for Globally Unique Identifier. The GUID is the number that is given to your library object, so that it can be called for placement later on. As the name already says the GUID is unique. If you think a bit about this, this is logical of course. What would happen if two objects have the same GUID? Which one would be shown in FS when you call that GUID? That also means that you should never reuse the same GUID twice, always use a new GUID for a new object.

GUIDs can be given in a few notations. For Fs2004 the following notation is used:

 3AFA59125E39441ABD8A040F354B62B6

For FsX the notitation has changed a bit. It is now giving in the following form:

 {62c07657-984c-46d6-af52-097061684c05}

[edit] Why use this tool?

Now that you know what an object library is, you might be wondering why do I need this tool to work with them? Of course you can also create an object library by writing the XML code manually and compiling it with BGLComp. But using this tool has a few advantages.

• You can edit your library using a Graphical User Interface (GUI), which means that you can easily add, change or remove objects in a visual way.
• The tool will write the needed XML code for you, so you don't have to understand how the code works.
• The tool will help you in compiling the library and provide you with error in case something goes wrong. When drag-and-drop compiling with BGLComp this is not always the case.
• The tool will create a new unique GUID for your objects so that you don't have to worry about this yourself. This is only the case for Fs2004 MDL object, as in FsX MDL objects the GUID is already stored inside it.
• The tool gives you extra functionality to make it easier to use your library, you can for example export files to use your library in other tools.

[edit] How to use this tool

[edit] Installation

The first step before you can use this tool is of course the installation. Luckily the installation process is quite simple. All you have to do is unzip the ZIP file you downloaded to a folder of your choice.

As the tool has been written using .NET, you will have to make sure that you have the .NET 2.0 framework installed on your computer. If that is not the case, you can download it from Microsoft.

[edit] The GUI

After you have started the tool, you will get the empty screen as shown below. As you can see the basic interface is quite simple. At the center you have a treeview where all objects contained in your library are listed. Below that are three buttons to perform some basic operations. And all other actions can be done from the menus shown at the top.

The three buttons do exactly what their caption says. The Add MDL objects button allows you to select the MDL files from your harddisk that you want to add to the library. The Remove MDL object button allows you to remove the select object from the library. The Replace MDL object button allows you to replace one object by another.

The tree view of objects also has a context menu if you right click on the GUID of the object. This will allow you to copy that GUID to the clipboard, so that you can easily paste it into a XML document or another tool.

[edit] Menus

This section will explain what all the menu options can do for you.

[edit] File

The file menu contains the options related to creating, opening, saving and compiling libraries.

New library

This option will create a new (blank) library XML file for you. After selecting it, you will get a file dialog to select where to create the XML file.

Open library

This option will open an existing library XML for you. After selecting it, you will get a file dialog to select the XML file you want to open.

Save library

This will save your currently loaded library XML to disk.

Save library as

This will save you currently loaded library XML to disk, asking you for the filename to save it with.

Compile library BGL

This will compile your library into a BGL file that can be used in FS. After selecting this option you will get a dialog to ask you where to create the BGL file.

Last opened

The file menu will also show the 8 last opened library XML files, so that you can reload them faster.

Exit

As the name says, this will exit the tool.

[edit] Tools

The tools menu allows you to perform some special operations on your library. For example export its content in a different format.

Create SBuilder object list

This creates a TXT file in the format used by SBuilder, listing all objects contained in this library. With this file you can make them available in SBuilder for easier placement.

Create Rwy12 XML file

This option creates a XML file in the format used by Rwy12 for your library. This allows you to place your objects using Rwy12.

Create API macros

This creates an API macro for each object in your library. This allows you to place your objects with tools using API macros.

Create SCM macros

This creates an SCM macro for each object in your library. This allows you to place your objects with tools using SCM macros.

[edit] Options

In the options menu you can set different options that determine how Library Creator XML works.

Fs2004 BGLComp path

After selecting this option you will get a file dialog which you can use to locate BGLComp on your system. The tool needs to know where the Fs2004 version of BGLComp is to compile Fs2004 style libraries.

FsX BGLComp path

After selecting this option you will get a file dialog which you can use to locate BGLComp on your system. The tool needs to know where the FsX version of BGLComp is to compile FsX style libraries.

Relative paths

Activating this option will store your objects with relative paths in the XML file, instead of absolute paths. This option is mainly useful if you want to share your library XML with other people.

Create EZ-Scenery TXT file

Activating this option will also write a TXT file in the EZ-Scenery format when you compile your library BGL. This TXT file is used by EZ-Scenery to display the correct name for your objects in the tool.

Automatically check for updates

When this option is checked, Library Creator XML will connect to the internet at startup to see if a newer version is available.

[edit] Help

The help menu gives you help, in case you need it.

Open Wiki manual

Opens a window where you can read this page.

Check for updates

Connects to the internet to check if a newer version of Library Creator XML is available.

About

Opens the about dialog of the tool.

[edit] Example

Now that you have read all about how the interface looks and what you can find in the menu, it is time for a more practicle example. In this example you will be shown all steps involved in making your first library.

Let's assume you just installed the tool. In that case you first need to set a few settings correct:

• If you want to make libraries for Fs2004, make sure that you set the path to the Fs2004 version of BGLComp in the Options menu.
• If you want to make libraries for FsX, make sure that you set the path to the FsX version of BGLComp in the Options menu.
• If you want to use the library you have created with EZ-Scenery later on, make sure it select the option "Create EZ-Scenery TXT" in the Options menu, this will make sure your objects get easier names in EZ-Scenery.

Now that you have made sure that all settings are correct, it is time to create your first library. To do this go to the File menu and select the option "New library". You will get a file selection dialog where you can enter the location and filename of the XML file that will be created for your library. For this example let's name it first_lib.xml. After you have pressed the Save button you are back on the main screen and you will see that the "Add MDL objects" button is now active, which means that you can add objects to the library.

So let's add your first object. To do this press the "Add MDL objects" button and in the file selection dialog that appears add the MDL file(s) you want to add. There are a few things you need to think about:

• You can select multiple MDL files at once.
• You can not mix MDL files made with the Fs2004 and FsX gamepack in one library, if you try this you will get an warning.
• If you select an object that is already in the library, it will not be added a second time.

After you have selected your MDL object, you will see that it has been added to the list of objects in your library. If you press the + next to the object name, you will see more information about the object. For example the GUID and the path to the MDL file. Below you see a screenshot of how your library could look at the moment.

Also note that at the right bottom you will see the FS version for which this library is. So in this example I have added a FsX MDL object to the library.

Now add some more objects to your library. As explained above their purpose is to collect object, so you will hardly ever create one with only one object in it.

Once you are done with adding your objects, it is best to first save the library. You can do this from the File menu with the option "Save library". This will make sure that the XML file is saved on your disk, so that you can reload it later to add more objects to the library. Or maybe remove an object that is no longer used. To load a save library again, you use the option "Open library" from the File menu.

Now, the last step before you can use your objects in FS is to compile the library into a BGL file. To do this select the option "Compile library BGL" from the file menu. This will give you a file selection dialog where you can specify where you want your library BGL to be placed. Once you have select the location and name, Library Creator XML will call BGLComp for you to do the actual compilation. Once this process is done you will see a log window that shows you if everything went OK. Below you see how the window should look if no errors occured.

Now you have your object library ready for use in FS. So use your favorite placement tool to put them somewhere in the big world.

[edit] Feedback and support

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

[edit] Thanks to

• All user who used the previous versions of this tool and provided me with feedback on how to improve it.

[edit] Version history

v2.0.1 29/04/2007

• Initial release

v2.0.2 18/06/2007

• Added: context menu to the GUID in the tree view, to allow easy copying to the clipboard
• Fixed: crash when compiling BGL, while FsX still has the BGL file locked
• Fixed: problem in reading FsX GUIDs that contain zeros, this also caused problems with the API/SBuilder/Rwy12 export functionality
• Fixed: problem with the relative path option, that sometimes resulted in unfound MDL objects on first load of a XML file

[edit] Users license

(c) 2007 Arno Gerretsen / SceneryDesign.org

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.