TrustedUser
2,147
edits
Difference between revisions of "Keymapper"
Jump to navigation
Jump to search
→For engine developers: Mention game controller mapping requirements
(Created page with "=== Keymapper considerations === == Basics == * Backends define what input devices are available and with which characteristics (number of buttons, button names..). * Engines...") |
(→For engine developers: Mention game controller mapping requirements) |
||
| (8 intermediate revisions by 2 users not shown) | |||
| Line 15: | Line 15: | ||
: Example when reusing the existing input handling: | |||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
| Line 42: | Line 42: | ||
while (_system->getEventManager()->pollEvent(event)) { | while (_system->getEventManager()->pollEvent(event)) { | ||
switch (event.type) { | switch (event.type) { | ||
case Common::EVENT_KEYDOWN: | |||
switch (event.kbd.keycode) { | |||
case Common::KEYCODE_t: | |||
doTalk(); | |||
break; | |||
case Common::KEYCODE_u: | |||
doUse(); | |||
break; | |||
} | |||
} | } | ||
} | } | ||
| Line 57: | Line 57: | ||
: Example when using custom engine actions: | |||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
| Line 89: | Line 89: | ||
while (_system->getEventManager()->pollEvent(event)) { | while (_system->getEventManager()->pollEvent(event)) { | ||
switch (event.type) { | switch (event.type) { | ||
case Common::EVENT_CUSTOM_ENGINE_ACTION_START: | |||
switch ((MyEngineAction)event.customType) { | |||
case kMyActionTalk: | |||
doTalk(); | |||
break; | |||
case kMyActionUse: | |||
doUse(); | |||
break; | |||
} | |||
} | } | ||
} | } | ||
| Line 103: | Line 103: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
: Engines with engine-driven input handing should prefer using custom action events as this approach it is more powerful. Engines where input handling is script-driven probably have no choice but to use the first option. It's up to the engine developer to choose which is the best in each specific context. | |||
* Keymaps can be situational, thus engines may define multiple keymaps. Keymaps can be enabled / disabled at any time to select which actions are relevant for the current situation. For example for a RPG game there may be one keymap for the overworld, one for combat and one for shops. | * Keymaps can be situational, thus engines may define multiple keymaps. Keymaps can be enabled / disabled at any time to select which actions are relevant for the current situation. For example for a RPG game there may be one keymap for the overworld, one for combat and one for shops. | ||
* Text input needs special care in conjunction with the keymapper. Given that keys can be remapped, players may want to remap, for example, the arrow keys to WSAD. But then when text input is required, it is no longer possible to type those letters because they map to the arrow keys. The solution to this issue is to disable the keymap that handles key shortcuts while a text input widget is focused. | * Text input needs special care in conjunction with the keymapper. Given that keys can be remapped, players may want to remap, for example, the arrow keys to WSAD. But then when text input is required, it is no longer possible to type those letters because they map to the arrow keys. The solution to this issue is to disable the keymap that handles key shortcuts while a text input widget is focused. | ||
* Keep in mind that some ports may not have a keyboard and mouse. The default input mapping should include mapping for game controllers. | |||
== For backend developers == | == For backend developers == | ||
| Line 112: | Line 113: | ||
* Backends can define (or replace) default bindings for any keymap. To do so, implement '''OSystem::getKeymapperDefaultBindings'''. This can be used to make room in the default keymaps for backend specific actions, or to provide better defaults for the platform than those defined in the keymap. | * Backends can define (or replace) default bindings for any keymap. To do so, implement '''OSystem::getKeymapperDefaultBindings'''. This can be used to make room in the default keymaps for backend specific actions, or to provide better defaults for the platform than those defined in the keymap. | ||
* Backends can use keymaps as well to allow players to remap the backend specific features. To do so, implement '''OSystem::getGlobalKeymaps'''. When implementing backend specific keymaps, it's best to request ''EVENT_CUSTOM_BACKEND_ACTION_{START,END}'' events in response to the user input. During event handling, ''Event::customType'' is used to recognize the action that needs to be executed. | * Backends can use keymaps as well to allow players to remap the backend specific features. To do so, implement '''OSystem::getGlobalKeymaps'''. When implementing backend specific keymaps, it's best to request ''EVENT_CUSTOM_BACKEND_ACTION_{START,END}'' events in response to the user input. During event handling, ''Event::customType'' is used to recognize the action that needs to be executed. | ||
== TODO == | |||
* Consider adding support for joystick button combos | |||
* Rework the way keyboard input is mapped to actions. Match only on the keycode and then filter on the modifiers to handle partial matches. Besides keep a list of currently started actions. When receiving a key up event, check if an end event needs to be emitted for one of the started actions ignoring the modifiers (to handle the case where the user stops pressing the modifier keys first). Additionally filter the emitted actions based on the list of currently started actions to prevent an action from being started twice at the same time by two different inputs. | |||