[Scummvm-devel] RFC: Flexible keymapping via new EVENT_ (post 0.10)

[Max Horn]

Hi folks,

it would be nice to get some progress on this. Especially from the  
porters -- hey, folks, this is for *you* guys, please at least  
provide input! For me, everything is already fine, my Mac doesn't  
need anything complicated like keymapping. It's the Nintendo DS, PSP,  
PlayStation 2, Dreamcast, WinCE and Palm users (and more) who needs  
this. And *you* guys are the experts, not me. So I can design a lot,  
but if in the end it's of no use to you and doesn't solve your  
problems, I don't have to start on it!

So, for now I started a wiki page for this. Right now it only  
contains my original mail, as a reference:
  <http://wiki.scummvm.org/index.php/Keymapping_improvements>

This should of course be changed. A more concrete plan should be  
outlined. Maybe a section explaining the requirements of the various  
ports? Also remarks from other people, in reply to my original mail,  
are of course not reflected. To anybody who's interested in this,  
feel free to edit the page.

Some additional thoughts:

* As an alternative to a new event type (which would require all  
engines to be modified), we could also just let the backend generate  
appropriate keyboard events. Is there really a reason for a separate  
event?

* For SCUMM, it would be useful to extend the KEY_ALL_SKIP hack so  
that all ports can use it (look at engines/scumm/input.cpp to see  
what I mean).

* Should we really restrict this to keyboard events? Mouse clicks,  
esp. in games where left/right/both clicks have separate meanings.  
So, engines should likely be able to notify the backend about these,  
too. Unless all backends always map both mouse buttons anyway, then  
we don't necessarily need this

* "Input triggers" used in engines usually fall into two categories:  
"important" keys, which the user *must* have access to (like e.g.  
access to the save/load dialog). Then there are other less important  
triggers: e.g. in SCUMM you can use letters to select verbs, but  
since you can also select them using a mouse click, it's not terrible  
if you miss them. So, we should mark the events with a "priority"  
level, I guess.

* The "UserActionType" in my original proposal could also be abused  
to indicate a certain "priority"; but the actual idea behind this is  
to help backends to generate *consistent* mappings. That is, you want  
to map the "save/load" key in all games to the same trigger, if  
possible. Rather than, e.g. mapping the input triggers in the order  
they are passed to the backend.

* For some games, it might not always be possible to "know" all  
useful inputs, because they are script controlled. However, I believe  
that at least the "vital" mappings can always be set by the engine.  
Correct me if I am wrong.

* In Indy3/Indy4, the keyboard fighting relies on a certain layout of  
the keys (think "number pad"). The Dreamcast handles this rather  
nicely, BTW (I think): If you use the directional pad while pressing  
a certain other button, it just generates the corresponding keypad  
events, suitable to control the fighting of Indy). Anyway, I think  
handling the keyboard fighting in Indy3/4 will always require some  
dedicated code on some engines, because they simply don't have enough  
buttons. Note quite sure what to do about this, but I think it  
deserves its own section on the Wiki page.


Combining some of this, a refined UserAction might be this:

   struct UserAction {
     UserActionType type;  // an enum type, see below
     String description; // Human readable description, for a GUI  
keymapping config dialog
     Common::KeyState  defaultKey;  // the default key for this action
     uint32 flags;    // for future extensions
     int priority;     // priority level. Alternative: bool  
isVitalAction; or use a kVitalActionFlag ?

   };

Then, there is a new OSystem API:

   OSystem::registerActions(List<UserAction> actions);
and also
   OSystem::unregisterActions();  // Resets all user actions

(The latter might be removed in favor of a more general   
OSystem::gameStarted(EngineID, GameID) / gameEnded()  set of APIs,  
see also #1595026).

The backend would take this list. It could then simply ignore the  
list, if all the inputs can be generated anyway; or provide some  
automatic remapping (based on some fixed tables); and/or provide a  
mapping dialog. It would be nice to have such a mapping dialog even  
in the SDL backend, so that all users can remap their keys (this  
would also resolve the Mac AZERTY bug #1643848
). A well written (flexible, portable, light-weight) key remapping  
dialog could be reused by many ports, so it would be a boon anyway.



Cheers,
Max