# Controller Chords
**If you do not have enough controller buttons, now you do.**
Controller Chords lets your Xbox-style controller "press" keyboard keys for you, so you can use keyboard-only mods without ever touching the keyboard.
---
## Start here: what this mod actually does
A lot of great Valheim mods are triggered by a keyboard key. Maybe a mod zooms when you press C, or drinks water when you press E. That's fine on a keyboard, but a controller only has so many buttons, and most are already doing something.
**Controller Chords is a translator.** It sits quietly in the background and waits for you to press a controller button. When you do, it tells the game *"the player just pressed this keyboard key"* — and your other mod reacts as if you really had.
One important thing to understand up front:
> **On its own, this mod does nothing you can see.** It has no menu and no visible effect. Its whole job is to feed key presses to your *other* mods. So you set it up once to match the mods you already have, and from then on your controller can do things that used to need a keyboard.
Think of it like a universal remote: the remote doesn't play the movie, it just sends the right signal to the thing that does.
---
## The three ways it can help you
There are three styles of mapping. You can use any mix of them, and you only set up the ones you need.
### 1. One button -> one key (the simplest)
Press a single controller button, and it sends one keyboard key.
*Example:* press **Y**, and the game acts as if you pressed **E**. If you have a "drink water" mod bound to E, now **Y** drinks water.
You can also choose **Hold** for this. With Hold turned on, the key stays pressed for as long as you hold the button, and lets go when you do. That's needed for mods where you *hold* a key (like a "hold to zoom" key).
### 2. Two buttons together -> one key (a "chord")
Hold one button and press a second one. Together they send a key.
*Example:* hold **RB** and tap **A**, and the game acts as if you pressed **Left Control**.
This is handy when you've run out of spare buttons. Holding **RB** turns your four face buttons (A, B, X, Y) into four *new* actions, without losing what those buttons normally do on their own.
### 3. A button -> a mouse scroll-wheel "notch"
Some mods use the **mouse scroll wheel** to zoom or cycle through options — something a controller can't normally do. This lets a button act like one click of the scroll wheel.
*Example:* a button can "scroll up" to zoom in, or "scroll down" to zoom out.
---
## Installing the mod
1. Install **BepInExPack Valheim** (the standard mod loader most Valheim mods need).
2. Put ControllerChords.dll in this folder:
BepInEx/plugins/ControllerChords/
3. Start Valheim once, then quit. This creates the settings file you'll edit.
4. Open the settings file:
BepInEx/config/marc.valheim.controllerchords.cfg
You can edit that file in any text editor (Notepad is fine), or use the in-game **Configuration Manager** mod if you have it.
---
## How to change what your buttons do
When you open the settings file you'll see it's split into labelled sections like \[SingleButton 01], \[Scroll 01], and \[Chord 01]. Each section is one mapping. To set one up, you fill in a few plain settings.
Here is what every setting means, in normal words:
| Setting | What it means |
| --- | --- |
| **Enabled** | Turn this mapping on (true) or off (false). |
| **Button** | The controller button you press. |
| **Modifier** | The button you hold *first* (for chords and gated scrolls). |
| **TargetKey** | The keyboard key you want it to send. This must match the key your other mod uses. |
| **HoldMode** | true = hold the key down while you hold the button. false = a quick tap. |
| **Direction** (scroll only) | In = scroll up (usually zoom in). Out = scroll down (usually zoom out). |
The button names you can use are: A, B, X, Y, DPadUp, DPadDown, DPadLeft, DPadRight, LB, RB, LT, RT, LeftStick, RightStick, Back, Start. For chords, the held **Modifier** must be one of RB, LB, RT, or LT.
The **TargetKey** uses standard key names like E, G, C, H, LeftControl, LeftAlt, and so on.
> **Tip:** if you don't know which key a mod uses, check that mod's own page or its config file — it'll tell you the key. Whatever key it lists is what you put in **TargetKey**.
---
## Ready-made examples (copy these)
### Drink water with a single button — for "You're Thirsty"
"You're Thirsty" drinks from water with the use key E, and empties your container with G. Map them to spare buttons:
```ini
[SingleButton 02]
Enabled = true
Button = Y
TargetKey = E
[SingleButton 03]
Enabled = true
Button = X
TargetKey = G
```
Now **Y** drinks and **X** empties. Pick whatever buttons feel free to you.
### Zoom with the controller — for FrostJack's "Zoom"
This one is the best example of all three ideas working together, because that mod needs you to **hold a key** *and* **use the scroll wheel**.
The mod holds C to turn zoom on, then scrolls to zoom in and out. So we hold a button to keep C pressed, and use the D-pad as the scroll wheel. **This setup is already turned on by default**, but here it is so you can see how it works:
```ini
[SingleButton 01]
Enabled = true
Button = LB
TargetKey = C
HoldMode = true
[Scroll 01]
Enabled = true
Modifier = LB
Button = DPadUp
Direction = In
[Scroll 02]
Enabled = true
Modifier = LB
Button = DPadDown
Direction = Out
```
**How you actually play it:** hold **LB** with your finger (that switches zoom on), then tap **D-pad Up** to zoom in and **D-pad Down** to zoom out, one step at a time. Let go of LB to stop zooming. Because the zoom is only active while LB is held, your D-pad still works normally for everything else.
A couple of quick fixes if it feels off:
- **Zoom goes the wrong way?** Swap the two Direction values (In and Out).
- **Changed the mod's hold key?** If you used the mod's /zoomkeybind command to pick a different key, set TargetKey in \[SingleButton 01] to match.
### Free up four extra buttons with a chord
Hold **RB** and the face buttons become four new actions:
```ini
[Chord 01]
Enabled = true
Modifier = RB
Button = A
TargetKey = LeftControl
HoldMode = false
```
Hold **RB** + tap **A** -> sends Left Control. Add more chords (RB + B, RB + X, RB + Y) the same way for other mods.
---
## A friendly suggested layout
You're free to do whatever you like, but if you want a starting point that's easy to remember:
| What you press | Good for |
| --- | --- |
| One spare face button (Y, X...) | Quick everyday actions (drink, eat) |
| Hold LB + D-pad | Zooming |
| Hold RB + A / B / X / Y | Four extra mod actions |
| Hold LB + A / B / X / Y | Four more |
| Hold RT or LT + a button | Rarer tools or debug actions |
Start with one or two mappings, make sure they feel natural, then add more. There's no need to turn your controller into a piano overnight.
---
## If something isn't working
- **Nothing happens when I press the button.** Double-check that the mapping's Enabled = true, and that its TargetKey exactly matches the key your other mod uses.
- **It works on keyboard but not controller.** Make sure you're actually pressing the controller button you set, and that the modifier (if any) is held *before* the second button.
- **I want to see if it's firing.** In the \[General] section set LogChordEvents = true. Each press will then be written to BepInEx/LogOutput.log, so you can confirm it's working.
- **My buttons fire while I'm in a menu.** By default they don't — mappings are switched off in menus, inventories, shops, text boxes, and the console. Only set AllowInMenus = true if you specifically want them active there.
- **Zoom steps two levels per press.** Make sure PulseFrames = 1 on the scroll slots. If presses are sometimes missed, raise it to 2.
---
## Good to know
- This mod does not add a menu, change your save, or affect other players. It only reads your controller and passes key presses to your other mods.
- Don't use the same button as both the modifier and the trigger in one chord.
- If two mods both react to the same key, they'll both fire — that's usually fine, but worth knowing.
---
## Reporting a problem
If you need help, include:
- Your Valheim version.
- Your controller type.
- The exact section from marc.valheim.controllerchords.cfg you're using.
- Your BepInEx/LogOutput.log file.
---
**Plugin GUID:** marc.valheim.controllerchords
**Version:** 0.4.0
