MFi Controllers

This guide is an extension of the Game Controllers guide. Apple MFi-certified controllers can be paired to iOS, tvOS, or macOS devices.

Notes

Control Schemes/Profiles

MFi devices can conform to one of three profiles as reported by device.MFiProfile. These profiles define the key layout of devices:

gamepad

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

extendedGamepad

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

microGamepad or directionalGamepad

These are special MFi profiles for Apple TV Remotes. Original Siri Apple TV Remote if value of device.MFiProfile is "microGamepad", or the 2nd Generation Siri Remote if value of device.MFiProfile is "directionalGamepad". 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
Notes
  • 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 spatially-appropriate orientation when the control is rotated.

Important
  • 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.