Troubleshooting: Input problems
OpenEmu handles input differently than most applications, accessing directly the hardware at a lower level - not through Cocoa but through the IOKit HID (Human Interface Device) interface. For this reason, sometimes you may encounter a situation in which for some reason inputs are not recognized.
Before asking for help, follow the checklist below to verify you have set up the correct settings for making OpenEmu work correctly and to fix common issues.
Note: OpenEmu running on non-Apple hardware aka "Hackintosh" is strictly unsupported.
Since macOS Mojave, accessing input devices directly like OpenEmu does is gated behind an additional permission called "Input Monitoring". The latest versions of OpenEmu automatically detect if this permission must be granted manually, and warn you in advance if necessary. If you still have problems with any controller or keyboard, follow these steps:
- Open System Preferences -> Security & Privacy
- Select the Privacy tab
- In the Privacy tab, select Input Monitoring in the list on the left side of the window
- Add OpenEmu to the list of apps allowed to monitor input by dragging it to the list or by using the "+" button.
Even though the text in System Preferences only refers to monitoring keyboard input, this permission applies to any other kind of input, included both wired and wireless controllers.
Q: Why is this necessary?
A: Despite what the text in System Preferences says, this permission does not only relate to access to input when the application is not in focus. If this permission is not granted, OpenEmu will not be able to access the keyboard or any game controller in any circumstance. Additionally, OpenEmu has a feature where you can enable inputs and continue to play even when the application is not in focus, which makes input permissions even more necessary.
Q: Other applications using controllers don't require this!
A: These applications are using a programming interface called "Game Controller" that does not require these additional permissions. However, with its lower-level approach to handling inputs, OpenEmu provides lower input latency and enables support for proprietary controllers that do not work with the Game Controller interface -- such as any Nintendo controller.
Q: Is OpenEmu going to spy on my passwords?
A: macOS itself does not deliver to OpenEmu any keyboard event that was produced while typing in a password field, even when input permissions are enabled, so OpenEmu cannot spy on your passwords.
Since macOS Monterey, access to Bluetooth wireless controllers is gated behind an additional permission you must give to OpenEmu. If your wireless controllers do not work, follow these steps:
- Open System Preferences -> Security & Privacy
- Select the Privacy tab
- In the Privacy tab, select Bluetooth in the list on the left side of the window
- Add OpenEmu to the list of apps allowed to use Bluetooth by dragging it to the list or by using the "+" button.
Note: Even when Bluetooth permissions are not granted the controllers will still appear in the Controls Preferences of OpenEmu.
OpenEmu works with all standard Bluetooth or USB controllers made for Macs or PCs that respect the standard HID specification.
However, controllers made for game consoles are often not fully HID compliant. Some of these controllers are partially HID compliant and are specifically supported by OpenEmu. Additionally, some controllers or adapters are not properly HID-compliant despite being supposedly made for Macs or PCs. OpenEmu will have trouble handling any of these devices.
To see a complete list of controllers tested to work, follow this link. Any controller not on this list is not explicitly supported and may not work correctly for a variety of reasons.
Finally, connecting controllers to USB hubs is generally fine, but some hubs are of very low quality and do not provide a stable connection or sufficient power for the controller. If you have problems with a controller connected to an USB hub, try removing the USB hub first.
Since version 2.2, OpenEmu performs auto-calibration of the analog inputs of most gamepads. In a nutshell, OpenEmu uses the inputs you give to the gamepad while you play to decide how to calibrate it.
However, in some situations, this feature may cause issues. For example, in an action game, the first time you try to perform a very small movement, it might register as a normal full-speed motion. Another common issue is that the Controls preference panel is overly sensitive or locks up after trying to map an analog stick.
In case you experience these issues, rotate by 360° the analog sticks of the affected controller before you start using it, to inform the auto-calibration system of the full extent of values reported by the sticks.
There are circumstances in which open applications, or other installed software can cause interference with gamepad and keyboard input in OpenEmu.
Typically, the reason is that applications can open an input device for exclusive access (kIOHIDOptionsTypeSeizeDevice) therefore preventing OpenEmu from receiving input from it.
The following applications are commonly found to interfere with input and should be closed while using OpenEmu. This is an incomplete list so if you are experiencing issues beyond these, try closing all other open applications. If issues persist, try restarting your computer and then only launch OpenEmu.
- Google Chrome (HTML5 Gamepad API)
- DOSBox
- Terminal (Secure Keyboard Entry)
- iTerm2
- Keybase.io
- Steam (Note: Reconnect your device after closing)
- Webroot Antivirus (Secure Keyboard Entry)
Input modifier apps such as these are not compatible with OpenEmu, cause interference and should be closed or uninstalled.
- ControllerMate
- DarwiinRemote
- Enjoy2
- Enjoyable
- GamePad Companion
- Joystick Mapper
- Karabiner (KeyRemap4MacBook) and Karabiner-Elements
- SteelSeries Engine
- USB Overdrive (disable the "Any Gaming, Any Application" option - you may need to fully uninstall.)
- WJoy (unload kexts for WJoy via Terminal.app with the following command:
sudo kextunload -b com.alxn1.driver.wjoy)
Remote Desktop apps such as these are not compatible with OpenEmu and will not be able to receive input events.
- Splashtop
- Synergy
- TeamViewer
The following hardware will NOT work with OpenEmu.
- Any non-HID compliant device (e.g. console-only Official Nintendo GameCube Controller Adapter for Wii U (WUP-028))