Sistema de Ação de Entrada

O sistema de Ação de Entrada multiplataforma permite conectar ações e arranjar vinculações em várias entradas de hardware em tempo de edição. Combinado com contextos, você pode facilmente configurar e editar um sistema de entrada modular que funciona em qualquer dispositivo em qualquer fase de jogo. Os casos de uso incluem:

• Um sistema de tiro em primeira pessoa com ações trocando dinamicamente dependendo se o jogador está no modo de batalha ou no modo espectador.
• Um sistema de direção abrangente equipado com aceleração/desaceleração, impulsionadores de carro e estações de reabastecimento.
• Teclas de atalho para um sistema de habilidades em um jogo de luta para mudar movimentos de forma suave sem que os jogadores deixem de dar um soco.

Contextos de entrada

Um InputContext é uma coleção de ações que mantém ações de entrada relacionadas, por exemplo, PlayContext para controles de personagem em jogo e NavContext para controles de navegação por menus de UI. Você pode ativar/desativar contextos (e suas respectivas ações) através de sua propriedade Enabled, como ativar o NavContext quando um menu de inventário está aberto e então mudar para o PlayContext quando o jogador fecha o menu e retorna à jogabilidade principal.

Mesmo que um jogo possa não usar múltiplos contextos de entrada inicialmente, é recomendado criar um contexto primário no nível superior de qualquer sistema de entrada, por exemplo, a instância PlayContext para entrada que ocorre durante a jogabilidade.

1. RECOMENDADO

   Crie uma Folder chamada Inputs dentro de ReplicatedStorage para armazenar vários contextos de entrada.

   

2. Insira um novo InputContext na pasta e renomeie-o para PlayContext.

   

3. Na janela de Propriedades, defina Priority para 2000 e ative Sink. Um contexto com Sink ativado consome eventos de entrada para seus KeyCodes vinculados em seu nível de prioridade, bloqueando essas entradas de alcançar contextos de menor prioridade. Isso é prático para casos de uso como uma tela de inventário que deve suprimir entradas de jogabilidade específicas enquanto está aberta. Neste exemplo, PlayContext recebe uma Priority alta o suficiente para afundar suas entradas vinculadas antes que os contextos padrão PlayerScripts as processem.

Ações de entrada

Um InputAction define uma mecânica de ação de jogabilidade como "Pular", "Correr" ou "Atirar". Essas ações são então mapeadas para entradas de hardware utilizando vinculações de entrada.

Um InputAction pode ter várias variações dependendo de sua propriedade Type (Enum.InputActionType). O padrão é Bool, projetado para receber valores true/false a partir do pressionamento/liberação de entradas, como ButtonA, E ou MouseLeftButton.

Para testar um InputAction para corrida simples do personagem:

1. Crie um novo InputAction dentro do contexto PlayContext em ReplicatedStorage. Renomeie-o para CharacterSprint para indicar sua ação dedicada.

   

2. Na janela de Propriedades, note que o Type da ação é Bool (padrão). Este é um tipo lógico para corrida simples de personagem como uma ação booleana true/false (o personagem está correndo ou não).

   

Vinculações de entrada

Um InputBinding define qual vinculação de hardware deve acionar o InputAction pai, como uma pressão de tecla, botão de gamepad ou toque em um dispositivo habilitado para toque. Para compatibilidade multiplataforma, cada InputAction deve ter um InputBinding para gamepad, teclado/mouse e toque, como ilustrado aqui.

O Type atribuído ao InputAction pai afeta diretamente quais tipos de entrada geral (tecla/botão/toque, gatilho analógico, thumbstick, etc.) são válidos para instâncias de InputBinding filhas. Por sua vez, os valores enviados aos eventos conectados da ação pai dependem do tipo de entrada escolhido para uma vinculação. Consulte eventos de entrada para detalhes sobre a correlação entre tipos de ação, vinculações e valores de retorno.

Para conectar vinculações para corrida simples do personagem:

1. Insira uma nova InputBinding na ação CharacterSprint e renomeie-a para KeyboardBinding. Então, defina a propriedade KeyCode da vinculação para LeftShift.

   

   

2. Para garantir que o bloqueio do mouse Shift não interfira na vinculação da tecla, selecione StarterPlayer no Explorer e desative a opção EnableMouseLockOption na janela de Propriedades.

   

   

3. Insira uma segunda InputBinding na ação CharacterSprint e renomeie-a para GamepadBinding. Então, defina a propriedade KeyCode da vinculação para ButtonY.

   

   

4. Dentro de um container ScreenGui dentro de StarterGui, crie um botão na tela, renomeie-o para SprintButton e posicione/redimensione conforme desejado.

   

