2.0 ‐ Adding a command

2.0 - Command Integration

Now, we will delve into the process of adding a command to your plugin. If you've been following the previous tutorial, your main plugin class should resemble the following:

using Terraria.ID;
using Terraria;
using TerrariaApi.Server;
using TShockAPI;

namespace TShockTutorials
{
    [ApiVersion(2,1)]
    public class TShockTutorialsPlugin : TerrariaPlugin
    {
        public override string Author => "Average";
        public override string Name => "TShock Tutorial Plugin";
        public override string Description => "A sample plugin for educating aspiring TShock developers.";
        public override Version Version => new(1,0);

        public TShockTutorialsPlugin(Main game) : base(game)
        {

        }

        public override void Initialize()
        {
            // new Command("permission.nodes", "add.as.many", "as.you.like", ourCommandMethod, "these", "are", "aliases");
            Commands.ChatCommands.Add(new Command("tutorial.command", TutorialCommand, "tutorial", "tcmd"));
        }

        private void TutorialCommand(CommandArgs args)
        {
            // retrieve our player from the CommandArgs object
            var player = args.Player;
            
            // if the player doesn't exist, return (this is done to prevent errors)
            // guards like this should be implemented frequently to avoid exceptions
            if (player is null) return;

            // make sure the player is active and not being run by the server
            if (player.Active && player.RealPlayer) return;

            // create a new Random class for random number generation
            Random rand = new Random();

            // create a new empty item object
            Item randItem = new Item();

            // get a random item id
            // you will need to add 'using Terraria.ID' to use ItemID
            int randItemID = rand.Next(0, ItemID.Count);

            // configure our newly created item class
            randItem.SetDefaults(randItemID);

            // we can also specify a prefix and stack size if desired:
            randItem.stack = 128;
            randItem.prefix = PrefixID.Legendary;

            // give the player the item
            player.GiveItem(randItem.type, randItem.stack, randItem.prefix);

            // inform the player
            player.SendSuccessMessage($"You have been given {randItem.stack}x {randItem.Name} ({Lang.prefix[randItem.prefix].Value}!");
        }
    }
}

To add a command, you can integrate the following line within the Initialize() method:

Commands.ChatCommands.Add(new Command("tutorial.command", TutorialCommand, "tutorial", "tcmd"));

Here's an explanation of each part:

• Permission nodes: These are added to groups and grant permission for the group and its users to execute the command.
• Our command method: This references the method that will execute the command's code and implement its functionality.
• Aliases: These are the triggers users can employ to execute the command. For example, both /tutorial and /tcmd will invoke the command in-game.

Upon implementing this code, you may notice that errors emerge, rendering the code uncompilable. This is due to the absence of the command method. To create it in Visual Studio, right-click the method and select "Refactorings." Then, choose the option to generate the method.

The generated method will look like this:

private void TutorialCommand(CommandArgs args)
{
    throw new NotImplementedException();
}

You can remove the throw new NotImplementedException(); line, as it will be replaced with your custom code.

Now, your command is integrated! However, if you execute the command in-game, you will notice that it has no function. Let's enhance the command to provide the player with a random item and a notification.

You can achieve this with the following code:

private void TutorialCommand(CommandArgs args)
{
    // Retrieve the player from the CommandArgs object
    var player = args.Player;
    
    // If the player doesn't exist, return (to prevent errors)
    // Implement such guards frequently to avoid exceptions
    if (player is null) return;

    // Ensure the player is active and not being controlled by the server
    if (player.Active && player.RealPlayer) return;

    // Create a new Random class for random number generation
    Random rand = new Random();

    // Create an empty item object
    Item randItem = new Item();

    // Get a random item ID
    // You will need to add 'using Terraria.ID' to use ItemID
    int randItemID = rand.Next(0, ItemID.Count);

    // Configure the newly created item class
    randItem.SetDefaults(randItemID);

    // Optionally specify a prefix and stack size
    randItem.stack = 128;
    randItem.prefix = PrefixID.Legendary;

    // Grant the item to the player
    player.GiveItem(randItem.type, randItem.stack, randItem.prefix);

    // Notify the player
    player.SendSuccessMessage($"You have been given {randItem.stack}x {randItem.Name} ({Lang.prefix[randItem.prefix].Value}!");
}

Now, when a player uses /tcmd or /tutorial, they will receive a random item with a stack size of 128, a Legendary prefix, and a notification informing them about the item they've obtained.

At this point, your main plugin class should resemble the following:

using Terraria.ID;
using Terraria;
using TerrariaApi.Server;
using TShockAPI;

namespace TShockTutorials
{
    [ApiVersion(2,1)]
    public class TShockTutorialsPlugin : TerrariaPlugin
    {
        public override string Author => "Average";
        public override string Name => "TShock Tutorial Plugin";
        public override string Description => "A sample plugin for educating aspiring TShock developers.";
        public override Version Version => new(1,0);

        public TShockTutorialsPlugin(Main game) : base(game)
        {

        }

        public override void Initialize()
        {
            // new Command("permission.nodes", "add.as.many", "as.you.like", ourCommandMethod, "these", "are", "aliases");
            Commands.ChatCommands.Add(new Command("tutorial.command", TutorialCommand, "tutorial", "tcmd"));
        }

        private void TutorialCommand(CommandArgs args)
        {
            // Retrieve the player from the CommandArgs object
            var player = args.Player;
            
            // If the player doesn't exist, return (to prevent errors)
            // Implement such guards frequently to avoid exceptions
            if (player is null) return;

            // Ensure the player is active and not being controlled by the server
            if (player.Active && player.RealPlayer) return;

            // Create a new Random class for random number generation
            Random rand = new Random();

            // Create an empty item object
            Item randItem = new Item();

            // Get a random item ID
            // You will need to add 'using Terraria.ID' to use ItemID
            int randItemID = rand.Next(0, ItemID.Count);

            // Configure the newly created item class
            randItem.SetDefaults(randItemID);

            // Optionally specify a prefix and stack size
            randItem.stack = 128;
            randItem.prefix = PrefixID.Legendary;

            // Grant the item to the player
            player.GiveItem(randItem.type, randItem.stack, randItem.prefix);

            // Notify the player
            player.SendSuccessMessage($"You have been given {randItem.stack}x {randItem.Name} ({Lang.prefix[randItem.prefix].Value}!");
        }
    }
}