Sistema di Azioni di Input

Il sistema di azioni di input cross-platform Input Action System ti consente di connettere azioni e organizzare binding attraverso vari input hardware in fase di modifica. Combinato con contesti, puoi facilmente configurare e modificare un sistema di input modulare che funziona su qualsiasi dispositivo in qualsiasi fase di gioco. I casi d'uso includono:

• Un sistema di sparatutto in prima persona con azioni che si scambiano dinamicamente a seconda che il giocatore sia in modalità battaglia o modalità spettatore.
• Un sistema di guida completo dotato di accelerazione/decelerazione, potenziamenti per auto e stazioni di rifornimento.
• Tasti di scelta rapida per un sistema di abilità in un gioco di combattimento per cambiare le mosse senza che i giocatori perdano un colpo.

Contesti di input

Un InputContext è una raccolta di azioni che contiene azioni di input correlate, ad esempio PlayContext per i controlli del personaggio in gioco e NavContext per i controlli per navigare nei menu dell'interfaccia utente. Puoi abilitare/disabilitare i contesti (e le loro azioni corrispondenti) attraverso la proprietà Enabled, ad esempio per abilitare il NavContext quando un menu di inventario è aperto e poi passare al PlayContext quando il giocatore chiude il menu e torna al gameplay principale.

Anche se un gioco potrebbe non utilizzare più contesti di input inizialmente, è consigliato creare un contesto primario a livello superiore di qualsiasi sistema di input, ad esempio l'istanza PlayContext per l'input che si verifica durante il gameplay.

1. RACCOMANDATO

   Crea una Folder chiamata Inputs all'interno di ReplicatedStorage per contenere vari contesti di input.

   

2. Inserisci un nuovo InputContext nella cartella e rinominalo in PlayContext.

   

3. OPZIONALE

   Nella finestra Proprietà, imposta Priority a 2000 e abilita Sink. Un contesto con Sink abilitato consuma eventi di input per i suoi KeyCodes associati al suo livello di priorità, bloccando quegli input dal raggiungere contesti di priorità inferiore. Questo è pratico per casi d'uso come uno schermo di inventario che dovrebbe sopprimere specifici input di gioco mentre è aperto. In questo esempio, a PlayContext viene data una Priority sufficientemente alta per affondare i suoi input associati prima che i contesti predefiniti PlayerScripts li elaborino.

   

Azioni di input

Un InputAction definisce una meccanica di azione di gioco come "Salta", "Corri" o "Spara". Queste azioni vengono quindi mappate a input hardware utilizzando binding di input.

Un InputAction può avere diverse varianti a seconda della sua proprietà Type (Enum.InputActionType). Il valore predefinito è Bool, progettato per ricevere valori true/false dalla pressione/rilascio di input come ButtonA, E o MouseLeftButton.

Per testare un InputAction per la corsa semplice del personaggio:

1. RACCOMANDATO

   Seleziona l'oggetto Workspace a livello superiore nell'Esplora e poi, nella finestra Proprietà, imposta la proprietà PlayerScriptsUseInputActionSystem su Enabled.

2. Crea un nuovo InputAction all'interno del contesto PlayContext in ReplicatedStorage. Rinominalo in CharacterSprint per indicare la sua azione dedicata.

   

3. Nella finestra Proprietà, nota che il Type dell'azione è Bool (predefinito). Questo è un tipo logico per la corsa semplice del personaggio come azione booleana true/false (il personaggio sta correndo o non sta correndo).

   

Binding di input

Un InputBinding definisce quale binding hardware dovrebbe attivare il InputAction genitore, ad esempio una pressione di tasto, un pulsante del gamepad o un tocco su un dispositivo abilitato al touch. Per la compatibilità cross-platform, ogni InputAction dovrebbe avere un InputBinding per gamepad, tastiera/mouse e touch come illustrato qui.

Il Type assegnato al InputAction genitore influisce direttamente su quali tipi di input generali (tasto/pulsante/tocco, grilletto analogico, joystick, ecc.) sono validi per le istanze di InputBinding figlie. A sua volta, i valori inviati agli eventi connessi all'azione genitore dipendono dal tipo di input scelto per un binding. Vedi eventi di input per dettagli sulla correlazione tra tipi di azione, binding e valori di ritorno.

Per collegare i binding per la corsa semplice del personaggio:

1. Inserisci un nuovo InputBinding nell'azione CharacterSprint e rinominalo in KeyboardBinding. Quindi imposta la proprietà KeyCode del binding su LeftShift.

   

   

2. Inserisci un secondo InputBinding nell'azione CharacterSprint e rinominalo in GamepadBinding. Quindi imposta la proprietà KeyCode del binding su ButtonY.

   

   

3. All'interno di un contenitore ScreenGui all'interno di StarterGui, crea un pulsante on-screen, rinominalo in SprintButton e posizionalo/ridimensionalo come desideri.

   

