Skip Navigation
Framework

Game Controller

Support hardware game controllers in your game.

Overview

Use Game Controller to support users interacting with your app using a physical or virtual game controller. Game controllers include third-party products, such as the DualShock 4, DualSense, and Xbox, as well as the mouse, keyboard, Siri Remote, and racing wheels.

An illustration of a laptop displaying a game that shows a car driving on the road toward a country landscape. On the left is an overlay of a steering wheel controller.

To support game controllers, add the Game Controller capability (the GCSupportsControllerUserInteraction property) to your project, and Xcode adds the Game Controller framework automatically. Then, choose the types of controllers your app supports (the GCSupportedGameControllers property) under the Game Controllers capability on the Signing & Capabilities pane.

For controllers other than the racing wheel, follow these steps to process the game controller input in your app:

  • To get a physical game controller object, register for specific notifications when users connect and disconnect game controllers. Alternatively, you can display a virtual controller for the user to interact with.

  • Then get a profile object from the physical or virtual controller to access its input elements, such as buttons, triggers, thumbsticks, and directional pads. Profiles encapsulate the hardware details and layout of the input elements on the controller from your app.

  • To process the input, either get the values directly from the elements or register callbacks for when the user changes their values. Apps running in visionOS receive input events only when the person is looking at the app’s window.

  • For controllers that support haptics, you can provide feedback to the user by creating an engine that manipulates the controller’s actuators.

Users may remap game controller elements in Settings and Preferences, so be sure to display the correct input element in your interface. If the hasRemappedElements property is true, the user remapped elements and you can get the mapping between the actual and alias elements using the mappedElementAlias(forPhysicalInputName:) and mappedPhysicalInputNames(forElementAlias:) methods.

To support racing wheel devices in your macOS app, see Racing wheel device support.

Topics

Deploy an app that takes advantage of advanced game controller features using the Game Controller framework, while supporting game controllers on older macOS releases using IOKit.
Current page is Game Controller