ActiGate developers SDK

From FSDeveloper Wiki
Jump to: navigation, search

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.