Système d'Action d'Entrée

Le Système d'Action d'Entrée multiplateforme vous permet de connecter des actions et d'organiser des liaisons à travers divers entrées matérielles au moment de l'édition. Combiné avec des contextes, vous pouvez facilement configurer et éditer un système d'entrée modulaire qui fonctionne sur n'importe quel appareil à n'importe quelle phase de jeu. Les cas d'utilisation incluent :

• Un système de tir à la première personne avec des actions qui changent dynamiquement en fonction de si le joueur est en mode bataille ou en mode spectateur.
• Un système de conduite complet équipé d'accélération/décélération, de boosters de voiture et de stations de ravitaillement.
• Des raccourcis pour un système d'aptitudes dans un jeu de combat pour échanger des mouvements sans que les joueurs ne ratent un coup.

Contextes d'entrée

Un InputContext est une collection d'actions qui contient des actions d'entrée liées, par exemple PlayContext pour les contrôles de personnage en jeu et NavContext pour les contrôles de navigation dans les menus UI. Vous pouvez activer/désactiver des contextes (et leurs actions correspondantes) via leur propriété Enabled, par exemple pour activer le NavContext lorsque le menu d'inventaire est ouvert, puis passer au PlayContext lorsque le joueur ferme le menu et revient au gameplay principal.

Même si un jeu peut ne pas utiliser plusieurs contextes d'entrée au départ, il est recommandé de créer un contexte principal au niveau supérieur de tout système d'entrée, par exemple l'instance PlayContext pour les entrées qui se produisent pendant le gameplay.

1. RECOMMANDÉ

   Créez un Folder nommé Inputs à l'intérieur de ReplicatedStorage pour contenir divers contextes d'entrée.

   

2. Insérez un nouveau InputContext dans le dossier et renommez-le en PlayContext.

   

3. OPTIONNEL

   Dans la fenêtre Propriétés, définissez Priority sur 2000 et activez Sink. Un contexte avec Sink activé consomme les événements d'entrée pour ses KeyCodes liés à son niveau de priorité, bloquant ces entrées d'atteindre des contextes de priorité inférieure. Cela est pratique pour des cas d'utilisation comme un écran d'inventaire qui doit supprimer des entrées de gameplay spécifiques lorsqu'il est ouvert. Dans cet exemple, PlayContext se voit attribuer une Priority suffisamment élevée pour absorber ses entrées liées avant que les contextes par défaut PlayerScripts ne les traitent.

   

Actions d'entrée

Un InputAction définit un mécanisme d'action de gameplay tel que "Sauter", "Sprint" ou "Tirer". Ces actions sont ensuite mappées à des entrées matérielles à l'aide de liaisons d'entrée.

Un InputAction peut avoir plusieurs variations en fonction de sa propriété Type (Enum.InputActionType). La valeur par défaut est Bool, conçue pour recevoir des valeurs true/false à partir de l'appui/release d'entrées telles que ButtonA, E, ou MouseLeftButton.

Pour tester un InputAction pour un sprint de personnage simple :

1. RECOMMANDÉ

   Sélectionnez l'objet Workspace de niveau supérieur dans l'Explorateur puis, dans la fenêtre Propriétés, définissez la propriété PlayerScriptsUseInputActionSystem sur Enabled.

2. Créez un nouveau InputAction à l'intérieur du contexte PlayContext dans ReplicatedStorage. Renommez-le en CharacterSprint pour indiquer son action dédiée.

   

3. Dans la fenêtre Propriétés, remarquez que le Type de l'action est Bool (par défaut). C'est un type logique pour un sprint de personnage simple en tant qu'action booléenne true/false (le personnage est soit en train de sprinter, soit pas).

   

Liaisons d'entrée

Un InputBinding définit quelle liaison matérielle doit déclencher l'InputAction parent, par exemple une pression de touche, un bouton de manette, ou un tapotement sur un appareil tactile. Pour la compatibilité multiplateforme, chaque InputAction doit avoir un InputBinding pour manette, clavier/souris, et tactile comme illustré ici.

