Read this manual in English

::: 注意 建议首先熟练掌握 Defold 中常规输入的消息处理方式, 例如输入消息获取以及脚本间输入消息广播顺序等. 关于输入系统详情请见 输入系统教程. :::

Gamepads

游戏手柄触发器可以绑定标准手柄输入到游戏功能的映射. 游戏手柄可以绑定:

• 左右摇杆 (方向和按下)
• 手柄按钮. 通常右手柄 Xbox 为 “A”, “B”, “X” 和 “Y”, Playstation 为 “方块”, “圆圈”, “三角” 和 “十叉”.
• 方向按钮.
• 左右肩按钮.
• 开始, 后退, 暂停按钮

::: 注意 下面的例子中使用了上图的映射绑定配置. 映射与命名可以根据项目需要自由设置. :::

十字键

十字键可以生成按下, 抬起和连按消息. 获取十字键消息的方法如下 (按下和抬起):

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lpad_left") then
        if action.pressed then
            -- 向左移动
        elseif action.released then
            -- 停止移动
        end
    end
end

摇杆

摇杆拨动到阈值以外就可以持续生成输入消息 (阈值配置见下文). 获取摇杆消息的方法如下:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") then
        -- 左摇杆向下拨动
        print(action.value) -- 取值范围 0.0 到 -1.0
    end
end

摇杆处于某方向极值的时候还会生成按下和抬起消息. 这样类似十字键的消息很适合用作方向导航:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") and action.pressed then
        -- 左摇杆向下拨动到头
    end
end

多手柄

Defold 基于其宿主操作系统支持多个手柄, 事件里 gamepad 项对应手柄输入来源:

function on_input(self, action_id, action)
    if action_id == hash("gamepad_start") then
        if action.gamepad == 0 then
          -- 手柄0号玩家申请加入游戏
        end
    end
end

Connect 和 Disconnect

游戏手柄还有 Connected 和 Disconnected 两种事件用以通知手柄的连接(包括一开始就连着的手柄)和断开.

function on_input(self, action_id, action)
    if action_id == hash("gamepad_connected") then
        if action.gamepad == 0 then
          -- 手柄0号已连接
        end
    elseif action_id == hash("gamepad_dicconnected") then
        if action.gamepad == 0 then
          -- 手柄0号已断开
        end
    end
end

手柄原始数据

(更新于 Defold 1.2.183)

手柄输入绑定提供了一个 Raw 事件给出按键, 十字键或者摇杆的原始 (不使用阈值) 数据.

function on_input(self, action_id, action)
    if action_id == hash("raw") then
        pprint(action.gamepad_buttons)
        pprint(action.gamepad_axis)
        pprint(action.gamepad_hats)
    end
end

手柄配置文件

在 Windows 上, 只支持 XBox 360 兼容手柄. 安装方法请见 http://www.wikihow.com/Use-Your-Xbox-360-Controller-for-Windows

每种手柄分别对应一份映射文件, 可以在 gamepads 配置文件中设置. Defold 自带一个通用的手柄映射配置文件:

如需自定义文件, 可以配合使用这个工具:

Click to download gdc.zip.

这个工具包含 Windows, Linux 和 macOS 的可运行文件. 命令行启动方法:

./gdc

这个工具通过收集连接控制器的输入自动生成映射文件. 新的映射文件可以在 “game.project” 里进行指定或者混合使用:

未映射手柄

(更新于 Defold 1.2.186)

如果手柄没有配置消息映射的话, 就只有 “connected”, “disconnected” 和 “raw” 三种事件. 这种情况下只能使用手柄原始数据来控制游戏.

HTML5上的游戏手柄

HTML5平台同样支持游戏手柄, 效果和原生应用一样. 游戏手柄的支持基于 标准游戏手柄API, 并且受绝大多数浏览器支持 (详见此图表). 万一遇到不支持的浏览器 Defold 会忽略所有游戏手柄的操作. 可以通过检查浏览器的navigator对象中是否存在getGamepads函数来判断其是否支持游戏手柄:

local function supports_gamepads()
    return not html5 or (html5.run('typeof navigator.getGamepads === "function"') == "true")
end
if supports_gamepads() then
    print("Platform supports gamepads")
end

运行在 iframe 上的游戏要确保 iframe 的 gamepad 权限已被开启:

<iframe allow="gamepad"></iframe>

安卓手柄

(更新于 Defold 1.2.183)

Android 和其他平台一样支持手柄的输入事件. 手柄支持基于 Android 按键和运动事件输入系统. 通过上文提到的 gamepad 文件把安卓输入事件转化成 Defold 手柄事件.

安卓手柄输入按键到 gamepad 文件手柄事件对应表如下:

(Android KeyEvent 定义)

(Android MotionEvent 定义)

为了正确使用手柄事件映射请参考上表以及 Google Play Store 上的手柄映射测试小工具.