Using the new extra, empty custom controls requires a nightly build from December 16, 2019 or later.EDIT: The caveats with default bindings not showing up in the key-pressed menu have now been fixed.
ChallengeMany mods and scripts use custom features that are triggered by key press. Those key-presses cannot be changed by the player in-game and may be bound to another control. Wouldn't it be nice if there were some controls just for modders/scripters that they could use? Wouldn't it be useful if the player could look up and even change the bindings for these controls in the configure controls menu? Also, it would be very convenient if custom controls could be check via the 'key-pressed' sexp similar to actual control keys.
New Feature:The nightly for December 12, 2019 adds five controls that do nothing and thus can be used for scripts/modding purposes. This way the modder can add new features/controls easily and have them show up in the controls menu and be bindable. This will also alert the player if there is a control conflict. This is much easier for the player as they can view and change the bindings in the configure controls menu. It also means that scripters and FREDers can call these custom controls in a much more versatile way (more details on that below).
Setup Overview:The empty custom controls are disabled by default, have a default key-binding of Shift-Alt (1-5) respectively, and no default index in strings.tbl. To use these, create a new entry in Controlconfigdefaults.tbl with the respective name and entry information. To change the string displayed for the control name add a string entry to strings.tbl and specify that index in '$Has XStr:'.
This information is also summarized on
https://wiki.hard-light.net/index.php/Controlconfigdefaults.tbl#List_of_Bindings.
There are currently five controls to use:
Custom Control 1
Custom Control 2
Custom Control 3
Custom Control 4
Custom Control 5
Setup Example:For a specific example, let's use Custom Control 1 to make a control that heals the player.
First we open Controlconfigdefaults.tbl and add this line:
$Bind Name: Custom Control 1
This enables the control to be used. If you do not want to set a custom binding you do not have to, but setting a default binding is recommended since it will allow you to use the key-pressed sexp. Just like any other entry in Controlconfigdefaults.tbl we can also specify key modifiers like shift or alt. For this example, let's say we want to set a default key binding of 'X', so add the line:
$Key Default: KEY_X
Now we can change which tab we want the custom control to show up in. By default it is the Computer Tab. We can set the tab just like any other control. For this example I'm going to set it to the ship tab, so add this line:
$Category: SHIP_TAB
Now we probably want to change the display name of this control. First though, we need to add a new string entry to strings.tbl. For this example we are making a heal control, so let's open strings.tbl and add the line:
1570, "Heal Ship" ; used with Custom Control 1
Now save the updated strings.tbl file and hop back to Controlconfigdefaults.tbl. To use that new string entry add the following line to our ongoing entry for Custom Control 1 and save the file.
$Has XStr: 1570 ; "Heal Ship"
The last thing we need to do is ensure that the game recognizes to use the default key we have assigned. If you do not do this step then a player will have the default key set to 'None'. To complete this step simply add this line:
$Disable: false
The final, complete entry of this example would be:
Added to Controlconfigdefaults.tbl:
$Bind Name: Custom Control 1
$Key Default: KEY_X
$Category: SHIP_TAB
$Has XStr: 1570 ; "Heal Ship"
$Disable: false
Added to strings.tbl:
1570, "Heal Ship" ; used with Custom Control 1
Use In-game:Everything is setup and ready to use, but we still need to make sure the control actually does something! Two of the easiest ways to do this would be with the 'key-pressed' sexp in FRED or the '$On Action:' with scripting.
Using the 'key-pressed' sexp in FRED would work just like any other control. This includes the ability of FSO to automatically account for any keys that have been remapped. In our example we set the default key to 'X'. With the most recent nightly, FRED will now know what we have specified in our Controlconfigdefaults.tbl. Thus, if there no other default keys with 'X' we can simply use:
( when
( key-pressed "X" )
( set-subsystem-strength
"Alpha 1"
"Hull"
100
)
)
Using the '$On Action:' with scripting also works well. Note, that we still need to use the bind name of the control, not the string name. Thus, our example would be:
$Action: Custom Control 1
$On Action: [
mn.runSEXP("( set-subsystem-strength !" .. hv.Player.Name .. "! !Hull! 100 )")
]
Please note that these sexp and scripting examples are not comprehensive and should include more error checking, but for the purposes of this tutorial I wanted to highlight how to use the new features and not clutter the example.
Summary:The nightly for December 12, 2019 adds five controls that do nothing and thus can be used for your scripts/modding in a much more versatile way then previous methods. These custom controls allow players to view and change key bindings in-game, easily view control conflicts, and allow you the modder/scripter to use more versatile calls with FRED or lua. I hope folks find these features useful and I would be happy to answer any additional questions.
Thanks!