ActiGate developers SDK
Introduction
This is the SDK that explains how you can use the functionality provided by the ActiGate module in your scenery. This document is only for scenery designers, it is of no use for normal users of Flight Simulator.
In the remainder of this document it will be explained what kind of functionality the ActiGate module provides and how you can make use of it in your scenery.
How the module works
Before explaining which variables are available and how they can be used, it is also important to explain the basics of how the module works. The ActiGate module makes use of FSUIPC to read parts of the memory that can normally not be read by the scenery. This information is then used to set the scenery user variables to a certain value.
So this means that you (and the user of the scenery) need to have FSUIPC installed in your Flight Simulator, else the ActiGate module will not be able to read the information it is looking for. The ActiGate has a freeware key, so you can also use it with the freeware version of FSUIPC.
As the information is then written into the user variables, this means conflicts can occur when the same user variables are also used by other programs or scenery. The ActiGate module uses the user variables 4 and 5 (usrvr4 and usrvr5), so you should not use these in other places as well. The module also has the option to be disable from the Flight Simulator modules menu, so this can be used to prevent conflicts with other scenery or tools.
Available variables
The ActiGate modules writes data to the user variables 4 and 5. This section explains which data is written.
In user variable 4 (usrvr4) the type of aircraft used at the moment is written. The ActiGate module uses the name string as defined in the aircraft.cfg
file. Below is a list of all types that can be recognised and the value that is written to user variable 4 in that case.
0 Unknown/not recognised 1 Airbus A300 2 Airbus A310 3 Airbus A318 4 Airbus A319 5 Airbus A320 6 Airbus A321 7 Airbus A330-200 8 Airbus A330-300 9 Airbus A340-200 10 Airbus A340-300 11 Airbus A340-500 12 Airbus A340-600 13 Airbus A380 14 McDonnell Douglas DC-10 / MD10 15 McDonnell Douglas MD-11 16 McDonnell Douglas DC-9 17 McDonnell Douglas MD-80 18 McDonnell Douglas MD-87 19 Boeing 717 20 Douglas DC8 21 Convair CV-880 22 Convair CV-990 23 Boeing 707 24 Boeing 720 25 Boeing 727-100 26 Boeing 727-200 27 Boeing 737-100 28 Boeing 737-200 29 Boeing 737-500 30 Boeing 737-600 31 Boeing 737-300 32 Boeing 737-700 33 Boeing 737-400 34 Boeing 737-800 35 Boeing 737-900 36 Boeing 747 37 Boeing 747SP 38 Boeing 757-200 39 Boeing 757-300 40 Boeing 787-300 41 Boeing 787-800 42 Boeing 787-900 43 Boeing 767-200 44 Boeing 767-300 45 Boeing 767-400 46 Boeing 777-200 47 Boeing 777-300 48 Fokker F28 49 Fokker 70 50 Fokker 100 51 BAe 146-100 52 BAe 146-200 53 BAe 146-300 54 Canadair RJ 55 Canadair RJ-700 56 Canadair RJ-900 57 Embraer ERJ135 58 Embraer ERJ140 59 Embraer ERJ145 60 Embraer EMB-170 61 Embraer EMB-175 62 Embraer EMB-190 63 Embraer EMB-195 64 Lockheed L1011-100 65 Lockheed L1011-500 66 Tupolev Tu-134 67 Tupolev Tu-154 68 Tupolev Tu-204 69 Tupolev Tu-334 70 Yakovlev Yak-40 71 Yakovlev Yak-42 72 Antonov An-74 73 Antonov An-124 74 Antonov An-225 75 Ilyushin IL-76 76 Ilyushin IL-86 77 Ilyushin IL-96 78 Concorde 79 Vickers VC10 80 BAC 1-11 81 Hawker Siddeley Trident 82 De Havilland DH-104 Comet 83 Gulfstream Gulf III 84 Gulfstream Gulf IV 85 Gulfstream Gulf VI 86 Sud Aviation Caravelle 87 Dassault Falcon 88 Cessna Citation 89 Bombardier Global Express 90 Bombardier Challenger 91 Bombardier Learjet 92 De Havilland Canada DHC-7 93 De Havilland Canada DHC-8-200 94 De Havilland Canada DHC-8-300 95 De Havilland Canada DHC-8-400 96 Shorts 360 97 Shorts 330 98 Shorts Skyvan 99 Saab 340 100 Saab 2000 101 Fokker F27 102 Fokker F50 103 ATR-42 104 ATR-72 105 Bae Jetstream 31 106 Bae Jetstream 41 107 Bae Jetstream 61/ATP/746 108 Antonov An-12 109 Antonov An-24 110 Antonov An-140 111 Tupolev Tu-114 112 Embraer EMB-120 113 Dornier 228 114 Dornier 328 115 Douglas DC-2 116 Douglas DC-3 117 Douglas DC-4 118 Douglas DC-6 119 Douglas DC-7 120 Lockheed L0749 121 Lockheed L1149 122 Convair 240 123 Convair 340 124 Boeing 240 125 Boeing 317 126 Fokker F.VII 127 Ford Trimotor 128 Beechcraft 1900 129 Aero Commander
The different subtypes of a certain aircraft have been grouped in such a way that you don't have to use them. For example if you just want to check if the user aircraft is any 737, you could check if the value is between 27 and 35.
In user variable 5 (usrvr5) a number of different conditions have been combined. All these condition have the state of being either true or false. If multiple of them are true, there values are added together. The available values are:
1 parking brake set 2 rain 4 snow 8 Monday 16 Tuesday 32 Wednesday 64 Thursday 128 Friday 256 Saturday 512 Sunday
To give a few examples of how this work. If it is a Friday and you have the parking brake set at the moment, usrvr5 will have a value of 129. If it is a rainy Monday usrvr5 will have the value of 10. See the example below to see how you can check for these conditions.
Source code tweaking examples
If you want to check if the aircraft the user is using at the moment is a Boeing 737, you need to check if the value of the user variable 4 is between 27 and 35. In BGLC code this check can be done with the following code:
IFIN1 lbl_end, usrvr4, 27, 35 ; code only to be displayed for the selected aircraft lbl_end label word
If you are modelling your object in SCASM code, you could do a similar check with code like shown below:
IfVarRange( :lbl_end 0318 27 35 ) ; code only to be displayed for the selected aircraft :lbl_end
If you want to check for one specific type, you need to set the minimum and maximum value in the check the same. For example to check if the user is flying a Airbus A380 you could use code like this:
IFIN1 lbl_end, usrvr4, 13, 13 ; code only to be displayed for the selected aircraft lbl_end label word
You could also use the aircraft type variable as the secondary condition in CAT or as a condition in MDL Tweaker. In that case you do not have to tweak the source code yourself. Check FsDeveloper.com to download these tools.
For the user variable 5 a different command is needed to check the value. This is because the value is a combination of different conditions. To see if the parking brakes are set for example, you can not simple check if the value of usrvr5 is 1 or not. This is because the value for the current day of the week is also added to usrvr5 for example. So therefore a different command needs to be used to check usrvr5.
This command is IFMSK
in BGLC or IfVarAnd
in SCASM. To see if the parking brake has been set you can use code like this:
IFMSK lbl_end, usrvr5, 1 ; code only to be displayed when condition is true lbl_end label word
This check if the bit that corresponds with the value of 1 has been set. So for any value of usrvr5 where the value of 1 has been set will result in a positive result of the check. For example, if the value of usrvr5 is 13 (1 parking brake, 4 snow, 8 Monday) the result is true.
In SCASM this code is written like this:
IfVarAnd( :lbl_end 031A 1 ) ; code only to be displayed when condition is true :lbl_end
If you want to check if the day is Saturday or Sunday (so if it is a weekend) then you can use a check like this:
IFMSK lbl_end, usrvr5, 768 ; code only to be displayed when condition is true lbl_end label word
Please note that CAT is not able to write the IFMSK
command in your source code at the moment. So you will have to tweak the source code a little bit manually to be able to trigger your animation with the parking brake setting.
Users license
(c) 2005-2006 Arno Gerretsen / SceneryDesign.org
This software program is distributed without charge to other scenery designers, redistribution of the original installer EXE of the module and the SDK is allowed. You are NOT allowed to sell this software module or ask money for its distribution. The use of the module is only allowed in freeware sceneries, if you want to use it in a commercial scenery please contact me.
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.
Distribution of the module
It is the task of the scenery designer to make sure the module and its documentation is distributed correctly. So if the scenery designer is using an installer for his scenery, the installer software must make sure the module is installed correctly in the modules folder and that a newer version of the module (if it exists) is not overwritten. If the scenery does not use an installer, the scenery designer should include the proper instructions in his readme file.
Please do also include the ActiGate End User documentation PDF file with your scenery, it provides your end user with some basic information about the module.
Support
If you have questions, suggestion or comment about the use of the ActiGate module please let me know. Maybe you have an idea for a new variable that could be added or for an aircraft type that I forgot. But also questions about the use of the module in your scenery are welcome of course. You can reach me either by email or through the forums of my website FsDeveloper.com.
If you have questions related to animations, CAT, MDL Tweaker together with the ActiGate module you could also contact Nick Witthome (he also reads the forum, so you can still post your questions there as well).
Thanks to
- Nick Whittome for all the ideas and suggestions that helped in shaping this module in its final form
- Pete Dowson for FSUIPC and especially for solving the problems with Fs2004 and scenery user variables
- Russel Dirks, Cyril Hruscak, Joel DeYoung and José Oliveira who all provided code examples for a FS module. With the help of these examples I was able to create the ActiGate module.