Key Mappings 26.2

Creating key mappings and reacting to them.

Minecraft handles user input from peripherals such as the keyboard and mouse using key mappings. Many of these key mappings can be configured through the settings menu.

With help of Fabric API, you can create your own custom key mappings and react to them in your mod.

Key mappings only exist on the client side. This means that registration and reacting to key mappings should be done on the client side. You can use the client initializer for this.

Creating a Key Mapping

A key mapping consists of two parts: the mapping to a key, and the category it belongs to.

Let's start with creating a category. A category defines a group of key mappings that will be shown together in the settings menu.

KeyMapping.Category CATEGORY = KeyMapping.Category.register(
		ExampleMod.id("custom_category")
);

Next, we can create a key mapping. We will be using Fabric API's KeyMappingHelper to register our key mapping at the same time.

KeyMapping sendToChatKey = KeyMappingHelper.registerKeyMapping(
	new KeyMapping(
			"key.example-mod.send_to_chat", // The translation key for the key mapping.
			InputConstants.Type.KEYSYM, // The type of the keybinding; KEYSYM for keyboard, MOUSE for mouse.
			InputConstants.KEY_J, // The keycode of the key.
			this.CATEGORY // The category of the mapping.
	));

INFO

Note that the names of the key tokens (InputConstants.KEY_*) assume a standard US layout.

This means that if you're using an AZERTY layout, pressing on A would yield InputConstants.KEY_Q.

Sticky keys can also be created with KeyMappingHelper by passing a ToggleKeyMapping instance instead of a KeyMapping.

Once registered, you can find your key mappings in Options > Controls > Key Binds.

Translations

You'll need to provide translations for both the key mapping and the category.

Category name translation key takes the form of key.category.<namespace>.<path>. The key mapping translation key will be the one you provided when creating the key mapping.

Translations can be added manually or using data generation.

{
  "key.category.example-mod.custom_category": "Example Mod Custom Category",
  "key.example-mod.send_to_chat": "Send to Chat"
}

Reacting to Key Mappings In-World

Now that we have a key mapping, if we want to react to it when gameplay is active, we can use a client tick event:

ClientTickEvents.END_CLIENT_TICK.register(client -> {
	while (this.sendToChatKey.consumeClick()) {
		if (client.player == null) return;

		client.player.sendSystemMessage(Component.literal("Key press detected in the world"));
	}
});

This will print "Key press detected in the world" to the in-game chat every time the mapped key is pressed. Keep in mind that holding the key will repeatedly print the message to the chat, so you might want to implement guards if this logic only needs to trigger once.

Reacting to Key Mappings In-GUI

We can also react to key mappings inside of screens, both when a world is open, and when it's not.

ScreenEvents.BEFORE_INIT.register((client, screen, scaledWidth, scaledHeight) -> {
	if (!(screen instanceof CreativeModeInventoryScreen) && !(screen instanceof TitleScreen)) {
		return;
	}

	ScreenKeyboardEvents.beforeKeyPress(screen).register((s, keyEvent) -> {
		if (!this.sendToChatKey.matches(keyEvent)) return;

		this.handleKeyPressInMainScreen(client);
		this.handleKeyPressInGameScreen(client);
	});
});

And add the two handlers:

private void handleKeyPressInMainScreen(Minecraft client) {
	if (client.player != null) return;

	ExampleMod.LOGGER.info("Key press detected in the title screen");
}

private void handleKeyPressInGameScreen(Minecraft client) {
	if (client.player == null) return;

	client.player.sendSystemMessage(Component.literal("Key press detected in the GUI with a world open, closing screen"));
	client.gui.setScreen(null);
}

This checks if the current screen is the TitleScreen or CreativeModeInventoryScreen. If it is, we implement two distinct behaviors based on whether we are inside or outside a world:

• When outside a world, in other words when no player entity exists, it logs "Key press detected in the title screen" to console.
• Otherwise, if pressed inside a world, it sends "Key press detected in the GUI with a world open, closing screen" to the in-game chat and closes the screen.

INFO

The second "Key press detected in the world" message is sent to the chat because of the previously registered clientTickEvents event listener.

TIP

screen will be an instance of InventoryScreen in survival mode, whereas it will be a CreativeModeInventoryScreen when in creative mode.

If needed, you can remove the screen instanceof check to hook the event listener to all screens.