Tutorial: Axis group binding in KSP 1.7.1, a brief modder's how-to

[Snark]

So, KSP 1.7.1 just released, with a new feature in it, axis groups.  This is a really cool feature for the player, which allows binding control axes (pitch, yaw, roll, wheel steer, etc.) to scalar inputs for controls.

It was added to help support robotic parts from Breaking Ground, but the feature itself is in stock 1.7.1 and is really cool to use.  But for a player to be able to take advantage of it in a mod... the mod needs to be equipped to support it.

I've already equipped a couple of my mods with this, and the good news, it's super easy to retro-fit axis group support into an existing mod.  Just takes a few lines of code, and opens up all kinds of options for players.  So I thought folks might enjoy a brief tutorial on how to do it.

I'll be using my AttitudeAdjuster mod as an example of a good use case for this feature, and walk you through how I added it.

 

Background:  The playability issue that axis groups solve

The basic premise of the AttitudeAdjuster mod is that it adds a slider in the PAW for certain command-pod parts (e.g. cockpits), which you can use to set a nose-up attitude for your craft (useful for spaceplane-style reentry).  Slide the PAW slider, and it adjusts the angle of your craft.

Works great.  So... why do we need this axis-group feature?

Well, let's say a player is going through spaceplane-style nose-up reentry, and wants to adjust the pitch angle.  Until KSP 1.7.1, the only way to do that would be for the player to open the PAW and slide the slider around.

Works just fine... but is kinda immersion-breaking while playing.  Wouldn't it be nice if the player could just use control input bindings to adjust things, without having to pop the PAW open and fiddle with UI?

Well, that's what axis groups are for.  Here's what it looks like for the player, once the mod is enabled to support axis groups:

See that "Pitch Angle" in the action groups UI?  That's the same "Pitch Angle" that's coming from the KSPField in the PAW, i.e. the one that powers the slider.  By enabling my mod for axis groups, it means that when I open the UI and click on one of the axis groups (e.g. "Translate U/D" in the above example)... my "Pitch Angle" shows up as an option.  If I hadn't equipped my mod for axis groups, it wouldn't show up there.

But since I have so equipped it... there it is.  The player can use just a couple of mouse clicks to assign "Pitch Angle" to the control axis of their choice ("translate up/down" in the above example, i.e. the I and K keys by default).

Once that's done... presto!  When the player's in flight, they can press the I and J keys to pivot the pitch angle up and down.

So... what do I need to do to the code to make this happen?

 

How to code it

It's really simple. 

All you do is replace the KSPField annotation on your UI_FloatRange with a KSPAxisField annotation instead, and supply appropriate parameters thereto.  The main parameters you need to supply are, 1. should it default to "incremental" or "absolute" mode, 2. what are the min/max range values, and 3. how fast should it change the value when the player holds down the key.

Here's my github commit where I added the axis group support.  Note that before the change, I had a KSPField and an UI_FloatRange.

Well, the UI_FloatRange I just left alone (other than some code reformatting for readability).  The real change is that I replaced the KSPField with a KSPAxisField.

Before the change:

