Sistema de Ação de Entrada

O Sistema de Ação de Entrada multiplataforma permite que você conecte ações e organize vinculações em vários dispositivos de hardware durante o 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. Exemplos de uso incluem:

• Um sistema de tiro em primeira pessoa com ações que trocam 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, impulso de carro e estações de reabastecimento.
• Teclas de atalho para um sistema de habilidades em um jogo de luta para trocar movimentos sem que os jogadores percam um soco.

Contextos de entrada

Um InputContext é uma coleção de ações que contém ações de entrada relacionadas, por exemplo, PlayContext para controles de personagem no jogo e NavContext para controles de navegação em menus de UI. Você pode ativar/desativar contextos (e suas ações correspondentes) através da propriedade Enabled, como ativar o NavContext quando um menu de inventário está aberto e depois mudar para o PlayContext quando o jogador fecha o menu e retorna ao jogo 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 entradas que ocorrem durante o jogo.

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. OPCIONAL

   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 prioridade inferior. Isso é prático para casos de uso como uma tela de inventário que deve suprimir entradas específicas de jogo enquanto está aberta. Neste exemplo, o 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 jogo, como "Pular", "Correr" ou "Atirar". Essas ações são então mapeadas para entradas de hardware usando 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 da pressão/liberação de entradas como ButtonA, E ou MouseLeftButton.

Para testar um InputAction para corrida simples do personagem:

1. RECOMENDADO

   Selecione o objeto Workspace de nível superior no Explorer e, em seguida, na janela de Propriedades, defina a propriedade PlayerScriptsUseInputActionSystem para Enabled.

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

   

3. Na janela de Propriedades, observe que o Type da ação é Bool (padrão). Este é um tipo lógico para corrida simples do 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, por exemplo, uma pressão de tecla, botão de gamepad ou toque em um dispositivo com tela sensível ao 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 gerais (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 para os eventos conectados da ação pai dependem do tipo de entrada escolhido em uma vinculação. Veja 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 um novo InputBinding na ação CharacterSprint e renomeie-o para KeyboardBinding. Em seguida, defina a propriedade KeyCode da vinculação para LeftShift.

   

   

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

   

   

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

   

4. Insira uma terceira InputBinding na ação CharacterSprint e renomeie-a para TouchBinding. Em seguida, 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 possui três eventos integrados para lidar com a entrada do jogador proveniente de InputBindings.

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

Dependendo do Type da ação de entrada (Bool, Direction1D, Direction2D, Direction3D ou ViewportPosition) e do tipo de entrada geral proveniente de uma InputBinding filha (tecla/botão/toque, gatilho analógico, thumbstick, etc.), diferentes valores são retornados para os 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 limiares pressionados/liberados 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. Em seguida, defina seu RunContext para Client e renomeie-o para OnActivate.

   

2. Cole o seguinte código no script OnActivate. Observe 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 conexão do evento Released correspondente nas linhas 16‑18, que redefine a velocidade de caminhada para o padrão quando uma vinculação de entrada de corrida é liberada.

   OnActivate (Script do Cliente)

   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 botão na tela SprintButton para dispositivos com tela sensível ao toque. Lembre-se de que você pode usar o Emulador de Controlador para testar entradas de gamepad diretamente no Roblox Studio.

Mudanças de contexto

Uma vez que você tenha um contexto de entrada como PlayContext, você pode ativá-lo/desativá-lo durante o jogo através de scripts, mudar sua Priority para determinar quais ações têm precedência sobre outras e Sink entradas para que não sejam processadas dentro de contextos de prioridade inferior.

1. Para facilitar a troca de contextos a partir de outros scripts, insira um novo BindableEvent na 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 (Script do Cliente)

   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 contêiner 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 ativado
   	contextEvent:Fire("PlayContext", true)
   end)

Gerenciador de Ação de Entrada

A ferramenta Gerenciador de Ação de Entrada é uma interface unificada, estilo matriz, para projetar, auditar e escalar sua arquitetura de entrada.

Para acessá-la, navegue até o menu Janela no Studio e selecione Entrada ⟩ Gerenciador de Ação de Entrada. Se seu jogo já usa contextos, ações ou vinculações de entrada, o gerenciador irá automaticamente escanear o DataModel e extrair essas instâncias existentes para a grade do editor. Qualquer nova instância relacionada à entrada será automaticamente populada em uma pasta Inputs dentro de ReplicatedStorage.

Para configurar uma configuração de entrada para corrida do personagem conforme descrito nas seções acima:

1. RECOMENDADO

   Selecione o objeto Workspace de nível superior no Explorer e, em seguida, na janela de Propriedades, defina a propriedade PlayerScriptsUseInputActionSystem para Enabled.

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

   

3. No Gerenciador de Ação de Entrada, passe o mouse sobre o cabeçalho da coluna Contexto e clique no botão ＋. Insira um nome apropriado para o novo contexto, como PlayContext, e pressione Enter. Um InputContext com o nome correspondente aparece em ReplicatedStorage.

   

   

4. Passe o mouse sobre o novo contexto e clique no botão ＋. No menu pop-up, selecione Bool, insira CharacterSprint para o nome da ação e pressione Enter. Um InputAction com o nome correspondente aparece sob o contexto.

   

   

5. Na nova linha CharacterSprint, atribua vinculações para cada tipo de entrada:

   1. Teclado e Mouse — Clique no botão de seta e selecione LeftShift no menu de seleção.
   2. Toque — Clique na célula e, em seguida, na hierarquia do Explorer, clique no objeto SprintButton que você inseriu anteriormente no ScreenGui.
   3. Gamepad — Clique no botão de seta e selecione ButtonY no menu de seleção.

   

   Ao atribuir vinculações, fique atento a ícones de aviso/erro na interface do usuário. Avisos amarelos (⚠) indicam uma vinculação faltando para compatibilidade multiplataforma, enquanto avisos vermelhos (⚠) indicam uma vinculação duplicada para ações dentro do mesmo contexto.

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

   

7. Cole o seguinte código no script OnActivate. Observe 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 conexão do evento Released correspondente nas linhas 16‑18, que redefine a velocidade de caminhada para o padrão quando uma vinculação de entrada de corrida é liberada.

   OnActivate (Script do Cliente)

   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)