4. Inserisci un terzo InputBinding nell'azione CharacterSprint e rinominalo in TouchBinding. Quindi, nella finestra Proprietà, collega la proprietà UIButton del binding al pulsante SprintButton che hai creato in precedenza all'interno di StarterGui.

   

   

Eventi di input

L'istanza InputAction ha tre eventi integrati per gestire l'input del giocatore proveniente da InputBindings.

• Pressed — Questo evento si attiva solo quando il Type dell'input è impostato su Bool, e solo quando lo stato passa da false a true.
• Released — Questo evento si attiva solo quando il Type dell'input è impostato su Bool, e solo quando lo stato passa da true a false.
• StateChanged — Questo evento si attiva per tutti i tipi di azione di input ogni volta che lo stato cambia, tranne se lo stato tenta di passare allo stesso stato.

A seconda del Type dell'azione di input (Bool, Direction1D, Direction2D, Direction3D o ViewportPosition) e del tipo di input generale proveniente da un InputBinding figlio (tasto/pulsante/tocco, grilletto analogico, joystick, ecc.), diversi valori vengono restituiti ai gestori di eventi Pressed, Released e StateChanged. Esamina le seguenti tabelle per comprendere meglio la correlazione.

Il tipo Bool è il migliore per azioni attivate come saltare, sparare, correre, ecc. con supporto per soglie di premuto/rilasciato su input analogici.

Per connettere eventi per la corsa semplice del personaggio:

1. Inserisci un nuovo Script nell'albero di CharacterSprint, insieme ai vari binding di input. Quindi imposta il suo RunContext su Client e rinominalo in OnActivate.

   

2. Incolla il seguente codice nello script OnActivate. Nota la connessione dell'evento Pressed alle righe 13‑15 che raddoppia la velocità di camminata del personaggio quando un binding di input per la corsa è premuto, e la corrispondente connessione dell'evento Released alle righe 16‑18 che ripristina la velocità di camminata predefinita quando un binding di input per la corsa è rilasciato.

   OnActivate (Script Client)

   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. Prova il tuo gioco e testa l'azione di corsa del personaggio con i binding che hai scelto in precedenza: LeftShift per la tastiera, ButtonY per il gamepad e il pulsante on-screen SprintButton per i dispositivi abilitati al touch. Ricorda che puoi utilizzare l'Emulatore di Controller per testare gli input del gamepad direttamente in Roblox Studio.

Cambiamenti di contesto

Una volta che hai un contesto di input come PlayContext, puoi abilitarlo/disabilitarlo durante il gameplay tramite scripting, cambiare la sua Priority per determinare quali azioni hanno la precedenza su altre, e Sink input per non essere elaborati all'interno di contesti di priorità inferiore.

1. Per facilitare il passaggio tra contesti da altri script, inserisci un nuovo BindableEvent nella tua cartella di input all'interno di ReplicatedStorage e rinominalo in ContextEvent.

   

2. Crea un nuovo Script allo stesso livello, imposta il suo RunContext su Client, e rinominalo in UpdateContext.

   

3. All'interno dello script UpdateContext, incolla il seguente codice:

   UpdateContext (Script Client)

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   -- Connetti l'evento bindable
   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 non trovato!")
   	end
   end)

4. Con lo script UpdateContext in posizione, ora puoi aggiornare un InputContext nominato attivando l'evento bindable, ad esempio da un LocalScript che alimenta un GuiButton all'interno di un contenitore ScreenGui.

   

   Script del Pulsante

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   local button = script.Parent
   button.Activated:Connect(function()
   	-- Attiva l'evento bindable con il contesto di input target e stato abilitato
   	contextEvent:Fire("PlayContext", true)
   end)

Visualizzazione dei binding

Una volta che hai impostato azioni e binding, di solito dovrai mostrare ai giocatori, tramite suggerimenti assistivi on-screen, quale tasto o pulsante attiva ciascuna azione:

Il sistema di azioni di input fornisce due approcci:

• RACCOMANDATO

  InputActionLabel — Un GuiObject senza codice, drag-and-drop che visualizza automaticamente il corretto input per piattaforma.
• INTERMEDIO

  PreferredBinding — Una proprietà di sola lettura InputAction per i creatori che vogliono il pieno controllo su come i binding vengono visualizzati nell'interfaccia utente personalizzata.

InputActionLabel è un GuiObject che puoi inserire in qualsiasi ScreenGui o SurfaceGui. Una volta che la sua proprietà InputAction è impostata per fare riferimento a un'istanza esistente di InputAction, risolve automaticamente e visualizza il corretto binding di tasti per il dispositivo di input attuale del giocatore — nessuna programmazione richiesta. Quando il giocatore cambia dispositivo (ad esempio, raccogliendo un gamepad dopo aver usato una tastiera) o riassocia un controllo, l'etichetta si aggiorna istantaneamente.

