游戏手柄

要求

• 游戏手柄在 Corona Simulator for macOS 或 Windows、Win32 桌面应用程序以及 Android 设备上受支持。

• 受支持的游戏手柄。Corona Simulator for macOS 支持大多数游戏手柄，但有些手柄需要额外的设置。测试过的游戏手柄包括

  • Xbox 360 游戏手柄（有线或无线并带 PC 接收器）。此游戏手柄需要 360Controller 驱动程序。
  • Xbox One 游戏手柄。此游戏手柄需要 Xone-OSX 驱动程序。
  • DualShock 4/3/2/1（PlayStation 游戏手柄）。这些游戏手柄开箱后即可使用，但它们的按键绑定各不相同。
  • 各种罗技/普通 PC 游戏手柄，均在测试中没有出现问题。但是，按键绑定在不同设备之间差异很大。

• 本指南配套“Pew Pew!”示例应用，它利用了所有游戏手柄 API。你可以从我们的 GitHub 存储库 下载它。

查询设备

首先要使用的 API 是 system.getInputDevices()，它返回所有检测到的输入设备的列表。不过，请注意平台之间的以下差异

• 在 Android 上，此调用返回所有已连接的输入设备，包括触摸屏、手柄、键盘等。
• 在 macOS 上，此调用仅返回摇杆/游戏手柄。
• 在 Windows 上，此调用返回所有 DirectInput 和 XInput 设备。

基本上，当一个应用程序启动时，你可以检查设备的按键绑定是否已存储

local inputDevices = system.getInputDevices()

for i = 1,#inputDevices do
    local device = inputDevices[i]
    print( device.descriptor )
end

实际上，system.getInputDevices() 返回的列表中的每个条目都是 InputDevice 的一个实例。你可以查询它以获取有关设备的信息，例如

• object.descriptor 属性指示会话/运行期间的手柄标识符。如果断开了相同设备然后又重新连接，它将具有相同的 descriptor 值，但这并不意味着 descriptor 在会话/运行之间保持不变。在后续的会话/运行中，手柄可能会具有不同的 descriptor 值。

• object.displayName 由操作系统报告。你可以显示此信息，以便用户可以识别正在使用的游戏手柄。

• 你还可以通过 object:getAxes() 方法查询 InputDevice 对象的状态，或使用 object:vibrate() 函数使其振动。请参阅 文档 以获取完整属性和方法列表。

连接/断开手柄

每当控制器连接或断开连接时，inputDeviceStatus 事件便会被触发。以下示例显示如何处理此事件

local function onInputDeviceStatusChanged( event )
    
    if ( event.connectionStateChanged ) then
        if ( event.device.isConnected ) then
            -- Device has been connected
        else
            -- Connection has been lost
        end
    end
end

Runtime:addEventListener( "inputDeviceStatus", onInputDeviceStatusChanged )

在侦听器函数中，event 表格包含有关收到状态更改的设备的以下属性

• event.connectionStateChanged — Boolean 值，表示设备与系统的连接是否已更改。
• event.device — 返回具有各种属性的 InputDevice 对象。
• event.name — String 值为 "inputDeviceStatus"。
• event.reconfigured — 表示设备是否已重新配置的 Boolean 值。

处理手柄输入

作为输入结果，游戏手柄会产生两类事件：axis 和 key。

在 macOS 和 Windows 中，key 事件的 event.device 属性将为 nil。如果此事件来自虚拟输入设备（例如虚拟键盘），则在 Android 中它也可能为 nil。

以下示例显示了如何检测特定手柄。当触发 axis 或 key 事件时，会调用 setDevice() 函数来设置 event.device 和 InputDevice displayName。

local controller = { device="", displayName="" }

--Predeclare
local onKeyEvent
local onAxisEvent

local function setDevice( device, displayName )

    -- Set current controller
    controller["device"] = device
    controller["displayName"] = displayName

    -- Remove event listeners
    Runtime:removeEventListener( "axis", onAxisEvent )
    Runtime:removeEventListener( "key", onKeyEvent )
end

function onKeyEvent( event )
    setDevice( event.device, event.device.displayName )
end

function onAxisEvent( event )
    if ( math.abs(event.normalizedValue) > 0.5 ) then
        setDevice( event.device, event.device.displayName )
    end
end

Runtime:addEventListener( "axis", onAxisEvent )
Runtime:addEventListener( "key", onKeyEvent )

总结

• 游戏手柄在 Corona Simulator for macOS 或 Windows、Win32 桌面应用程序以及 Android 设备上受支持。

• 可以使用以下事件来实现游戏手柄支持

  • axis 事件会在每次游戏手柄轴改变位置时触发，而 event.normalizedValue 通常应用于访问其位置。
  • key 事件会为每个按钮/键按下报告 event.keyName 和 "down" 或 "up" 的 event.phase。
  • inputDeviceStatus 事件会在每次连接、断开连接或重新配置某个设备时触发。
• 上述三个事件均引用生成事件的 InputDevice，可通过 event.device 访问。
  • 如果设备是系统键盘，event.device 可为 nil。
  • 使用 object.descriptor 识别会话内的设备，而 object.displayName 获得操作系统报告的可读设备名称。

• 要列出已知游戏控制器，请使用 system.getInputDevices() 函数。

• 最好累计轴变化并在稍后执行操作，例如在运行时 "enterFrame" 侦听器中，类似于 示例应用程序 方法。

参考