Key Bindings

Adds a Key Bindings tab to the game settings where every mod that supports it lists its hotkeys, for keyboard, mouse and controller. Players change all mod keys in one place, in the game. Mod developers add their keys with one line.

By Nathan's Norse Niceties, a group of small, independent Valheim QoL mods.

The Key Bindings tab. Mod developers register their keys with this mod, and they show up here, in one place, for keyboard, mouse and controller. The two examples are NathansQol_EquipmentSlots and NathansQol_QuickStack.

For players

What it does

• A new tab Key Bindings appears next to the other tabs in the game settings (main menu and in game). It only shows up when at least one installed mod registers keys.

The new tab sits at the end of the settings tabs.

• Each mod gets a section with its name. Each key is a row with the action, the keyboard / mouse key and the controller button.
• Click a key to change it, then press the new key. Hold Ctrl, Shift or Alt first for a combination (for example Ctrl + G). Mouse buttons work too; the left one only together with Ctrl, Shift or Alt (for example Alt + Left Mouse), so you can not take over normal clicking by accident. Esc cancels.

Rebinding a keyboard key: press the new key or mouse button.

• Click a controller button and press the new button on your controller. To bind a combination, hold up to three buttons together (for example L3 and Cross) and let go of all of them; the action only runs while all of them are held. It works the same for Xbox, PlayStation, Switch and Steam Deck controllers; the tab uses the controller type the game detected and shows the right label (A or Cross or B, LB or L1 or L, ...). Right-click a controller button to clear it.

Rebinding a controller button: hold up to three buttons together, then let go to confirm.

• Keys that are used twice are shown in red, so you notice conflicts.

Two actions with the same key are shown in red.

• Reset to default in a section puts all keys of that mod back.
• Back or Esc discards your changes in this tab, OK keeps them, like in the other tabs.

Install

Install it with r2modman or the Thunderstore Mod Manager: search for NathansQol_KeyBindings by NathansNorseNiceties and click install. The dependency (BepInExPack_Valheim) is installed automatically. Mods that support the tab install this mod themselves. You normally do not need to install it by hand.

Manual install: download the zip from the Releases page and use Settings → Import local mod in r2modman.

Configuration

The config file nathan.qol.keybindings.cfg is created in the profile's BepInEx/config folder after the first start. The keys of the other mods are stored in the config files of those mods, so the tab and the r2modman config editor always show the same values. The controller buttons are stored in this mod's config file.

Setting	Default	Meaning
Enabled	true	Shows the Key Bindings tab. Mods can still register their keys when it is off. Applies after a restart
ControllerLayout	Auto	Button names for the controller: Auto, Xbox, PlayStation or Nintendo. Set it by hand if Steam Input makes your controller look like an Xbox controller

Compatibility

• Saves: the mod stores nothing in your character or world. You can remove it at any time; mods that registered keys keep working with their own settings.
• Multiplayer: it only changes your own settings screen and does not need to be installed on the server.
• Controller and Steam Deck: the tab is built to be operated with a controller (stick or d-pad to select, A to rebind), which works (tested with a PlayStation 4 controller; the labels for Xbox, Switch and Steam Deck controllers follow the same rules but are untested). A mod only reacts to the controller button if that mod uses the library for its key checks; otherwise only keyboard and mouse work for it.
• Other mods: it works with every mod that registers its keys. Mods that do not are simply not listed.
• Game version: developed and tested on Valheim 1.0.x (BepInExPack_Valheim 5.4.2351). The tab is added to the game's settings screen, so after big game updates it may need a new release.

Known limitations

• Tested on Linux, in single-player worlds and on multiplayer servers, with keyboard and mouse and with a PlayStation 4 controller (through Steam Input). Not tested on Windows or on a Steam Deck.
• On the keyboard, only modifier keys (Ctrl, Shift, Alt) plus one key are supported, not several regular keys. Controller combinations may have up to three buttons.

---

For mod developers

Your mod keeps its normal BepInEx setting and hands it over. The tab reads and writes your own ConfigEntry, so the key stays in your config file, in sync with the r2modman config editor, and your code that checks the key does not change.

// In Awake():
StackKey = Config.Bind("Hotkeys", "StackKey",
    new KeyboardShortcut(KeyCode.G, KeyCode.LeftControl), "Quick stack your inventory into the chests nearby.");

_stack = KeyBindings.Register(Info, StackKey, "Quick stack to nearby chests", GamepadButton.ButtonWest);

