游戏手柄输入

Roblox 接受 Xbox 和 PlayStation 控制器等 USB 游戏手柄的输入。由于游戏手柄有不同的种类，您需要遵循额外的设置来验证玩家的游戏手柄输入是否在您的体验中可用。

要设置游戏手柄输入，您可以使用或来检测连接到玩家设备的游戏手柄，验证与 Roblox 兼容的支持输入 > ，接收输入 > 等等。

当绑定游戏手柄输入时，请参阅常见控制图以创建一致的游戏手柄体验给玩家。在输入设置后，您可以通过包含触觉反馈在支持的控制器上增强玩家的体验。

检测游戏板

您可以使用 UserInputService.GamepadEnabled 属性检测玩家的设备目前是否有游戏手柄激活。

检测游戏机
local UserInputService = game:GetService("UserInputService")

if UserInputService.GamepadEnabled then
	print("Player has gamepad enabled...")
end

您可以通过 UserInputService.GamepadConnected 和 UserInputService.GamepadDisconnected 事件检查连接的游戏手柄。当设备连接或断开时，这些事件会发生，两个事件都会向连接的函数传递 Enum.UserInputType 指示哪个游戏手柄导致事件。在大多数情况下，连接的游戏手柄是 Gamepad1 。

检查连接和断开连接
local UserInputService = game:GetService("UserInputService")

UserInputService.GamepadConnected:Connect(function(gamepad)
	print("User has connected controller: " .. tostring(gamepad))
end)

UserInputService.GamepadDisconnected:Connect(function(gamepad)
	print("User has disconnected controller: " .. tostring(gamepad))
end)

您还可以使用 UserInputService:GetGamepadConnected() 方法查询特定控制器是否使用连接方法连接。这需要一个 Enum.UserInputType 作为参数，只接受 Gamepad1 通过 Gamepad8 的值。

查询特定游戏手柄连接
local UserInputService = game:GetService("UserInputService")

if UserInputService:GetGamepadConnected(Enum.UserInputType.Gamepad1) then
	print("Gamepad1 is connected")
elseif UserInputService:GetGamepadConnected(Enum.UserInputType.Gamepad2) then
	print("Gamepad2 is connected")
end

验证支持的输入

由于游戏手柄可以有不同的输入集，你应该检查哪些输入支持 UserInputService:GetSupportedGamepadKeyCodes() 。该方法接受 Enum.UserInputType 作为参数，并返回一个包含指定控制器所有可用输入列表的表。

验证支持的输入
local UserInputService = game:GetService("UserInputService")

local availableInputs = UserInputService:GetSupportedGamepadKeyCodes(Enum.UserInputType.Gamepad2)

print("This controller supports the following controls:")
for _, control in availableInputs do
	print(control)
end

接收输入

ContextActionService 对于绑定控件到游戏手柄和其他输入源，例如鼠标和键盘输入或移动触摸屏按钮，或对于绑定多个函数到单个按钮输入任何设备上，都有用。例如，以下代码示例将OpenSpellBook行动绑定到游戏手柄的ButtonR2按钮和键盘的B键。

上下文行动服务绑定行动
local ContextActionService = game:GetService("ContextActionService")

local function openSpellBook(actionName, inputState, inputObject)
	if inputState == Enum.UserInputState.Begin then
		-- 打开法术书
	end
end

ContextActionService:BindAction("OpenSpellBook", openSpellBook, false, Enum.KeyCode.ButtonR2, Enum.KeyCode.B)

绑定到的函数将在所有输入状态（、和）上发射，因此建议您检查第 4 行中看到的》以确保所需的操作仅发生在您打算使用游戏手柄输入状态上。

或者，你可以使用 UserInputService 从游戏手柄直接绑定控件。通过此服务检测游戏手柄事件时，使用 InputBegan 事件检测按钮初始压下时间以及 InputEnded 检测按钮释放时间。在处理函数中，InputObject.UserInputType 属性表示哪个游戏手柄发射了事件，InputObject.KeyCode 表示发射它的特定按钮或棍子。

用户输入服务按钮压力检测
local UserInputService = game:GetService("UserInputService")

UserInputService.InputBegan:Connect(function(input)
	if input.UserInputType == Enum.UserInputType.Gamepad1 then
		if input.KeyCode == Enum.KeyCode.ButtonA then
			print("Button A pressed on Gamepad1")
		end
	end
end)

游戏手柄状态

您可以使用 UserInputService:GetGamepadState() 方法检测游戏手柄上所有按钮和棍子的当前状态。如果您需要在体验中检查当前游戏手柄输入时发生独特事件，例如检查角色触碰物对象时是否按下特定按钮，这很有用。

检查游戏手柄输入状态
local Players = game:GetService("Players")
local UserInputService = game:GetService("UserInputService")

local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local leftFoot = character:WaitForChild("LeftFoot")

-- 当左脚接触到某物时，检查游戏手柄输入状态
leftFoot.Touched:Connect(function(hit)
	local state = UserInputService:GetGamepadState(Enum.UserInputType.Gamepad1)
	for _, input in state do

		-- 如果 ButtonR2 当前持有，打印出一条信息
		if input.KeyCode == Enum.KeyCode.ButtonR2 and input.UserInputState == Enum.UserInputState.Begin then
			print("Character's left foot touched something while holding right trigger")
		end
	end
end)

