2.2. The Basics of Denizen Commands

Before We Start

You know that tags are a way to retrieve information about something. Now what if we want to do something? You know, kill a player. Put that zombie in its place with a lightning strike. Maybe even just say hi to a player.

This all can be accomplished using something that we’ve been referring to and using almost nonstop since Section 1.2. Commands!

1. Command Syntax

In Denizen, commands are incredibly straightforward. They consist of the command name and the arguments. For more information regarding what is considered an argument, refer to Section 1.3.

Let’s look at the give command as a simple example. The basic syntax is outlined below. Additional information about the give command can be found here.

- give [money/xp/<item>|...] (quantity:<#>) (engrave) (unlimit_stack_size) (to:<inventory>) (slot:<slot>)

The first part of any Denizen command is the command name. This command’s name is, of course, “give”. Each new bit of text after the command name are the arguments.

Commands can have required arguments and optional arguments. If you fail to specify all of the required arguments, Denizen will throw an error. Optional arguments can be left out.

As we can see, there is one required argument and multiple optional arguments for the give command. For more information on how to read the command documentation, refer to the command syntax language explanation.

2. Command Arguments

When we write a command, what happens when we exclude certain arguments? What will Denizen do if we don’t tell it to do certain things? Not to worry, it won’t start throwing errors everywhere.

Consider this very simple script:

1
2
3
4
task_script:
    type: task
    script:
    - give i@diamond

Figure 2.2.1 A simple give command

As you can see, there is only one argument given to the give command. In plain terms, this give command gives you one diamond item, provided that you are playing on your server and are running this script using /ex run task_script.

What if we started including the other optional arguments? For example, the quantity argument?

Consider this edit of Figure 2.2.1:

1
2
3
4
task_script:
    type: task
    script:
    - give i@diamond quantity:10

Figure 2.2.2 A simple give command with a quantity argument

This give command will, in plain language, give us ten diamonds. When we didn’t specify a quantity, we only got one diamond.

When the optional arguments are left unspecified, Denizen will fill in the gaps for you. Specifying the optional arguments will allow you to further customize your experience. Neat, isn’t it?

In some cases, the default behavior may not be very clear. In that case, the Denizen command documentation will explicitly note which value is considered the default value of a particular optional argument. A good example of a command that has such behavior is the title command (documentation can be found here).

Afterword

With this, you know of the two most fundamental parts of a script block: tags and commands. We can finally start learning about unique script containers, how to use them, and what to do with them.