Conditional Animation Tool

This is the user manual for the Conditional Animation Tool (CAT) version 1.02. CAT is a tool that allows you to tweak animation made with GMax or FSDS3 by attaching certain conditions to them. For example, this gives you the ability to let the animation start at a certain trigger and not run endlessly.

Please read the rest of the manual as that describes how you can use the interface and gives you more examples of the kind of animation tweaks you can perform. CAT is too complex to skip this nice manual.

Installation

The installation procedure of CAT depends on the version you have downloaded. If you have downloaded one of the installers, then you only need to run that installer and you are ready to go. If you have chosen to download the ZIP file version, you need to unzip the content of the file to a folder of your choice.

If you ever want to uninstall CAT, you can run the uninstall program that is located in your CAT folder. You can also start this uninstaller from the “Add or remove software” section of the control panel. If you used the ZIP file distribution you can just delete the folder you placed the files in.

Available animation tweaks

What kind of tweaks can you apply to your animation with CAT? This section will give an overview of the possibilities. Three kind of conditions can be added, these are:

• Animation Condition The animation condition is one big check that determines if the animation should be shown at all or not. This can for example be used to make sure that the animation only shows if the aircraft is within a certain range. When this condition fails the initial static position will be shown.
  
  When applying an animation condition you have the choice to apply it to the animation directly or to the animation trigger. Applying it to the animation trigger has the advantage that the animation will be untrigged correctly when the condition fails, this causes the reverse animation to show correctly. If you apply the condition to the animation directly, the animation will jump back the static condition right away. But when you want to place mulitple copies of your object, you can not apply the animation condition to the animation trigger as that will cause the total animation to fail, so in that case you need to apply it to the animation itself. An alternative would be to create a new GUID for each copy of the object you want to place, but when placing a lot of copies this is no good option.

• Animation Trigger This condition determines when your animation should start. By default the animations run endlessly, but for many animation this is not what you want. When you activate the animation trigger the animation will only start when a certain condition has been fulfilled. After that the animation plays once till the endpoint is reached. The animation will stay at this endpoint, till the trigger condition is no longer valid. In that case the reverse animation is shown once, till the animation is at its initial position again. The possibilities of the animation trigger are almost endless, but you can for example use it to animate a gate when a certain radio frequency is selected or to open your hangar doors when the aircraft comes close.

• Secondary Condition The secondary condition allows you to display a different animation depending on a certain condition. This can for example be used show a different gate animation depending on your aircraft type. When the secondary condition fails the animation will show at the initial static position.

These three types of condition can also be combined, you can have all three of them for one object. But if needed you can also use only one of them.

For the animation condition and the animation trigger three types of conditions can be specified. You can check if the value of a variable is between two values, you can check if certain bits of the value of a variable are set and you can check if the aircraft is within a certain bounding box. For the secondary condition only the value of a variable can be checked.

There is one big limitation that you should know when you use the bounding box as condition. The command used to define the bounding box does not depend on the rotation of your object and there is no other command available that does so. This means that the bounding box you define is always facing north, even if you rotate your object when you place it with the XML code. This means that you will have to define the bounding box for the rotation you are going to use the object at.

Interface

This section of the manual explains the interface of CAT, by taking a look at the different elements you will come across. This interface consists of six screens where you can enter options. After going through all these screens your tweaked animation is ready for you. To navigate between the different screens you can use the Previous and Next buttons you will find at the bottom of the screen.

On the screens of the three main features (the animation condition, animation trigger and secondary condition), you will find a checkbox that allows you to enable or disable this feature. When the feature is disabled you will not be able to use the text boxes, buttons, etcetera belonging to this feature. They are grayed out in that case.

On the screens of the animation condition and the animation trigger you have the choice between checking if a variable is between two values (condition between), checking if a variable matches a certain bitmask (condition mask) or using a bounding box (checking the position of the aircraft). To make this choice you can use the radio buttons.

