RivalBridge

I have played World of Warcraft with the same mouse for years: a SteelSeries Rival 500, fifteen buttons, a thumb cluster that fits my hand, and a little flick switch under the thumb that I bind to something important. Then SteelSeries moved on. The mouse was dropped from the current software, the old Engine 3 was left behind, and on a new Mac the extra buttons did nothing at all. The hardware was perfect. The company had simply stopped talking to it.

RivalBridge is the app I wrote to talk to it instead.

The problem, exactly

Plug the Rival 500 into a Mac and look at what it announces on the USB bus. It offers three channels. One is an ordinary mouse: movement, the wheel, and room for exactly eight buttons. One is a keyboard, which the mouse uses when a button has been told to type a key. The third is a private configuration channel that only SteelSeries' software knew how to speak.

That eight-button limit is the whole story. Fifteen buttons cannot all be mouse buttons, so buttons 9 through 13 and the two wheel tilts were always routed through the configuration software, which either turned them into keystrokes or ran them itself. Take that software away and seven buttons go dark. WoW can bind a mouse button, and it can bind a key; what it cannot bind is a button the computer never hears about.

What RivalBridge does

It works in two layers.

The hardware layer speaks the configuration channel directly, from native Swift, with no drivers and no SteelSeries software. The protocol was recovered by the open-source rivalcfg project, and RivalBridge's version of it is checked byte-for-byte against that project's output in a test suite. Through this channel the app sets the two DPI presets, the polling rate, the colours and cycles of the logo and wheel lights, and the job of every one of the fifteen buttons: a mouse button, a scroll, the DPI switch, a typed key, a media key, off, or app-controlled. Whatever it writes can also be saved into the mouse's own memory, so the mouse behaves the same on another computer with nothing installed.

The bridge layer is the part SteelSeries used to provide and no longer does. Each of the seven orphaned buttons is told, in the mouse, to send a key of its own: F16 to F19 and the keypad asterisk for buttons 9 to 13, Page Up and Page Down for the wheel tilts. Those were chosen the hard way. They are keys macOS has codes for and World of Warcraft will bind. They avoid F14 and F15, which a Mac quietly uses for display brightness, and F13, which is the Mac's Print Screen: the game binds Screenshot to it and takes a picture instead of letting you rebind it, as a folder of accidental screenshots taught me. My first version used F20 to F24 for some buttons; the Mac has no key codes for most of those, and the game never saw them.

The consequence is the part I like best: in the game, the mouse needs no software at all. Write the map once, save it into the mouse, and all fifteen buttons bind in WoW even with RivalBridge closed.

RivalBridge earns its place everywhere else. It listens to the mouse's own key reports, so it can tell the mouse's Page Up from your keyboard's, and it watches key events as they pass. When the profile for the app in front wants a button to do something other than its key, the key is swallowed and replaced:

• an extra mouse button, up to button 32;
• a keyboard shortcut, held for as long as the button is held;
• a scroll, in either direction, which is what the wheel tilts do on my desktop;
• typed text, or a sequence of steps with waits between them, for work outside the game.

When the profile wants the button's own key, as the WoW profile does, the event is passed through untouched, so the game sees exactly the same thing whether the app is running or not, and a binding never changes meaning. (macOS reserves taking a keyboard away from the system for root, which is why RivalBridge listens and replaces rather than seizes. I found that out the hard way.)

Using it

1. Open RivalBridge from the menu bar. The Buttons tab shows the mouse from the top and from the thumb side, with the name World of Warcraft gives each button (F18, Num Pad *, Mouse Button 6) printed beside it, and a switch flips the circles between button numbers and WoW names; click any button to change what it does in the mouse and what it does in each profile.
2. Grant the two macOS permissions it asks for: Input Monitoring, to read the hidden keys, and Accessibility, to post the events it makes.
3. Press Write to mouse. The map, DPI, polling rate and lights go into the mouse, and by default into its onboard memory.
4. In WoW, open Options › Keybindings, click the action you want, and press the mouse button. Buttons 4 to 8 appear as Mouse Button 4 to 8; the other seven appear as F16 to F19, Num Pad *, Page Up and Page Down.

Every button keeps working with RivalBridge closed. The app is only needed for profiles that turn a button's key into something else; that is what the menu-bar icon is for.

Playing by the rules

Blizzard's policy is one press, one action. A key that casts two spells is automation, and RivalBridge does not encourage it: the sequence and text actions exist for the desktop, and the app labels any action that would send more than one input per press. In the game, every button is a single key or a single mouse button, exactly as a keyboard would be.

Under the hood

Native SwiftUI menu-bar app for macOS 14 and later, built with XcodeGen. IOKit HID for the configuration channel and for listening to the mouse's key reports; a Core Graphics event tap for replacing keys. Sixteen unit tests compare every packet the app can build with rivalcfg's reference output, including the LED gradient encoding and its rule that a colour cycle closes back on its first colour. Nothing is sent anywhere: there is no account, no network, no telemetry.

RivalBridge is not affiliated with SteelSeries or Blizzard Entertainment.