API macro creation using FsRegen for a GMax object

Applicable
MS Flight
FSXA
FSX
FS2004
FS2002

This article describes how you can use FsRegen to place a GMax object with a SCASM API. This only works if you are using the Fs2002 GMax gamepack. For the Fs2004 and FsX gamepacks you can better use the XML code to make a library and place the object.

What is FsRegen?

Just like the name already says FsRegen is a tool to regenerate source files made with GMax. This way you can add extra features that are not supported by MakeMDL directly. By using specific material properties FsRegen will recognise these parts and can then change the source code to get the desired effect. Besides that FsRegen also has some features to work with object libraries.

FsRegen has been made by George Ioannu and you can also download it from the downloads section (program and update).

In this tutorial I will give some examples of what you can do with FsRegen, but I will not discuss all available options, for more information see the manual of FsRegen or just play with the options the program has for you.

Creating a library with FsRegen

GMax is a great tool to make objects with. But it is not always easy to place an object using MakeMDL only. Where do you find the exact coordinates for example? And if the object should be placed on a airfield you are making it would be nice if it would line up correctly with the runway and taxiways that you have placed with a program like FSSC or Airport. This is where the object library comes in. Let's explain the idea behind it first and then how you can make the library with FsRegen.

What the object library does

The idea behind an object library is this. The library is a BGL file that contains different objects and each of these objects has a number to identify them. This number is called the GUID of the object. With a macro (for FSSC, GroundMaker or Airport the macros are called API files, while ASD uses SCM macros - but they all consist of similar SCASM code) you can then call an object from the object library by calling the GUID.

For GMax this has the advantage that you can make the library with the BGLC source that MakeMDL makes, but you can still place the object with SCASM code that is used by most design programs. This way you can still place the objects like you used to do.

A second advantage is that when you are using an object multiple times, the objects code is loaded only once in the object library, but is called multiple times. While normally the same code would be loaded again and again for each of the different instances the object is called for. This gives you a performance advantage.

But enough talking about the theory, let's make a library!

Making the library BGL

Before you can make the object library you must of course have an object to put into it. I assume that you have already made some sort of object in GMax that you want to use.

The first step is then to export the object with MakeMDL. It is important that you select the Keep files option, otherwise the source code of your object will not be saved. It does not really matter in which directory you save you files, as long as you are able to find them back later on when we create the library. It does also not matter on which coordinates you place your object now, as we are going to put it in the library and not use the BGL file made by MakeMDL directly.

In the folder you have select three files will be created. One is the BGL, as we do not need this you can delete it. You must be sure that you do not keep this file in one of the scenery folders of Flight Simulator, because then it will still be loaded. The other two files are the source files. FsRegen will only use the myproject_0.asm file, as this file contains the actual code of the object that needs to be inserted into the library.

Now you have created the source files it is time to start FsRegen. To create an object library you need to press the button Library compiler, this will open a new screen where you can make the library.

On this screen you must take the following steps:

Click on the ... button and select the ASM file you made with GMax. You need to select the myproject.asm file here (If you get an error that the myproject_0.asm file can not been found, then you are probably using an old version of MakeMDL or you are using MiddleMan. See this topic for more information about this).
If you want you can change the name of the object in the box labeled Object name. Ussually I keep the name the same as the filename I used in GMax, which is the same name I use for the source files.
Then you must assign a GUID to the object. This is a very import part. As discussed above the GUID is used to identify your object and so you must be sure that it is unique. There may not be another library loaded by Flight Simulator that uses the same GUID, as FS does not know which object to choose then. OK, but how do I choose my GUID then? It is best to use the new button in FsRegen as that generates a new random GUID for you.
I usually don’t change the Image Power, Scale, Object type and Object size boxes, because I have not found any real influence of them. The value in the Object size box is important, but we will come back to that later on.
Now you are ready to press the Add to list button and your object will be added to the library.
If you want to add more objects to this library, repeat the previous steps for each other object you want to add. It is best to increase the last group of 8 characters of the GUID by 1 each time, as that will make sure that all objects have a sequnetal GUID. This will speed up the performance a little bit more.
When you have added all the objects you want, the final step is to select the name of the library. You can choose any name for your library, as long as it is unique of course. When I am making an airport I usually name the library after the ICAO code of the airport. For the airport of Oostwold (EHOW) I thus use the name ehow_lib.asm for my library.
You can now do the final step and that is to compile to library BGL or save the source by clicking on the appropriate button. I prefer to save the ASM source file and then compile it manual with BGLC from the DOS prompt. When I have updated an object in GMax I export it again and then I just recompile the ASM file of the library. The new myproject_0.asm is then included in the library and I don't need to add the object again.
There is one last step that you can better do, as it can save you a lot of work in the future. Before you close the library compiler of FsRegen you must save your library information. This way you can load it again later on and then just add one new object. Otherwise you would have to add all the object again ever ... \n