Got a question that the wiki doesn't answer? Ask on the forum (preferred), or join us on IRC.


CommandHelper/Staged/Beginner's Guide

From Wiki
Jump to: navigation, search

This page assumes you have already installed and are running CommandHelper. Note that the instructions here are designed for the master alias file, but in general will work for user aliases and LocalPackages as well.


In general, an alias is specified as such:

1   /alias_command = /real_command

and macros are specified as such:

1   /alias_command = /real1 \ /real2 \ /real3 \ etc...

When using global aliases, each alias is defined on it's own line, meaning that a newline separates the aliases from each other. The exception to this rule is that when using macros, each macro can be on a line of its own, as long as the previous line ends in a backslash. (Another exception is when you use the "multiline construct", which is covered below.) All rules applying to aliases may be used for individual user aliases, except of course that you can't have newlines when adding user aliases. Global aliases go in the aliases.msa file, located at the root of the CommandHelper folder, and use the exact same syntax as in game aliases, which are added using the /alias command. Global aliases are added in aliases.msa, and everybody can use them, and user aliases are added in game with /alias, and only apply to that user.

1   /alias_command = /real1 \
2   /real2 \
3   /real3

A macro is a series of scripts that are all run at the same time (in order). Each script is completely separate from each other, so things like variable declarations and such won't carry over from each macro. If you have a more complex script, consider using multiline scripts and the run() function. In general, you should use the best practice method of writing scripts, even for simple scripts:

1   /alias = run('/real_command');

This corresponds to the same simple script:

1   /alias = /real_command

however, the best practice method is more guaranteed to work in future versions. For scratch or temporary aliases however, the less verbose method is acceptable. The rest of the examples in the wiki will generally conform to the best practice method.

In the config file, lines that begin with a # or // are comments, and are ignored by the compiler. This is useful for commenting complex scripts, to show what exactly they do. When the plugin starts, it attempts to compile all the scripts. If the compilation fails, it will try to give you a useful error message to let you know where the error was in your script. Commands on the right side must be commands that the player could have simply typed in themselves. CommandHelper does no permission checking at all before running commands using run(), but simply runs commands as that user. If a real command is provided by a plugin, that plugin must be installed and working for the command to run successfully. (Having said that, the built-in functions do provide alot of functionality that is not strictly alias related). Once you have added a new alias or new scripts, you must use /reloadaliases to refresh the aliases. If you messed up the syntax, you will get a compiler warning, in which case, you should carefully read the error, which will give you a line number and file to look at, and see what it is that you messed up.

Simple Aliases

A simple alias maps one command to another. For example, in the vanilla server, there is the command /save-all, which for brevity sake, we may want to shorten to /save. The alias for this command would be:

1   /save = run('/save-all');

Fairly simple! Note that we MUST quote this (though using run() is technically optional) because the - symbol would cause a compile error otherwise.

Multiline Construct

The multiline construct is only available in global configs, due to the sheer nature of how users input aliases.

Since complex alias scripts would be hard to read if they were only on one line, the multiline construct allows you to put as many newlines in the middle of your alias definition as you want. To use the multiline construct, use the following syntax:

/cmd = >>>
#As many newlines as you want

The special symbols >>> and <<< are the "multiline start" and "multiline end" symbols. They may not appear in any other context throughout your script (even in strings). Newlines inside the construct are simply ignored, and do not denote the end of the alias. The multiline end symbol does not have to be on a line of it's own, but the multiline start symbol must come directly after the equals sign.

If you need a literal multiline construct, you must break it apart and concatenate it, for instance, instead of using

1   '>>>'

you would use

1   '>'.'>>'

There is no runtime penalty for doing this concatenation, the compiler is smart enough to figure out what you mean at compile time, but since these symbols are part of the lexer, they cannot be used normally in any other context.


Note: Macros are not recommended for use, see below for alternate syntax to do the same thing, see below

Macros allow you to run several commands with only having typed in one command. One common use may be to create "kits" for players to use, which spawn several items at once. Here is an example for that:

1   /kit gold = /give player() 284 64 \ /give player() 285 64 \ /give player() 286 64

Note that we are defining the literal "gold" here. The command will not be intercepted without the user running "/kit gold", simply running "/kit" will not trigger this alias.

