In-game keyboard configuration

[phkb]

Anyone who has tried to edit the keyconfig.plist file will attest to the difficulty of getting the content right. It is a mostly workable solution to the need of allowing customisable keyboard layouts, but doing so with a text editor in hand, and only being able to check on whether everything worked by running the game and testing it (and then, if it doesn't work, closing the game and trying again) is a fairly painful process. There are also limits to content of the file, like not being able to utilise CTRL or ALT key combinations in the definition.

Oolite lacks a in-game keyboard configuration screen. We can configure our joysticks, but not our keyboards.

This thread is intended to work through the issues (and there are a few) surrounding the implementation of a full in-game keyboard configuration system. I don't know, at this point, when the results of this discussion will end up being implemented in the game itself, but there are some things we can work through in the interim so that we can get the best possible result for everyone.

The first area to discuss is where we store the keyboard configuration. At the moment, (almost) all keyboard configuration is stored and controlled with the keyconfig.plist file. I say almost, because there are some things that are actually hardcoded - things like Ctrl keys reversing MFD selection, or primable equipment selection. (The function keys might also be hardcoded - the number keys 1-8 and function keys 1-8 do the same thing, but keyconfig only references the number keys, so the function keys might be independant - I'll need to check).

When looking to put the keyboard configuration in the game itself, we are straight away faced with the problem of what to do with the keyconfig.plist file. Any change we make to the configuration cannot be written back to the keyconfig.plist file (because, well, reasons). Plist files are readonly. So, as I see it, the only place to store key configurations is to put it in the same spot joystick configurations are placed - in the "oolite.app\GNUstep\Defaults\.GNUstepDefaults" file.

But that then creates a potentially confusing scenario where any change to keyconfig.plist is overridden by changes loaded from the GNUStepDefaults file. If someone has downloaded a custom keyconfig file from the expansions manager, they might find that none of the promised configurations work, because they've all been negated by the local GNUstepDefaults file. How much of a problem this would be I guess is debatable (there is only one keyconfig file on the manager that I know of), and once we have an in-game method of changing things, it should be easy to point people to the solution.

Another downside of having the in-game config stored in the GNUstepDefaults file is that it makes it much harder to share custom setups with other players. Again, this might not be a huge problem, but it's worth noting.

Where this is leading to is: Should we do away with keyconfig.plist altogether? There are already limitations in the file format, it can be really confusing working out when you need a numeric keycode rather than a character, and if everything can be done in-game, is it of any use anymore? If we keep the file, how do we avoid confusing end-user scenarios?

That should start as an opener on this topic. I'd love to make in-game keyboard config the major component of the 1.92 release, as it would help solve a couple of other issues, so the more clarity we can add to this the better.

[hiran]

This thread is intended to work through the issues (and there are a few) surrounding the implementation of a full in-game keyboard configuration system. I don't know, at this point, when the results of this discussion will end up being implemented in the game itself, but there are some things we can work through in the interim so that we can get the best possible result for everyone.

This could ensure a player does not have to find 'impossible combinations'. One example you mentioned is shift-'\', which is impossible on german keyboards as the '\' is generated pressing AltGr-ß
Plus indeed it would make editing keyboard mapping straightforward.

The first area to discuss is where we store the keyboard configuration. At the moment, (almost) all keyboard configuration is stored and controlled with the keyconfig.plist file. I say almost, because there are some things that are actually hardcoded - things like Ctrl keys reversing MFD selection, or primable equipment selection. (The function keys might also be hardcoded - the number keys 1-8 and function keys 1-8 do the same thing, but keyconfig only references the number keys, so the function keys might be independant - I'll need to check).

When looking to put the keyboard configuration in the game itself, we are straight away faced with the problem of what to do with the keyconfig.plist file. Any change we make to the configuration cannot be written back to the keyconfig.plist file (because, well, reasons). Plist files are readonly. So, as I see it, the only place to store key configurations is to put it in the same spot joystick configurations are placed - in the "oolite.app\GNUstep\Defaults\.GNUstepDefaults" file.

That looks a bit strange for me. Why should plist files be readonly per se? But actually as a user I would not care where that data is stored.

But that then creates a potentially confusing scenario where any change to keyconfig.plist is overridden by changes loaded from the GNUStepDefaults file. If someone has downloaded a custom keyconfig file from the expansions manager, they might find that none of the promised configurations work, because they've all been negated by the local GNUstepDefaults file. How much of a problem this would be I guess is debatable (there is only one keyconfig file on the manager that I know of), and once we have an in-game method of changing things, it should be easy to point people to the solution.

Another downside of having the in-game config stored in the GNUstepDefaults file is that it makes it much harder to share custom setups with other players. Again, this might not be a huge problem, but it's worth noting.

Where this is leading to is: Should we do away with keyconfig.plist altogether? There are already limitations in the file format, it can be really confusing working out when you need a numeric keycode rather than a character, and if everything can be done in-game, is it of any use anymore? If we keep the file, how do we avoid confusing end-user scenarios?

That should start as an opener on this topic. I'd love to make in-game keyboard config the major component of the 1.92 release, as it would help solve a couple of other issues, so the more clarity we can add to this the better.

Removing hardcoded keys is for sure not an easy task but would add to a consistent keyboard handling.
I am also wondering why the function keys and the digits in the first row mimic their behaviour. If we are going to change it anyway, would it make sense to leave the function keys for add-on equipment and have much more priming options? The function keys are superbly suitable for that as with changing setups users could still place labels on the top of the keyboard...

Plus when it comes to OXP-keyboard-handling different OXPs may need a different amount of keys for activation. E.g. an OXP just providing new graphics will require none at all, while others with new ships or equipment will. It would be great if there were a mechanism fo OXPs to register for keyboard functionality that then could be shown in addition on the keyboard config page.

It may require yet another mapping layer from virtual keys to in-game keys, where one of then might be labelled "Fuel Generator Activation", another one "Fuel Generation Stop". For PlanetFall equipment there could be something like "Retract Landing gear" and "Deploy Landing Gear". You get the idea...

With such a mapping players might even choose which hardware button to press - be it on the joystick, the mouse or the keyboard. I do not know how other keyboards fit in: Do they behave like joysticks or keyboards or do they daisy-chain existing keyboards?

[phkb]

Why should plist files be readonly per se?

It's complicated, but largely comes down to security, I believe.

But actually as a user I would not care where that data is stored.

True, most users aren't going to care where the data is stored. But, I'm looking at the entire implementation here, from the ground up, so these sorts of things become important.

One example you mentioned is shift-'\', which is impossible on german keyboards as the '\' is generated pressing AltGr-ß

I had wondered about that one. So, pressing AltGr-ß gets you the "|" (pipe) symbol?

I am also wondering why the function keys and the digits in the first row mimic their behaviour.

Most likely for historical reasons, but I'm not sure. And I just did a test: if the keys 1-8 are changed, the function keys don't keep working as mimics - I changed "8" for the market screen to "+", and then F8 also didn't work.

Plus when it comes to OXP-keyboard-handling different OXPs may need a different amount of keys for activation.

There are a few implementation steps we need to cover off for the core game before we get to OXP's, which was why I didn't get to this in the first post. How we store the config, how we override keyconfig, are the first steps.

I mean, if we decide to keep keyconfig.plist, we need to also decide if we expand the format so that CTRL and ALT can be added to key choices. The format we apply to that will will then largely be fully transferable to the GNUstepDefaults file.

I know there are a lot of players out there who want to be able to activate all their special equipment with different keys, but we need to work out the basics first.

[phkb]

It would be great if there were a mechanism fo OXPs to register for keyboard functionality that then could be shown in addition on the keyboard config page.

The downsides of having an OXP decide what key it should use is the mess of conflicts that will likely occur, and the difficulty in just finding a consistent key across international keyboards. But again, this is for a later stage of the discussion, once we've nailed down the core game implementation.

[Cholmondely]

Unless of course we had a complete German package, say, with German GUIs, equipment lists, plänët nämes & gubbinen and a QWERTZ adaptation.

But I suppose that that might well come a cropper in the Windows/AppleMac/Linux vendettas.

But ... don't you think that Herr Gimlet looks a tad Germanic?

[hiran]

One example you mentioned is shift-'\', which is impossible on german keyboards as the '\' is generated pressing AltGr-ß

I had wondered about that one. So, pressing AltGr-ß gets you the "|" (pipe) symbol?

Not that easy.
From the picture of my keyboard in the other thread you can see the key to the right of 0 (zero) on the alphanumeric keypad?
Pressing that will give you the national special character which is also resembled by the HTML entity ß
Pressing the same key with shift will give you the question mark, and pressing the same key with altgr (the right alt key) will give you the backslash.

The pipe symbol however is on the key that is made possible by the reduced left shift key.
Pressing that key will give you a 'less than' or <
Pressing that with shift will give you a 'greater than' or >
Pressing that with altgr will give you the pipe symbol.

As you can see pipe and backslash are not even on the same key for a german keyboard.

Plus when it comes to OXP-keyboard-handling different OXPs may need a different amount of keys for activation.

There are a few implementation steps we need to cover off for the core game before we get to OXP's, which was why I didn't get to this in the first post. How we store the config, how we override keyconfig, are the first steps.

Makes sense. I probably wanted to point out requirements without going into implementation details.

[hiran]

It would be great if there were a mechanism fo OXPs to register for keyboard functionality that then could be shown in addition on the keyboard config page.

The downsides of having an OXP decide what key it should use is the mess of conflicts that will likely occur, and the difficulty in just finding a consistent key across international keyboards. But again, this is for a later stage of the discussion, once we've nailed down the core game implementation.

I do not think letting the OXP decide for the key would be a good pattern either.
But the OXP needs to register, or 'request' a key and the 'key manager component' can then assign one and allow the user to reassign it if need be.

[phkb]

Full disclosure: I'm not presenting fully formed ideas here. This is kind of more like brainstorming in public. So, I'm quite prepared to share an idea, and then backtrack on it. Hopefully, we'll end up with something fully formed at the end...

Anyway, to demonstrate this:

Should we do away with keyconfig.plist altogether?

After more thought on this, I can't see how we can eliminate the file completely. Even if it were to become an internal resource of the app, it still needs to exist in one form or another. The only question is whether we make it user editable. And if the keyboard controls were fully editable in the game, I don't see that as being a huge impediment. It would be the same as it is for joystick config now.

Looking at the content of keyconfig.plist, it's clear the format is limited. Each key function can have one value. For example:

Code: Select all

      key_prime_equipment = "N"; // ie shift+n

I'm thinking about a structure that looks more like this:

Code: Select all

      key_prime_equipment = {
      	   key = "n";
      	   shift = true;
      	   mod1 = false; // ie ctrl
      	   mod2 = false; // ie alt (pc/linux) or option (mac)
      };
      key_roll_left = {
           key_code = 253;
           shift = false;
           mod1 = false;
           mod2 = false;
      };

Given such a departure from the original definition, I'm wondering whether this should be called "keyconfig2.plist", and if present, will override any keyconfig.plist file. That would keep backward compatibility for older versions of Oolite (which would ignore the file), but provide a consistent way forward for newer versions.

The other issue to address is the key 1-8/F1-F8 duplication, which is not defined by the current keyconfig.plist file. One option is to allow duplicate entries, like this:

Code: Select all

      key_gui_screen_status = {
      	   key = "5";
      	   shift = false
      	   mod1 = false; // ie ctrl
      	   mod2 = false; // ie alt (pc/linux) or option (mac)
      };
      key_gui_screen_status = {
      	   key = "f5";
      	   shift = false
      	   mod1 = false; // ie ctrl
      	   mod2 = false; // ie alt (pc/linux) or option (mac)
      };

Although that could be confusing (are the duplicate definitions replacing or adding to existing ones), plus it might be harder to actually code. Alternatively, we could do some sort of internal referencing, something like this:

Code: Select all

      key_gui_screen_status = {
      	   key = "5";
      	   shift = false
      	   mod1 = false; // ie ctrl
      	   mod2 = false; // ie alt (pc/linux) or option (mac)
      	   alt_key = "special_key_1";
      };
      special_key_1 = {
      	   key = "f5";
      	   shift = false
      	   mod1 = false; // ie ctrl
      	   mod2 = false; // ie alt (pc/linux) or option (mac)
      };      

[phkb]

I should also add: I think in terms of development, getting a fully-defined configuration file that covers every key combination and possibility is the first step in getting the in-game configuration to work. That will mean, once the definition is nailed down, going through the core code and adding everything that is currently hard-coded into the definition.

[hiran]

The other issue to address is the key 1-8/F1-F8 duplication, which is not defined by the current keyconfig.plist file. One option is to allow duplicate entries, like this:

Code: Select all

      key_gui_screen_status = {
      	   key = "5";
      	   shift = false
      	   mod1 = false; // ie ctrl
      	   mod2 = false; // ie alt (pc/linux) or option (mac)
      };
      key_gui_screen_status = {
      	   key = "f5";
      	   shift = false
      	   mod1 = false; // ie ctrl
      	   mod2 = false; // ie alt (pc/linux) or option (mac)
      };

Although that could be confusing (are the duplicate definitions replacing or adding to existing ones), plus it might be harder to actually code.

You might change the data format slightly (if it is edited rarely or not by users manually that would be perfectly ok.

Code: Select all

      key_gui_screen_status = [
          {
          	   key = "5";
          	   shift = false
          	   mod1 = false; // ie ctrl
          	   mod2 = false; // ie alt (pc/linux) or option (mac)
          },
          {
          	   key = "f5";
          	   shift = false
          	   mod1 = false; // ie ctrl
          	   mod2 = false; // ie alt (pc/linux) or option (mac)
          }
      };

This should make it pretty clear that the two key bindings are parallel since they resemble a list. (Not sure whether the syntax is correct - I am getting confused between JSON and PList - they are too close)

And I am not questioning why one would want to have several keys for one function, just suggesting how that feature could be implemented. Noone has to use it, but someone may use it if need be.

[phkb]

This should make it pretty clear that the two key bindings are parallel since they resemble a list.

Hmm. I was trying to keep the defintion of the key binding to one type. Your suggestion is very nice architecturally, but it would change the definition of the key binding from a dictionary to an array, which isn't impossible to code, but does make life a little trickier for us poor programmers!

[hiran]

This should make it pretty clear that the two key bindings are parallel since they resemble a list.

Hmm. I was trying to keep the defintion of the key binding to one type. Your suggestion is very nice architecturally, but it would change the definition of the key binding from a dictionary to an array, which isn't impossible to code, but does make life a little trickier for us poor programmers!

Well, as mentioned above I did not want to defend the use of duplicate key bindings.
If you think it makes programming difficult, just throw out duplicates and go without the list.

[phkb]

I did not want to defend the use of duplicate key bindings.

Neither do I! It’s not a case of one right and wrong answer. I’m just trying to nut out a spec that covers all the possibilities, keeping in mind some of the programming challenges the new spec might throw up.

If you think it makes programming difficult, just throw out duplicates and go without the list.

That would be nice, but at this stage I’m hoping to be able to reproduce exactly what exists right now. There may come a time during the coding phase where that goal needs to be reassessed, but for now, at least, we can plan as if there are no issues to overcome.

And your suggestion is good, don’t get me wrong! It’s quite elegant - I just went immediately to “coding mode” and saw a potential pitfall. But as I said, not an insurmountable one.

[hiran]

If you think it makes programming difficult, just throw out duplicates and go without the list.

That would be nice, but at this stage I’m hoping to be able to reproduce exactly what exists right now. There may come a time during the coding phase where that goal needs to be reassessed, but for now, at least, we can plan as if there are no issues to overcome.

And your suggestion is good, don’t get me wrong! It’s quite elegant - I just went immediately to “coding mode” and saw a potential pitfall. But as I said, not an insurmountable one.

I think we are on the same page, and I agree it's sometimes hard to separate specification from implementation.

And although I am not an Objective C guy, I might help with some algorithms...

[phkb]

I am not an Objective C guy

Neither am I! I mostly code in C#, JS and HTML/ASP. So, to be completely open, I have no idea if I'll be able to get half of what I'm proposing implemented. But hopefully, I can do enough that others can jump in and fill in whatever I can't manage myself.