Le Type attribué à l'InputAction parent affecte directement quels types d'entrées générales (touche/bouton/tap, déclencheur analogique, joystick, etc.) sont valides pour les instances InputBinding enfants. En retour, les valeurs envoyées aux événements connectés de l'action parent dépendent du type d'entrée choisi pour une liaison. Voir événements d'entrée pour des détails sur la corrélation entre les types d'action, les liaisons et les valeurs de retour.

Pour connecter des liaisons pour un sprint de personnage simple :

1. Insérez un nouveau InputBinding dans l'action CharacterSprint et renommez-le en KeyboardBinding. Ensuite, définissez la propriété KeyCode de la liaison sur LeftShift.

   

   

2. Insérez une seconde InputBinding dans l'action CharacterSprint et renommez-la en GamepadBinding. Ensuite, définissez la propriété KeyCode de la liaison sur ButtonY.

   

   

3. À l'intérieur d'un conteneur ScreenGui dans StarterGui, créez un bouton à l'écran, renommez-le en SprintButton, et positionnez/redimensionnez comme désiré.

   

4. Insérez une troisième InputBinding dans l'action CharacterSprint et renommez-la en TouchBinding. Ensuite, dans la fenêtre Propriétés, liez la propriété UIButton de la liaison au bouton SprintButton que vous avez créé précédemment à l'intérieur de StarterGui.

   

   

Événements d'entrée

L'instance InputAction a trois événements intégrés pour gérer l'entrée du joueur provenant de InputBindings.

• Pressed — Cet événement se déclenche uniquement lorsque le Type de l'action d'entrée est défini sur Bool, et uniquement lorsque l'état passe de false à true.
• Released — Cet événement se déclenche uniquement lorsque le Type de l'action d'entrée est défini sur Bool, et uniquement lorsque l'état passe de true à false.
• StateChanged — Cet événement se déclenche pour tous les types d'action d'entrée chaque fois que l'état change, sauf si l'état tente de passer au même état.

En fonction du Type de l'action d'entrée (Bool, Direction1D, Direction2D, Direction3D, ou ViewportPosition) et du type d'entrée général provenant d'un InputBinding enfant (touche/bouton/tap, déclencheur analogique, joystick, etc.), différentes valeurs sont renvoyées aux gestionnaires d'événements Pressed, Released, et StateChanged. Examinez les tableaux suivants pour mieux comprendre la corrélation.

Le type Bool est le meilleur pour les actions déclenchées telles que sauter, tirer, sprinter, etc. avec support pour les seuils pressés/released sur les entrées analogiques.

Pour connecter des événements pour un sprint de personnage simple :

1. Insérez un nouveau Script dans l'arborescence CharacterSprint, à côté des diverses liaisons d'entrée. Ensuite, définissez son RunContext sur Client et renommez-le en OnActivate.

   

2. Collez le code suivant dans le script OnActivate. Notez la connexion de l'événement Pressed aux lignes 13‑15 qui double la vitesse de marche du personnage lorsque une liaison d'entrée de sprint est pressée, et la connexion de l'événement Released aux lignes 16‑18 qui réinitialise la vitesse de marche à la valeur par défaut lorsque une liaison d'entrée de sprint est relâchée.

   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. Testez votre jeu et testez l'action de sprint de personnage avec les liaisons que vous avez choisies précédemment : LeftShift pour le clavier, ButtonY pour la manette, et le bouton à l'écran SprintButton pour les appareils tactiles. N'oubliez pas que vous pouvez utiliser l'Émulateur de Contrôleur pour tester les entrées de manette directement dans Roblox Studio.

Changements de contexte

Une fois que vous avez un contexte d'entrée tel que PlayContext, vous pouvez l'activer/désactiver pendant le gameplay via le script, changer sa Priority pour déterminer quelles actions prennent la priorité sur d'autres, et Sink les entrées pour qu'elles ne soient pas traitées dans des contextes de priorité inférieure.

1. Pour faciliter le changement de contextes depuis d'autres scripts, insérez un nouveau BindableEvent dans votre dossier d'entrées à l'intérieur de ReplicatedStorage et renommez-le en ContextEvent.

   

2. Créez un nouveau Script au même niveau, définissez son RunContext sur Client, et renommez-le en UpdateContext.

   

