Author Topic: How to use the new extra, empty controls for modders  (Read 7185 times)

0 Members and 1 Guest are viewing this topic.

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
How to use the new extra, empty controls for modders
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. 

Challenge
Many 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:
Code: [Select]
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:
Code: [Select]
$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:
Code: [Select]
$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:
Code: [Select]
$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:
Code: [Select]
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.
Code: [Select]
$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:   
Code: [Select]
$Disable: false
The final, complete entry of this example would be:

Added to Controlconfigdefaults.tbl:
Code: [Select]
$Bind Name: Custom Control 1
$Key Default: KEY_X
$Category: SHIP_TAB
$Has XStr: 1570 ; "Heal Ship"
$Disable: false

Added to strings.tbl:
Code: [Select]
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:
Code: [Select]
( 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:
Code: [Select]
$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!
« Last Edit: December 23, 2019, 03:09:11 pm by wookieejedi »

 
Re: How to use the new extra, empty controls for modders
Cool.
I guess it's time to move away from the awkwardness of using multiplayer keys for abilities.

 

Offline Iain Baker

  • 210
  • 'Sup?
    • Steam
    • Twitter
    • NOMAD's Reviews
Re: How to use the new extra, empty controls for modders
Awesome. I was about to post a general plea to modders to write somewhere prominent if their campaigns use specific keys for campaign / mod specific stuff and if so what these keys are, so that we know in advance not to assign that key to something else and break the game (as has happened to me on several occasions.)

But I'm guessing this would take care of that anyway  :)
Wanna check out my video games, technology and media website? If so, visit; https://www.nomadsreviews.co.uk/

Interested in hiring my freelance writing, proof-reading, editing, SEO, TTSO, Web Development or Social Media Management services? If so, please messege me at [email protected]

 
Re: How to use the new extra, empty controls for modders
Nice! :yes:

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Thanks!

 

Offline mjn.mixael

  • Cutscene Master
  • 212
  • Chopped liver
    • Steam
    • Twitter
Re: How to use the new extra, empty controls for modders
Should I expect these to show up in the key-pressed list in FRED?

I setup a custom command for Shift-2 which doesn't seem to be used by default. It doesn't show in the list.
Cutscene Upgrade Project - Mainhall Remakes - Between the Ashes
Youtube Channel - P3D Model Box
Between the Ashes is looking for committed testers, PM me for details.
Freespace Upgrade Project See what's happening.

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Should I expect these to show up in the key-pressed list in FRED?

I setup a custom command for Shift-2 which doesn't seem to be used by default. It doesn't show in the list.

Good question. As it turns out, a key default value must be specified in `controlsconfigcommon.cpp` for the sexp `key-pressed` to track key binding changes. I had thought as long as the default was specified in the controlconfigdefault.tbl it would show up in FRED but alas not. I have just submitted a PR to add that functionality to the custom controls for modders and will keep this topic updated. Thanks for bringing that to my attention.

EDIT: Now these will show up in the key-pressed list in FRED.
« Last Edit: December 14, 2019, 03:32:08 pm by wookieejedi »

 

Offline mjn.mixael

  • Cutscene Master
  • 212
  • Chopped liver
    • Steam
    • Twitter
Re: How to use the new extra, empty controls for modders
Something else I noticed and it may or may not be able to be fixed. If you add these keybinds and then run FSO using a pre-existing pilot, the binds will be set to 'none'. I have not yet tested if that affects the key-pressed sexp. I'm assuming there's no data for these keybinds in the player file, so FSO defaults to 'none' rather than the specified default from the table.
Cutscene Upgrade Project - Mainhall Remakes - Between the Ashes
Youtube Channel - P3D Model Box
Between the Ashes is looking for committed testers, PM me for details.
Freespace Upgrade Project See what's happening.

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Yeah, I have been looking for a way in the code to potentially fix this, but that's indeed the issue. FSO reads the Control_config array first and that does not currently have default keys set for these controls (the upcoming PR should fix that though). In the meantime, clicking cycle presets in the config control window will load in the tabled defaults instead of the coded default of none.

EDIT: Adding the line '$Disable: false' will ensure that the default keys will be used even with old pilots.
« Last Edit: December 14, 2019, 03:33:02 pm by wookieejedi »

 

Offline mjn.mixael

  • Cutscene Master
  • 212
  • Chopped liver
    • Steam
    • Twitter
Re: How to use the new extra, empty controls for modders
I'm more curious how this will affect players who load up a mod with added/changed defaults but use the same player across mods.

If I added Custom Control 1 bind and use that in a mission but their control is set to 'none'.. how will that play out?
Cutscene Upgrade Project - Mainhall Remakes - Between the Ashes
Youtube Channel - P3D Model Box
Between the Ashes is looking for committed testers, PM me for details.
Freespace Upgrade Project See what's happening.

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Ah I actually found a solution that you can use right away. In looking through the code it turns out you can ensure that the default key you set in the table is loaded if you add `$Disable: false` to the last line of the Custom Control entry. Thus the entire entry would be:

Code: [Select]
$Bind Name: Custom Control 1
$Key Default: KEY_X
$Category: SHIP_TAB
$Has XStr: 1570 ; "Heal Ship"
$Disable: false

Now, even if you load in a pilot that was missing that key before it will automatically update the control with the default key you set and the player won't have to worry about it. In other words this fixes the issue of having it automatically set to `None`.

The incoming PR will then also add the ability to select that key from the menu for `key-pressed`. In the meantime though you can use the `string` input method and type out your control. In my tests it works just as expected. It also works for using with $$ in the directive text.
« Last Edit: December 14, 2019, 12:24:03 pm by wookieejedi »

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Just updating to state that everything should be working as expected with the newest nightly, (Dec 16 or later). Custom controls that are specified in the table will also show in the key-pressed menu, too.

 

Offline mjn.mixael

  • Cutscene Master
  • 212
  • Chopped liver
    • Steam
    • Twitter
Re: How to use the new extra, empty controls for modders
Ah I actually found a solution that you can use right away. In looking through the code it turns out you can ensure that the default key you set in the table is loaded if you add `$Disable: false` to the last line of the Custom Control entry. Thus the entire entry would be:

Code: [Select]
$Bind Name: Custom Control 1
$Key Default: KEY_X
$Category: SHIP_TAB
$Has XStr: 1570 ; "Heal Ship"
$Disable: false

Now, even if you load in a pilot that was missing that key before it will automatically update the control with the default key you set and the player won't have to worry about it. In other words this fixes the issue of having it automatically set to `None`.

Just tested this and did not see that happen. My previously existing pilots still had 'none' selected for the custom actions.
Cutscene Upgrade Project - Mainhall Remakes - Between the Ashes
Youtube Channel - P3D Model Box
Between the Ashes is looking for committed testers, PM me for details.
Freespace Upgrade Project See what's happening.

  

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Hmm that's odd. In my tests it worked. Which nightly are you using?

 

Offline mjn.mixael

  • Cutscene Master
  • 212
  • Chopped liver
    • Steam
    • Twitter
Re: How to use the new extra, empty controls for modders
The latest from the 16th. I see the keys in key-pressed now.

And I have verified that if the custom actions are set to key 'none', then they will not work in-mission.

My table...

Code: [Select]
#ControlConfigOverride

$Bind Name: Custom Control 1
$Key Default: KEY_A
$Key Mod Shift: 1
$Key Mod Alt: 1
$Category: SHIP_TAB
$Has XStr: 615
$Disable: false

$Bind Name: Custom Control 2
$Key Default: KEY_S
$Key Mod Shift: 1
$Key Mod Alt: 1
$Category: SHIP_TAB
$Has XStr: 616
$Disable: false

$Bind Name: Custom Control 3
$Key Default: KEY_D
$Key Mod Shift: 1
$Key Mod Alt: 1
$Category: SHIP_TAB
$Has XStr: 617
$Disable: false

$Bind Name: Custom Control 4
$Key Default: KEY_Z
$Key Mod Shift: 1
$Key Mod Alt: 1
$Category: SHIP_TAB
$Has XStr: 618
$Disable: false

$Bind Name: Custom Control 5
$Key Default: KEY_X
$Key Mod Shift: 1
$Key Mod Alt: 1
$Category: SHIP_TAB
$Has XStr: 619
$Disable: false

#End
« Last Edit: December 17, 2019, 09:35:34 pm by mjn.mixael »
Cutscene Upgrade Project - Mainhall Remakes - Between the Ashes
Youtube Channel - P3D Model Box
Between the Ashes is looking for committed testers, PM me for details.
Freespace Upgrade Project See what's happening.

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Ah I see the challenge. If a player opened their pilot in that window of time when the controls didn't have a default then the player file saved that and now thinks the player bound the control to None, so it saved it. This will not be an issue with any new pilot files, but still most folks use the same pilot for most things.

I would say remind players to make sure they either click use default controls and make sure they have the keys bound.
« Last Edit: December 23, 2019, 03:13:53 pm by wookieejedi »

 

Offline mjn.mixael

  • Cutscene Master
  • 212
  • Chopped liver
    • Steam
    • Twitter
Re: How to use the new extra, empty controls for modders
Why does Key 5 act differently than Custom Control 1? (trying to understand) Aren't they both essentially custom controls your PRs just added?
Cutscene Upgrade Project - Mainhall Remakes - Between the Ashes
Youtube Channel - P3D Model Box
Between the Ashes is looking for committed testers, PM me for details.
Freespace Upgrade Project See what's happening.

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Good question and yes, they work the same way. The only difference is that those keys had a default key assigned when the PR went through, whereas the Custom Controls at first had no default key (though they do now). Thus when you opened the game when the first custom controls PR went through the game saw, oh the default key is none, so I'm going to save that in the player file as the current binding (similar to as if the player themselves cleared that control binding and saved it). This, in difference to when the PR for the number keys went through and the game ran and saw, oh new controls, but they have a default value so I'm going to use that for the current binding.

In either case the game reads the controls table to find the value to use with key-pressed, so as long as their is a key binding in place it will translate properly and work. I'd be happy to elaborate more, I might not have explained it very well.

 

Offline wookieejedi

  • 29
  • Intensify Forward Firepower
Re: How to use the new extra, empty controls for modders
Just to note here that keys 5-9 and 0 will be removed in the next nightly (to maintain multi compatibility). I don't think anyone was using those but if you were be sure to remove them from you mod! Custom Control 1-5 are not going to be affected.

 

Offline mjn.mixael

  • Cutscene Master
  • 212
  • Chopped liver
    • Steam
    • Twitter
Re: How to use the new extra, empty controls for modders
Bump.. for I thought this issue was resolved? Might need another look.

https://www.hard-light.net/forums/index.php?topic=92701.msg1894312#msg1894312
Cutscene Upgrade Project - Mainhall Remakes - Between the Ashes
Youtube Channel - P3D Model Box
Between the Ashes is looking for committed testers, PM me for details.
Freespace Upgrade Project See what's happening.