Sistema de Acción de Entrada

El sistema de acción de entrada multiplataforma Input Action System te permite conectar acciones y organizar enlaces a través de varias entradas de hardware en el tiempo de edición. Combinado con contextos, puedes configurar y editar fácilmente un sistema de entrada modular que funcione en cualquier dispositivo en cualquier fase de juego. Los casos de uso incluyen:

• Un sistema de disparos en primera persona con acciones que cambian dinámicamente dependiendo de si el jugador está en modo de batalla o en modo espectador.
• Un sistema de conducción integral equipado con aceleración/desaceleración, potenciadores de coche y estaciones de repostaje.
• Teclas de acceso rápido para un sistema de habilidades en un juego de lucha para cambiar movimientos sin problemas sin que los jugadores se pierdan un golpe.

Contextos de entrada

Un InputContext es una colección de acciones que contiene acciones de entrada relacionadas, por ejemplo, PlayContext para controles de personajes en el juego y NavContext para controles para navegar por los menús de la interfaz de usuario. Puedes habilitar/deshabilitar contextos (y sus acciones correspondientes) a través de su propiedad Enabled, como habilitar el NavContext cuando un menú de inventario está abierto y luego cambiar al PlayContext cuando el jugador cierra el menú y regresa al juego principal.

Incluso si un juego no utiliza múltiples contextos de entrada inicialmente, se recomienda crear un contexto primario en el nivel superior de cualquier sistema de entrada, por ejemplo, la instancia PlayContext para la entrada que ocurre durante el juego.

1. RECOMENDADO

   Crea una Folder llamada Inputs dentro de ReplicatedStorage para contener varios contextos de entrada.

   

2. Inserta un nuevo InputContext en la carpeta y renómbralo a PlayContext.

   

3. OPCIONAL

   En la ventana de Propiedades, establece Priority en 2000 y habilita Sink. Un contexto con Sink habilitado consume eventos de entrada para sus KeyCodes vinculados a su nivel de prioridad, bloqueando esas entradas de llegar a contextos de menor prioridad. Esto es práctico para casos de uso como una pantalla de inventario que debería suprimir entradas específicas del juego mientras está abierta. En este ejemplo, se le da a PlayContext una Priority lo suficientemente alta como para hundir sus entradas vinculadas antes de que los contextos predeterminados de PlayerScripts las procesen.

   

Acciones de entrada

Un InputAction define una mecánica de acción de juego como "Saltar", "Correr" o "Disparar". Estas acciones se asignan a entradas de hardware utilizando enlaces de entrada.

Un InputAction puede ser de varias variaciones dependiendo de su propiedad Type (Enum.InputActionType). El valor predeterminado es Bool, diseñado para recibir valores true/false de la presión/liberación de entradas como ButtonA, E, o MouseLeftButton.

Para probar un InputAction para correr un personaje simple:

1. RECOMENDADO

   Selecciona el objeto Workspace de nivel superior en el Explorer y luego, en la ventana de Propiedades, establece la propiedad PlayerScriptsUseInputActionSystem en Enabled.

2. Crea un nuevo InputAction dentro del contexto PlayContext en ReplicatedStorage. Renómbralo a CharacterSprint para indicar su acción dedicada.

   

3. En la ventana de Propiedades, observa que el Type de la acción es Bool (predeterminado). Este es un tipo lógico para correr un personaje simple como una acción booleana true/false (el personaje está corriendo o no).

   

Enlaces de entrada

Un InputBinding define qué enlace de hardware debe activar el InputAction padre, por ejemplo, una pulsación de tecla, un botón de gamepad o un toque en un dispositivo habilitado para táctil. Para la compatibilidad multiplataforma, cada InputAction debe tener un InputBinding para gamepad, teclado/mouse y táctil como se ilustra aquí.

El Type asignado al InputAction padre afecta directamente qué tipos de entrada generales (tecla/botón/tap, gatillo analógico, joystick, etc.) son válidos para las instancias de InputBinding hijo. A su vez, los valores enviados a los eventos conectados de la acción padre dependen del tipo de entrada elegido de un enlace. Consulta eventos de entrada para obtener detalles sobre la correlación entre tipos de acción, enlaces y valores de retorno.

Para conectar enlaces para correr un personaje simple:

1. Inserta un nuevo InputBinding en la acción CharacterSprint y renómbralo a KeyboardBinding. Luego establece la propiedad KeyCode del enlace en LeftShift.

   

   

2. Inserta un segundo InputBinding en la acción CharacterSprint y renómbralo a GamepadBinding. Luego establece la propiedad KeyCode del enlace en ButtonY.

   

   

