roblox-ts-template/docs/input.md

Contrôles multiplateformes

Le template utilise le Input Action System Roblox, disponible dans les types installés @rbxts/types 1.0.957. GameJoy 1.1.4 reste installé pour compatibilité, mais n'est pas utilisé : les instances natives InputContext, InputAction et InputBinding offrent directement le raccordement clavier, manette et bouton tactile. Ne pas enregistrer la même action dans les deux systèmes.

Ajouter une action

Créer une ButtonAction côté client, dans le contrôleur propriétaire de la fonctionnalité :

const action = new ButtonAction({
  name: "Interact",
  label: "Interact",
  keyboard: [Enum.KeyCode.E],
  gamepad: [Enum.KeyCode.ButtonX],
  vr: [Enum.KeyCode.ButtonX],
  onPressed: () => this.requestInteraction(),
  onReleased: () => this.stopInteraction(),
});
this.trove.add(action);
action.setEnabled(true);

Importer ButtonAction depuis client/input/button-action. Chaque action possède son contexte, désactivé à la création, de priorité 2000 par défaut. Le contexte consomme ses touches avant les contextes de priorité inférieure. Choisir des touches distinctes pour les actions simultanément actives ; éviter les touches Roblox réservées. priority permet de donner la priorité à une action de menu.

Les callbacks reçoivent une transition logique, indépendamment du périphérique. onReleased est également appelé si une action maintenue est désactivée, détruite ou perd le focus de fenêtre. Les actions sont suspendues pendant la saisie dans un TextBox, sauf allowWhileTyping: true. Les changements de clavier/manette ne nécessitent pas de réenregistrement. Les bindings VR remplacent ceux de la manette quand VREnabled change ; sans option vr, les bindings manette sont conservés.

Pour le tactile, rendre un bouton React puis le transmettre par ref={(button) => action.setTouchButton(button)}. Le binding UIButton déclenche l'action sans callback Activated supplémentaire. ActionTouchButton fournit un bouton de 112 × 48 dans une zone sûre ; pour plusieurs actions, définir leur disposition dans l'interface de la fonctionnalité. Démonter le bouton efface sa référence. Détruire l'action avec le Trove du contrôleur.

L'instance publique action.input permet de consulter GetState() et PreferredBinding, ou d'écouter les changements de ce dernier pour afficher des indications adaptées au périphérique. Cette abstraction couvre les actions booléennes ; utiliser les types natifs Direction1D/2D/3D pour de futures actions analogiques.

Intégration actuelle

CmdrController utilise une action ToggleConsole : F2 sur PC, ButtonY sur manette et contrôleurs VR compatibles, bouton « Console » sur les appareils tactiles hors VR. L'ancien raccourci Cmdr est désactivé pour éviter un double déclenchement. L'action et son bouton sont accessibles uniquement lorsque le serveur publie CmdrEnabled=true. Les autorisations des commandes restent contrôlées côté serveur.

Ce raccordement ouvre ou ferme Cmdr ; son interface de saisie reste celle de la bibliothèque. Il ne fournit pas un clavier virtuel VR ou une interface d'administration spécialement conçue pour la manette. Les déplacements, le saut, la caméra et le suivi des mains/tête restent les contrôles Roblox standard. Une interaction VR spatiale doit utiliser VRService en complément des actions de boutons.

Vérification

Vérifié via Roblox Studio MCP : ouverture F2, déclenchement du composant tactile par clic simulé, transitions appui/relâchement, suppression des transitions répétées, annulation à la désactivation, blocage d'une action désactivée, raccordement/détachement du bouton, destruction et révocation d'accès serveur. Les transitions ont été exercées avec un binding de test scriptable, retiré après vérification. Pour le test clavier virtuel, le contexte a été réactivé pendant que la fenêtre Studio était sans focus.

Les tests ne remplacent pas les essais sur une manette, un écran tactile et un casque VR physiques. La projection spatiale d'interfaces VR, les gestes et le remappage persistant ne sont pas fournis par cette couche.

Sources consultées : Input Action System, InputContext, GameJoy, README local GameJoy 1.1.4 et déclarations locales des API Roblox.