This guide is an extension of the Game Controllers guide. Apple
macOS supports both MFi controllers and "classic" HID controllers. To distinguish between them, check the object.driver property when handling input events (its value will be either "HID" or "MFi").
iOS and tvOS support only MFi controllers.
If you're creating an app with MFi game controller support, we recommend that you follow Apple's guidelines, starting with this checklist.
MFi devices can conform to one of three profiles as reported by device.MFiProfile. These profiles define the key layout of devices:
"gamepad""extendedGamepadgamepad""microGamepad"If device.MFiProfile is "gamepad", check the following keyName values to identify specific controls:
| Control/Input | keyName | |
|---|---|---|
| D-pad "up" | up |
|
| D-pad "down" | down |
|
| D-pad "left" | left |
|
| D-pad "right" | right |
|
| Button "A" | buttonA |
|
| Button "B" | buttonB |
|
| Button "X" | buttonX |
|
| Button "Y" | buttonY |
|
| Left shoulder button (1) | leftShoulderButton1 |
|
| Right shoulder button (1) | rightShoulderButton1 |
|
| Pause button | menu |
If device.MFiProfile is "extendedGamepad", the controller will have additional keyName or axis values. Note that triggers can be handled both as keys and axes.
| Control/Input | keyName | axis |
|---|---|---|
| Left thumbstick horizontal axis | leftX |
|
| Left thumbstick vertical axis | leftY |
|
| Right thumbstick horizontal axis | rightX |
|
| Right thumbstick vertical axis | rightY |
|
| Left shoulder button (2) | leftShoulderButton2 |
|
| Right shoulder button (2) | rightShoulderButton2 |
|
| Left trigger | leftShoulderButton2 |
leftTrigger |
| Right trigger | rightShoulderButton2 |
rightTrigger |
This is a special MFi profile for the Apple TV Remote. If device.MFiProfile is "microGamepad", the controller will have the following keyName and axis values:
| Control/Input | keyName | axis |
|---|---|---|
| Horizontal slide on trackpad | x |
|
| Vertical slide on trackpad | y |
|
| Swipe/flick up on trackpad | up |
|
| Swipe/flick down on trackpad | down |
|
| Swipe/flick left on trackpad | left |
|
| Swipe/flick right on trackpad | right |
|
| Press trackpad | buttonA |
|
| Pause/play button | buttonX |
|
| Tap trackpad | buttonZ |
|
| Quick tap on menu button | menu |
The Apple TV Remote will generate accelerometer events.
The Apple TV Remote has a trackpad instead of a thumbstick. By default, every time the user touches the trackpad, it creates a virtual joystick "window" centered on the initial tap location and a relativeTouch event. However, if you want to track the absolute position of a touch, you can set device.reportsAbsoluteDpadValues to true.
If your app can be used in both horizontal and vertical orientations, we recommended that you set device.allowsRotation to true. This setting will automatically flip axes to keep them in the
All MFi controllers have a pause button which pass a keyName of menu. In this case, two events with phases of "up" and "down" are generated instantly.
Typically, this button should be used to pause and resume a game.
Holding down this button on the controller may trigger a system action such as opening the springboard on tvOS.