Difference between revisions of "Key Mappings"

Revision as of 22:29, 2 August 2021

An input is required to produce some sort of action to the player within the game. These inputs can be boiled down to mappings associated with a certain key or mouse click. To allow these inputs to be remappable, a KeyMapping can be declared and registered.

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 KeyMapping#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.
+An input is required to produce some sort of action to the player within the game. These inputs can be boiled down to mappings associated with a certain key or mouse click. To allow these inputs to be remappable, a <code>KeyMapping</code> can be declared and registered.
-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>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.