Originally posted by Dunc
Well...
it has been quite some time since somebody explained the inner working of the Falcon keyfiles to us. With the introduction of FalconAF and especially the multi-controller-capability, the format has changed again (or at least it has been extended). So I thought it might be a good idea going through that file, its format and structure again. Perhaps somebody finds that information helpful.
1st Disclaimer:
I am not the 1st one who's posting about the keyfile format, so the credit for finding out hardly belongs to me. Nevertheless, I'd like to make a summary that is valid for the current FalconAF version (patch 1.05).
2nd Disclaimer:
The name "secret decoder update" was chosen because 'Gorny asked me a long time ago what is the "secret decoder ring" for those keyfiles. Well, I was unable to answer that question satisfactorily.
So here we go...
Part 1: Where to find the file
Ok, as you all know, the FalconAF keyfiles define the binding between the functionallity you can trigger within the sim and the different input devices like keyboard and joysticks that you have available. You find your keyfiles in the "config" subfolder of your FalconAF installation directory, so the default location would be:
"C:\Program Files\Lead Pursuit\Battlefield Operations\config\"
The keyfiles available to the sim all end with ".key", LP provided backup copies of those files (in case you screw them up), ending in ".orig" for your reference.
Let's have a look at the file - simply open it with a text editor. What you'll find are multiple lines, each line describing one particular binding. Let's pick out one line as an example...
SimToggleAutopilot 1076 0 0X1E 0 0 0 1 "Ckpit-Autopilot"
Basically, all lines look like this example line (well, more or less, details will follow). First part names an internal function name in the sim that is described by that line, then some code to which key/input device it is bound, and last not least (if we're lucky) some human-readable description of what that function really does. Let's get into the details...
Part 2: Keyboard bindings
The example line that we picked describes a keyboard binding. So let's have a deeper look (I use color coding to better distinguish between the different parts):
SimToggleAutopilot 1076 0 0X1E 0 0 0 1 "Ckpit-Autopilot"
The 1st part (SimToggleAutopilot) describes the sim function that is defined here. This is something what is defined by FalconAF and can not arbitrarily chosen by you. The most complete list of possible functions can be found in the cockpitbuilders.key file.
The 2nd part (1076) defines an ID within the 2D cockpit that you see within the sim. Those IDs are basically used within the cockpit definitions (somewhere in the art/ckptart folders) and are NOT related to the keyboard binding that is done here. So why does it show up? It simply means that the same sim function described by the current line can be toggled when you click on the cockpit graphic (button or switch) that has that particular ID. Long speech, short sense: You should NOT adjust that number. Always leave it as it is, otherwise you may lose cockpit mouse functionality.
If that number is "-1", it simply means that there is no 2D cockpit button/switch assigned to that function.
The 3rd part (0) seems not to be used anymore and is always "0" for keyboard bindings. Again, just leave it alone... (In the "old" Falcon days, here could have been used a "1" as well, which meant that ONLY the mouse cockpit input (2nd part) could be used to trigger the function and the keyboard binding was not used. Never saw this in FalconAF).
With the 4th part (0X1E 0), the interesting things start to happen. Basically you see 2 numbers: "0X1E", which describes the keyboard button that is assigned, and "0", which describes the modifier that needs to be applied (Alt, Shift, Ctrl or combinations).
Let's start with the modifier. This entry can have 8 different values:
"0" = (no modifier)
"1" = Shift
"2" = Ctrl
"3" = Shift+Ctrl
"4" = Alt
"5" = Shift+Alt
"6" = Ctrl+Alt
"7" = Shift+Ctrl+Alt
So this is the key combination that you need to press together with the button defined before to trigger the function.
Ok, so here's the big list of possible keys - for a US keybard layout (for those of you who *really* want to know it: those are customised XT keycodes, not AT!):
Edit: The "modifier keys" mentioned above (Shift, Ctrl, Alt) are NOT recognized as individual keys in FalconAF. That's why they do not show up in that following list. And that's why you cannot distinguish between left Shift/Ctrl/Alt and right Shift/Ctrl/Alt.
"0X1E" = "A"
"0X30" = "B"
"0X2E" = "C"
"0X20" = "D"
"0X12" = "E"
"0X21" = "F"
"0X22" = "G"
"0X23" = "H"
"0X17" = "I"
"0X24" = "J"
"0X25" = "K"
"0X26" = "L"
"0X32" = "M"
"0X31" = "N"
"0X18" = "O"
"0X19" = "P"
"0X10" = "Q"
"0X13" = "R"
"0X1F" = "S"
"0X14" = "T"
"0X16" = "U"
"0X2F" = "V"
"0X11" = "W"
"0X2D" = "X"
"0X15" = "Y"
"0X2C" = "Z"
"0X1" = "Escape"
"0X3B" = "F1"
"0X3C" = "F2"
"0X3D" = "F3"
"0X3E" = "F4"
"0X3F" = "F5"
"0X40" = "F6"
"0X41" = "F7"
"0X42" = "F8"
"0X43" = "F9"
"0X44" = "F10"
"0X57" = "F11"
"0X58" = "F12"
"0XB7" = "PrintScreen"
"0X46" = "ScrollLock"
"0X29" = " ~ "
"0X2" = "1"
"0X3" = "2"
"0X4" = "3"
"0X5" = "4"
"0X6" = "5"
"0X7" = "6"
"0X8" = "7"
"0X9" = "8"
"0XA" = "9"
"0XB" = "0"
"0XC" = " - "
"0XD" = " = "
"0XE" = "Backspace"
"0XF" = "Tabulator"
"0X1A" = " [ "
"0X1B" = " ] "
"0X2B" = " \ "
"0X3A" = "CapsLock"
"0X27" = " ; "
"0X28" = " ' "
"0X1C" = "Enter"
"0X33" = " , "
"0X34" = " . "
"0X35" = " / "
"0XDB" = "Win(left)"
"0X39" = "Space"
"0XDC" = "Win(right)"
"0XDD" = "Menu"
"0XD2" = "Insert"
"0XD3" = "Delete"
"0XC7" = "Home"
"0XCF" = "End"
"0XC9" = "PageUp"
"0XD1" = "PageDown"
"0XC8" = "CursorUp"
"0XD0" = "CursorDown"
"0XCB" = "CursorLeft"
"0XCD" = "CursorRight"
"0X45" = "NumLock"
"0XB5" = "Num/"
"0X37" = "Num*"
"0X4A" = "Num-"
"0X4E" = "Num+"
"0X52" = "Num0"
"0X4F" = "Num1"
"0X50" = "Num2"
"0X51" = "Num3"
"0X4B" = "Num4"
"0X4C" = "Num5"
"0X4D" = "Num6"
"0X47" = "Num7"
"0X48" = "Num8"
"0X49" = "Num9"
"0X53" = "NumDel"
"0X9C" = "NumEnter"
"0XFFFFFFFF" = "(Not assigned)"
As you can see, a non-assignment (0XFFFFFFFF) is possible.
Sorry for that looong list, I just wanted to be sure...
Ok, the 5th part (0 0) basically works exactly the same as the 4th part. 1st number is a key, 2nd number is a modifier. So what's the deal here?
Well, this is a key combination that you have to press before the key combination of defined in the 4th part. Huh? Let's pick an example, because the one we have used uses "0 0", which basically means there is no need for a 2nd keycombo... Alright, here's a better example (only highlighting the important things now):
SaveCockpitDefaults -1 0 0X1F 0 0X2E 4 -1 "Sim-cockpit setup save"
The first keycombo is "0X1F 0", which we can translate now to "no modifier" and "key S". Or simply "S". The second keycombo is "0X2E 4" which we can translate to "Alt" and "key C".
So this means that for triggering the function, you have to press
first ALT+C then S
OK? Good.
However, there is a restriction for this double-keycombo. You can not choose everything you want for that 5th part (ALT+C in our example). The available keycombos need to be defined as normal functions in the keyfile in order to use them. Here are the lines that are defined by default:
CommandsSetKeyCombo -1 0 0X2C 2 0 0 -1 "Key-Combination Ctrl-Z"
CommandsSetKeyCombo -1 0 0X2D 2 0 0 -1 "Key-Combination Ctrl-X"
CommandsSetKeyCombo -1 0 0X2E 4 0 0 -1 "Key-Combination Alt-C"
So that means that you can use those three combos (0X2C 2, 0X2D 2, 0X2E 4) as 5th part in your other function lines. I never tried defining different combos, but I guess it should be no problem
The 6th part (1) defines whether you can see and assign the function within the setup screen of FalconAF. The possible values are:
"1" = You can see and change the assignment
"-1" = You can see it, but not change it
"-2" = You can neither see nor change it
Have a look at the cockpitbuilders.key file, you'll see there are quite a bunch of "hidden" functions...
And last not least, the 7th part ("Ckpit-Autopilot") simply holds the description that you see in the FalconAF setup screen for that function.
That's it for the keyboard...
Part 3: DirectX bindings
Right, you do not need to use keyboard bindings only, you can also use DirectX button assignments to toggle a function. As you might have guessed already, the binding lines for DirectX look different then the ones that we have described so far. So let's pick two examples. Why two? Well, because there is a (minor) difference whether you have only one DirectX device connected to your PC or multiple DirectX devices.
First example line, only one DirectX device:
SimTrigger 0 -1 -2 0 0x0 0
Second example line, multiple DirectX devices:
SimTrigger 0 -1 -2 0 0x0 0 {46D7A990-DCF4-11D9-8001-444553540000}
As you can see, the only difference is a looooong identifier string in the end. Let's start with that identifier, because the rest of the line is the same for both examples. The long identifier simply identifies the DirectX device that is used to generate the input. Oh, you guessed already? Well, that's all there is to it...
Now the question "How the hell do I know which device is described with that identifier?" Honestly, I don't know where to find a definition. I've searched the registry as well as I made a dxdiag, msinfo... No luck. However, I only have TWO devices connected, so I just tried. The identifier above {46D7A990-DCF4-11D9-8001-444553540000} seems to be my Cougar. Just try, assign a function in the FalconAF setup screen with different controllers and take note for your individual controllers yourself.
Edit: No need to search the registry or something else to get the controller ID. Just assign a DX button within the FalconAF setup screen, and FalconAF writes the ID to the keyfile. Open the file, look for the new entry, there you go!
Before we explain the DirectX lines in detail, I want you make aware of the following:
If you assign a DirectX button to a sim function that has already a keyboard input assigned, you will NOT overwrite the keyboard input! Instead, both the keyboard input AND the DirectX input are functional now. And yes, that means that you may have two lines in your keyfile beginning with the same sim function name. That is completely OK!
Now back to the details. I'll take the line without the identifier in the end for simplification:
SimTrigger 0 -1 -2 0 0x0 0
The 1st part ("SimTrigger") is the sim function that should be triggered. Nothing new here.
Let me just jump to the 3rd part ("-1"), because we know this already as well. Like the 2nd part of the keyboard bindings, this 3rd part describes the 2D cockpit ID that can trigger the same function as well when clicked with the mouse. In our example, the "-1" simply means that there is no cokpit ID assigned.
The 2nd part ("0") is the DirectX button of the device that is assigned to that function. Be aware that FalconAF starts to count the buttons up from "0", whereas most joystick start to count from "1". So if your stick has four buttons 1 2 3 4, FalconAF will identify them as 0 1 2 3.
Edit: If you use more then one controller, every controller starts with the DX buttons from 0 again. FalconAF distinguished between different controllers just by the identifier/GUID at the end of the line mentioned above.
However, this 2nd part ("0") is only relevant if the 4th part ("-2") is "-2", which means that the normal DirectX buttons of the device should be used. If the 4th part is not "-2", the 2nd part seems to be always "0". If the 4th part is "-2", the 5th part ("0") is always "0".
The only other value I have noticed for that 4th part is "-3". This means that your input device should NOT use the normal DirectX buttons, but directions of the POV/FieldOfView Hat switch. If that is the case, the 2nd part is not used and always "0", however, now the 5th part ("0") is used to determine the hat direction:
"0" = Hat UP
"2" = Hat RIGHT
"4" = Hat DOWN
"6" = Hat LEFT
I assume that a value of "1" would lead to "Hat UP-RIGHT", a value of "3" would lead to "Hat RIGHT-DOWN" etc., but I haven't verified that yet.
The 6th part ("0x0 0") seems to be always "0x0 0", I've never seen anything else.
And last not least, if you have a 7th part, it is the identifier of your joystick.
Confused? Well, it's not so hard if you see a complete example. Here's what my oooold Wingman is capable of (please ignore the actual sim functions that I have used, they make no sense at all, I just wanted to assign *something*):
"Wingman Trigger (Button 1)"
SimLeftHptOff 0 -1 -2 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman Button2"
SimLeftHptOn 1 -1 -2 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman Button3"
SimMAPOff 2 -1 -2 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman Button4"
SimMAPOn 3 -1 -2 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman Button5"
SimDLOff 4 -1 -2 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman Button6"
SimDLOn 5 -1 -2 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman Button7"
SimGPSOff 6 -1 -2 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman HatUP"
SimUFCOff 0 -1 -3 0 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman HatRIGHT"
SimMFDOn 0 -1 -3 2 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman HatDOWN"
SimUFCOn 0 -1 -3 4 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
"Wingman HatLEFT"
SimMFDOff 0 -1 -3 6 0x0 0 {CB7F0BB0-8F1F-11DA-8001-444553540000}
Part 4: The best thing about multi-controller support
With the addition of the device identifier to the DirectX bindings, FalconAF is now capable of using 32 DirectX buttons for every DirectX device! So if you have 3 devices connected, you could assign up to 3x32 = 96 DirectX functions! This means a complete DirectX cockpit implementation is possible now.
---
Well, that's it, I think. I hope that you find some useful info. If I made some errors or you have some other feedback, please let me know.
Cheers!
dunc.
