MethodScript

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 LocalPackages as well. ===General=== In general, an alias is specified as such: and macros are specified as such: 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.) Global aliases go in the aliases.msa file, located at the root of the CommandHelper folder, and everybody can use them. 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 {{function|run}} function. In general, you should use the best practice method of writing scripts, even for simple scripts: This corresponds to the same simple script: 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, and being able to add freeform text within the code 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: 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=== 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: 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 you would use 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. ===Macros=== {{TakeNote|text=Macros are not recommended for use, as they become difficult to read if the command becomes more than, just a few lines. See below for alternate syntax to do the same thing with a more programmatic approach.}} 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: 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() golden_shovel" would be turned into "/give playerName golden_shovel". 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): The advantage of this is that the code is easier to read, and details like variable assignments work as expected. ===Variables=== 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: 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: 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: ===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. 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. Another common use is to accept the entirety of the user's command into the $ var, and use the {{function|parse_args}} function to use a more "standard" command line type argument. ===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. 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: Both of these signatures are ambiguous, because the command "/cmd one two" would match both signatures. 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 aliases and other useful features. * /recompile - Reloads the global alias file, while the game is running (ops only) \ [[Advanced_Guide#recompile|(See the advanced page for usage options)]]. /reloadaliases is an alias to this command. * /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, at the bottom of this page.

Find a bug in this page? Edit this page yourself, then submit a pull request.