SHIELD portable and SHIELD controller are console-class game controllers. This ensures that all SHIELD users have a high-quality, consistent experience.
Applications tuned for SHIELD should have full controller support; all aspects of the user interface should be navigable via the controller. Games should support controller input across all menu screens, and of course throughout gameplay as well, in order to create an enjoyable "made for SHIELD" experience. More importantly, applications should detect they are running on SHIELD, and preset control mappings to be natural for the game controller.
The following sections provide an overview of the various SHIELD controls, how to detect the SHIELD controller specifically (should you need to), and how to detect that you are on SHIELD in general.
Note that you can refer to the accompanying Supporting Android Game Controllers for a more detailed discussion on how to approach developing application support for a wide range of controllers (including SHIELD). We strongly recommend you look to a generic approach to controller support if at all possible, and only detect that you are on SHIELD in order to enable proper controller mappings. But should you need to customize for individual devices, we’ve made it easy to identify SHIELD’s built-in controller.
The built-in SHIELD controls are mapped to Android buttons and axes (SHIELD portable shown below):
As noted in the previous diagram, many of the buttons and axes on SHIELD have fallbacks. In addition, SHIELD supports a virtual mouse (and cursor) that uses the right analog stick along with the right trigger. If virtual mouse is enabled via the SHIELD controller settings panel, then any right stick movements that are not “eaten” (reported as handled) by the application will cause the mouse mode to be triggered temporarily and control an on-screen pointer.
It is important that SHIELD applications accurately report whether they are using the right analog axes or not (AXIS_Z and AXIS_RZ). If the application reads these stick values but returns false (not handled) from the Java level onGenericMotionEvent (or the native equivalent event handler), then both the application and the virtual mouse code will assume that they own the motion event, and there can be confusing behavior.
Applications that use AXIS_Z and/or AXIS_RZ (or any other axes, for that matter) should return true (nonzero in the case of native code) from the Android callbacks upon receiving events for those axes.
NVIDIA’s recommendation for all applications has been to provide a game controller configuration screen to give the user the ability to customize the controller experience. However, since the layout of the SHIELD controller is known a priori, applications should be able to detect that they are running a device with a SHIELD controller and pre-configure the controls to be reasonable on SHIELD. This should make the game launch-and-go for almost all SHIELD users.
In many cases, this pre-configuration for SHIELD can be done without explicitly customizing for SHIELD alone. The SHIELD controller mappings match NVIDIA’s "amalgamated controller" specification. For details of how to map to the amalgamated controller layout, see The Amalgamated Gamepad.
If it is necessary for your application to detect the availability of a SHIELD controller at runtime, this detection can be done easily. See the section entitled Detecting SHIELD Portable at Runtime for details on identifying the controller.
The SHIELD controller buttons match the basic layout of the XBOX360 controller (aside from the DPAD and left-stick swapping location). The scancodes are also matched, and the keycodes generated are similar to the mapping of the XBOX360 controller mapping on Android. Thus, for development purposes, any modern Tegra device may be used along with a wired XBOX360 controller to implement and test proper controller support. A SHIELD devkit or commercial device is not necessary to test the correct mapping of SHIELD controller buttons to game events.
NVIDIA® GameWorks™ Documentation Rev. 1.0.220830 ©2014-2022. NVIDIA Corporation and affiliates. All Rights Reserved.