5. Insira uma terceira InputBinding na ação CharacterSprint e renomeie-a para TouchBinding. Então, na janela de Propriedades, vincule a propriedade UIButton da vinculação ao botão SprintButton que você criou anteriormente dentro de StarterGui.

   

   

Eventos de entrada

A instância InputAction tem três eventos embutidos para lidar com a entrada do jogador proveniente de InputBindings.

• Pressed — Este evento é acionado apenas quando o Type de entrada está definido para Bool, e apenas quando o estado muda de false para true.
• Released — Este evento é acionado apenas quando o Type de entrada está definido para Bool, e apenas quando o estado muda de true para false.
• StateChanged — Este evento é acionado para todos os tipos de ações de entrada sempre que o estado muda, exceto se o estado tenta transitar para o mesmo estado.

Dependendo do Type da ação de entrada (Bool, Direction1D, Direction2D, Direction3D ou ViewportPosition) e o tipo de entrada geral proveniente de uma InputBinding filha (tecla/botão/toque, gatilho analógico, thumbstick, etc.), diferentes valores são retornados aos manipuladores de eventos Pressed, Released e StateChanged. Examine as tabelas a seguir para entender melhor a correlação.

O tipo Bool é melhor para ações acionadas, como pular, atirar, correr, etc., com suporte para limites pressionado/liberado em entradas analógicas.

Para conectar eventos para corrida simples do personagem:

1. Insira um novo Script na árvore CharacterSprint, ao lado das várias vinculações de entrada. Então, defina seu RunContext para Client e renomeie-o para OnActivate.

   

2. Cole o seguinte código no script OnActivate. Note a conexão do evento Pressed nas linhas 13‑15, que dobra a velocidade de caminhada do personagem quando uma vinculação de entrada de corrida é pressionada, e a correspondente conexão do evento Released nas linhas 16‑18, que redefine a velocidade de caminhada para o padrão quando uma vinculação de entrada de corrida é liberada.

   OnActivate (Cliente Script)
   local Players = game:GetService("Players")
   
   local player = Players.LocalPlayer
   local character = player.Character
   if not character or character.Parent == nil then
   	character = player.CharacterAdded:Wait()
   end
   local humanoid = character:WaitForChild("Humanoid")
   local defaultWalkSpeed = humanoid.WalkSpeed
   
   local inputAction = script.Parent
   
   inputAction.Pressed:Connect(function()
   	humanoid.WalkSpeed = defaultWalkSpeed * 2
   end)
   inputAction.Released:Connect(function()
   	humanoid.WalkSpeed = defaultWalkSpeed
   end)

3. Teste seu jogo e teste a ação de corrida do personagem com as vinculações que você escolheu anteriormente: LeftShift para teclado, ButtonY para gamepad, e o SprintButton na tela para dispositivos habilitados para toque. Lembre-se de que você pode usar o Emulador de Controlador para testar entradas de gamepad diretamente no Roblox Studio.

Alterações de contexto

Depois de ter um contexto de entrada como o PlayContext, você pode ativá-lo/desativá-lo durante a jogabilidade por meio de script, alterar sua Priority para determinar quais ações têm precedência sobre outras e Sink entradas para impedir que sejam processadas em contextos de menor prioridade.

1. Para facilitar a troca de contextos a partir de outros scripts, insira um novo BindableEvent em sua pasta de entradas dentro de ReplicatedStorage e renomeie-o para ContextEvent.

   

2. Crie um novo Script no mesmo nível, defina seu RunContext para Client, e renomeie-o para UpdateContext.

   

3. Dentro do script UpdateContext, cole o seguinte código:

   UpdateContext (Cliente Script)
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   -- Conectar evento vinculável
   contextEvent.Event:Connect(function(targetContext, enabled)
   	local context = inputsFolder:FindFirstChild(targetContext)
   	if context then
   		context.Enabled = enabled
   		print(context.Name .. ": " .. tostring(context.Enabled))
   	else
   		warn("InputContext não encontrado!")
   	end
   end)

4. Com o script UpdateContext em funcionamento, você pode agora atualizar um InputContext nomeado disparando o evento vinculável, por exemplo, a partir de um LocalScript que alimenta um GuiButton dentro de um container ScreenGui.

   

   Script do Botão
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   local button = script.Parent
   button.Activated:Connect(function()
   	-- Disparar evento vinculável com o contexto de entrada alvo e estado ativo
   	contextEvent:Fire("PlayContext", true)
   end)

Vinculações padrão

O Roblox fornece vinculações de entrada padrão para movimento, controle de câmera e interação básica com o ambiente — os jogadores do Roblox estão familiarizados com esses controles, portanto, você deve sobrescrevê-los apenas em casos específicos. Também note que as entradas reservadas não podem ser sobrescritas e sempre funcionarão com seu propósito pretendido.