街机摇杆Arcade stick

此页介绍使用 Windows.Gaming.Input.ArcadeStick 和通用 Windows 平台 (UWP) 的相关 API 进行 Xbox One 街机摇杆编程的基本知识。This page describes the basics of programming for Xbox One arcade sticks using Windows.Gaming.Input.ArcadeStick and related APIs for the Universal Windows Platform (UWP).

在本页中,你将了解如下内容:By reading this page, you'll learn:

  • 如何收集相连街机摇杆及其用户的列表how to gather a list of connected arcade sticks and their users
  • 如何检测是否已添加或删除某街机摇杆how to detect that an arcade stick has been added or removed
  • 如何读取一个或多个街机摇杆的输入how to read input from one or more arcade sticks
  • 拱廊类棒如何表现为 UI 导航设备how arcade sticks behave as UI navigation devices

街机摇杆概述Arcade stick overview

要重现单独街机的感觉并实现其高精度数字控制,街机摇杆是尤为重要的输入设备。Arcade sticks are input devices valued for reproducing the feel of stand-up arcade machines and for their high-precision digital controls. 街机摇杆对于肉搏战和其他街机风格的游戏来说是完美的输入设备,并适合所有能正常使用全数字控件的游戏。Arcade sticks are the perfect input device for head-to-head-fighting and other arcade-style games, and are suitable for any game that works well with all-digital controls. 街机摇杆在 Windows 10 和 Xbox One UWP 应用中受 Windows.Gaming.Input 命名空间支持。Arcade sticks are supported in Windows 10 and Xbox One UWP apps by the Windows.Gaming.Input namespace.

Xbox One 拱廊类棒配有一个8向数字游戏杆,六个 操作 按钮 (表示为下图中的 A1-A6) ,两个 特殊 按钮 (表示为 S1 和 S2) ;它们是不支持模拟控件或振动的所有数字输入设备。Xbox One arcade sticks are equipped with an 8-way digital joystick, six Action buttons (represented as A1-A6 in the image below), and two Special buttons (represented as S1 and S2); they're all-digital input devices that don't support analog controls or vibration. Xbox One 拱廊类棒还配备了用于支持 UI 导航的 视图菜单 按钮,但它们并不用于支持游戏命令,也不能作为游戏杆按钮轻松访问。Xbox One arcade sticks are also equipped with View and Menu buttons used to support UI navigation but they're not intended to support gameplay commands and can't be readily accessed as joystick buttons.

带4个拱廊类的游戏杆,6个动作按钮 (A1-A6) ,2个特殊按钮 (S1 和 S2)

UI 导航UI navigation

为了减轻支持很多适用于用户界面导航的不同输入设备的负担并促进游戏和设备之间的一致性,大多数_物理_输入设备同时充当单独的称为 UI 导航控制器 的_逻辑_输入设备。In order to ease the burden of supporting many different input devices for user interface navigation and to encourage consistency between games and devices, most physical input devices simultaneously act as a separate logical input device called a UI navigation controller. UI 导航控制器可跨各种输入设备提供通用的 UI 导航命令词汇。The UI navigation controller provides a common vocabulary for UI navigation commands across input devices.

作为 UI 导航控制器,拱廊类棒将 所需的一组 导航命令映射到游戏杆和 视图菜单操作 1操作 2 按钮。As a UI navigation controller, arcade sticks map the required set of navigation commands to the joystick and View, Menu, Action 1, and Action 2 buttons.

导航命令Navigation command 街机摇杆输入Arcade stick input
向上Up 上摇杆Stick up
向下Down 下摇杆Stick down
LeftLeft 左摇杆Stick left
RightRight 右摇杆Stick right
查看View “视图”按钮View button
菜单Menu “菜单”按钮Menu button
接受Accept “操作 1”按钮Action 1 button
取消Cancel “操作 2”按钮Action 2 button

街机摇杆不会映射导航命令的任何 可选组Arcade sticks don't map any of the optional set of navigation commands.

检测和跟踪街机摇杆Detect and track arcade sticks

检测和跟踪拱廊类棒的工作方式与用于 gamepads 的方式完全相同,只是 ArcadeStick 类,而不是 游戏板 类。Detecting and tracking arcade sticks works in exactly the same way as it does for gamepads, except with the ArcadeStick class instead of the Gamepad class. 有关详细信息,请参阅游戏板和振动See Gamepad and vibration for more information.

读取街机摇杆Reading the arcade stick

确定感兴趣的街机摇杆之后,便可以从街机摇杆收集输入了。After you identify the arcade stick that you're interested in, you're ready to gather input from it. 但是,与你可能已习惯的某些其他输入类型不同,街机摇杆不会通过触发事件来表达状态更改。However, unlike some other kinds of input that you might be used to, arcade sticks don't communicate state-change by raising events. 相反,你需要通过对它们进行“轮询”__ 来定期读取其当前状态。Instead, you take regular readings of their current state by polling them.

