372
edits
Changes
From Forge Community Wiki
Copy Key Mappings to MC1.17 archive
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/1.17|Controls menu]]. In the code, these key mappings are declared and represented by <code>KeyMapping</code> instances
A <code>KeyMapping</code> can be declared with the following parameters:
{| class="wikitable"
! Parameter !! Description
|-
| 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 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>.
|-
| 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>.
|-
| category || A translation key representing the category this key is located in (e.g. <code>key.modid.categories.category_name</code>).
|}
{{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>KeyMapping</code> can then be registered using <code>ClientRegistry::registerKeyBinding</code> within <code>FMLClientSetupEvent</code>.
== 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.
A <code>KeyMapping</code> can be declared with the following parameters:
{| class="wikitable"
! Parameter !! Description
|-
| 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 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>.
|-
| 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>.
|-
| category || A translation key representing the category this key is located in (e.g. <code>key.modid.categories.category_name</code>).
|}
{{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>KeyMapping</code> can then be registered using <code>ClientRegistry::registerKeyBinding</code> within <code>FMLClientSetupEvent</code>.
== 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.