When you have selected to use any of the two conditions, you will see a box where you need to enter the variable. You can either type in the variable name in the box yourself (don't forget the h at the end in that case) or you can use the combo box next to the text box to select a variable from the list of predefined ones. Use the arrow button to copy the value to the text box after you have selected it.

After you have selected the variable you also need to enter the minimum and maximum value between which the variable must be for the condition to be fulfilled. Use the minimum and maximum text boxes for these values. If you only want to check for a certain value you need to enter it for both the minimum and maximum. Some values might require an h at the end, like a radio frequency for example. Don't forget these. If you have selected the mask option, you only need to enter one value.

When you have selected a bounding box you will see seven text boxes. These allow you to enter the minimum and maximum values of the box along the three axes. These values must be integers (whole numbers, so without a decimal). The last box allows you to enter the rotation at which you want to use the bounding box, it will then be rotated to this heading. This is to solve the problem with the bounding box not responding to the rotation of your object, as discussed before.

If you have enabled the secondary condition, you do not only have to enter the variable you want to check, but also the number of secondary animations you want to use. On the file selection screen you will then be asked to select a file for each of these animations.

On the final to last screen, you will be asked to enter the source files CAT should process. When you are not using secondary condition you will see two text boxes, one for the input and one for the output file. You can use the ... button to bring up a Windows file dialog to select your file.

MakeMDL does save two source files of your object, myfile.asm and myfile_0.asm. It is very important that you never select the _0.asm file.

When you select your input file (or the first input file in case you use secondary conditions), the output file will automatically get the same name, but with the suffix of _cat. So when you file is called hangar.asm the default output file will be called hangar_cat.asm. Of course you can overwrite this filename if you wish.

When you are using secondary conditions, you will not only be asked to select a source file. But you will also be asked to enter the minimum and maximum values between which the variable of the secondary condition must be to show the animation of this source file.

If you have selected more than five secondary conditions, the file list will not fit onto the screen at once. You will then see arrow buttons to navigate through the list. The file numbers will be updated while you move.

Now that you have finished this section you will be familiar with the elements of the interface, but how can you use all this to tweak your animation? The next two sections will give some practical examples.

Example: Hangar

So you have come this far already. The boring parts of the manual about the interface etcetera are now over. Let's start with a practical example. For this example I will take a hangar and show how you could trigger the animation to open the doors when the aircraft is close enough.

The figure below shows the hangar as I have made it in GMax. This hangar has a grass roof and is located on the airstrip of Drachten in the Netherlands. As you can see there are two doors at the front and I want these to open when the aircraft gets close enough to them.

To get this result the opening animation will be triggered with a bounding box condition. But the first question then is how are the axes of the bounding box located compared to the object? The figure below shows how the different sizes of the bounding box are related to the axes of the object. The width is along the X axis in GMax, the length along the Y axis and the height along the Z axis.

These dimensions are all along the axes as defined in GMax. If you want to rotate your object during the placement, you must enter that heading in the rotation box of the bounding box. As described before, this is because the commands checking the bounding box do not take the rotation of the XML placement into account.

So what could we enter for our bounding box if we want the doors to open while you approach with your aircraft? The figure below shows an example of the trigger that could be used. In this case I enter -20 to 20 for the width, this means that the aircraft must be in a 40 meter width path ahead of the hanger. For the height I entered 0 to 10, which is enough for the small aircraft using this hangar. If you would make this heigh a lot bigger the doors would also open when an aircraft flies over the hangar, which is not what we want of course. The last dimension of the bounding box is the length, here I entered between -50 and -3. This makes sure that the aircraft is at the side of the doors and not at the other side of the hangar. As the middle of the hangar is at 0, the value of -3 means that the doors will close behind you after you have driven into the hangar.

And that's all that is needed to trigger your hangar doors with a bounding box. Depending on the size (and location of the reference point) of your hangar you need to adjust the values of the bounding box of course.

To make your hangar really special you could for example add an animation condition for the time of day, making sure that the doors will only open during the day. Just use your imagination and make something special out of your hangar.

Example: Gate

A bounding box trigger, as discussed in the previous section, is not suitable for each type of animation. Some animations you only want to happen when a certain condition is fulfilled. An example of this can be the docking of a gate to your aircraft. It is not enough that the aircraft is close to the gate, you also want to make sure that it has stopped. Therefore gate animations are often triggered with the NAV2 frequency. This section will show the settings required to do so.

The figure below shows how the animation trigger screen can look when the NAV2 frequency has been set as trigger. First the correct variable is selected, which is the NAV2 frequency in this case. When using a variable as trigger you need to enter the values between which this variable must be true to start the animation. In this case we want to use a frequency of 112.00, which corresponds with a variable value of 1200h (so the first 1 is dropped in the variable). As we only want the animation to start exactly on this frequency, the minimum and maximum values are set the same.

And that is all that is required to use a variable to trigger your animation. To make your gate better you could add a bounding box as animation condition. This makes sure only the gate your are close to will animate and not all other gates at the entire airport as well.

Example: Advanced gate

There could be one additional feature that you would like to add to your gate. Would it not be very cool if the animation would stop at different heights, depending on the aircraft type used? This section describes how you can do that.

For this selection of different animations, the secondary condition is used. Based on the value of the secondary condition variable different animations are displayed, once the animation is triggered. In this example the altitude above MSL variable is used, as that provides an indication of the altitude of the aircraft being used at the moment.

The figure below shows the secondary condition screen. I have selected the altitude above MSL variable in this case and entered that three different animations will be used.

On the next screen where the source files used are specified, you need to enter the values between which the variable of the secondary condition must be for that animation to show. The figure below shows how this can look for our three animations. The first animation is valid between an altitude of 0 and 9 meters, the second between 10 and 19 meter and the last between 20 and 29 meters. These altitudes would be a bit big for a real aircraft, then you would use differences of only 1 or 2 meters, but I think it makes the principle clear.

When the secondary condition fails, so in this example if the altitude is more than 30 meter, the animation will show static at the initial conditions.

Additional resources

Do you want to know more about CAT or animations? Then please have a look at the following resources:

Video tutorial for CAT: http://www.fsdeveloper.com/forum/showthread.php?t=750

Video tutorial about animating gates: http://www.fsdeveloper.com/forum/showthread.php?t=29

Support

If you have questions, comments or suggestions about CAT you can reach me either by email or through the forums of the website FsDeveloper.com.

Thanks to

The development of CAT from the first beta version till this released version has taken quite some time. And of course this program would not have been there without the help of a lot of people. So I would like the following persons for their help.

• The first step in the development of CAT was actually to discover how animations could be controlled. I can't remember anymore how I started working on that, but a long time ago this subject was discussed on the AvSim scenery design forum. I discovered then how it could be done and wrote my Frequency Controlled Animation tutorial about it. Thanks to whom ever got me looking into this and of course all the people who gave me feedback about the tutorial.
• Oliver Minchin, who gave me the idea to use secondary conditions and also encouraged me to write a tool to perform the actions described in my tutorial.
• Nick Whittome for his constant stream of ideas and suggestions that helped a lot to shape this tool. And of course for all the testing he did, often with still very buggy alpha versions.
• Dick Ludowise for BGLC_9 that is used to compile the new MDL file.
• Garfield for allowing me the take a picture of him, which is now used as the logo of CAT.
• Marco Pipino for the DOSOutputs class I used to compile the MDL file from within CAT.
• Bill Lyons for the feedback on getting CAT to work with FSDS3.
• All users who tested the previous beta versions of CAT and gave me feedback to improve the tool even further.
• And of course all the other people I have forgotten now, who gave me responds and encouraged me to develop this tool.

Version history

v1.02 19/03/2006

• ASM source files created with FSDS3 now also supported
• Found problem with animation condition, when multiple copies of the same object are placed. Added a new option to let the user choice where the animation condition applies to.
• Added new type of condition, instead of checking if a variable is between two values, you can now also use a bitmask.
• Minor interface tweaks

v1.01 29/05/2005

• Bug with animations with more than 10 animation tables solved
• Tab order of interface improved
• Animation condition now controls the trigger and not the animation itself
• New installer

v1.00 08/02/2005

• First non-beta released
• New manual
• Fixed remaining problems with windows regional settings
• Other minor fixes and improvements

v0.94 beta 16/11/2004

• Bounding box added as option for animation condition or animation trigger
• CAT now works independent of windows regional settings
• More then one saved configuration possible

v0.93 beta 12/10/2004

• Problems with filenames containing underscores solved

v0.92 beta 11/10/2004

• Fs2002 and Fs2004 functionality split into two program, CAT is now for Fs2004 only
• Complex linked animations now working correct
• Option to analyse secondairy condition files for correct number of frames and animations
• Ability to save and restore settings
• Increased the maximum amount of secondairy conditions
• Increased the maximum number of keyframes in an animation from 256 to 1025
• Store the state in local variables again
• Compile button working and result of compilation shown in CAT
• Move all file selection boxes
• Show file numbers on GUI
• Multiple animation conditions

v0.91 beta 11/09/2004

• Label naming problems solved
• SCEN section processing improved

v0.90 beta 10/09/2004

• First version with Fs2004 support
• Manual not updated yet

v0.81 beta 01/09/2004

• Bug fixed of corrupt code when there are more then 9 animation tables
• Output file name is now determined from the first input file name automatically
• Tab order corrected

v0.80 beta 07/06/2004

• New user interface
• Rewritten manual
• When secondary condition fails the object will show static and not sunken
• Maximum amount of keyframes increased to 256

v0.20 beta 18/09/2003

• Instead of storing the state in an user variable a local variable is used now

v0.18 beta 17/08/2003

• FIXED: Maximum number of frames in an animation increased from 100 to 200
• FIXED: Rotation that continued in the static states

v0.17 beta 14/08/2003

• FIXED: BGLC compile error when there is a - in the file name

v0.16 beta 14/08/2003

• FIXED: Two small bugs in the source that caused the animation of longer animations still not to work

v0.15 beta 14/08/2003

• FIXED: Animations longer then 100 frames that jump suddenly

v0.14 beta 12/08/2003

• FIXED: BGLC compile error when the object file and name starts with a number[/list]

v0.13 beta 12/08/2003

• FIXED: Reverse animation keyframes are now calculated correct
• Button added to be able to close the variable chooser screen without selecting anything

v0.12 beta 11/08/2003

• FIXED: Some objects appeared with an offset from their correct position
• FIXED: User variable list updated, not working variables removed and new added
• FIXED: Bug resulting in a BGLC error do to use of integer instead of float
• New way to select variables added, clicking the button next to the text box will give a list of options (please indicate which variables are still missing from that list).

v0.11 beta 10/08/2003

• Documentation included
• FIXED: Source files are now created correct. In the previous version only the \verb|_0.asm| file was created
• FIXED: Crash when pressing "Create Animation" without entering options

v0.10 beta 10/08/2003

• First version available for testing. This version should work correct, but there is no documentation yet. I am going to work on that now. Most options have a tooltip and if you still have others questions you know where to find me I guess.

Users license

(c) 2003-2006 SceneryDesign.org / Arno Gerretsen

This software program is distributed without charge to other scenery designers, redistribution of the original installer file is allowed. You are NOT allowed to sell this software program or ask money for its distribution. But the tweaked scenery objects produced 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.