The player() is a function. Using all the functions is a more advanced feature, but the player() function is fairly simple; all it does is give you the name of the player issuing the command. So, specifically, "/give player() 284 64" would be turned into "/give playerName 284 64".

In general, macros are not recommended for use. Instead, use the multiline construct and multiple run() calls. The same code from above can be written as such (using full strict syntax with operators):

1   /kit gold = >>>
2      run('/give '.player().' 284 64');
3      run('/give '.player().' 285 64');
4      run('/give '.player().' 286 64');
5   <<<

The advantage of this is that the code is easier to read, and details like variable assignments work as expected.


Sometimes we want to use the input provided by the user to put into our aliased command. For instance, if we wanted to shorten a /give command, we could do this:

1   /i $data $qty = run('/give' player() $data $qty);

This gives the player $qty blocks of $data. So, if they typed "/i 1 64" then $data would be assigned 1, and $qty would be assigned 64. Note that all variables start with a dollar sign ($).

What if we want to provide a default value for a variable? We can do that too. Suppose the player by default would want 64 of an item. We can do that with the following syntax:

1   /i $data [$qty=64] = run('/give' player() $data $qty);

Now, in the event the player types "/i 1", $qty would still get assigned 64. The square brackets denote an optional argument. We could have not assigned anything to the variable [$qty], and by default we would have assigned an empty string. Sometimes this may be useful, but most of the time, you will want to actually assign some sort of value.

Only static values can be assigned as default. Function calls or other dynamic code cannot be assigned, however, strings (with or without special symbols) may be assigned using [$var='the-string']. If literal portions of the alias have special symbols in them, they may also be quoted, for instance:

1   '//alias-with-special-characters' = run('/command');

Final Variable

Final variables allow you to specify a variable number of arguments be assigned to one variable. There is a special variable defined for this purpose, "$". This is particularly useful for writing some sort of message alias. Say we want to create an alias for /tell.

1   /msg $player $ = >>>
2      // Only allow the player 'player' to receive messages
3      if($player == 'player'){
4         run('/tell' $player $);
5      }
6   <<<

Note that a user's command is parsed into sections based on spaces but any arguments not specifically captured by variables will be put in the final variable. Another common approach is to trigger an alias based on the first command verb, and ignore the rest of the arguments, whether or not they provided them.

1   /command [$] = msg('Runs this command no matter what extra parameters were sent in');

Another common use is to accept the entirety of the user's command into the $ var, and use the parse_args() function to use a more "standard" command line type argument.

1   /command [$] = >>>
2      @array = parse_args($); // Now the arguments will be separated into various parameters.
3   <<<

Alias Signatures

To better understand how to write a script and debug a potential problem, it may be helpful to understand the basics of how the alias engine works. When the config file is initially parsed, it is checked for compile errors, but no commands are being run at that time. It is however compiled into an intermediate stage that can more quickly be processed when a user runs a command. Once a user runs a command, this sequence is followed:

The command is checked against the signatures of all defined aliases (the left side of the alias) to see if it matches. It is not possible to have the same signature for two aliases within the config file, but a user may have defined an alias with an identical signature in their personal aliases. In this event, the global alias will be run. If a match is found, any variables are assigned, then filled in on the right side, and functions are resolved, then each command in the macro (possibly only one command) is run.

For a command to "match" an alias, the following factors are taken into consideration. Any literals must match exactly. Non-optional variables must be present, but can be anything. Optional variables may be present, but extra arguments will make the match fail. (Except in the case of a final variable being present.) Let's look at the following two command signatures:

1   /cmd $var1 [$var2]
2   /cmd $var1 $var2

Both of these signatures are ambiguous, because the command "/cmd one two" would match both signatures.

1   /cmd $var1
2   /cmd $var1 $var2

The above two commands would not be ambiguous however, because the command "/cmd one two" would only match the second one.

Built-In Commands

As well as providing alias functionality, there are a few built in commands. These commands provide meta-functionality for dealing with user aliases and other useful features.

  • /reloadaliases - Reloads the global alias file, while the game is running (ops only)

(See the advanced page for usage options)

  • /runalias - Certain configurable plugins might not use the standard method to call commands, so you would get "Unknown Command."

for commands that otherwise work when entered normally. Instead use "/runalias /myalias".

Continued Learning

The advanced guide covers more of the scripting elements of CommandHelper, and can be used to jump start learning the scripting basics. The API and other concepts are covered in the learning trail:

Navigation menu