Per aggiungere un InputActionLabel:

1. All'interno di un contenitore ScreenGui all'interno di StarterGui, inserisci un InputActionLabel proprio come qualsiasi altro GuiObject.

2. Nella finestra Proprietà, imposta la sua proprietà InputAction sull'istanza di InputAction che desideri visualizzare (ad esempio, la tua azione "Sprint" sotto ReplicatedStorage) e posizionalo/ridimensionalo come desideri.

3. Quando l'etichetta risolve cosa mostrare, controlla quanto segue in ordine:

   1. Immagini Personalizzate — Se i InputBindings figli hanno la loro proprietà DisplayImage impostata, l'etichetta renderizza quelle immagini direttamente.

   2. Immagini di Tasti per Piattaforma — Mancando immagini personalizzate, l'etichetta renderizza immagini fornite dalla piattaforma per i InputBindings figli tramite UserInputService:GetImageForKeyCode(), se tali immagini sono disponibili. I binding compositi con modificatori mostrano più icone con separatori +.

   3. Nomi Personalizzati — Mancando immagini disponibili, se i InputBindings figli hanno la loro proprietà DisplayName impostata, l'etichetta renderizza quel testo utilizzando le proprietà di stile dell'etichetta.

   4. Stringhe di Tasti per Piattaforma — Mancando tutto quanto sopra, l'etichetta renderizza stringhe fornite dalla piattaforma tramite UserInputService:GetStringForKeyCode().

   5. Se non è assegnato alcun InputAction o non esiste alcun InputBinding figlio, l'etichetta renderizza un'icona segnaposto.

Gestore delle Azioni di Input

Lo strumento Gestore delle Azioni di Input è un'interfaccia unificata in stile matrice per progettare, controllare e scalare la tua architettura di input.

Per accedervi, naviga nel menu Finestra in Studio e seleziona Input ⟩ Gestore delle Azioni di Input. Se il tuo gioco utilizza già contesti di input, azioni o binding, il gestore scansionerà automaticamente il DataModel ed estrarrà quelle istanze esistenti nella griglia dell'editor. Qualsiasi nuova istanza relativa all'input verrà automaticamente popolata in una cartella Inputs all'interno di ReplicatedStorage.

Per configurare un'impostazione di input per corsa del personaggio come descritto nelle sezioni sopra:

1. RACCOMANDATO

   Seleziona l'oggetto Workspace a livello superiore nell'Esplora e poi, nella finestra Proprietà, imposta la proprietà PlayerScriptsUseInputActionSystem su Enabled.

2. All'interno di un contenitore ScreenGui all'interno di StarterGui, crea un pulsante on-screen, rinominalo in SprintButton e posizionalo/ridimensionalo come desideri.

   

3. Nel Gestore delle Azioni di Input, passa il mouse sopra l'intestazione della colonna Contesto e fai clic sul pulsante ＋. Inserisci un nome appropriato per il nuovo contesto come PlayContext e premi Invio. Un InputContext con il nome corrispondente appare in ReplicatedStorage.

   

   

4. Passa il mouse sopra il nuovo contesto e fai clic sul pulsante ＋. Dal menu a comparsa, seleziona Bool, inserisci CharacterSprint come nome dell'azione e premi Invio. Un InputAction con il nome corrispondente appare sotto il contesto.

   

   

5. Nella nuova riga CharacterSprint, assegna binding per ciascun tipo di input:

   1. Tastiera e Mouse — Fai clic sul pulsante a freccia e seleziona LeftShift dal menu di selezione.
   2. Touch — Fai clic sulla cella e poi, nell'Esplora gerarchia, fai clic sull'oggetto SprintButton che hai precedentemente inserito nel ScreenGui.
   3. Gamepad — Fai clic sul pulsante a freccia e seleziona ButtonY dal menu di selezione.

   

   Mentre assegni i binding, fai attenzione alle icone di avviso/errore nell'interfaccia utente. Gli avvisi gialli (⚠) indicano un binding mancante per la compatibilità cross-platform, mentre gli avvisi rossi (⚠) indicano un binding duplicato per azioni all'interno dello stesso contesto.

6. Inserisci un nuovo Script nell'albero di CharacterSprint, insieme ai vari binding di input. Quindi imposta il suo RunContext su Client e rinominalo in OnActivate.

   

7. Incolla il seguente codice nello script OnActivate. Nota la connessione dell'evento Pressed alle righe 13‑15 che raddoppia la velocità di camminata del personaggio quando un binding di input per la corsa è premuto, e la corrispondente connessione dell'evento Released alle righe 16‑18 che ripristina la velocità di camminata predefinita quando un binding di input per la corsa è rilasciato.

   OnActivate (Script Client)

   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)