Skip to content

CommandBase

Jump to bottom
Axwabo edited this page Apr 19, 2025 · 7 revisions

CommandBase

The Axwabo.CommandSystem.CommandBase class is the core of creating commands.

See also:

You can specify common properties using attributes, with resolvers or by overriding them.

Register your command in the Remote Admin, Server Console or the Client Console (what's the difference?) using the Axwabo.CommandSystem.Attributes.CommandTargetAttribute

Note

Setting the description is done with the Axwabo.CommandSystem.Attributes.CommandDescriptionAttribute and not System.ComponentModel.DescriptionAttribute

There is an attribute to set each of the following properties: Name Description Aliases Usage MinArguments

Alternatively, the Axwabo.CommandSystem.Attributes.CommandPropertiesAttribute allows you to set Name Description Aliases MinArguments in one attribute.

Important

A command must specify its name in one of the ways described above (otherwise, an exception is thrown) and override the Execute method. The latter method takes in an ArraySegment<string> and a CommandSender - and returns a CommandResult

Example:

using System;
using Axwabo.CommandSystem.Attributes;
using Axwabo.CommandSystem.Commands;

[CommandProperties(CommandHandlerType.RemoteAdmin, "myCommand", "My description", "myAlias")]
public sealed class MyCommand : CommandBase
{

    protected override CommandResult Execute(ArraySegment<string> arguments, CommandSender sender)
    {
        return "Hello, World!"; // implicitly converted to a CommandResult
    }

}

Same command with overrides:

using System;
using Axwabo.CommandSystem.Attributes;
using Axwabo.CommandSystem.Commands;

[RemoteAdminCommand] // handler types must be specified using attributes (if applicable)
[CommandTarget(CommandHandlerType.RemoteAdmin)] // same as above
public sealed class MyCommand : CommandBase
{

    public override string Name => "myCommand";

    public override string Description => "My description";

    public override string[] Aliases { get; } = ["myAlias"];

    protected override CommandResult Execute(ArraySegment<string> arguments, CommandSender sender)
    {
        return CommandResult.Succeeded("Hello, World!");
    }

}

CommandResult

A CommandResult struct stores the response string and a bool indicating whether the command executed successfully.

You can create a CommandResult in one of the following ways:

  • Calling the string-only constructor
  • Calling the constructor with signature (bool, string) to specify whether the command was successful
  • Invoking the static method CommandResult.Succeeded(string)
  • Invoking the static method CommandResult.Failed(string)

Tip

Multiple implicit casts make it easier to create a CommandResult

  • string (based on the string-only constructor)
  • bool (response will be null)
  • (string, bool) (bool, string)
  • Enum conversion happens using result translation > - Up to 4 objects can be passed in using a tuple, for example: (Enum, object, object)

Caution

When using the implicit string cast, null will be converted as a null string, leading to an exception. Use CommandResult.Null in nullable result (CommandResult?) contexts.

String-only constructor

Invoking the constructor that only takes in a string will treat the response as failing if it begins with an ! (exclamation point). The first exclamation point is trimmed from the start.

If you want the ! symbol to be the first character of your message, create the CommandResult in a different way.

Permissions

Most commands should be restricted to certain groups of staff.

A command itself may implement the IPermissionChecker interface to override checking behavior. When this interface is implemented, attribute-based permission checkers are not resolved.

See the permissions article for details.

Execution sequence

  1. Ensure that the sender is a player if the command is player-only
  2. Permissions are checked
  3. A pre-execution filter may intercept the execution here
  4. Minimum argument count is checked
  5. The overriding command's Execute method is invoked

Player-Only

Add the PlayerOnlyCommandAttribute to the class to specify that the command can only be executed by players.

Implement the IPlayerOnlyCommand to specify a custom message when the sender is not a player. If the OnNotPlayer method returns CommandResult.Null, the execution sequence continues at step 4.

Warning

Only return CommandResult.Null if there won't be an attempt to get the player from the sender. Proceeding with execution when the sender isn't a player might lead to an exception.

Pre-Execution Filter

Implement the IPreExecutionFilter interface in the command class to add certain custom conditions before the command is executed. If the OnBeforeExecuted method returns CommandResult.Null, the execution sequence continues at step 4.

Caution

Returning null will be implicitly converted as a null string, leading to an exception. Use CommandResult.Null to allow execution to continue.

Command Handlers

Remote Admin

A command registered in this handler can be executed through the Text-Based Remote Admin. The base-game handler is RemoteAdminCommandHandler

The attribute is RemoteAdminCommand which uses CommandHandlerType.RemoteAdmin

Server Console

These commands can only executed by someone who has access to the dedicated server's console. Also known as the GameConsoleCommandHandler and not to be confused with the ClientCommandHandler

The attribute is ServerCommand which uses CommandHandlerType.ServerConsole

Client Console

Client commands are invoked by opening the game console (~ or `) on the client, then typing the command with a . prefix.

The attribute is ClientCommand which uses CommandHandlerType.Client

Clone this wiki locally