Entrada do gamepad

O Roblox aceita a entrada de gamepads USB, como o Xbox e os controladores da PlayStation.Como os gamepads vêm em diferentes variedades, você precisa seguir uma configuração adicional para verificar se as entradas do gamepad de um jogador são utilizáveis em sua experiência.

Para configurar as entradas do gamepad, você pode usar ContextActionService ou UserInputService para detectar gamepads conectados para o dispositivo de um jogador , verificar entradas compatíveis com o Roblox que são compatíveis com o Roblox, receber entrada e muito mais.

Ao vincular as entradas do gamepad, veja esquemas de controle comuns para criar uma experiência de gamepad consistente para os jogadores.Depois que os inputs forem configurar, você pode melhorar a experiência do jogador incluindo feedback háptico em controladores suportados.

Detectar controladores de jogos

Você pode detectar se o dispositivo de um jogador atualmente tem um gamepad ativo usando a propriedade UserInputService.GamepadEnabled.

Detectando Controlador de Jogo
local UserInputService = game:GetService("UserInputService")

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

Você pode verificar gamepads conectados via UserInputService.GamepadConnected e UserInputService.GamepadDisconnected eventos.Esses eventos ativam quando um dispositivo é conectado ou desconectado, respectivamente, e ambos os eventos passam um Enum.UserInputType para a função conectada indicando qual gamepad causou o evento.Na maioria dos casos, o gamepad conectado é Gamepad1 .

Verificando Conexão e Desconexão
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)

Você também pode consultar se um controlador específico está conectado usando o método UserInputService:GetGamepadConnected().Isso leva um Enum.UserInputType como argumento e só aceita valores de Gamepad1 através de Gamepad8 .

Conexão específica de gamepad de consulta
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

Verifique as entradas suportadas

Como os gamepads podem ter diferentes conjuntos de entradas, você deve verificar quais entradas são suportadas com UserInputService:GetSupportedGamepadKeyCodes() .Este método toma um Enum.UserInputType como argumento e retorna uma tabela com uma lista de todos os inputs disponíveis para o Controleespecificado.

Verificando Entradas Suportadas
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

Receber entrada

ContextActionService é útil para vincular controles a ambos os gamepads e outras fontes de entrada, como mouse e teclado ou toque móvel na tela de toque, ou para vincular várias funções a um único botão de entrada em qualquer dispositivo.Por exemplo, o seguinte código de exemplo vincula uma ação OpenSpellBook à tecla do controle / controle de jogoButtonR2 e à tecla do teclado B.

Ação de vinculação do ContextActionService
local ContextActionService = game:GetService("ContextActionService")

local function openSpellBook(actionName, inputState, inputObject)
	if inputState == Enum.UserInputState.Begin then
		-- Livro de feitiços aberto
	end
end

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

Alternativamente, você pode usar UserInputService para vincular controles diretamente de um controle / controle de jogo.Ao detectar eventos de gamepad através deste serviço, use o evento InputBegan para detectar quando o botão foi pressionado inicialmente e InputEnded para detectar quando o botão é liberado.Na função de manipulação, a propriedade InputObject.UserInputType indica qual gamepad disparou o evento e InputObject.KeyCode indica o botão ou graveto específico que o disparou.

Detecção de pressão de botão do serviço de entrada do usuário
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)

Estado do gamepad

Você pode detectar o estado atual de todos os botões e gravetos em um gamepad com o método UserInputService:GetGamepadState().Isso é útil se você precisar verificar as entradas atuais do gamepad quando um evento distinto ocorrer em sua experiência, como verificar se botões específicos estão sendo pressionados quando um personagem toca em um Objeto.

Verificando Estado de Entradas de Gamepad
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")

-- Quando o pé esquerdo entra em contato com algo, verifique o estado de entrada do gamepad
leftFoot.Touched:Connect(function(hit)
	local state = UserInputService:GetGamepadState(Enum.UserInputType.Gamepad1)
	for _, input in state do

		-- Se o ButtonR2 estiver atualmente segurado, imprima uma mensagem
		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)

Ativar pressão

Você pode detectar quanta pressão está sendo aplicada aos gatilhos do gamepad verificando o valor Position.Z da entrada do gatilho.

Testando a Pressão do Gatilho
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)

Esquemas de controle comuns

Os gamepads vêm em uma variedade de formas e tamanhos.Como com qualquer método de entrada do jogador, é melhor criar alguma consistência entre diferentes jogos e experiências.

Os seguintes são comuns vinculações de entrada que ajudarão os jogadores a se sentirem familiarizados e confortáveis imediatamente com os controles do gamepad:

Feedback comentário/retorno

Muitos controladores de gamepad têm motores construídos para fornecer comentário/retornoháptico.Adicionar roncos e vibrações pode melhorar muito a experiência de um jogador e fornecer feedback sutil além de visuais ou áudio.Você pode usar o HapticService para verificar o suporte à vibração antes de ligar os motores.

Suporte de vibração

Nem todos os controladores têm motores, por isso é importante verificar o suporte antes de tentar usar os motores hapticos.Para consultar se um determinado controlador tem Suporteà vibração, chame HapticService:IsVibrationSupported() .

Verificar Suporte à Vibração
local HapticService = game:GetService("HapticService")

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

Alguns controladores têm motores múltiplos para várias escalas de vibração.Depois de verificar se um gamepad suporta vibração, você também deve verificar se ele suporta os motores que você pretende usar através de HapticService:IsMotorSupported() .

Verifique os Motores Suportados
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

Ativar motores

Uma vez que você confirmou que o gamepad de um jogador suporta vibração, você pode ligar um motor específico com HapticService:SetMotor() .Este método pega o gamepad e a amplitude da vibração como argumentos.A amplitude pode ser qualquer valor entre 0 e 1.

Ativando o Motor
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

Emulação de controlador

O Emulador de Controlador permite que você simule com precisão a entrada do gamepad diretamente no Studio.O controlador padrão é um controle / controle de jogogenérico, mas você pode selecionar alternativas para PlayStation, Xbox e dispositivos Quest no menu de seleção à esquerda superior.

Durante o teste do jogo, você pode controlar a experiência com o controlador virtual usando seu mouse.

Você também pode clicar em Editar mapeamentos no canto superior direito para ver e editar mapas de chave para o Controlevirtual, por exemplo E para ButtonL2 ou 9 para ButtonA .Esses mapeamentos são salvos como outras configurações do Studio (por Controle, por usuário, por computador) e são traduzidos para eventos de gamepad na janela do emulador e na janela de visualização 3D.