轮询街机摇杆Polling the arcade stick

轮询会捕获街机摇杆在某个精确时间点的快照。Polling captures a snapshot of the arcade stick at a precise point in time. 此输入收集方法对于大多数游戏都非常适合,因为其逻辑通常按确定的循环运行,而不是受事件驱动;而且,相对于随着时间逐个收集许多单个输入解释游戏命令,从一次性收集的输入解释游戏命令,通常会更为简单。This approach to input gathering is a good fit for most games because their logic typically runs in a deterministic loop rather than being event-driven; it's also typically simpler to interpret game commands from input gathered all at once than it is from many single inputs gathered over time.

你通过调用 GetCurrentReading 来轮询街机摇杆;此功能会返回包含街机摇杆状态的 ArcadeStickReadingYou poll an arcade stick by calling GetCurrentReading; this function returns an ArcadeStickReading that contains the state of the arcade stick.

下面是轮询街机摇杆来获取其当前状态的示例。The following example polls an arcade stick for its current state.

auto arcadestick = myArcadeSticks[0];

ArcadeStickReading reading = arcadestick->GetCurrentReading();

除了街机摇杆状态之外,每个读数还包括一个时间戳,准确指出检索状态的时间。In addition to the arcade stick state, each reading includes a timestamp that indicates precisely when the state was retrieved. 该时间戳对于关联之前读数的时间或者游戏模拟的时间非常有用。The timestamp is useful for relating to the timing of previous readings or to the timing of the game simulation.

读取按钮Reading the buttons

每个 "拱廊类棒" 按钮 — 的四个游戏杆方向、六个 操作 按钮和两个 特殊 按钮都 — 提供数字读数,用于指示是 (按) 还是释放 () 。Each of the arcade stick buttons—the four directions of the joystick, six Action buttons, and two Special buttons—provides a digital reading that indicates whether it's pressed (down) or released (up). 为提高效率,按钮读数并不表示为单个布尔值;相反,它们全部打包为 ArcadeStickButtons 枚举表示的单个位域。For efficiency, button readings aren't represented as individual boolean values; instead, they're all packed into a single bitfield that's represented by the ArcadeStickButtons enumeration.


拱廊类棒配有用于 UI 导航的其他按钮,如 " 视图 " 和 " 菜单 " 按钮。Arcade sticks are equipped with additional buttons used for UI navigation such as the View and Menu buttons. 这些按钮不是 ArcadeStickButtons 枚举的一部分,只能作为 UI 导航设备通过访问街机摇杆进行读取。These buttons are not a part of the ArcadeStickButtons enumeration and can only be read by accessing the arcade stick as a UI navigation device. 有关详细信息,请参阅 UI 导航设备For more information, see UI Navigation Device.

ArcadeStickReading 结构的 Buttons 属性中读取按钮值。The button values are read from the Buttons property of the ArcadeStickReading structure. 因为此属性是位域,所以使用按位掩码隔离你感兴趣的按钮值。Because this property is a bitfield, bitwise masking is used to isolate the value of the button that you're interested in. 设置相应位时按钮为按下(向下);否则,按钮为释放(向上)。The button is pressed (down) when the corresponding bit is set; otherwise, it's released (up).

下面的示例确定是否按下了 " 操作 1 " 按钮。The following example determines whether the Action 1 button is pressed.

if (ArcadeStickButtons::Action1 == (reading.Buttons & ArcadeStickButtons::Action1))
    // Action 1 is pressed

下面的示例确定是否释放 " 操作 1 " 按钮。The following example determines whether the Action 1 button is released.

if (ArcadeStickButtons::None == (reading.Buttons & ArcadeStickButtons::Action1))
    // Action 1 is released (not pressed)

有时你可能需要确定:何时将按钮从按下转换为释放或从释放转换为按下,是按下还是释放多个按钮,或者是否按特定方式安排一组按钮(按下一些按钮,释放一些按钮)。Sometimes you might want to determine when a button transitions from pressed to released or released to pressed, whether multiple buttons are pressed or released, or if a set of buttons are arranged in a particular way—some pressed, some not. 有关如何检测这些状态的详细信息,请参阅检测按钮转换检测复杂按钮安排For information on how to detect these conditions, see Detecting button transitions and Detecting complex button arrangements.

运行 InputInterfacing 示例Run the InputInterfacing sample

InputInterfacingUWP 示例 (github) 演示了如何将街机摇杆和不同类型的输入设备配合使用,以及这些输入设备如何像 UI 导航控制器那样运行。The InputInterfacingUWP sample (github) demonstrates how to use arcade sticks and different kinds of input devices in tandem, as well as how these input devices behave as UI navigation controllers.

另请参阅See also