Keymapping Improvements

This page is meant to track the design of the new keymapping (or rather, "input mapping" code). Right now, it only contains a copy of my original mail on the subject. This should be rewritten and updated with input from other people. Also the plan needs to be developed, e.g. a detailed proposal for the new API should be added.

Max' Email "RFC: Flexible keymapping via new EVENT_ (post 0.10)", June 4 2007

Recently a new event was added: EVENT_PREDICTIVE_DIALOG; Kostas already informed us via an explanatory email about its purpose. Short version of the story, this event can be used to tell the frontend (i.e. the game engine) to show a special dialog, if desired/required.

However, I think this event is rather to special and to narrow in scope. So I was thinking about this, and I came up with the following idea, and I hope I'll get some helpful comments from you guys.

In short, I'd propose to replace EVENT_PREDICTIVE_DIALOG with a new more generic event, by letting a frontend specify an arbitrary list of actions which the backend should map to a button or hotkey. This list would contain structs similar to this:

  struct UserAction {
    UserActionType type;  // an enum type, see below
    String description; // Human readable description, for a GUI keymapping config dialog
    KeyDesc  defaultKey;  // an (optional) default key combo to be assigned to this; includes modifier state
    // ... your idea goes here
  };

The UserActionType might look like this:

  enum UserActionType {
    kQuitUserAction,  // *maybe* could replace EVENT_QUIT
    kPredictiveDialogUserAction,
    kOptionsDialogUserAction,
    kSaveLoadDialogUserAction,
    kPauseUserAction,
    ...
    kGenericUserAction
  };

The backend then would use this information to map triggers to actions; either by using the provided defaultKeys; or by using custom hard mappings (based on the UserType, or on the currently running game/engine); or by letting the user configure this via a trigger/ hotkey mapping dialog (that's what the "description" field is for); etc.

Then, whenever such a trigger occurs, instead of sending a regular keyboard event, the backend generates the appropriate useraction event (might be named EVENT_USERACTION). The goal here is to replace EVENT_PREDICTIVE_DIALOG (and maybe EVENT_QUIT) with a more generic and powerful setup. Oh, also hacks like "KEY_ALL_SKIP" could be subsumed under this. And hopefully many other similar hacks, which currently backends with few keys have to use to map their few input triggers in a sensible way to the various actions our many engines provide.

How to implement this, w/o too much effort? Well, the mapping code would go into the EventManager. The default event manager would simply use the specified defaultKey verbatim. Backend which want enhanced mapping capabilities (e.g. to map PDA buttons to actions) would have to use a custom event manager, but that shouldn't be a major problem.

Over time, we could adapt our engines to register their standard hotkeys/actions via the new API. E.g. in the SCUMM engine, at least F5 (save/load) and space (pause) come immediately to mind, but many more certainly would be desirable.

My hope is that by breaking this down into sensible small pieces, it should be possible to implement this gradually and w/o too much effort, w/o requiring backend authors to add extra code, unless they want to; and finally, with minimal impact on engines (maybe the handling of EVENT_QUIT has to be changed, but that'd be a no- brainer). The gain would initial not be too big. Over time we'd convert more and more engines to use it. My hope is that on the long run it will allow us to get rid of many engine-specific hacks in backends, will make user friendly key mapping dialog(s) possible, and simply make it easier for us to add certain new features.