Créer des commandes de chat et de console avec CounterStrikeSharp

Comment fonctionnent les commandes

Une commande est une méthode marquée [ConsoleCommand]. Le framework l’enregistre au chargement du plugin et la retire à son déchargement. Toute commande dont le nom commence par css_ est utilisable de trois façons : dans la console sous css_hello, et dans le chat sous !hello ou /hello. La version avec la barre oblique masque le message aux autres joueurs.

Votre première commande

La méthode reçoit le joueur qui a lancé la commande et un objet CommandInfo qui sert à lire les arguments et à répondre. Le joueur est vide quand la commande vient de la console du serveur : testez donc ce cas en premier.

using CounterStrikeSharp.API.Core;
using CounterStrikeSharp.API.Core.Attributes.Registration;
using CounterStrikeSharp.API.Modules.Commands;

public class CommandsPlugin : BasePlugin
{
    public override string ModuleName => "Commands Example";
    public override string ModuleVersion => "1.0.0";

    [ConsoleCommand("css_hello", "Says hello to the player")]    public void OnHelloCommand(CCSPlayerController? player, CommandInfo commandInfo)
    {
        if (player == null) return;

        commandInfo.ReplyToCommand($"Hello, {player.PlayerName}!");    }
}

Pourquoi le joueur peut être null

Quand vous tapez la commande dans la console du serveur, aucun joueur n’est derrière. Si votre code utilise le joueur sans vérifier, il plante. Soit vous quittez la méthode pour la console, comme ci-dessus, soit vous écrivez le code de façon à ce qu’il marche aussi pour le serveur.

Arguments et mode d’emploi

L’attribut CommandHelper décrit comment la commande doit être utilisée : nombre minimal d’arguments, court texte d’aide et qui peut l’exécuter. Si le joueur se trompe, CounterStrikeSharp lui affiche lui-même le mode d’emploi. GetArg(1) est le premier argument, car le nom de la commande est l’argument 0.

[ConsoleCommand("css_greet", "Greets another player by name")]
[CommandHelper(minArgs: 1, usage: "<name>", whoCanExecute: CommandUsage.CLIENT_ONLY)]
public void OnGreetCommand(CCSPlayerController? player, CommandInfo commandInfo)
{
    var name = commandInfo.GetArg(1);
    commandInfo.ReplyToCommand($"Hello, {name}!");
}

Commandes avec une lambda

Vous pouvez aussi enregistrer une commande dans la méthode Load au lieu d’utiliser un attribut. C’est pratique pour les petites commandes, ou quand le nom de la commande vient d’un fichier de configuration.

public override void Load(bool hotReload)
{
    AddCommand("css_ping", "Replies with pong", (player, commandInfo) =>
    {
        commandInfo.ReplyToCommand("pong");
    });
}

Restreindre une commande avec des permissions

Ajoutez RequiresPermissions pour réserver la commande aux joueurs ayant un flag, par exemple @css/kick. Les autres sont refusés automatiquement. Les flags s’attribuent dans admins.json, comme l’explique notre guide pour devenir admin.

[ConsoleCommand("css_kickme", "Example of a protected command")]
[RequiresPermissions("@css/kick")]
public void OnKickMeCommand(CCSPlayerController? player, CommandInfo commandInfo)
{
    commandInfo.ReplyToCommand("You have the @css/kick flag.");
}

Messages colorés dans le chat

ChatColors permet de colorer des parties d’un message envoyé avec PrintToChat. Commencez la chaîne par une espace, comme dans l’exemple, sinon la première couleur peut mal s’afficher. ChatColors se trouve dans CounterStrikeSharp.API.Modules.Utils.

player.PrintToChat($" {ChatColors.Green}Hello, {player.PlayerName}!");

Erreurs courantes

Une commande qui ne répond jamais n’a souvent pas le préfixe css_, donc n’existe pas dans le chat, ou lève une exception parce que le joueur était null. Rappelez-vous aussi que les noms doivent être uniques : si deux plugins enregistrent la même commande, le comportement est imprévisible, donnez donc un nom distinctif à la vôtre.