[KSPField(
    guiName = "#AttitudeAdjuster_pitchAngle",
    guiActive = false,
    guiActiveEditor = false,
    isPersistant = true,
    guiFormat = "F1"),

After the change:

[KSPAxisField(
    guiName = "#AttitudeAdjuster_pitchAngle",
    guiActive = false,
    guiActiveEditor = false,
    isPersistant = true,
    guiFormat = "F1",
    axisMode = KSPAxisMode.Incremental,
    minValue = DEFAULT_MIN_PITCH,
    maxValue = DEFAULT_MAX_PITCH,
    incrementalSpeed = DEFAULT_AXIS_SPEED),

As you see... it's almost identical, other than swapping KSPField for KSPAxisField.

I did need to supply a few extra parameters.  Here's what they are:

• axisMode:  This is a KSPAxisMode enum value with choices of Incremental or Absolute.
  • Note that the choice here merely sets the default for this binding.  Whichever you pick, the player can always switch it to the other one via a little checkbox in the action groups UI in-game.
  • Incremental:  This is good for axes that are typically controlled by a pair of up-down keys, like wheel steering.  When no key is pressed, the controlled slider will stay stationary.  When a key is held down, the slider will move up or down at constant speed.
  • Absolute:  This is good for binary on/off type behavior, or for control axes that have an analog input such as a joystick.  When no input is received, the slider is held in the middle.  If you press the "up" or "down" key, the slider jumps instantly to the max or min value, and stays there as long as you're holding the key down; when you release, it snaps back to center again.  If you use this mode with an analog input, it means that the value of the slider will always exactly match the input.
• minValue, maxValue:  Describes the numeric range over which the axis group can modify the value.  If you don't specify these, it defaults to 0 and 1.  Normally you'll want to set these to the same min/max values as your UI_FloatRange so that the axis group can control it over the entire range of the slider.
• incrementalSpeed:  This is in "units per second".  Only relevant for when an axis group is bound in "incremental" mode.  This describes how rapidly the value changes when the player is holding down the corresponding key.  For example, if the float range of the control is in the range 0 to 90, and you set incrementalSpeed = 10, that means "10 per second", meaning that if you start at 0, it would take nine seconds of holding down the key to reach the maximum.
• There are some other parameters available, too, but I didn't mess with those and the defaults appear to work fine.

 

Another example:  IndicatorLights

I also tweaked my IndicatorLights mod so that the BL-01 light (a small surface-mountable LED light) has axis bindings, too.  Result?  The part is now usable as a functioning turn signal for rovers. 

...built that just by using the action groups UI in-game to bind the lights to the "Wheel Steer" axis.

Here's the commit where I added the code.  It's a little less "clean" than the above example, because I did a bunch of other stuff in the commit, too, but this gives another example of using the feature.

 

...And that's basically it.  That's all there is.  It's literally just a few lines of code, practically a drop-in replacement.  It's a fantastic feature for users, and if anyone has a mod that involves PAW sliders that serve a craft control purpose, I'd strongly recommend enabling this feature.

[Dafni]

Thank you!

[VoidSquid]

On 5/30/2019 at 10:05 PM, Snark said:

Well, let's say a player is going through spaceplane-style nose-up reentry, and wants to adjust the pitch angle.  Until KSP 1.7.1, the only way to do that would be for the player to open the PAW and slide the slider around.

Stupid question: "before" I just used W and S key to adjust pitch, and ALT+W / ALT+S to trim pitch - where is the big plus here?
And I never saw such a slider in the PAW. 

Yes, I now can configure actions to axis, like "extend solar panel when using the W-key", might become pretty handy (save for this silly example), but else?

[Snark]

8 minutes ago, VoidSquid said:

Stupid question: "before" I just used W and S key to adjust pitch

And you still do.  This is not about that.  It's about something else.

8 minutes ago, VoidSquid said:

And I never saw such a slider in the PAW.

Probably because you're not running my mod that adds it.

Bear in mind that this is not a tutorial for players, even vaguely.  It's a tutorial for  modders, to explain to them how to update their mods so that players can use axis groups to control them.  Unless you're a modder writing code, there is zero point in your reading this thread; you're not the target audience. 

8 minutes ago, VoidSquid said:

where is the big plus here?

That's a good question, but this thread isn't the right place for it.  Better to ask in my mod's thread, since it's a question about a particular mod feature and not about "how do I update my mod's code to work with axis groups".

8 minutes ago, VoidSquid said:

Yes, I now can configure actions to axis, like "extend solar panel when using the W-key", might become pretty handy (save for this silly example), but else?

Again:  good question, but completely in the wrong place.  Better to ask in Gameplay Questions or something, since it's about playing the game rather than writing code for mods. 

[VoidSquid]

5 minutes ago, Snark said:

you're not the target audience

OK, never mind then, didn't mean to bother anyone
Just been looking for "enlightenment" about this new feature and came along this thread.

[Snark]

16 minutes ago, VoidSquid said:

Just been looking for "enlightenment" about this new feature and came along this thread.

Yeah, Breaking Ground is just crying out for good player tutorials.  This just happens not to be that.  It's a modder tutorial.

The goal here is not "show players how to use the new feature", but rather "make it really easy for modders to update all their mods so that players can use the new feature with them".

[Climberfx]

Thank you for sharing Snark!

Edited May 11, 2020 by Climberfx