Skip to content

Creating Custom Discord Commands

This mod supports creating your own custom Discord commands that can then translate to Minecraft commands on call. This allows you to, for example, easily give your Discord moderators access to Minecraft moderation, even if they can't join the server or aren't trusted enough to be given full console access!

It can also be used to allow your normal users to access some less dangerous commands that they can normally access in game, out of game. For example, you could create a /currentday command which would allow all your Discord members to get the current day count without joining the server.

To get started, first open up the commands.yaml config file, which can be found at config/APDiscordIntegration/commands.yaml relative to the server folder. You should then see something like this:

Default Config:

commands.yaml
#   Custom Commands
#   Make custom Discord commands that then get ran as Minecraft Commands
#   Scroll to the bottom for commented examples

# Enable custom commands.
# If this is left at false, custom commands will not be created and any existing ones will be deleted!
enabled: false
# Restore the default commands on the next restart (this will set itself back to `false` after the
# default commands are restored)
# Note: This will not replace any existing commands contents to restore the default commands. If you edited
# one of the default commands instead of deleting them, you need to delete that command AND set this value to true
restoreDefaults: false
# Map of names (the part after the `/` on Discord) to custom commands.
# Names must be unique and are case-insensitive, and will be converted to lowercase to satisfy
# Discord's rules.
commands:
  kick:
    enabled: false
    description: Kick a player
    command: /kick ${Username} ${reason}
    outputFormat: TEXT_OUTPUT
    successMessage: '${output}'
    failureMessage: '${error}'
    ephemeral: true
    roleID: 0
    arguments:
      reason:
        description: Reason to kick player, shown to player on kick screen
        type: STRING
        required: false
        spaces: true
      username:
        description: Name of player to kick
        type: STRING
        required: true
        spaces: false
  currentday:
    enabled: true
    description: Get the current day count
    command: /time query day
    outputFormat: EXECUTE_STORE
    successMessage: The current day is ${output}
    failureMessage: 'Error: ${error}'
    ephemeral: false
    roleID: 0
    arguments: {}

The CustomCommand Object:

You may have seen that block of text as a config and got very confused. What does ephemeral: mean? What is a EXECUTE_STORE output format?

So before we get into actually making a custom command, let's get into what all of these keys mean!

enabled:

Is this command enabled? Options include:

  • true: This command is enabled. It will be in Discord's command list and the mod will respond to this command by executing it.
  • false: This command is disabled. It will not be in Discord's command list, and if it's somehow sent, the mod will respond to it with an error.

description:

Description of the command as shown on Discord

command:

Minecraft command to run.

The arguments are available here as placeholders. For example, you can get the value of an argument named username by using placeholder ${username}! Argument names are not case-sensitive.

outputFormat:

How should the ${output} placeholder in successMessage: be filled! Options include:

  • TEXT_OUTPUT: ${output} will be filled with the text output of the command.

    Example

    Command /time query day (on Day 5) would fill ${output} with The time is 5!

  • EXECUTE_STORE: ${output} will be filled with the return value of the command. This is what a /execute store result on said command would store. This result is different with every command. Usually you can figure out what a command's return value is using the Minecraft Wiki! Each command page on the Minecraft Wiki has an "Output" section which shows what /execute store result would output for the command.

    Example

    The Minecraft wiki says that command /time query day (on Day 5) will "output the obtained value". This means that ${output} will be filled with the number 5!

successMessage:

What should the bot send back to the user on success. The ${output} placeholder will be available and filled as above!

failureMessage:

What should the bot send back to the user on failure. The ${error} placeholder will be available and filled with the text error message output of the command.

ephemeral:

Should the command output be only shown to the caller? Ephemeral messages are those Discord messages bots send that have a blue background and can be dismissed, and more importantly, messages that only the person who ran the command can see. Options include:

  • true: The command output will only be visible to the message user.
  • false: The command output will be visible to everyone who can see the channel.

roleID:

Role ID that is allowed to run the command. You can obtain a role's ID by turning on Developer Mode in your Discord client and then right-clicking a role and clicking 'Copy Role ID'.

Alternatively, set roleID: to 0 to allow any user to run this command.

Warning

Be careful with what roles you allow to run a command, especially if the command is something laggy (like /fill) or something privileged (like /ban). Giving the wrong person access to certain commands can ruin the server for everyone else, especially if they keep lagging the server or just completely delete builds.

arguments:

List of arguments the command will have. Argument names are case-insensitive and will always appear lowercase in Discord. Argument order is kept to the best of the mod's ability, however optional arguments are forced to the end (this is a Discord limitation). Arguments are stored as a named list, where the name of an entry is the name of the argument.

Each argument has its own options, which will be shown below:

description:

Description of the argument as shown on Discord.

type:

Type of argument. This determines what input formats Discord will allow. Options include:

  • INTEGER: Whole number (number that is evenly divisible by 1)
  • NUMBER: Number (doesn't have to be whole)
  • STRING: Text (e.g. "player512" is a string)

required:

Is this argument required. If the argument is optional, the placeholder may hold an empty value. Options include:

  • true: Argument is required
  • false: Argument is optional

spaces:

Can this argument contain spaces. Options include:

  • true: Argument can contain spaces. This should only really be done for the last argument!
  • false: Argument cannot contain spaces. Spaces will be stripped out before the argument's contents are put into a placeholder. For example, "Spaces Thing" will be turned into "SpacesThing" before being passed to a command.

Creating a command:

To create a command, simply copy the following example command into the config's commands: section: 

exampleCommand:
  enabled: false
  description: Kick a player
  command: /kick ${Username} ${Reason}
  outputFormat: TEXT_OUTPUT
  successMessage: '${output}'
  failureMessage: '${error}'
  ephemeral: true
  roleID: 0
  arguments: {}

Note

YAML (the config language this mod uses) is indent based. This means the amount of spaces before each line matters. The more spaces behind the line, the deeper the line is. Make sure that if you're putting something into a section, you indent the line (add the set number of spaces before it) to tell the mod that a config item is part of a section. This mod's config has an indent size of 2 spaces, which means to increase a line's level by one, you need to add two spaces before it.

Example

In particular, for this code block, you'll need it to be at level 1, as it's part of the commands: section, which is at level 0. This means you have to add 2 spaces before every line, manually.

Tip

If you're confused, just compare your indentation with the default config!

Then fill in the values as required by the explanations above. Also replace exampleCommand with the name you want to give your command (this is the part after the / on Discord). You can do this until you reach the arguments: {} entry. At that point, you need to create an argument.

Creating an argument:

To create an argument, simply copy the following example argument into the command's arguments: {} section: 

exampleArgument:
  description: Name of player to kick
  type: STRING
  required: true
  spaces: false

Tip

Don't forget about the correct indentation

Fill in the values as required by the explanations above again, and also replace exampleArgument with the name you want to give your argument (as shown on Discord).

Enable the command system:

Now, you need to enable the command system. To do this, set enabled at the top of the config file to true. Also make sure to review the other default commands that have been generated, and make sure to disable or remove any you do not want.

After enabling the command system, just restart and...

Success

That's all! If you followed these steps correctly, you should now have a functioning custom command visible in Discord's command list. You can run it and a Minecraft command will run.

Didn't work?

If you failed to get the command to work correctly, then double check that your indentation is correct. Additionally, you can see the full command that's being run in the server logs. Make sure your placeholders are correct by checking said command run in the server logs.