Bukkit

Replacement Syntax

The most basic functionality Commander offers (and kinda what you have to use in order to even consider using its scripting) is the replacement functionality. The Commander plugin has three contexts in which it parses and replaces input: the console command line, the players' commands, and the players' chat messages. Each of these contexts have a separate file in which replacements are listed. They are, by default, consolecmd.txt, playercmd.txt, and playerchat.txt, respectfully. What follows is the syntax Commander uses in these files:

Simple Replacement Example

Here is an example of a simple replacement in playercmd.txt. This example uses a warp plugin, which is called via the "warp" command:

/hub/ ==> warp $p hubWarp

With this replacement, when the player types in the command "/hub" (or "/HUB", as the first part is matched insensitively by default), Commander will execute the command "warp <PlayerName> hubWarp" in its place. It's that simple.

Syntax

Here are the valid syntaxes for replacements:

/regex/opts ==> replacement
/regex/opts =r=> random;replacement;semicolon;separated
/regex/opts =c=> command

(Upgrade Note: When moving from version 1.x to version 2.x, the replacement options have been removed in favor of in-line [run script] constructs. Any options that were available have been replaced with better-functioning script versions.)

Let's take a look at what goes in these syntax definitions:

• regex - The regex is the regular expression to be matched against ("regex" is short for "regular expression". The expression can use any of the features a regular expression in java can use, including end matching, look-backs, look-aheads, group capture, etc. By default, regexes are matched case-insensitively.
• opts - The regex options are optional one-letter options that change how the regular expression is matched. Supported options are:
  • s = turn on case sentitivity
  • l = (lowercase L) turn on the regex literal option
• replacement or command - The replacement command that will be executed, for command contexts or forced commands in chat, or the text that will replace the matched text in chat contexts. Back references can be used in the replacement or command. These include back references to regex matching groups ($1 to $9, or $0 for the whole matched text), and special references provided by Commander ($p for the name of the player activating the replacement, $w for the name of world that player is in).

Beyond these, there is also the replacement method, which is defined by the arrow that comes between the regex and the replacement.

• ==> - Normal replacement. If the context is command-matching, the regex will be tested against the whole command, and the replacement is the substitute command. If the context is chat-matching, the regex will run as a find-replace on the chat, and can hit multiple times. Each time, the replacement will replace the matched text.
• =c=> - Force command (or command word). In a command-matching context, this is no different from normal mode. But in a chat-matching context, this will activate as a "command word" (see below), and will run the command or script.
• =r=> - Random replacement. Available only in a chat-matching context, the random replacement mode will replace the matched text with one of the possible strings separated by semicolons (;).

Scripting

I forgot to include one syntax type above: the script syntax type:

/regex/opts =={ alias
    script
}

This creates a script that will execute when the regex is matched. In addition to the regex and regex options from above, there are now:

• alias - An optional script alias for the script below.
• script - The script itself. See the Advanced Scripting section on how scripting works.

Command Words

When you have a chat replacement that executes a command, we call it a "command word" as a short hand. When executing a command word, scripts have access to two extra special variables that are taken into account when the script is finished:

• @__repl__ - This variable holds the string that will replace the matched word. By default, it is "$0", or the whole matched word, essentially meaning that that word will not change when the command word is spoken. You may assign any string to this variable.
• @__endparse__ - This boolean variable tells Commander that when this word is spoken, the rest of what the player says will be cut off. This is the replacement for the "cutoff" replacement option from 1.x.

So, for example, if you want the player to be kicked for a word (like a swear word or, in this example, a meme), you can use this replacement:

/candlejack/ =={
    @__repl__ = candleja--*
    @__endparse__ = true
    sudo kick $p Candlejack has taken you
}

Or, if you want a special command word to do something in the world, while obscuring the word, you can do something like this:

/strun bah qo/ =={     #Skyrim's Storm Call shout
    @__repl__ = §k$0§r     #code §k is the random letter code, §r resets
    toggledownfall       #vanilla minecraft's toggle rain/snow command
}