RegisterCommand et RegisterKeyMapping : touches redéfinissables dans FiveM

Vous voulez une commande comme /garage que n'importe qui peut taper, une touche comme E qui fait la même chose, et un moyen pour chaque joueur de changer cette touche. FiveM vous donne RegisterCommand pour la commande et RegisterKeyMapping pour la touche. Cet article montre les deux, comment restreindre une commande aux administrateurs, comment faire une action qui fonctionne pendant qu'une touche est enfoncée, et pourquoi modifier une touche par défaut plus tard ne fait rien pour les joueurs existants.

#Une commande simple

Une commande est un nom et une fonction :

RegisterCommand('garage', function(source, args, rawCommand)
    print('garage opened')
end, false)

Sur le client, source n'est pas utile. La table args contient les mots tapés après la commande, et rawCommand est le texte complet. Sur le serveur, source est l'ID du joueur, ou 0 quand la commande vient de la console du serveur.

La même sur le serveur, avec un argument :

RegisterCommand('heal', function(source, args)
    local target = tonumber(args[1]) or source
    TriggerClientEvent('my_script:heal', target)
end, true)

#Restreindre une commande avec ACE

Le dernier argument de RegisterCommand est restricted. Avec true, personne ne peut exécuter la commande à moins qu'il n'ait la permission ACE command.<name>. Accordez-la à vos administrateurs dans server.cfg :

add_ace group.admin command.heal allow
add_principal identifier.license:your_license_here group.admin

Les joueurs sans elle reçoivent une erreur de permission et la commande ne s'exécute jamais. Le fonctionnement des groupes ACE et des principaux est couvert dans permissions ACE pour les administrateurs FiveM.

Attention : une commande false peut être tapée par tout le monde, y compris les tricheurs qui l'appellent à la main. Ne vous fiez jamais à une commande côté client pour garder quelque chose de valeur. Faites la vraie vérification de permission sur le serveur.

#Lier la commande à une touche

RegisterKeyMapping lie une commande à une touche, sur le client. La commande doit exister, alors enregistrez les deux :

RegisterCommand('garage', function()
    print('garage opened')
end, false)

RegisterKeyMapping('garage', 'Open the garage', 'keyboard', 'F5')

Les quatre arguments sont le nom de la commande, la description affichée au joueur, l'appareil d'entrée ('keyboard' ici) et la touche par défaut. Le nom de la touche est écrit comme E, F5 ou LSHIFT.

Les joueurs peuvent maintenant appuyer sur F5, ou taper /garage, et les deux font la même chose.

#Où les joueurs le redéfinissent

La touche par défaut n'est qu'une suggestion. Les joueurs ouvrent les Paramètres du jeu > Liaisons de touches > FiveM et trouvent votre action là, listée par le texte de description. Ils peuvent modifier la touche en ce qu'ils aiment.

Écrivez une description claire ('Open the garage', pas 'garage'), car c'est tout ce que le joueur voit. Gardez-le court et unique, pour que deux scripts ne montrent pas la même étiquette.

#Maintenir les actions avec + et - commandes

Pour quelque chose qui dure pendant qu'une touche est enfoncée, comme un push-to-talk ou une corde, enregistrez une paire de commandes : une commençant par + et une par -. Le jeu exécute +name quand la touche descend et -name quand elle remonte :

local holding = false

RegisterCommand('+my_hold', function()
    holding = true
end, false)

RegisterCommand('-my_hold', function()
    holding = false
end, false)

RegisterKeyMapping('+my_hold', 'Hold to aim the tool', 'keyboard', 'G')

CreateThread(function()
    while true do
        if holding then
            -- do the held action here
            Wait(0)
        else
            Wait(250)
        end
    end
end)

Cartographiez le nom +. Les deux commandes + et - doivent être enregistrées, ou la libération n'est jamais vue.

#Pourquoi une nouvelle touche par défaut ne fait rien

Cela attrape beaucoup de développeurs. Vous libérez la version 1 avec 'F5', puis passez à 'F6' dans la version 2. Les joueurs qui ont déjà exécuté la version 1 appuient toujours sur F5.

La raison : la touche par défaut de RegisterKeyMapping est appliquée seulement la première fois que le jeu voit ce mappage. Après cela, la liaison vit dans les paramètres du joueur, et la nouvelle valeur par défaut n'est pas utilisée. Alors :

• Les nouveaux joueurs obtiennent la nouvelle touche.
• Les joueurs existants gardent l'ancienne, ou tout ce qu'ils ont choisi eux-mêmes.

Il n'y a pas de moyen propre de forcer une touche sur les joueurs qui ont déjà la liaison. Vos options :

1. Dire aux joueurs de redéfinir dans Paramètres > Liaisons de touches > FiveM. Mettez-le dans vos notes de mise à jour.
2. Utilisez un nouveau nom de commande pour l'action, par exemple garage_v2 au lieu de garage. C'est un nouveau mappage, la nouvelle valeur par défaut s'applique. Les joueurs verront les deux entrées jusqu'à ce que l'ancienne soit supprimée.
3. Ne vous fiez pas à la valeur par défaut. Affichage la touche réelle dans votre interface utilisateur au lieu d'une lettre fixe, ou dites aux joueurs comment la redéfinir.

C'est aussi pourquoi vous devriez tester les modifications de touche sur un profil frais, ou après suppression de la liaison dans les paramètres. Sinon, vous continuez à tester votre ancienne touche.

#Gardez la logique de commande petite

Un gestionnaire de commande doit faire une chose : appeler une fonction. Puis la touche, la commande et une interaction cible (consultez ox_target : comment ajouter des cibles) appelent tous la même fonction :

local function openGarage()
    print('garage opened')
end

RegisterCommand('garage', openGarage, false)
RegisterKeyMapping('garage', 'Open the garage', 'keyboard', 'F5')

Évitez les touches que d'autres choses utilisent déjà. Vérifier IsControlJustPressed dans une boucle pour la même touche qu'une commande mappée fait déclencher les deux. Utilisez seul le mappage.

#Liste de contrôle