Modding:Commands

This page was last verified for Vintage Story version 1.19.3.

Ever wanted to know how to add a command to the game? If yes, this is the right place to get an answer.

Preparations

The idea is to add a command which makes it easier for your friends to locate you. Therefore we will spawn some particles alongside a playing sound, so others can see and hear where you are at the moment.

Implementation

As always, we need to create a class extending ModSystem:

public class CommandMod : ModSystem
{

}

We will be creating a server-side command, so our mod only needs to load on the server's side:

        public override bool ShouldLoad(EnumAppSide side)
        {
            return side == EnumAppSide.Server;
        }

Now we need to create the command itself:

        public override void StartServerSide(ICoreServerAPI api)
        {
            base.StartServerSide(api);
            AssetLocation sound = new AssetLocation("here", "sounds/partyhorn");
            api.ChatCommands.Create("here")
            .WithDescription("spawns particles around the player")
            .RequiresPrivilege(Privilege.chat)
            .RequiresPlayer();
        }

This command can be used by any player who is allowed to send a message (by default everyone). When a player types in /here, the command will be executed. Now we the only thing missing is the actual code to spawn particles and to play the sound.

        public override void StartServerSide(ICoreServerAPI api)
        {
            base.StartServerSide(api);
            AssetLocation sound = new AssetLocation("here", "sounds/partyhorn");
            api.ChatCommands.Create("here")
            .WithDescription("spawns particles around the player")
            .RequiresPrivilege(Privilege.chat)
            .RequiresPlayer()
            .HandleWith((args) =>
            {
                var byEntity = args.Caller.Entity;
                byEntity.World.PlaySoundAt(sound, byEntity);
                Vec3d pos = byEntity.Pos.XYZ.Add(0, byEntity.LocalEyePos.Y, 0);
                Random rand = new Random();
                for (int i = 0; i < 100; i++)
                {
                    Vec3d realPos = pos.AddCopy(-0.1 + rand.NextDouble() * 0.2, 0, -0.1 + rand.NextDouble() * 0.2);
                    Vec3f velocity = new Vec3f(-0.2F + (float)rand.NextDouble() * 0.4F, 0.4F + (float)rand.NextDouble() * 2F, -0.2F + (float)rand.NextDouble() * 0.4F);
                    byEntity.World.SpawnParticles(1, ColorUtil.ToRgba(255, rand.Next(0, 255), rand.Next(0, 255), rand.Next(0, 255)),
                        realPos, realPos,
                        velocity, velocity, (float)rand.NextDouble() * 1 + 1, 0.01F,
                        1, EnumParticleModel.Cube);
                }
                return TextCommandResult.Success();
            });
        }

If you want to learn more about how to use particles you can check out this tutorial.

Testing

Finally, we are ready to run our first test:

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.