Lumberyard
User Guide (Version 1.15)

Virtual Gamepad Gem

Use the Virtual Gamepad gem to provide your game's UI with touch screen capabilities on mobile devices. After you enable the Virtual Gamepad gem, you can add the virtual gamepad components to your game's UI in the UI Editor.

The Virtual Gamepad gem includes a sample UI canvas that you can either customize for your game or use as an example for a new UI canvas. To view this canvas in the UI Editor, open Gems\VirtualGamepad\Assets\UI\Canvases\VirtualGamepad\VirtualGamepad.uicanvas.

There is no limit for the number of active UI canvases that can contain virtual gamepad components. This means you can create many virtual gamepad canvases to display for the appropriate scenarios, or even at the same time. For example, you can show a different UI canvas on each half of your virtual gamepad.

Example

To experiment with the Virtual Gamepad gem, run the Advanced_RinLocomotion Sample level from the Samples Project on a device with touch screen support.


                Provide your game with touch screen capabilities when played on a mobile device.

You can customize the virtual gamepad's appearance and layout by creating or modifying an existing UI canvas. For more information on working with UI Canvases, see Working with UI Canvases.

Configuring Virtual Gamepad Behavior

You can configure the virtual gamepad's behavior in the UI Editor.

To configure virtual gamepad behavior

  1. In the UI Editor, add the UI components VirtualGamepadButton and VirtualGamepadThumbStick to the UI canvas.

  2. For each component, select an Input Channel.


                Input Channel selection for the VirtualGamepadButton

For more information about input in Lumberyard, see Input in Amazon Lumberyard.

To modify the list of available virtual gamepad input channels, use the Project Configurator to edit the virtual gamepad's system component . For more information, see Configuring Advanced Settings.


                Use the Project Configurator to modify the list of available virtual gamepad input channels.

Virtual Gamepad Component Properties

The Virtual Gamepad gem features two components that you can use to customize input for your mobile games:

VirtualGamepadButton

VirtualGamepadButton has one property, Input Channel. Select the appropriate input.


                            Input Channel selection for the VirtualGamepadButton.
VirtualGamepadThumbstick

VirtualGamepadThumbstick has the following properties:


                            VirutalGamepadThumbStick component properties

Name Description
Input Channel The input channel that is updated when the user interacts with this control.
Thumb Stick Image Centre The child element that is positioned at the center of the virtual thumbstick.
Thumb Stick Image Radial The child element that is positioned beneath the user's finger when the virtual thumbstick is active. The image's position is always clamped to the radial edge of the virtual thumbstick center image.
Centre When Pressed If selected, centers the virtual thumbstick when it is pressed.
Adjust Position While Pressed If selected, adjusts the position of the virtual thumbstick when it is active. Tracks the player's finger when it moves outside the thumbstick radius.

Displaying the Virtual Gamepad at Runtime

You can enable the virtual gamepad for runtime by creating instructions that loads the virtual gamepad UI canvas. You can do this with C++, Lua, or Script Canvas. For more information, see UICanvasManager and UICanvasComponent.

The following example Lua script displays a virtual gamepad UI canvas if touch screen support is detected.

local touchDevice = InputDeviceRequestBus.Event.GetInputDevice(InputDeviceId(InputDeviceTouch.name)) if (touchDevice and touchDevice:IsSupported()) then self.virtualGamepadCanvasId = UiCanvasManagerBus.Broadcast.LoadCanvas("UI/Canvases/VirtualGamepad/virtualgamepad.uicanvas"); end

The following example Lua script checks if a physical gamepad is connected. If found, the Lua script disables the virtual gamepad.

local gamepadDevice = InputDeviceRequestBus.Event.GetInputDevice(InputDeviceId(InputDeviceGamepad.name)) if (gamepadDevice and gamepadDevice:IsConnected()) then UiCanvasBus.Event.SetEnabled(self.virtualGamepadCanvasId, false); end

The following Lua script enables the virtual gamepad when a physical gamepad is disconnected and disables the virtual gamepad when a physical gamepad is connected.

You can find a working example of this Lua script in the lumberyard_version\dev\SamplesProject\AnimationSamples\Advanced_RinLocomotion\Scripts\Advanced_RinLocomotion.lua file.

function Example:OnActivate() self.inputDeviceNotificationBus = InputDeviceNotificationBus.Connect(self); end function Example:OnInputDeviceConnectedEvent(inputDevice) if (inputDevice.deviceName == InputDeviceGamepad.name) then UiCanvasBus.Event.SetEnabled(self.virtualGamepadCanvasId, false); end end function Example:OnInputDeviceDisonnectedEvent(inputDevice) if (inputDevice.deviceName == InputDeviceGamepad.name) then UiCanvasBus.Event.SetEnabled(self.virtualGamepadCanvasId, true); end end function Example:OnDeactivate() if (self.inputDeviceNotificationBus) then self.inputDeviceNotificationBus:Disconnect(); end end