Arcade Stick Devices

Xbox One provides expanded capabilities for arcade stick devices, allowing you to retrieve detailed information about the state of the actuator and a large number of buttons.

This topic contains the following sections:

Overview

Arcade sticks have a number of fixed characteristics and features. These values often differ from model to model, but remain static for a specific device. You can also request information about the physical layout of an arcade stick; this allows your game to render a realistic graphical representation of the stick that is connected to the console.

Arcade stick devices report their current state to the application at speeds of up to four milliseconds per reading. Device state is reported only when the state of the device changes, with an additional state request that is made by the underlying driver during initialization. Arcade stick devices avoid spamming the bus with extraneous reports; however, it is not unusual to see reports without any apparent changes (other than the timestamp).

Transactions with the device are limited to 64 bytes every four milliseconds. In an application running at 60 frames per second (about 16.7ms per frame), this means that up to four transactions can be sent to the device per frame. The API is designed to give you more control over and visibility into the number of transactions. Naming conventions indicate which calls generate one or more transactions with the device.

Setting up your project

To use the ArcadeStick API, you must first reference the ArcadeStick .winmd file from your project.

To reference the ArcadeStick .winmd file from your project

  1. Load your project in Microsoft Visual Studio.
  2. On the View menu, click Solution Explorer.
  3. In the Solution Explorer pane, right-click the name of your project and then click Properties.
  4. In the Common Properties section of the Property Pages dialog box, select Framework and References.
  5. In the Framework and References property page, click Add New Reference.
  6. In the Add Reference dialog box, click the Browse button at the bottom right.
  7. In the Select the files to reference dialog box, do the following:
    1. Navigate to “%DurangoXDK%\xdk\Extensions\Xbox Arcade Stick API\8.0\References\CommonConfiguration\neutral”.
    2. Select the Microsoft.Xbox.Input.ArcadeStick.winmd file.
    3. Click Add.

If the project was set up correctly and the DLL is in the same folder as Microsoft.Xbox.Input.ArcadeStick.winmd, the following <Extension> element should have been automatically added to the main package object of your project’s appxmanifest.xml file.

<Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
        <InProcessServer>
            <Path>Microsoft.Xbox.Input.Arcadestick.dll</Path>
            <ActivatableClass  ActivatableClassId="Microsoft.Xbox.Input.ArcadeStick" ThreadingModel="both" />
        </InProcessServer>
    </Extension>
</Extensions>

This performs the proper registration, which indicates that the arcade stick DLL contains the listed type class.

The appxmanifest.xml file and the Microsoft.Xbox.Input.ArcadeStick.dll will be placed in your project’s layout\image\loose folder when built from Microsoft Visual Studio. During deployment, files in this folder are overwritten with the application executable.

Getting information about the capabilities of an arcade stick

An ArcadeStick object represents a single instance of an arcade stick device attached to a Xbox One console. This object contains the static configuration information for the device. It also provides the GetCurrentReading method, which provides access to the current state of the device.

Unlike the Gamepad class, there is no static list of the arcade sticks connected to the console—you must enumerate the devices yourself. Alternatively, you can listen for controller connection events on the IController interface, determine whether the new controller is an arcade stick, and then cast appropriately, as shown in the following example.

Important Problems can arise if you mistakenly identify other input devices as arcade sticks. To avoid these issues, make sure to get a valid pointer when trying to cast to IArcadeStick.

C++

void OnControllerAdded(IController^ pIController)
{
    if (dynamic_cast<Microsoft::Xbox::Input::ArcadeStick^>(pIController) != nullptr)
    {
        auto^ pArcadeStick = (Microsoft::Xbox::Input::ArcadeStick ^)(pIController);
        auto^ pIArcadeStick = (Microsoft::Xbox::Input::IArcadeStick^)(pIController);
    }
}

The user that is associated with an arcade stick can be retrieved from the Controller object.

C++

void OnControllerAdded_(IController^ pIController)
{
    if (dynamic_cast<Microsoft::Xbox::Input::ArcadeStick^>(pIController) != nullptr)
    {
        Windows::Xbox::System::User^ user = pIController->User;
    }
}

Alternatively, you can get the user from the ArcadeStick object (which implements IController).

C++

void OnControllerAdded_(IController^ pIController)
{
    if (dynamic_cast<Microsoft::Xbox::Input::ArcadeStick^>(pIController) != nullptr)
    {
        Microsoft::Xbox::Input::ArcadeStick^ pArcadeStick = (ArcadeStick^)(pIController);
        Windows::Xbox::System::User^ user = pArcadeStick->User;
    }
}

Once you have retrieved the user object, you can cast directly to an IUser interface.

C++

Windows::Xbox::System::IUser^ pIUser = user;

The ArcadeStick class and IArcadeStick interface implement the INavigationController interface, and can be directly cast to this type.

C++

auto^ pIArcadeStick = (Microsoft::Xbox::Input::IArcadeStick^)(pIController);
auto^ pINavController = (Windows::Xbox::Input::INavigationController ^)pIArcadeStick;

Getting the current state of an arcade stick

The ArcadeStickReading class represents a single reading from an arcade stick device. It provides information about the current state of the actuator and of the buttons supported by the device.

The simple actuator readings (such as the ArcadeStickReading.IsActuatorLeft property) indicate only the direction of the actuator, which makes it the equivalent of a normal DPad. The enhanced actuator readings (such as the ArcadeStickReading.ActuatorPositionX property) provide the exact position of the actuator, as well as the magnitude, velocity and force of the motion of the actuator. To determine whether the current device supports the enhanced actuator readings, look for a nonzero value of the ArcadeStick.PositionResolution property.

The Arcade Stick API supports up to 64 device-specific buttons. To determine whether the button at a specific index is currently pressed, use the ArcadeStickReading.IsButtonPressed method. To get the current pressed state of all buttons on the device, use the ArcadeStickReading.GetButtonPressedStates method.

Troubleshooting

How do I avoid Warning C4691?

After including the provided reference Microsoft.Xbox.ArcadeStick.dll you may see a few warnings similar to the following.

application.cpp(672): warning C4691: 'Windows::Foundation::DateTime' : type referenced was expected in unreferenced assembly 'Windows.Foundation',
type defined in current translation unit used instead
This diagnostic occurred while importing type 'Microsoft::Xbox::IArcadeStickReading ' from assembly 'Microsoft.Xbox.ArcadeStick, Version=255.255.255.255,
Culture=neutral, PublicKeyToken=null'.

This is caused by types pulled in both by the arcade stick DLL and by your application. The warning can be safely ignored. In Microsoft Visual Studio, you can suppress this warning for your entire project or for individual files. To do this, open the property page for the project or file. Expand Configuration Properties, expand C/C++, and then select Advanced. Add the warning number to the Disable Specific Warnings list.

See also

Overview

Input Technologies and Devices Overviews

Reference

ArcadeStick Class

ArcadeStickReading Class