Difference between revisions of "Key Mappings"

From Forge Community Wiki
(reword lead section)
(Update to 1.19)
 
Line 19: Line 19:
 
== Using Registered Mappings ==
 
== Using Registered Mappings ==
  
There are two contexts in which a key mapping can be used normally: in or not in a screen. As such, there are two ways to handle these mappings. When not in a screen, <code>ClientTickEvent</code> should be used to determine whether the key is down using <code>KeyMapping#isDown</code>. If within a screen, the following logic can be applied using <code>KeyMapping#isActiveAndMatches</code> within <code>GuiEventListener#keyPressed</code> and <code>GuiEventListener#mouseClicked</code> for mouse input. Note that the necessary <code>InputConstants$Key</code> can be constructed using <code>InputConstants::getKey</code> or <code>InputConstants$Type::getOrCreate</code> respectively.
+
There are two contexts in which a key mapping can be used normally: in or not in a screen. As such, there are two ways to handle these mappings. When not in a screen, <code>ClientTickEvent</code> should be used to determine whether the key is down using <code>KeyMapping#isDown</code>. If within a screen, the following logic can be applied using <code>IForgeKeyMapping#isActiveAndMatches</code> within <code>GuiEventListener#keyPressed</code> and <code>GuiEventListener#mouseClicked</code> for mouse input. Note that the necessary <code>InputConstants$Key</code> can be constructed using <code>InputConstants::getKey</code> or <code>InputConstants$Type::getOrCreate</code> respectively.

Latest revision as of 15:03, 18 June 2022

A key mapping or keybinding is the relation of an action to an input, such as a mouse click or a combination of key presses. The action for the keymapping is defined in the code, while the triggering input is configurable by the user through the Controls menu. In the code, these key mappings are declared and represented by KeyMapping instances

A KeyMapping can be declared with the following parameters:

Parameter Description
name A translation key used to set the name of this key mapping (e.g. key.modid.key_name).
keyConflictContext Determines when the key mapping should conflict with another defined key mapping. By default, there are three values within KeyConflictContext: UNIVERSAL which are used in every context, GUI which are used whenever a screen is open, and IN_GAME whenever a screen is not open. Custom contexts can be created by implementing IKeyConflictContext.
key Determines the input context this mapping will declare by default. This is a combination of the input type, input code, and any additional modifiers. There are three possible values for the input type: KEYSYM which represents a mapped key, SCANCODE which represents the value emitted by the keyboard itself, and MOUSE which represents a mouse click. The associated input codes and modifiers are based on the specified input type as mapped by GLFW.
category A translation key representing the category this key is located in (e.g. key.modid.categories.category_name).
If you would like there to be no mapping by default, use a constructor that contains InputConstants$Key instead and supply InputConstants#UNKNOWN as the argument.

The KeyMapping can then be registered using ClientRegistry::registerKeyBinding within FMLClientSetupEvent.

Using Registered Mappings

There are two contexts in which a key mapping can be used normally: in or not in a screen. As such, there are two ways to handle these mappings. When not in a screen, ClientTickEvent should be used to determine whether the key is down using KeyMapping#isDown. If within a screen, the following logic can be applied using IForgeKeyMapping#isActiveAndMatches within GuiEventListener#keyPressed and GuiEventListener#mouseClicked for mouse input. Note that the necessary InputConstants$Key can be constructed using InputConstants::getKey or InputConstants$Type::getOrCreate respectively.