Skip to main content

​
Defining Keybinds

Keybinds are defined programatically within the overlayed setup. This means runtime keybinds are not supported. 
export const overlay = overlayed({
	keybinds: {
		showMainWindow: {
			keys: ["AltLeft", "KeyX"],
			mode: "toggle",
		},
		showScoreboardWindow: {
			keys: ["Backquote"],
			mode: "hold",
		},
	},
});
Let’s break down the above config:
  • showMainWindow or showScoreboardWindow
    • These are names that you define for the keybind.
    • They’ll be used later on to listen to the keybind
  • keys
    • An array of KeyboardEvent#code
    • Whatever you configure will be the default value
    • Here is a good tool to easily find the codes for a given keybind
  • mode
    • "toggle" will trigger the callback when the key is toggled on and off
    • "hold" will trigger the callback when the key is held down
    • This can be updated at runtime
We currently offer no way to migrate keybind names to new ones.

​
Listening to Keybinds

Once a keybind is configured, its trivial to listen to it anywhere in your overlay: 
overlay.keybinds.showMainWindow.on("toggle", () => {
	myWindow.toggleVisibility();
});

overlay.keybinds.showMainWindow.on("up", () => {
	myWindow.hide();
});

overlay.keybinds.showMainWindow.on("down", () => {
	myWindow.show();
});
If you plan on allowing users to configure the mode of a keybind, you’ll want to handle all three events.

​
Updating Keybinds

It’s highly recommended to create a UI to allow users to update the app’s keybinds for complete customization. You can accomplish this easily: 
// Update a single keybind
overlay.keybinds.updateKeybind("showMainWindow", {
	// ...
});

// Bulk update,
overlay.keybinds.updateKeybinds({
	// ...
});
This will save their new settings to the file system automatically, so there’s nothing else for you to worry about.

​
Pausing Keybind Listening

When implementing your UI to allow users to record new keybinds, it’s critical to call pauseKeybindListening and resumeKeybindListening functions before and after the user records the keybind. This will prevent them from triggering an existing keybind while recording a new one. This is only a concern for in-game windows, so if you don’t allow users to change keybinds via an in-game window, you can skip this section.

​
Rejecting Keybinds

Sometimes you may want to block a keybind on a window, for example blocking opening of a custom scoreboard if the user isn’t in a match. You can accomplish this by returning a string from the listener, which represents a reason for blocking the keybind. 
overlay.keybinds.showMainWindow.on("toggle", () => {
	if (!siegeState.match) {
		return "Not in a match";
	}

	myWindow.toggleVisibility();
});

overlay.keybinds.showMainWindow.on("down", () => {
	if (!siegeState.match) {
		return "Not in a match";
	}

	myWindow.show();
});
Currently the returned reason string is just used for logging purposes, but can also serve as self-documenting code.

​
Best Practices

  • Always pause keybind listening during keybind recording.
  • Validate keybind conflicts when users update keybinds.
⌘I