3. À l'intérieur du script UpdateContext, collez le code suivant :

   UpdateContext (Script Client)

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   -- Connecter l'événement 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 trouvé !")
   	end
   end)

4. Avec le script UpdateContext en place, vous pouvez maintenant mettre à jour un InputContext nommé en déclenchant l'événement bindable, par exemple depuis un LocalScript qui alimente un GuiButton à l'intérieur d'un conteneur ScreenGui.

   

   Script de Bouton

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local inputsFolder = ReplicatedStorage:WaitForChild("Inputs")
   local contextEvent = inputsFolder:WaitForChild("ContextEvent")
   
   local button = script.Parent
   button.Activated:Connect(function()
   	-- Déclencher l'événement bindable avec le contexte d'entrée cible et l'état activé
   	contextEvent:Fire("PlayContext", true)
   end)

Gestionnaire d'Action d'Entrée

L'outil Gestionnaire d'Action d'Entrée est une interface unifiée de style matrice pour concevoir, auditer et étendre votre architecture d'entrée.

Pour y accéder, naviguez vers le menu Fenêtre dans Studio et sélectionnez Entrée ⟩ Gestionnaire d'Action d'Entrée. Si votre jeu utilise déjà des contextes, actions, ou liaisons, le gestionnaire scannera automatiquement le DataModel et extraira ces instances existantes dans la grille de l'éditeur. Toute nouvelle instance liée à l'entrée sera automatiquement peuplée dans un dossier Inputs à l'intérieur de ReplicatedStorage.

Pour configurer un setup d'entrée pour le sprint de personnage comme décrit dans les sections ci-dessus :

1. RECOMMANDÉ

   Sélectionnez l'objet Workspace de niveau supérieur dans l'Explorateur puis, dans la fenêtre Propriétés, définissez la propriété PlayerScriptsUseInputActionSystem sur Enabled.

2. À l'intérieur d'un conteneur ScreenGui dans StarterGui, créez un bouton à l'écran, renommez-le en SprintButton, et positionnez/redimensionnez comme désiré.

   

3. Dans le Gestionnaire d'Action d'Entrée, survolez l'en-tête de colonne Contexte et cliquez sur le bouton ＋. Entrez un nom approprié pour le nouveau contexte tel que PlayContext et appuyez sur Entrée. Un InputContext du nom correspondant apparaît dans ReplicatedStorage.

   

   

4. Survolez le nouveau contexte et cliquez sur le bouton ＋. Dans le menu contextuel, sélectionnez Bool, entrez CharacterSprint pour le nom de l'action, et appuyez sur Entrée. Un InputAction du nom correspondant apparaît sous le contexte.

   

   

5. Dans la nouvelle ligne CharacterSprint, attribuez des liaisons pour chaque type d'entrée :

   1. Clavier et Souris — Cliquez sur le bouton flèche et sélectionnez LeftShift dans le menu de sélection.
   2. Tactile — Cliquez sur la cellule puis, dans la hiérarchie de l'Explorateur, cliquez sur l'objet SprintButton que vous avez précédemment inséré dans le ScreenGui.
   3. Manette — Cliquez sur le bouton flèche et sélectionnez ButtonY dans le menu de sélection.

   

   En attribuant des liaisons, surveillez les icônes d'avertissement/d'erreur dans l'UI. Les avertissements jaunes (⚠) indiquent une liaison manquante pour la compatibilité multiplateforme, tandis que les avertissements rouges (⚠) indiquent une liaison dupliquée pour des actions au sein du même contexte.

6. Insérez un nouveau Script dans l'arborescence CharacterSprint, à côté des diverses liaisons d'entrée. Ensuite, définissez son RunContext sur Client et renommez-le en OnActivate.

   

7. Collez le code suivant dans le script OnActivate. Notez la connexion de l'événement Pressed aux lignes 13‑15 qui double la vitesse de marche du personnage lorsque une liaison d'entrée de sprint est pressée, et la connexion de l'événement Released aux lignes 16‑18 qui réinitialise la vitesse de marche à la valeur par défaut lorsque une liaison d'entrée de sprint est relâchée.

   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)