Creating Chat and Console Commands in CounterStrikeSharp

How commands work

A command is a method marked with [ConsoleCommand]. The framework registers it when the plugin loads and removes it when the plugin unloads. Any command whose name starts with css_ is available in three ways: in the console as css_hello, and in chat as !hello or /hello. The slash version hides the message from other players.

Your first command

The method receives the player who ran it and a CommandInfo object used to read arguments and to reply. The player is empty when the command was typed in the server console, so check for that first.

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}!");    }
}

Why the player can be null

When you type the command in the server console there is no player behind it. If your code uses the player without checking, it crashes. Either return early for the console, as above, or write the code so that it also works for the server.

Arguments and usage

The CommandHelper attribute describes how the command must be used: the minimum number of arguments, a short usage text, and who may run it. If the player gets the arguments wrong, CounterStrikeSharp shows them the usage for you. GetArg(1) is the first argument, because the command name itself is 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}!");
}

Commands with a lambda

You can also register a command in the Load method instead of using an attribute. This is handy for small commands, or when the command name comes from a config file.

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

Restrict a command with permissions

Add RequiresPermissions to allow only players with a flag, for example @css/kick. Players without it are refused automatically. Flags are assigned in admins.json, as explained in our guide on becoming 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.");
}

Colored chat messages

ChatColors lets you color parts of a message sent with PrintToChat. Start the string with a space, as in the example, otherwise the first color may not be displayed correctly. ChatColors is found in CounterStrikeSharp.API.Modules.Utils.

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

Common mistakes

A command that never answers is usually missing the css_ prefix, which means it is not available in chat, or it is throwing an exception because the player was null. Also remember that names must be unique: if two plugins register the same command, the behaviour is unpredictable, so give yours a distinctive name.