在 CounterStrikeSharp 中创建聊天与控制台命令

命令是如何工作的

命令是用 [ConsoleCommand] 标记的方法。框架会在插件加载时注册它，在插件卸载时移除它。名称以 css_ 开头的命令有三种用法：在控制台中输入 css_hello，在聊天中输入 !hello 或 /hello。带斜杠的写法不会让其他玩家看到这条消息。

你的第一个命令

方法会收到执行命令的玩家，以及一个 CommandInfo 对象，用来读取参数和回复。当命令是在服务器控制台输入时，玩家为空，所以要先检查这一点。

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

为什么玩家可能为 null

在服务器控制台输入命令时，背后并没有任何玩家。如果代码不检查就直接使用玩家，就会出错。你可以像上面那样在控制台场景下提前退出方法，也可以把代码写成对服务器也适用。

参数与用法

CommandHelper 特性描述命令应当如何使用：最少参数个数、一段简短的用法说明，以及谁可以执行。如果玩家参数填错，CounterStrikeSharp 会自动向他显示用法。GetArg(1) 是第一个参数，因为命令名本身是参数 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}!");
}

使用 lambda 的命令

你也可以在 Load 方法里注册命令，而不是使用特性。这对小命令很方便，或者当命令名来自配置文件时也很合适。

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

用权限限制命令

加上 RequiresPermissions，就可以只允许拥有某个标志的玩家使用该命令，例如 @css/kick。没有的人会被自动拒绝。标志在 admins.json 中分配，详见我们关于成为管理员的指南。

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

彩色聊天消息

ChatColors 可以给通过 PrintToChat 发送的消息的部分文字上色。请像示例那样让字符串以一个空格开头，否则第一个颜色可能显示不正确。ChatColors 位于 CounterStrikeSharp.API.Modules.Utils。

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

常见错误

一个始终没有反应的命令，通常要么缺少 css_ 前缀，导致无法在聊天中使用，要么因为玩家为 null 而抛出了异常。还要记住名称必须唯一：如果两个插件注册了同一个命令，行为就无法预测，所以给你的命令起一个有辨识度的名字。