View source for API macro creation using FsRegen for a GMax object

[[Category:GMax]]
[[category:Modeling]]
[[category:Scenery Design]]
[[Category:Airport Design]]
[[category:Tweaking]]
[[category:SDK]]
{{Infobox-Applicable-FSVersion
| MSFS2024 = unknown
| MSFS2020 = unknown
| FSXI = unknown
| P3D5 = unknown
| P3D4 = unknown
| P3D3 = unknown
| P3D2 = unknown
| P3D = unknown
| FSW = unknown
| FSXSE = unknown
| FSXA = unknown
| FSX = unknown
| FS2004 = unknown
| FS2002 = true
| XP11 = unknown
| XP10 = unknown
| XP9 = unknown

}}
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 ([http://www.fsdeveloper.com/forum/downloads.php?do=file&id=40 program] and [http://www.fsdeveloper.com/forum/downloads.php?do=file&id=41 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 everytime.

The save option is in the File menu at the lefttop of the window. Here you also find the load option to reload the library next time you use FsRegen. Don't confuse this saving with making your library BGL, this function only saves the information you entered in FsRegen, so it can be used again later on.[/list]

So you now have a library BGL that contains all the objects you want. Now we need to call those objects from your scenery design program, how to do this will be discussed on the next page.

== Using your FsRegen library ==

Now you know how to create an object library BGL, but how to use those objects in your scenery? This chapter will provide information on the different kind of API macros you can use to call such objects.

=== Calling a 3D object ===

To call the object from the object library you need to make an API macro. The easiest way to do this is to select the object in the library compiler of FsRegen. If you then press the button Create API macro the API will be created in the same folder as your library. The API macro has the following structure:

 Area( 5 %1 %2 22 )
 
 PerspectiveCall( :OBJ )
 ShadowCall( :OBJ )
 Jump( : )
 
 :OBJ
 mif( %11 )
 refpoint( 2 :END %4 %1 %2 E= %11 v1= %10 %13 %14 )
 melse
 refpoint( 7 :END %4 %1 %2 v1= %10 %13 %14 )
 mifend
 RotatedCall( :ROT 0 0 %5 )
 Return
 
 :ROT
 CallLibObj( 0 11111979 14122000 05062003 00000001 )
 
 :END
 Return
 EndA

Let's have a closer look at the different commands to see what they do.

First there is the Area command. This command is used to define the area in which the object is located, this allows Flight Simulator to determine when an object should be loaded into the memory.

The next two commands PerspectiveCall and ShadowCall tell Flight Simulator that a 3D object will be define after label :OBJ and also to draw a shadow for it.

The RefPoint command defines the reference point for the object. Ussually this is the center point of the object. The parameters %1 and %2 are the latitude and the longitude of the object. These are passed on by the design program when the API is placed. Some more parameters are passed to the RefPoint. %4 is the scale of the object (to get your object at the exact size you designed it with in GMax you must always use scale 0.5 for your object. If you don't want to place your object with different scale you can also replace the %4 by 0.5 and then you don't have to think about the scale anymore when you place the object), %11 is the altitude, %10 is the range at which the object should become visible and %13 and %14 define the radius of the object. These last parameters are important to optimal framerates.

The next command, the RotatedCall command, makes sure the the object can be rotated to the correct heading. This heading is the parameter %5, which is also passed on by the design program when you place the API.

The last command, which is called by the RotatedCall, is the CallLibObj command which calls the library object from the library BGL by its GUID. Here you should see the GUID you have assigned to your object normally. The last two commands only mark the end of the object.

=== Calling a ground polygon ===

When you place an ground polygon in an object library and call it with the API that has been made by FsRegen you will notice that you have a bleedthrough problem. This is the same problem as described in chapter ef{cpt:grpol}. But the fix described there will not work with an object library, because these changes are not included in the library. You need to use a different calling API to fix them.

Below you will find the type of macro you should use in this case. The only difference is that the PerspectiveCall and ShadowCall commands have been replaced by a LayerCall command. Where the first two commands tell Flight Simulator that a 3D object with a shadow is following, the LayerCall command tells Flight Simulator that a ground polygon is following. The second parameter in the LayerCall command is the layer number. In this example the layer number is set to 8, but you can of course use a different value if you want to arange different ground polygons on different layers.

 Area( 5 %1 %2 22 )
 
 LayerCall( :OBJ 8 )
 Jump( : )
 
 :OBJ
 mif( %11 )
 refpoint( 2 :END %4 %1 %2 E= %11 v1= %10 %13 %14 )
 melse
 refpoint( 7 :END %4 %1 %2 v1= %10 %13 %14 )
 mifend
 RotatedCall( :ROT 0 0 %5 )
 Return
 
 :ROT
 CallLibObj( 0 11111979 14122000 05062003 00000001 )
 
 :END
 Return
 EndA

=== Calling multiple objects ===

In some cases you might want to call more then one object with the same macro. The API macro that can be used for that will be discussed in this section.

Multiple objects in one macro can for example be easy if your object consists of both a 3D part and also ground polygons. To prevent bleedthrough problems these need to be called in a different way (see the example of macros in the previous sections). But if both parts belong to the same object it is easier to place them with one macro, otherwise you could get problems in correctly lining up the two macros. Below you find an example of such a code. It contains two library calls, one for the 3D object and one for the ground polygons.

 Area( 5 %1 %2 22 )
 
 PerspectiveCall( :OBJ )
 ShadowCall( :OBJ )
 LayerCall( :OBJ2 8 )
 Jump( : )
 
 :OBJ
 mif( %11 )
 refpoint( 2 :END %4 %1 %2 E= %11 v1= %10 %13 %14 )
 melse
 refpoint( 7 :END %4 %1 %2 v1= %10 %13 %14 )
 mifend
 RotatedCall( :ROT 0 0 %5 )
 Return
 
 :ROT
 CallLibObj( 0 11111979 14122000 05062003 00000001 )
 Return
 
 :OBJ2
 mif( %11 )
 refpoint( 2 :END %4 %1 %2 E= %11 v1= %10 %13 %14 )
 melse
 refpoint( 7 :END %4 %1 %2 v1= %10 %13 %14 )
 mifend
 RotatedCall( :ROT2 0 0 %5 )
 Return
 
 :ROT2
 CallLibObj( 0 11111979 14122000 05062003 00000002 )
 
 :END
 Return
 EndA