Commands
SwiftlyS2's command system lets you register commands, hook client commands and chat, and manage permissions - via attributes or programmatically.
Access it through Core.Command (APIISwiftlyCore.Command, type APIICommandService).
Every attribute on this page is discovered on registered instances: the
plugin class is registered automatically, any other class needs
Core.Registrator.Register(instance) (APIIRegistratorService)
- see Using Attributes.
Registering Commands
With Attributes
Attach [Command] to a method matching void CommandListenerFunction(ICommandContext context).
[Command("heal", registerRaw: false, permission: "admins.commands.heal", helpText: "Heals yourself")]
public void OnHealCommand(ICommandContext context)
{
if (!context.IsSentByPlayer)
{
context.Reply("This command can only be used by players!");
return;
}
var player = context.Sender!;
}APICommand takes (name, registerRaw = false, permission = "", helpText = "SwiftlyS2 registered command") - registerRaw skips the sw_ prefix (so heal above registers as sw_heal), permission is checked through Permissions before the handler runs, and helpText is the description shown in command listings. All four values are also settable properties (Name, RegisterRaw, Permission, HelpText), so [Command("heal", HelpText = "Heals yourself")] works too, and an overload taking (name, registerRaw, permission) without helpText is kept for backward compatibility. A method takes only one [Command] (AllowMultiple = false) - see Command Aliases below for extra names.
Programmatically
The handler is a APIICommandService.CommandListener (void (ICommandContext context)), registered via APIICommandService.RegisterCommand - the returned Guid is for later unregistration.
public override void Load(bool hotReload)
{
var commandGuid = Core.Command.RegisterCommand("heal", OnHealCommand, helpText: "Heals yourself");
}
public void OnHealCommand(ICommandContext context)
{
context.Reply($"You used {context.CommandName}.");
}RegisterCommand(commandName, handler, registerRaw = false, permission = "", helpText = "SwiftlyS2 registered command") has the same options as the attribute. An overload taking registerRaw and permission without defaults (and no helpText) is kept for backward compatibility.
Command Context
Every handler receives an APIICommandContext:
Sender(APIIPlayer) andIsSentByPlayer(bool).CommandName(the command name) andArgs(string[], the arguments passed with the command).Prefix(the command prefix) andIsSlient(bool, the API's spelling) - whether the command should run without broadcasting to other players.Reply(string)andReplyAsync(string)(Task) to answer the sender.
Sender is null when the command is executed from server console. Always
check IsSentByPlayer before dereferencing Sender.
Unregistering Commands
Plugins auto-unregister their commands on unload. To do it manually, APIICommandService.UnregisterCommand takes either the Guid returned by RegisterCommand or a command name (unregistering every listener with that name), and APIICommandService.IsCommandRegistered checks whether a name is already taken.
Command Aliases
Aliases register the same handler under extra command names.
With Attributes
Stack APICommandAlias on an already-[Command]-registered method - it takes (alias, registerRaw = false), exposing both as the settable Alias and RegisterRaw properties, and allows multiple attributes per method, so heal can gain both hp and h:
[Command("heal")]
[CommandAlias("hp")]
[CommandAlias("h")]
public void OnHealCommand(ICommandContext context)
{
// reachable as sw_heal, sw_hp, sw_h
}Programmatically
RegisterCommandAlias(commandName, alias, registerRaw = false) adds an alias for the command registered under commandName (pass registerRaw: true when that command was registered raw):
// e.g. in Load():
Core.Command.RegisterCommandAlias("heal", "hp");
Core.Command.RegisterCommandAlias("heal", "h");See APIICommandService.RegisterCommandAlias for the full signature.
Introspection
Core.Command can enumerate what's registered, e.g. for a /plugins commands admin command: APIICommandService.GetAllCommands returns the registered names, APIICommandService.GetCommandsByPlugin takes a plugin name, APIICommandService.GetAllCommandsByPlugin maps every plugin name to its commands, and APIICommandService.GetAllCommandsInfo returns every command in one list - the latter three return APICommandInfo.
APICommandInfo is a record with four required, init-only properties: CommandName, RegisterRaw, Permission and HelpText.
Client Command Hooks
Intercept every console command a player sends (~ console), not just ones you registered - via [ClientCommandHookHandler] (a parameterless attribute) or programmatically with APIICommandService.HookClientCommand/APIICommandService.UnhookClientCommand. The handler is a ClientCommandHandler(int playerId, string commandLine) returning APIHookResult:
[ClientCommandHookHandler]
public HookResult OnClientCommand(int playerId, string commandLine)
{
if (commandLine.StartsWith("say"))
Console.WriteLine($"Player #{playerId} is using the say command");
return HookResult.Continue;
}HookClientCommand returns the Guid to pass to UnhookClientCommand:
var hookGuid = Core.Command.HookClientCommand(OnClientCommand);
// later:
Core.Command.UnhookClientCommand(hookGuid);Client Chat Hooks
Block or inspect chat messages before they reach other players - word filters, private chats, etc. Same shape, via [ClientChatHookHandler] or APIICommandService.HookClientChat/APIICommandService.UnhookClientChat. The handler is a ClientChatHandler(int playerId, string text, bool teamonly) returning APIHookResult (teamonly tells you whether the message is team-only):
[ClientChatHookHandler]
public HookResult OnClientChat(int playerId, string text, bool teamonly)
{
return text.Contains("badword") ? HookResult.Stop : HookResult.Continue;
}HookResult.Stop cancels the original call - the command is not processed and
the chat message is not broadcast - and skips the remaining hooks, so use it
deliberately. See APIHookResult for the other values
(Continue, Handled, CancelOriginal).