Difference between revisions of "Key Mappings"

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.

@@ Line 1: / Line 1: @@
-An input is required to produce some sort of action to the player within the game. These inputs can be boiled down to bindings associated with a certain key or mouse click. To allow these inputs to be remappable, a <code>KeyBinding</code> can be declared and registered.
+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 [[:mc:Options#Controls|Controls menu]]. In the code, these key mappings are declared and represented by <code>KeyMapping</code> instances
-A <code>KeyBinding</code> can be declared with the following parameters:
+A <code>KeyMapping</code> can be declared with the following parameters:
 {| class="wikitable"
 ! Parameter !! Description
 |-
-| description || A translation key used to describe what this binding will do (e.g. <code>key.modid.keyName</code>).
+| name || A translation key used to set the name of this key mapping (e.g. <code>key.modid.key_name</code>).
 |-
-| keyConflictContext || Determines when the key binding should conflict with another defined key binding. By default, there are three values within <code>KeyConflictContext</code>: <code>UNIVERSAL</code> which are used in every context, <code>GUI</code> which are used whenever a screen is open, and <code>IN_GAME</code> whenever a screen is not open. Custom contexts can be created by implementing <code>IKeyConflictContext</code>.
+| keyConflictContext || Determines when the key mapping should conflict with another defined key mapping. By default, there are three values within <code>KeyConflictContext</code>: <code>UNIVERSAL</code> which are used in every context, <code>GUI</code> which are used whenever a screen is open, and <code>IN_GAME</code> whenever a screen is not open. Custom contexts can be created by implementing <code>IKeyConflictContext</code>.
 |-
-| inputType || Determines the type of input this binding will declare by default. There are three possible values: <code>KEYSYM</code> which represents a mapped key, <code>SCANCODE</code> which represents the value emitted by the keyboard itself, and <code>MOUSE</code> which represents a mouse click.
+| 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: <code>KEYSYM</code> which represents a mapped key, <code>SCANCODE</code> which represents the value emitted by the keyboard itself, and <code>MOUSE</code> which represents a mouse click. The associated input codes and modifiers are based on the specified input type as mapped by <code>GLFW</code>.
 |-
-| keyCode || The associated key codes based on the specified input type as mapped by <code>GLFW</code>.
+| category || A translation key representing the category this key is located in (e.g. <code>key.modid.categories.category_name</code>).
-|-
-| category || A translation key representing the category this key is located in (e.g. <code>key.modid.categories.categoryName</code>).
 |}
-{{Tip|If you would like there to be no binding by default, use a constructor that contains <code>InputMappings$Input</code> instead and supply <code>InputMappings#INPUT_INVALID</code> as the argument.}}
+{{Tip|If you would like there to be no mapping by default, use a constructor that contains <code>InputConstants$Key</code> instead and supply <code>InputConstants#UNKNOWN</code> as the argument.}}
-The <code>KeyBinding</code> can then be registered using <code>ClientRegistry::registerKeyBinding</code> within <code>FMLClientSetupEvent</code>.
+The <code>KeyMapping</code> can then be registered using <code>ClientRegistry::registerKeyBinding</code> within <code>FMLClientSetupEvent</code>.
-== Using Registered Bindings ==
+== Using Registered Mappings ==
-There are two contexts in which a key binding can be used normally: in or not in a screen. As such, there are two ways to handle these bindings. When not in a screen, <code>ClientTickEvent</code> should be used to determine whether the key is down using <code>KeyBinding#isKeyDown</code>. If within a screen, the following logic can be applied using <code>KeyBinding#isActiveAndMatches</code> within <code>IGuiEventListener#keyPressed</code> and <code>IGuiEventListener#mouseClicked</code> for mouse input. Note that the necessary <code>InputMappings$Input</code> can be constructed using <code>InputMappings::getInputByCode</code> or <code>MOUSE::getOrMakeInput</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.