Apple provides the Game Controller framework to simplify supporting game controllers for games on Apple platforms. The Game Controller framework includes the GCVirtualController class for iOS games that displays a virtual controller on the touch screen. The virtual controller lets people play your game if they don’t have a physical game controller. The benefit of using Apple’s virtual controller is you don’t have to write your own.

You have to do the following tasks to use a virtual controller in your iOS game:

• Configure the controller
• Create the controller
• Add value changed handlers

Configure the Controller

When you configure a virtual controller, you specify the input elements (controls) you want for the controller: joysticks, direction pads, and buttons.

To configure the controller, create an instance of GCVirtualController.Configuration. The instance has an elements property that contains a set of elements the virtual controller has.

You must specify the input elements your game needs. The names of the elements have the prefix GCInput. The following code creates a controller with a virtual joystick on the left side of the screen and an A button:

let controllerConfig = GCVirtualController.Configuration()
controllerConfig.elements = [GCInputLeftThumbstick, GCInputButtonA]

Create the Controller

To create the virtual controller, call the initializer for the GCVirtualController class. Supply the configuration you created. Call the connect function to use the virtual controller in your game:

let controller = GCVirtualController(configuration: controllerConfig)
controller.connect()

Add Value Changed Handlers

When the player uses the virtual controller, it creates value changed events. You must create value changed handlers for the input elements (controls) your game handles. You must also set the value changed handler for each input element to the handler you created.

The value changed handler is a closure (a function without a name). The data type for joystick and direction pad handlers is GCControllerDirectionPadValueChangedHandler. The data type for button handlers is GCControllerButtonValueChangedHandler.

In the closure write code to handle the particular event. For example a side scrolling platform game may have a button for jumping. Call the jump function in the closure for the jump button’s value changed handler. The following code shows the value changed handler for a button:

let buttonAHandler: GCControllerButtonValueChangedHandler = 
	{ button, pressure, pressed in
			
	if pressed {
			jump()
	}
}

The pressure argument is a value from 0 to 1 that measures the force of the button press. The pressed argument tells you whether or not the button was pressed.

The following code shows a value changed handler for using a virtual joystick to move the player:

let movementHandler: GCControllerDirectionPadValueChangedHandler = 
		{ dPad, xValue, yValue in
						
		movePlayer(x: xValue, y: yValue)
}

The xValue and yValue arguments tell you how far the joystick moved on the x and y axes.

The final step is to set the value changed handler for each input element. The virtual controller has a controller property where you access input elements. This property has an extendedGamepad property that contains the input elements.

For each input element in the extendedGamepad property that your game uses, set its valueChangedHandler property to the value changed handler you created. The following code sets the value changed handlers for the virtual joystick and a jump button:

if let gamePad = virtualController?.controller?.extendedGamepad {
		gamePad.leftThumbstick.valueChangedHandler = movementHandler
		gamePad.buttonA.valueChangedHandler = buttonAHandler
}

Demo Project

I have a demo project on GitHub that moves a sprite around the screen using a virtual joystick.