Need help? Ask on the forum, ask a fellow user or developer (join us on IRC), or contact sk89q.
Contribute to the wiki, edit this page! Register an account, or login with Facebook first.
HEY! Do you integrate (or want to) a plugin into yours? Do you help work on WE/WG/etc.? Please subscribe to our mailing list!
This page assumes you have already installed and are running CommandHelper. Note that the instructions here are designed for the master configuration file, but in general will work for user aliases as well.
In general, an alias is specified as such:
/alias_command = /real_command
and macros are specified as such:
/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", but that's an advanced topic.) 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 config.txt 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 config.txt, and everybody can use them, and user aliases are added in game with /alias, and only apply to that user.
/alias_command = /real1 \ /real2 \ /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
In the config file, lines that begin with a # are comments, and are ignored by the alias engine. This is useful for commenting complex aliases, to show what exactly they do. When the plugin starts, it attempts to compile the config file. If the compilation fails, it will try to give you a useful error message to let you know where the error was in your config file. 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, but simply runs the aliased 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, you must use /reloadaliases to refresh the aliases. If you messed up the syntax, you may get a compiler warning, in which case, you should carefully read the error, which will give you a line number to look at, and see what it is that you messed up.
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:
/save = /save-all
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:
/kit gold = /give player() 284 64 \ /give player() 285 64 \ /give player() 286 64
Note that we are defining the literal "gold" here. See the advanced guide for an introduction of data types in regards to scripting.
But wait! What is that player() thing there? That's 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".
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:
/i $data $qty = /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:
/i $data [$qty=64] = /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.
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.
- /. or /repeat - Reruns the user's last command, if there was one.
- /alias <alias> - Adds a new user alias to the list of aliases for this user
- /viewalias or /viewaliases - Shows all of the aliases for this user, as well as their id, which is used to delete the alias
- /delalias <id> [<id>...] - Deletes the specified alias(es)
- /reloadaliases - Reloads the global alias file, while the game is running (ops only)