触发压力

您可以通过检查输入触发器的 Position.Z 值来检测游戏手柄触发器受到多少压力。

测试触发压力
local UserInputService = game:GetService("UserInputService")

UserInputService.InputChanged:Connect(function(input)
	if input.UserInputType == Enum.UserInputType.Gamepad1 then
		if input.KeyCode == Enum.KeyCode.ButtonL2 then
			print("Pressure on left trigger has changed:", input.Position.Z)
		elseif input.KeyCode == Enum.KeyCode.ButtonR2 then
			print("Pressure on right trigger has changed:", input.Position.Z)
		end
	end
end)

常用控制模型

游戏手柄有各种形状和尺寸。与玩家输入的任何方法一样，最好在不同游戏和体验中创建一些一致性。

以下是常见的输入绑定，可以立即帮助玩家感觉熟悉并舒适地使用游戏手柄控制：

输入	常见使用案例
ButtonA	接受玩家提示或图形界面选择。也可用于主要操作，例如跳跃。
ButtonB	取消玩家提示或图形用户界面选择。也可用于次要动作，例如闪避、滚动或冲刺。
Thumbstick1	一般与角色移动相关。
Thumbstick2	一般与相机移动相关。
ButtonL2 , ButtonR2	一般用于主要操作，例如射击。
ButtonL1 , ButtonR1 , ButtonX , ButtonY	次要操作，例如重新加载、瞄准或访问库存或小地图。

触觉反馈

许多游戏手柄控制器内置了马达，用于提供触觉反馈。添加隆隆声和振动可以大幅提升玩家的体验，并提供超出视觉或音频的微妙反馈。您可以使用 HapticService 来验证振动支持之前启动发动机 .

振动协助

不是所有控制器都有马达，因此在尝试使用触觉马达之前检查支持很重要。要查询是否给定的控制器具有振动协助，请拨打 HapticService:IsVibrationSupported() 。

检查振动支持
local HapticService = game:GetService("HapticService")

local gamepad = Enum.UserInputType.Gamepad1
local isVibrationSupported = HapticService:IsVibrationSupported(gamepad)

一些控制器具有多个马达，用于各种振动强度。一旦您检查了游戏手柄是否支持振动，您还应该检查它是否支持您通过 HapticService:IsMotorSupported() 使用的电机。

检查支持的电机
local HapticService = game:GetService("HapticService")

local gamepad = Enum.UserInputType.Gamepad1
local isVibrationSupported = HapticService:IsVibrationSupported(gamepad)

if isVibrationSupported then
	local largeMotor = HapticService:IsMotorSupported(gamepad, Enum.VibrationMotor.Large)
	local smallMotor = HapticService:IsMotorSupported(gamepad, Enum.VibrationMotor.Small)
	local leftTriggerMotor = HapticService:IsMotorSupported(gamepad, Enum.VibrationMotor.LeftTrigger)
	local rightTriggerMotor = HapticService:IsMotorSupported(gamepad, Enum.VibrationMotor.RightTrigger)
	local leftHandMotor = HapticService:IsMotorSupported(gamepad, Enum.VibrationMotor.LeftHand)
	local rightHandMotor = HapticService:IsMotorSupported(gamepad, Enum.VibrationMotor.RightHand)
end

大小或位置	描述
Large	更大的汽油机，对于通用隆隆有用。
Small	更小的马达，对于更隐秘的噪音，例如轮胎滑动、电击等有用
LeftTrigger	在左触发器下。
RightTrigger	在右侧触发器下。
LeftHand	在控制器的左侧。
RightHand	在控制器的右侧。

激活马达

一旦您确认玩家的游戏手柄支持振动，您可以通过 HapticService:SetMotor() 启动特定的电机。这个方法接受游戏手柄和振动幅度作为参数。幅度可以是 0 和 1 之间的任何值。

激活电机
local HapticService = game:GetService("HapticService")

local gamepad = Enum.UserInputType.Gamepad1
local isVibrationSupported = HapticService:IsVibrationSupported(gamepad)

if isVibrationSupported then
	local largeMotor = HapticService:IsMotorSupported(gamepad, Enum.VibrationMotor.Large)
	if largeMotor then
		HapticService:SetMotor(gamepad, Enum.VibrationMotor.Large, 0.5)
	end
end

控制器模拟

控制器模拟器让你在工作室中准确模拟游戏手柄输入默认控制器是通用游戏手柄，但您可以在左上角的选择菜单中选择 PlayStation、Xbox 和 Quest 设备的替代方案。

Emulate Device Controllers button indicated in Test tab

View of the generic controller in the Controller Emulator.

在游戏测试时，您可以使用鼠标控制虚拟控制器来控制体验。

您还可以单击右上角的编辑映射以查看并编辑虚拟控制器的键映射，例如 E 到 ButtonL2 或 9 到 ButtonA 。这些映射与其他 Studio 设置一样保存（每个控制器、每个用户、每台计算机），在模拟器窗口和 3D 视图中都翻译为游戏手柄事件。

在此页面