3. Dentro de un contenedor ScreenGui dentro de StarterGui, crea un botón en pantalla, renómbralo a SprintButton, y posiciónalo/redimensiona como desees.

   

4. Inserta un tercer InputBinding en la acción CharacterSprint y renómbralo a TouchBinding. Luego, en la ventana de Propiedades, vincula la propiedad UIButton del enlace al botón SprintButton que creaste anteriormente dentro de StarterGui.

   

   

Eventos de entrada

La instancia InputAction tiene tres eventos integrados para manejar la entrada del jugador proveniente de InputBindings.

• Pressed — Este evento se activa solo cuando el Type de la acción de entrada está configurado en Bool, y solo cuando el estado cambia de false a true.
• Released — Este evento se activa solo cuando el Type de la acción de entrada está configurado en Bool, y solo cuando el estado cambia de true a false.
• StateChanged — Este evento se activa para todos los tipos de acción de entrada cada vez que el estado cambia, excepto si el estado intenta cambiar al mismo estado.

Dependiendo del Type de la acción de entrada (Bool, Direction1D, Direction2D, Direction3D, o ViewportPosition) y el tipo de entrada general proveniente de un InputBinding hijo (tecla/botón/tap, gatillo analógico, joystick, etc.), se devuelven diferentes valores a los controladores de eventos Pressed, Released, y StateChanged. Examina las siguientes tablas para comprender mejor la correlación.

El tipo Bool es mejor para acciones activadas como saltar, disparar, correr, etc. con soporte para umbrales de presionado/liberado en entradas analógicas.

Para conectar eventos para correr un personaje simple:

1. Inserta un nuevo Script en el árbol de CharacterSprint, junto a los varios enlaces de entrada. Luego establece su RunContext en Client y renómbralo a OnActivate.

   

2. Pega el siguiente código en el script OnActivate. Nota la conexión del evento Pressed en las líneas 13‑15 que duplica la velocidad de caminata del personaje cuando se presiona un enlace de entrada de sprint, y la conexión correspondiente del evento Released en las líneas 16‑18 que restablece la velocidad de caminata a la predeterminada cuando se libera un enlace de entrada de sprint.

   OnActivate (Script del 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. Prueba tu juego y prueba la acción de correr del personaje con los enlaces que elegiste anteriormente: LeftShift para teclado, ButtonY para gamepad, y el botón en pantalla SprintButton para dispositivos habilitados para táctil. Recuerda que puedes usar el Emulador de Controlador para probar entradas de gamepad directamente en Roblox Studio.

Cambios de contexto

Una vez que tengas un contexto de entrada como PlayContext, puedes habilitar/deshabilitar durante el juego a través de scripting, cambiar su Priority para determinar qué acciones tienen prioridad sobre otras, y Sink entradas para que no sean procesadas dentro de contextos de menor prioridad.

1. Para facilitar el cambio de contextos desde otros scripts, inserta un nuevo BindableEvent en tu carpeta de entradas dentro de ReplicatedStorage y renómbralo a ContextEvent.

   

2. Crea un nuevo Script al mismo nivel, establece su RunContext en Client, y renómbralo a UpdateContext.

   

3. Dentro del script UpdateContext, pega el siguiente código:

   UpdateContext (Script del Cliente)

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   -- Conectar evento vinculable
   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 no encontrado!")
   	end
   end)

4. Con el script UpdateContext en su lugar, ahora puedes actualizar un InputContext nombrado disparando el evento vinculable, por ejemplo, desde un LocalScript que alimenta un GuiButton dentro de un contenedor ScreenGui.

   

   Script del Botón

   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 vinculable con el contexto de entrada objetivo y estado habilitado
   	contextEvent:Fire("PlayContext", true)
   end)

Mostrando enlaces

Una vez que hayas configurado acciones y enlaces, normalmente necesitarás mostrar a los jugadores, a través de sugerencias asistivas en pantalla, qué tecla o botón activa cada acción:

El sistema de acción de entrada proporciona dos enfoques:

• RECOMENDADO

  InputActionLabel — Un GuiObject sin código, de arrastrar y soltar que muestra automáticamente la entrada correcta por plataforma.
• INTERMEDIO

  PreferredBinding — Una propiedad de solo lectura de InputAction para creadores que desean control total sobre cómo se muestran los enlaces en la interfaz de usuario personalizada.

InputActionLabel es un GuiObject que puedes insertar en cualquier ScreenGui o SurfaceGui. Una vez que su propiedad InputAction se establece para hacer referencia a una instancia existente de InputAction, resuelve y muestra automáticamente el enlace de tecla correcto para el dispositivo de entrada actual del jugador — no se requiere scripting. Cuando el jugador cambia de dispositivo (por ejemplo, recoge un gamepad después de usar un teclado) o vuelve a asignar un control, la etiqueta se actualiza instantáneamente.