// Later, in Update():
if (_stack.IsDown()) { /* keyboard, mouse OR controller */ }

Register returns a KeyBinding. Its IsDown(), IsPressed() and IsUp() also react to the controller button the player chose. If you keep using StackKey.Value.IsDown(), your mod reacts to keyboard and mouse only.

Get the API

There are three ways, from most to least convenient:

1. NuGet (compile-time reference only; the library itself is a mod the player installs):

   <PackageReference Include="NathansQol.KeyBindings" Version="0.*" ExcludeAssets="runtime" />
   

   Packages are published to nuget.org and to the feed of this GitLab project (https://gitlab.com/api/v4/projects/87958813/packages/nuget/index.json).
2. The DLL: download the NathansQol_KeyBindings package from Thunderstore, take NathansQol.KeyBindings.dll and add a <Reference> to it in your project.
3. No reference at all: copy bridge/KeyBindingsBridge.cs into your mod (see below). Your mod then works with or without the library.

The XML documentation comes with the NuGet package and the DLL, so your IDE shows it.

If the library is not installed

• Hard dependency (your mod needs the tab): add [BepInDependency("nathan.qol.keybindings")] to your plugin class and a dependency on NathansNorseNiceties-NathansQol_KeyBindings in your Thunderstore manifest. r2modman installs it with your mod.
• Soft dependency (your mod should work without it): add [BepInDependency("nathan.qol.keybindings", BepInDependency.DependencyFlags.SoftDependency)], which makes BepInEx load the library first when it is present. Then either register inside a check,

  if (Chainloader.PluginInfos.ContainsKey("nathan.qol.keybindings")) RegisterKeys();   // RegisterKeys() calls KeyBindings.Register
  

  (put the call in its own method marked [MethodImpl(MethodImplOptions.NoInlining)], so the library is only loaded when it exists), or use the bridge file, which does all of this with reflection:

  _stack = KeyBindingsBridge.Register(this, StackKey, "Quick stack to nearby chests", "ButtonWest");
  if (_stack.IsDown()) { ... }   // uses the library if installed, otherwise your own key
  

API

All public types are in the namespace NathansQol.KeyBindings.

Member	Description
KeyBindings.Register(PluginInfo, ConfigEntry<KeyboardShortcut>, string label, GamepadButton defaultGamepad)	Lists a shortcut (modifier keys plus one key or mouse button). Returns a KeyBinding
KeyBindings.Register(PluginInfo, ConfigEntry<KeyCode>, string label, GamepadButton defaultGamepad)	Lists a single key, for example a modifier like LeftAlt
KeyBindings.Register(string guid, string name, ...)	The same without a PluginInfo
KeyBinding.IsDown() / IsPressed() / IsUp()	Keyboard, mouse or controller
KeyBinding.Gamepad, GamepadButtons, Label, ModName	First controller button, all buttons of the (combination) binding, row label, section name
KeyBinding.Changed	Raised when the player changes the binding in the tab
GamepadButton	Logical controller buttons: DPadUp, ButtonSouth, LeftShoulder, RightTrigger, ...
KeyBindings.Register(PluginInfo, ConfigEntry<...>, string label, string defaultGamepad)	Since version 2: the default controller binding as a combination of up to three buttons, for example "LeftStickButton+ButtonSouth"
KeyBindings.ApiVersion	The API version (currently 2)

Notes:

• Register in Awake(), in any load order. The tab is built each time the player opens the settings.
• Registering the same ConfigEntry twice returns the first binding.
• The section name is the plugin name from your BepInPlugin attribute; keys are shown in the order you register them, sections sorted by name.
• Controller bindings are stored by the library in nathan.qol.keybindings.cfg, keyed by your plugin GUID and setting.
• Stability: existing members of the API are never changed or removed within a major version; new members only grow ApiVersion.

---

Feedback

• Found a bug? Report it. The form asks for your versions and the log file, which makes it much easier to find the cause.
• Have an idea or a mod that should work with it? Request a feature.
• No GitLab account? Send an email to contact-project+nathans-norse-niceties-feedback-87970732-issue-@incoming.gitlab.com with the name of the mod in the subject. For a bug, please include your versions and the file BepInEx/LogOutput.log. More about it in the feedback project. Reports sent by email are private.
• Existing reports and ideas are listed on the issues page.

Building the mod yourself, and the release process: DEVELOPMENT.md. The version history is in the Changelog tab.

License

MIT