Superheroes_Incremental/.agents/skills/roblox-keybinds/SKILL.md

name	description
roblox-keybinds	Ajouter ou modifier les keybinds et actions de boutons de ce projet Roblox, avec raccordement clavier/souris, manette, tactile et VR via ButtonAction. Utiliser pour les raccourcis, interactions, actions maintenues et conflits de touches ; pas pour les commandes Cmdr seules ni le suivi spatial VR.

Ajouter des keybinds au projet

Partir de la couche existante

Lire les fichiers depuis la racine du dépôt :

• src/client/input/button-action.ts : API réellement disponible et gestion du cycle de vie.
• docs/input.md : conventions et limites de la couche multiplateforme.
• Le contrôleur propriétaire de l'action ; src/client/controllers/cmdr-controller.ts fournit un exemple de raccordement complet.
• src/client/ui/action-touch-button.tsx si un bouton tactile est nécessaire.

Réutiliser ButtonAction pour les actions booléennes. GameJoy peut être installé sans être utilisé : ne pas enregistrer une seconde fois l'action dans GameJoy, ContextActionService, Cmdr ou un listener global. Un nouveau raccourci doit déclencher la logique existante de la fonctionnalité, pas une copie de cette logique.

Pour une action analogique, une combinaison de touches ou un remappage persistant, vérifier les besoins et les API natives actuelles avant d'étendre l'abstraction. ButtonAction ne fournit pas ces fonctionnalités ; les éléments d'un tableau de touches sont des alternatives, pas une combinaison.

Définir puis raccorder l'action

Déterminer le comportement (appui unique ou maintien), les conditions d'activation et les bindings par périphérique. Rechercher les bindings existants avant de choisir les touches ; éviter les entrées Roblox réservées et les conflits entre contextes actifs. Conserver les déplacements et la caméra Roblox, sauf demande explicite.

Créer l'action dans le contrôleur client propriétaire :

import { ButtonAction } from "client/input/button-action";

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);

Adapter les callbacks au comportement demandé ; omettre onReleased pour une action ponctuelle. Les noms et textes de jeu restent en anglais. Les tableaux keyboard et gamepad sont requis. Une entrée souris utilise un Enum.KeyCode souris pris en charge par les types et le moteur installés.

• L'action démarre désactivée. Appeler setEnabled selon l'état réel du jeu, des menus et des permissions, puis la détruire via le Trove propriétaire.
• Chaque action possède un InputContext avec Sink=true et une priorité par défaut de 2000. Une priorité différente doit correspondre à un besoin de précédence réel ; elle ne règle pas un conflit entre deux actions de même priorité.
• onReleased sert aussi à annuler un maintien lors d'une désactivation, d'une perte de focus ou d'une destruction. Prévoir un arrêt sans effet indésirable, même si l'action n'atteint pas sa durée normale.
• Garder le blocage pendant la saisie par défaut. Réserver allowWhileTyping: true aux raccourcis qui doivent fonctionner dans un TextBox, comme fermer la console. Le contournement clavier est déjà implémenté dans ButtonAction : ne pas ajouter un second listener dans le contrôleur.
• Les boutons VR utilisent des KeyCodes de contrôleur. vr remplace les bindings manette en VR ; sans cette option, la manette sert de repli. Ne pas présenter cela comme une prise en charge des gestes, du suivi des mains ou d'une interface spatiale.
• Une action ayant des conséquences de gameplay envoie une intention au serveur, qui conserve les validations et autorisations. Un binding client n'est pas une permission.

Interface tactile et indications

Raccorder le bouton React avec ref={(button) => action.setTouchButton(button)}. Laisser le démontage transmettre undefined. Ne pas ajouter un Activated déclenchant aussi l'action : InputBinding.UIButton est déjà responsable de l'entrée.

Réutiliser ActionTouchButton pour un bouton isolé si sa position convient. Pour plusieurs actions, organiser leurs boutons dans l'interface de la fonctionnalité afin d'éviter leur superposition et les contrôles Roblox. Préserver les zones sûres et des cibles tactiles d'au moins 44 × 44. Afficher les boutons selon les capacités tactiles et l'état d'activation ; la configuration actuelle de Cmdr les masque en VR et sans permission.

Utiliser action.input.PreferredBinding et son signal de changement pour des indications adaptatives si la fonctionnalité en affiche. Ne pas figer toutes les indications au périphérique détecté au démarrage. Ne pas exposer une indication clavier comme seule manière de découvrir une action mobile.

Vérifier le comportement

Pour une modification de code, exécuter les vérifications du projet (pnpm check, pnpm format:check, pnpm build) et distinguer les échecs préexistants de ceux introduits. Si Rojo manque au PATH alors qu'il est installé, ajouter son dossier au PATH de la session plutôt que modifier la configuration du projet.

Dans Roblox Studio via MCP, exercer les chemins affectés :

• Appui unique, relâchement et maintien selon l'action ; absence de double déclenchement.
• Activation/désactivation et annulation pendant un maintien ; saisie dans un TextBox et perte/reprise de focus.
• Bouton tactile raccordé à la même action ; montage/démontage et absence de superposition.
• Changement de périphérique et bindings manette/VR lorsque les moyens de test le permettent.
• Validation serveur et révocation d'accès si l'action est protégée.

Inspecter Output après les tests, corriger les erreurs liées au changement et rejouer le scénario corrigé. Retirer les instances et scripts de test temporaires. Un binding Scriptable peut tester les transitions logiques avec InputBinding:Fire() ; il ne prouve pas qu'une entrée matérielle ou tactile fonctionne. Laisser les signaux différés s'exécuter avant les assertions.

Les entrées virtuelles MCP peuvent laisser Studio sans focus. Si le test réactive artificiellement un contexte, le signaler et tester séparément le comportement de focus ; ne pas modifier la logique de production pour contourner cette limite de test. Distinguer un clic simulé sur un bouton d'un essai sur écran tactile, et un mapping VR d'un essai avec casque.

Terminer selon AGENTS.md : rapporter les vérifications et limites, puis inclure le commit des changements vérifiés. Actualiser docs/input.md si l'API ou les conventions changent.