Para agregar un InputActionLabel:

1. Dentro de un contenedor ScreenGui dentro de StarterGui, inserta un InputActionLabel como cualquier otro GuiObject.

2. En la ventana de Propiedades, establece su propiedad InputAction en la instancia de InputAction que deseas mostrar (por ejemplo, tu acción "Sprint" bajo ReplicatedStorage) y posiciónalo/redimensiona como desees.

3. Cuando la etiqueta resuelve qué mostrar, verifica lo siguiente en orden:

   1. Imágenes Personalizadas — Si los InputBindings hijo tienen su propiedad DisplayImage establecida, la etiqueta renderiza esas imágenes directamente.

   2. Imágenes de Teclas de Plataforma — Sin imágenes personalizadas, la etiqueta renderiza imágenes proporcionadas por la plataforma para los InputBindings hijo a través de UserInputService:GetImageForKeyCode(), si tales imágenes están disponibles. Los enlaces compuestos con modificadores muestran múltiples íconos con separadores +.

   3. Nombres Personalizados — Sin imágenes disponibles, si los InputBindings hijo tienen su propiedad DisplayName establecida, la etiqueta renderiza ese texto utilizando las propiedades de estilo de la etiqueta.

   4. Cadenas de Teclas de Plataforma — Sin todo lo anterior, la etiqueta renderiza cadenas proporcionadas por la plataforma a través de UserInputService:GetStringForKeyCode().

   5. Si no se asigna ningún InputAction o no existe ningún InputBinding hijo, la etiqueta renderiza un ícono de marcador de posición.

Administrador de Acción de Entrada

La herramienta Administrador de Acción de Entrada es una interfaz unificada estilo matriz para diseñar, auditar y escalar tu arquitectura de entrada.

Para acceder a ella, navega al menú Ventana en Studio y selecciona Entrada ⟩ Administrador de Acción de Entrada. Si tu juego ya utiliza contextos, acciones o enlaces de entrada, el administrador escaneará automáticamente el DataModel y extraerá esas instancias existentes en la cuadrícula del editor. Cualquier nueva instancia relacionada con la entrada se poblará automáticamente en una carpeta Inputs dentro de ReplicatedStorage.

Para configurar un ajuste de entrada para correr personaje como se describe en las secciones anteriores:

1. RECOMENDADO

   Selecciona el objeto Workspace de nivel superior en el Explorer y luego, en la ventana de Propiedades, establece la propiedad PlayerScriptsUseInputActionSystem en Enabled.

2. Dentro de un contenedor ScreenGui dentro de StarterGui, crea un botón en pantalla, renómbralo a SprintButton, y posiciónalo/redimensiona como desees.

   

3. En el Administrador de Acción de Entrada, pasa el cursor sobre el encabezado de la columna Contexto y haz clic en el botón ＋. Ingresa un nombre apropiado para el nuevo contexto como PlayContext y presiona Enter. Un InputContext del nombre correspondiente aparece en ReplicatedStorage.

   

   

4. Pasa el cursor sobre el nuevo contexto y haz clic en el botón ＋. En el menú emergente, selecciona Bool, ingresa CharacterSprint para el nombre de la acción y presiona Enter. Un InputAction del nombre correspondiente aparece bajo el contexto.

   

   

5. En la nueva fila de CharacterSprint, asigna enlaces para cada tipo de entrada:

   1. Teclado y Mouse — Haz clic en el botón de flecha y selecciona LeftShift del menú de selección.
   2. Táctil — Haz clic en la celda y luego, en la jerarquía del Explorer, haz clic en el objeto SprintButton que insertaste previamente en el ScreenGui.
   3. Gamepad — Haz clic en el botón de flecha y selecciona ButtonY del menú de selección.

   

   A medida que asignes enlaces, observa los íconos de advertencia/error en la interfaz de usuario. Las advertencias amarillas (⚠) indican un enlace faltante para la compatibilidad multiplataforma, mientras que las advertencias rojas (⚠) indican un enlace duplicado para acciones dentro del mismo contexto.

6. Inserta un nuevo Script en el árbol de CharacterSprint, junto a los varios enlaces de entrada. Luego establece su RunContext en Client y renómbralo a OnActivate.

   

7. Pega el siguiente código en el script OnActivate. Nota la conexión del evento Pressed en las líneas 13‑15 que duplica la velocidad de caminata del personaje cuando se presiona un enlace de entrada de sprint, y la conexión correspondiente del evento Released en las líneas 16‑18 que restablece la velocidad de caminata a la predeterminada cuando se libera un enlace de entrada de sprint.

   OnActivate (Script del 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)