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

About the ads

CommandHelper/API

From SK's Wiki
< CommandHelper
Revision as of 21:13, 1 March 2012 by Wraithguard01 (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Warning: If you are running a development version, you should read the staged wiki page, which has information pertinent to the latest development builds

Command Helper uses a language called MScript, which greatly extend the capabilities of the plugin, and make the plugin a fully Turing Complete language. There are several functions defined, and they are grouped into "classes".

Each function has its own page for documentation, where you can put examples for how to use particular functions. Because this is a wiki, it is encouraged that you edit the pages if you see errors, or can think of a better example to show. Please copy over this template and use it.

Contents

ArrayHandling

This class contains functions that provide a way to manipulate arrays. To create an array, use the array function. For more detailed information on array usage, see the page on arrays

Function Name Returns Arguments Throws Description Since Restricted
array_contains boolean array, testValue CastException Checks to see if testValue is in array. 3.0.1
No
array_contains_ic boolean array, testValue CastException Works like array_contains, except the comparison ignores case. 3.3.0
No
array_get mixed array, index CastException

IndexOverflowException

Returns the element specified at the index of the array. If the element doesn't exist, an exception is thrown. array_get(array, index). Note also that as of 3.1.2, you can use a more traditional method to access elements in an array: array[index] is the same as array_get(array, index), where array is a variable, or function that is an array. In fact, the compiler does some magic under the covers, and literally converts array[index] into array_get(array, index), so if there is a problem with your code, you will get an error message about a problem with the array_get function, even though you may not be using that function directly. 3.0.1
No
array_implode string array, [glue] CastException Given an array and glue, to-strings all the elements in the array (just the values, not the keys), and joins them with the glue, defaulting to a space. For instance array_implode(array(1, 2, 3), '-') will return "1-2-3". 3.3.0
No
array_index_exists boolean array, index CastException Checks to see if the specified array has an element at index 3.1.2
No
array_keys array array CastException Returns the keys in this array as a normal array. If the array passed in is already a normal array, the keys will be 0 -> (array_size(array) - 1) 3.3.0
No
array_merge array array1, array2, [arrayN...] InsufficientArgumentsException

CastException

Merges the specified arrays from left to right, and returns a new array. If the array merged is associative, it will overwrite the keys from left to right, but if the arrays are normal, the keys are ignored, and values are simply pushed. 3.3.0
No
array_normalize array array CastException Returns a new normal array, given an associative array. (If the array passed in is not associative, a copy of the array is returned). 3.3.0
No
array_push void array, value, [value2...] CastException Pushes the specified value(s) onto the end of the array 3.0.1
No
array_remove void array, index CastException Removes an index from an array. If the array is a normal array, all values' indicies are shifted left one. If the array is associative, the index is simply removed. If the index doesn't exist, the array remains unchanged. 3.3.0
No
array_resize void array, size, [fill] CastException Resizes the given array so that it is at least of size size, filling the blank spaces with fill, or null by default. If the size of the array is already at least size, nothing happens; in other words this function can only be used to increase the size of the array. 3.2.0
No
array_set void array, index, value CastException

IndexOverflowException

Sets the value of the array at the specified index. array_set(array, index, value). Returns void. If the element at the specified index isn't already set, throws an exception. Use array_push to avoid this. 3.0.1
No
array_size int array CastException Returns the size of this array as an integer. 3.0.1
No
range array start, finish, [increment]
finish
CastException Returns an array of numbers from start to (finish - 1) skipping increment integers per count. start defaults to 0, and increment defaults to 1. All inputs must be integers. If the input doesn't make sense, it will reasonably degrade, and return an empty array. 3.2.0
No

BasicLogic

These functions provide basic logical operations.

Function Name Returns Arguments Throws Description Since Restricted
and boolean var1, [var2...] CastException Returns the boolean value of a logical AND across all arguments. Uses lazy determination, so once an argument returns false, the function returns. 3.0.1
No
bit_and int int1, [int2...] CastException

InsufficientArgumentsException

Returns the bitwise AND of the values 3.3.0
No
bit_not int int1 CastException Returns the bitwise NOT of the given value 3.3.0
No
bit_or int int1, [int2...] CastException

InsufficientArgumentsException

Returns the bitwise OR of the specified values 3.3.0
No
equals boolean var1, var2[, varX...] InsufficientArgumentsException Returns true or false if all the arguments are equal 3.0.1
No
equals_ic boolean val1, val2[, valX...] InsufficientArgumentsException Returns true if all the values are equal to each other, while ignoring case. 3.2.0
No
gt boolean var1, var2 CastException Returns the result of a greater than operation 3.0.1
No
gte boolean var1, var2 CastException Returns the result of a greater than or equal to operation 3.0.1
No
if mixed cond, trueRet, [falseRet] CastException If the first argument evaluates to a true value, the second argument is returned, otherwise the third argument is returned. If there is no third argument, it returns void. 3.0.1
No
ifelse mixed [boolean1, code]..., [elseCode] InsufficientArgumentsException Provides a more convenient method for running if/else chains. If none of the conditions are true, and there is no 'else' condition, void is returned. 3.3.0
No
lshift int value, bitsToShift CastException Left shifts the value bitsToShift times 3.3.0
No
lt boolean var1, var2 CastException Returns the results of a less than operation 3.0.1
No
lte boolean var1, var2 CastException Returns the result of a less than or equal to operation 3.0.1
No
nand boolean val1, [val2...] CastException Return the equivalent of not(and()) 3.3.0
No
nequals boolean val1, val2 Returns true if the two values are NOT equal, or false otherwise. Equivalent to not(equals(val1, val2)) 3.3.0
No
nequals_ic boolean val1, val2 Returns true if the two values are NOT equal to each other, while ignoring case. 3.3.0
No
nor boolean val1, [val2...] CastException Returns the equivalent of not(or()) 3.3.0
No
not boolean var1 CastException Returns the boolean value of a logical NOT for this argument 3.0.1
No
or boolean var1, [var2...] CastException Returns the boolean value of a logical OR across all arguments. Uses lazy determination, so once an argument resolves to true, the function returns. 3.0.1
No
rshift int value, bitsToShift CastException Right shifts the value bitsToShift times 3.3.0
No
sequals boolean val1, val2 Uses a strict equals check, which determines if two values are not only equal, but also the same type. So, while equals('1', 1) returns true, sequals('1', 1) returns false, because the first one is a string, and the second one is an int. More often than not, you want to use plain equals(). 3.3.0
No
switch mixed value, [equals, code]..., [defaultCode] InsufficientArgumentsException Provides a switch statement. If none of the conditions match, and no default is provided, void is returned. See the documentation on Logic for more information. 3.3.0
No
urshift int value, bitsToShift CastException Right shifts value bitsToShift times, pushing a 0, making this an unsigned right shift. 3.3.0
No
xnor boolean val1, val2 CastException Returns the xnor of the two values 3.3.0
No
xor boolean val1, val2 CastException Returns the xor of the two values. 3.3.0
No

Crypto

Provides common cryptographic functions

Function Name Returns Arguments Throws Description Since Restricted
md5 string val PluginInternalException Returns the md5 hash of the specified string. The md5 hash is no longer considered secure, so you should not use it for storage of sensitive data, however for general hashing, it is a quick and easy solution. md5 is a one way hashing algorithm. 3.3.0
No
rot13 string val Returns the rot13 version of val. Note that rot13(rot13(val)) returns val 3.3.0
No
sha1 string val PluginInternalException Returns the sha1 hash of the specified string. Note that sha1 is considered more secure than md5, and is typically used when storing sensitive data. It is a one way hashing algorithm. 3.3.0
No

DataHandling

This class provides various methods to control script data and program flow.

Function Name Returns Arguments Throws Description Since Restricted
array array [var1, [var2...]] Creates an array of values. 3.0.1
No
assign ivariable ivar, mixed CastException Accepts an ivariable ivar as a parameter, and puts the specified value mixed in it. Returns the variable that was assigned. 3.0.1
No
boolean boolean item Returns a new construct that has been cast to a boolean. The item is cast according to the boolean conversion rules. Since all data types can be cast to a a boolean, this function will never throw an exception. 3.3.0
No
break nothing [int] CastException Stops the current loop. If int is specified, and is greater than 1, the break travels that many loops up. So, if you had a loop embedded in a loop, and you wanted to break in both loops, you would call break(2). If this function is called outside a loop (or the number specified would cause the break to travel up further than any loops are defined), the function will fail. If no argument is specified, it is the same as calling break(1). 3.1.0
No
call_proc mixed proc_name, [var1...] InvalidProcedureException Dynamically calls a user defined procedure. call_proc(_myProc, 'var1') is the equivalent of _myProc('var1'), except you could dynamically build the procedure name if need be. This is useful for having callbacks in procedures. Throws an InvalidProcedureException if the procedure isn't defined. 3.2.0
Yes
closure closure code Returns a closure on the provided code. A closure is a datatype that represents some code as code, not the results of some code after it is run. Code placed in a closure can be used as a string, or executed by other functions using the eval() function. If a closure is "to string'd" it will not necessarily look like the original code, but will be functionally equivalent. The environment is not inherently stored with the closure, however, specific functions may choose to store the environment in addition to the closure. 3.3.0
Yes
continue void [int] CastException Skips the rest of the code in this loop, and starts the loop over, with it continuing at the next index. If this function is called outside of a loop, the command will fail. If int is set, it will skip 'int' repetitions. If no argument is specified, 1 is used. 3.1.0
No
double double item CastException Returns a new construct that has been cast to an double. This function will throw a CastException if is_numeric would return false for this item, but otherwise, it will be cast properly. 3.3.0
No
export void ivar
name, value
InsufficientArgumentsException Stores a value in the global storage register. When using the first mode, the ivariable is stored so it can be imported later, and when using the second mode, an arbitrary value is stored with the give key, and can be retreived using the secode mode of import. If the value is already stored, it is overwritten. See import() and importing/exporting 3.3.0
Yes
for void assign, condition, expression1, expression2 CastException Acts as a typical for loop. The assignment is first run. Then, a condition is checked. If that condition is checked and returns true, expression2 is run. After that, expression1 is run. In java syntax, this would be: for(assign; condition; expression1){expression2}. assign must be an ivariable, either a pre defined one, or the results of the assign() function. condition must be a boolean. 3.0.1
No
foreach void array, ivar, code CastException Walks through array, setting ivar equal to each element in the array, then running code. 3.0.1
No
import mixed ivar
string
This function imports a value from the global value register. In the first mode, it looks for an ivariable with the specified name, and stores the value in the variable, and returns void. In the second mode, it looks for a value stored with the specified key, and returns that value. Items can be stored with the export function. If the specified ivar doesn't exist, the ivar will be assigned an empty string, and if the specified string key doesn't exist, null is returned. See the documentation on imports/exports for more information. 3.3.0
Yes
include void path IncludeException Includes external code at the specified path. 3.2.0
Yes
integer integer item CastException Returns a new construct that has been cast to an integer. This function will throw a CastException if is_numeric would return false for this item, but otherwise, it will be cast properly. Data may be lost in this conversion. For instance, 4.5 will be converted to 4, by using integer truncation. You can use is_integral to see if this data loss would occur. 3.3.0
No
is_array boolean item Returns whether or not the item is an array 3.1.2
No
is_associative boolean array CastException Returns whether or not the array is associative. If the parameter is not an array, throws a CastException. 3.3.0
No
is_boolean boolean item Returns whether the given item is of the boolean datatype. Note that all datatypes can be used as booleans, however this function checks the specific datatype of the given item. 3.1.2
No
is_double boolean item Returns whether or not the given item is a double. Note that numeric strings and integers can usually be used as a double, however this function checks the actual datatype of the item. If you just want to see if an item can be used as a number, use is_numeric() instead. 3.1.2
No
is_integer boolean item Returns whether or not the given item is an integer. Note that numeric strings can usually be used as integers, however this function checks the actual datatype of the item. If you just want to see if an item can be used as a number, use is_numeric() instead. 3.1.2
No
is_integral boolean item CastException Returns true if the numeric value represented by a given double or numeric string could be cast to an integer without losing data (or if it's an integer). For instance, is_numeric(4.5) would return true, and integer(4.5) would work, however, equals(4.5, integer(4.5)) returns false, because the value was narrowed to 4. 3.3.0
No
is_null boolean item Returns whether or not the given item is null. 3.1.2
No
is_numeric string item Returns false if the item would fail if it were used as a numeric value. If it can be parsed or otherwise converted into a numeric value, true is returned. 3.3.0
No
is_proc boolean procName Returns whether or not the given procName is currently defined, i.e. if calling this proc wouldn't throw an exception. 3.2.0
Yes
is_string boolean item Returns whether or not the item is a string. Everything but arrays can be used as strings. 3.1.2
No
proc void [name], [ivar...], procCode FormatException Creates a new user defined procedure (also known as "function") that can be called later in code. Please see the more detailed documentation on procedures for more information. 3.1.3
Yes
return nothing mixed Returns the specified value from this procedure. It cannot be called outside a procedure. 3.2.0
No
string string item Creates a new construct that is the "toString" of an item. For arrays, an human readable version is returned; this should not be used directly, as the format is not guaranteed. Booleans return "true" or "false" and null returns "null". 3.3.0
No

Debug

Provides methods for viewing data about both CommandHelper and the other plugins in your server. Though not meant to be called by normal scripts, these methods are available everywhere other methods are available. Note that for some of these functions to even work, play-dirty mode must set to on. These are most useful in conjuction with interpreter mode.

Function Name Returns Arguments Throws Description Since Restricted
debug void message IOException Manually logs a timestamped message to the debug log and the console, if debug-mode is set to true in the preferences 3.3.0
Yes

Echoes

These functions allow you to echo information to the screen

Function Name Returns Arguments Throws Description Since Restricted
broadcast void message CastException Broadcasts a message to all players on the server 3.0.1
Yes
chat void string PlayerOfflineException Echoes string to the chat, as if the user simply typed something into the chat bar. 3.0.1
Yes
chatas void player, msg PlayerOfflineException Sends a chat message to the server, as the given player. Otherwise the same as the chat function 3.0.2
Yes
color string name Returns the color modifier given a color name. If the given color name isn't valid, white is used instead. The list of valid color names can be found in the MCChatColor class, and case doesn't matter. For your reference, here is the list of valid colors: BLACK, DARK_BLUE, DARK_GREEN, DARK_AQUA, DARK_RED, DARK_PURPLE, GOLD, GRAY, DARK_GRAY, BLUE, GREEN, AQUA, RED, LIGHT_PURPLE, YELLOW, WHITE, in addition the integers 0-15 will work, or the hex numbers from 0-F. 3.0.1
Yes
console void message, [prefix] CastException Logs a message to the console. If prefix is true, prepends "CommandHelper:" to the message. Default is true. 3.0.2
Yes
die nothing [var1] Kills the command immediately, without completing it. A message is optional, but if provided, displayed to the user. 3.0.1
No
msg void var1, [var2...] PlayerOfflineException Echoes a message to the player running the command 3.0.1
No
strip_colors string toStrip Strips all the color codes from a given string 3.3.0
No
tmsg void player, msg, [...] PlayerOfflineException

InsufficientArgumentsException

Displays a message on the specified players screen, similar to msg, but targets a specific user. 3.0.1
Yes

Economy

Provides functions to hook into the server's economy plugin. To use any of these functions, you must have one of the following economy plugins installed: iConomy 4, 5, & 6+, BOSEconomy 6 & 7, Essentials Economy 2.2.17+, MultiCurrency. No special installation is required beyond simply getting the economy plugin working by itself. Using any of these functions without one of the economy plugins will cause it to throw a InvalidPluginException at runtime.

Function Name Returns Arguments Throws Description Since Restricted
acc_add void account_name, to_add PluginInternalException

InvalidPluginException
CastException

Adds an amount to the specified account 3.2.0
Yes
acc_balance double account_name PluginInternalException

InvalidPluginException

Returns the balance of the given account name. 3.2.0
Yes
acc_divide void account_name, to_divide PluginInternalException

InvalidPluginException
CastException

Divides the account by the given amount 3.2.0
Yes
acc_multiply void account_name, to_multiply PluginInternalException

InvalidPluginException
CastException

Multiplies the account balance by the given amount 3.2.0
Yes
acc_remove void account_name PluginInternalException

InvalidPluginException

Removes the specified account from the game 3.2.0
Yes
acc_set void account_name, value PluginInternalException

InvalidPluginException
CastException

Sets the account's balance to the given amount 3.2.0
Yes
acc_subtract void account_name, to_subtract PluginInternalException

InvalidPluginException
CastException

Subtracts the given amount from the specified account 3.2.0
Yes
bacc_add void bank_name, account_name, value PluginInternalException

InvalidPluginException
CastException

Adds the specified amount to the bank account's balance 3.2.0
Yes
bacc_balance void bank_name, account_name PluginInternalException

InvalidPluginException

Gets the specified bank account's balance 3.2.0
Yes
bacc_divide void bank_name, account_name, value PluginInternalException

InvalidPluginException
CastException

Divides the bank account's balance by the given value 3.2.0
Yes
bacc_multiply void bank_name, account_name, value PluginInternalException

InvalidPluginException
CastException

Multiplies the given bank account's balance by the given value 3.2.0
Yes
bacc_remove void bank_name, account_name PluginInternalException

InvalidPluginException

Removes the given bank account from the game 3.2.0
Yes
bacc_set void bank_name, account_name, value PluginInternalException

InvalidPluginException
CastException

Sets the bank account's balance to the given amount 3.2.0
Yes
bacc_subtract void bank_name, account_name, value PluginInternalException

InvalidPluginException
CastException

Subtracts the specified amount from the bank account's balance 3.2.0
Yes

Enchantments

Provides methods for dealing with enchanted items

Function Name Returns Arguments Throws Description Since Restricted
can_enchant_target boolean name, targetItem EnchantmentException

CastException

Given an enchantment name, and target item id, returns wether or not that item can be enchanted with that enchantment. Throws an EnchantmentException if the name is not a valid enchantment type. 3.3.0
No
enchant_inv void [player], slot, type, level CastException

EnchantmentException
PlayerOfflineException

Adds an enchantment to an item in the player's inventory. Type can be a single string, or an array of enchantment names. If slot is null, the currently selected slot is used. If the enchantment cannot be applied to the specified item, an EnchantmentException is thrown, and if the level specified is not valid, a RangeException is thrown. If type is an array, level must also be an array, with equal number of values in it, with each int corresponding to the appropriate type. You may use either the bukkit names for enchantments, or the name shown on the wiki: [1], and level may be a roman numeral as well. 3.3.0
Yes
enchant_rm_inv void [player], slot, type CastException

EnchantmentException
PlayerOfflineException

Removes an enchantment from an item. type may be a valid enchantment, or an array of enchantment names. It can also be null, and all enchantments will be removed. If an enchantment is specified, and the item is not enchanted with that, it is simply ignored. 3.3.0
Yes
get_enchant_inv array [player], slot PlayerOfflineException

CastException

Returns an array of arrays of the enchantments and their levels on the given item. For example: array(array(DAMAGE_ALL, DAMAGE_UNDEAD), array(1, 2)) 3.3.0
Yes
get_enchant_max int name EnchantmentException Given an enchantment name, returns the max level it can be. If name is not a valid enchantment, an EnchantException is thrown. 3.3.0
No
get_enchants array item CastException Given an item id, returns the enchantments that can be validly added to this item. This may return an empty array. 3.3.0
No
is_enchantment boolean name Returns true if this name is a valid enchantment type. Note that either the bukkit names or the wiki names are valid. 3.3.0
No

Environment

Allows you to manipulate the environment around the player

Function Name Returns Arguments Throws Description Since Restricted
break_block void locationObject FormatException Mostly simulates a block break at a location. (Does not trigger an event) 3.3.0
Yes
get_block_at string x, y, z, [world]
xyzArray, [world]
FormatException

CastException
LengthException
InvalidWorldException

Gets the id of the block at x, y, z. This function expects either 1 or 3 arguments. If 1 argument is passed, it should be an array with the x, y, z coordinates. The format of the return will be x:y where x is the id of the block, and y is the meta data for the block. All blocks will return in this format, but blocks that don't have meta data normally will return 0 in y. If world isn't specified, the current player's world is used. 3.0.2
Yes
get_sign_text array xyzLocation RangeException

FormatException

Given a location array, returns an array of 4 strings of the text in the sign at that location. If the location given isn't a sign, then a RangeException is thrown. 3.3.0
Yes
is_sign_at boolean xyzLocation FormatException Returns true if the block at this location is a sign. 3.3.0
Yes
set_block_at void x, y, z, id, [world]
xyzArray, id, [world]
CastException

LengthException
FormatException
InvalidWorldException

Sets the id of the block at the x y z coordinates specified. If the first argument passed is an array, it should be x y z coordinates. id must be a blocktype identifier similar to the type returned from get_block_at, except if the meta value is not specified, 0 is used. If world isn't specified, the current player's world is used. 3.0.2
Yes
set_sign_text void xyzLocation, lineArray
xyzLocation, line1, [line2, [line3, [line4]]]
RangeException

FormatException

Sets the text of the sign at the given location. If the block at x,y,z isn't a sign, a RangeException is thrown. If the text on a line overflows 15 characters, it is simply truncated. 3.3.0
Yes

EventBinding

This class of functions provide methods to hook deep into the server's event architecture

Function Name Returns Arguments Throws Description Since Restricted
bind string event_name, options, prefilter, event_obj, [custom_params], <code> BindException Binds some functionality to an event, so that when said event occurs, the event handler will fire. Returns the id of this event, so it can be unregistered later, if need be. 3.3.0
Yes
cancel void [state] BindException Cancels the event (if applicable). If the event is not cancellable, or is already cancelled, nothing happens. If called from outside an event handler, a BindException is thrown. By default, state is true, but you can uncancel an event (if possible) by calling cancel(false) 3.3.0
Yes
consume void BindException Consumes an event, so that lower priority handlers don't even recieve the event. Monitor level handlers will still recieve it, however, and they can check to see if the event was consumed. 3.3.0
Yes
dump_events array Returns an array of all the events currently registered on the server. Mostly meant for debugging, however it would be possible to parse this response to cherry pick events to unregister. 3.3.0
Yes
event_meta array BindException Returns meta information about the activity in regards to this event. This is meant as a debug tool. 3.3.0
Yes
is_cancelled boolean BindException Returns whether or not the underlying event is cancelled or not. If the event is not cancellable in the first place, false is returned. If called from outside an event, a BindException is thrown 3.3.0
Yes
is_consumed boolean BindException Returns whether or not this event has been consumed. Usually only useful for Monitor level handlers, it could also be used for highly robust code, as an equal priority handler could have consumed the event, but this handler would still recieve it. 3.3.0
Yes
is_locked boolean parameter BindException Returns whether or not a call to modify_event() would fail, based on the parameter being locked by a higher priority handler. If this returns false, it is still not a guarantee that the event would be successfully modified, just that it isn't locked. 3.3.0
Yes
lock void <none>
parameterArray
parameter, [parameter...]
BindException Locks the specified event parameter(s), or all of them, if specified with no arguments. Locked parameters become read only for lower priority event handlers. 3.3.0
Yes
modify_event boolean parameter, value, [throwOnFailure] CastException

BindException

Modifies the underlying event object, if applicable. The documentation for each event will explain what parameters can be modified, and what their expected values are. If an invalid parameter name is passed in, nothing will happen. If this function is called from outside an event handler, a BindException is thrown. Note that modifying the underlying event will NOT update the event object passed in to the event handler. The function returns whether or not the parameter was updated successfully. It could fail to modify the event if a higher priority handler has locked this parameter, or if updating the underlying event failed. If throwOnFailure is true, instead of returning false, it will throw a BindException. The default for throwOnFailure is false. If a monitor level handler even attempts to modify an event, an exception will be thrown. 3.3.0
Yes
trigger void eventName, eventObject, [serverWide] CastException Manually triggers bound events. The event object passed to this function is sent directly as-is to the bound events. Check the documentation for each event to see what is required. No checks will be done on the data here, but it is not recommended to fail to send all parameters required. If serverWide is true, the event is triggered directly in the server, unless it is a CommandHelper specific event, in which case, serverWide is irrelevant. Defaults to false, which means that only CommandHelper code will receive the event. 3.3.0
Yes
unbind void [eventID] BindException Unbinds an event, which causes it to not run anymore. If called from within an event handler, eventID is optional, and defaults to the current event id. 3.3.0
Yes

Exceptions

This class contains functions related to Exception handling in MScript

Function Name Returns Arguments Throws Description Since Restricted
throw nothing exceptionType, msg FormatException This function causes an exception to be thrown. If the exception type is null, it will be uncatchable. Otherwise, exceptionType may be any valid exception type. 3.1.2
No
try void tryCode, varName, catchCode, [exceptionTypes] CastException

FormatException

This function works similar to a try-catch block in most languages. If the code in tryCode throws an exception, instead of killing the whole script, it stops running, and begins running the catchCode. var should be an ivariable, and it is set to an array containing the following information about the exception: 0 - The class of the exception; 1 - The message generated by the exception; 2 - The file the exception was generated from; 3 - The line the exception occured on. If exceptionTypes is provided, it should be an array of exception types, or a single string that this try function is interested in. If the exception type matches one of the values listed, the exception will be caught, otherwise, the exception will continue up the stack. If exceptionTypes is missing, it will catch all exceptions. PLEASE NOTE! This function will not catch exceptions thrown by CommandHelper, only built in exceptions. Please see the wiki for more information about what possible exceptions can be thrown and where. 3.1.2
No

InventoryManagement

Provides methods for managing inventory related tasks.

Function Name Returns Arguments Throws Description Since Restricted
pgive_item int [player], itemID, qty CastException

FormatException
PlayerOfflineException

Gives a player the specified item * qty. Unlike set_pinv(), this does not specify a slot. The qty is distributed in the player's inventory, first filling up slots that have the same item type, up to the max stack size, then fills up empty slots, until either the entire inventory is filled, or the entire amount has been given. The number of items actually given is returned, which will be less than or equal to the quantity provided. This function will not touch the player's armor slots however. 3.3.0
Yes
phas_item int [player], itemId PlayerOfflineException

FormatException
CastException

Returns the quantity of the specified item that the player is carrying (including armor slots). This counts across all slots in inventory. Recall that 0 is false, and anything else is true, so this can be used to get the total, or just see if they have the item. itemId can be either a plain number, or a 0:0 number, indicating a data value. 3.3.0
Yes
pinv mixed [player, [index]] PlayerOfflineException

CastException
RangeException

Gets the inventory information for the specified player, or the current player if none specified. If the index is specified, only the slot given will be returned. The index of the array in the array is 0 - 35, 100 - 103, which corresponds to the slot in the players inventory. To access armor slots, you may also specify the index. (100 - 103). The quick bar is 0 - 8. If index is null, the item in the player's hand is returned, regardless of what slot is selected. If there is no item at the slot specified, null is returned. If all slots are requested, an associative array of item objects is returned, and if only one item is requested, just that single item object is returned. An item object consists of the following associative array(type: The id of the item, data: The data value of the item, or the damage if a damagable item, qty: The number of items in their inventory, enchants: An array of enchant objects, with 0 or more associative arrays which look like: array(etype: The type of enchantment, elevel: The strength of the enchantment)) 3.1.3
Yes
pitem_slot array [player], itemID CastException

FormatException
PlayerOfflineException

Given an item id, returns the slot numbers that the matching item has at least one item in. 3.3.0
Yes
ptake_item int [player], itemID, qty CastException

PlayerOfflineException
FormatException

Works in reverse of pgive_item(), but returns the number of items actually taken, which will be from 0 to qty. 3.3.0
Yes
set_pinv void [player], pinvArray PlayerOfflineException

CastException
FormatException

Sets a player's inventory to the specified inventory object. An inventory object is one that matches what is returned by pinv(), so set_pinv(pinv()), while pointless, would be a correct call. The array must be associative, however, it may skip items, in which case, only the specified values will be changed. If a key is out of range, or otherwise improper, a warning is emitted, and it is skipped, but the function will not fail as a whole. A simple way to set one item in a player's inventory would be: set_pinv(array(2: array(type: 1, qty: 64))) This sets the player's second slot to be a stack of stone. set_pinv(array(103: array(type: 298))) gives them a hat. To set the item in hand, use something like set_pinv(array(null: array(type: 298))), where the key is null. If you set a null key in addition to an entire inventory set, only one item will be used (which one is undefined). Note that this uses the unsafe enchantment mechanism to add enchantments, so any enchantment value will work. If type uses the old format (for instance, "35:11"), then the second number is taken to be the data, making this backwards compatible (and sometimes more convenient). 3.2.0
Yes

Math

Provides mathematical functions to scripts

Function Name Returns Arguments Throws Description Since Restricted
abs double arg CastException Returns the absolute value of the argument. 3.1.2
No
acos double number CastException Returns the arc cos of the number 3.3.0
No
add mixed var1, [var2...] CastException Adds all the arguments together, and returns either a double or an integer 3.0.1
No
asin double number CastException Returns the arc sin of the number 3.3.0
No
atan double number CastException Returns the arc tan of the number 3.3.0
No
atan2 double number CastException Returns the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta). This method computes the phase theta by computing an arc tangent of y/x in the range of -pi to pi. 3.3.0
No
ceil int number CastException Returns the ceiling of any given number. For example, ceil(3.2) returns 4, and ceil(-1.1) returns -1 3.1.3
No
cos double number CastException Returns the cos of the number 3.3.0
No
dec ivar var, [value] CastException Subtracts value from var, and stores the new value. Value defaults to 1. Equivalent to --var (or var -= value) in other languages. Expects ivar to be a variable, then returns the ivar. 3.0.1
No
divide mixed var1, [var2...] CastException Divides the arguments from left to right, and returns either a double or an integer 3.0.1
No
expr double expression, [valueArray] CastException

PluginInternalException

Sometimes, when you need to calculate an advanced mathematical expression, it is messy to write out everything in terms of functions. This function will allow you to evaluate a mathematical expression as a string, using common mathematical notation. For example, (2 + 3) * 4 would return 20. Variables can also be included, and their values given as an associative array. expr('(x + y) * z', array(x: 2, y: 3, z: 4)) would be the same thing as the above example. 3.3.0
No
floor int number CastException Returns the floor of any given number. For example, floor(3.8) returns 3, and floor(-1.1) returns 2 3.1.3
No
inc ivar var CastException Adds 1 to var, and stores the new value. Equivalent to ++var in other languages. Expects ivar to be a variable, then returns the ivar. 3.0.1
No
max number num1, [num2...] CastException

InsufficientArgumentsException

Returns the highest number in a given list of numbers. If any of the arguments are arrays, they are expanded into individual numbers, and also compared. 3.2.0
No
min number num1, [num2...] CastException

InsufficientArgumentsException

Returns the lowest number in a given list of numbers. If any of the arguments are arrays, they are expanded into individual numbers, and also compared. 3.2.0
No
mod int x, n CastException Returns x modulo n 3.0.1
No
multiply mixed var1, [var2...] CastException Multiplies the arguments together, and returns either a double or an integer 3.0.1
No
pow double x, n CastException Returns x to the power of n 3.0.1
No
rand int min/max, [max] RangeException

CastException

Returns a random number from 0 to max, or min to max, depending on usage. Max is exclusive. Min must be less than max, and both numbers must be >= 0 3.0.1
No
round int number CastException Unlike floor and ceil, rounds the number to the nearest integer. 3.3.0
No
sin double number CastException Returns the sin of the number 3.3.0
No
sqrt number number RangeException

CastException

Returns the square root of a number. Note that this is mathematically equivalent to pow(number, .5). Imaginary numbers are not supported at this time, so number must be positive. 3.2.0
No
subtract mixed var1, [var2...] CastException Subtracts the arguments from left to right, and returns either a double or an integer 3.0.1
No
tan double number CastException Returns the tan of the number 3.3.0
No
to_degrees double number CastException Converts the number to degrees (which is assumed to have been in radians) 3.3.0
No
to_radians double number CastException Converts the number to radians (which is assumed to have been in degrees) 3.3.0
No

Meta

These functions provide a way to run other commands

Function Name Returns Arguments Throws Description Since Restricted
call_alias void cmd Allows a CommandHelper alias to be called from within another alias. Typically this is not possible, as a script that runs "/jail = /jail" for instance, would simply be calling whatever plugin that actually provides the jail functionality's /jail command. However, using this function makes the command loop back to CommandHelper only. 3.2.0
No
eval string script_string Executes arbitrary MScript. Note that this function is very experimental, and is subject to changing or removal. 3.1.0
Yes
g string func1, [func2...] Groups any number of functions together, and returns void. 3.0.1
No
get_cmd mixed Gets the command (as a string) that ended up triggering this script, exactly how it was entered by the player. This could be null, if for instance it is called from within an event. 3.3.0
No
has_permission boolean [player], permissionName Using the built in permissions system, checks to see if the player has a particular permission. This is simply passed through to the permissions system. This function does not throw a PlayerOfflineException, because it works with offline players, but that means that names must be an exact match. If you notice, this function isn't restricted. However, it IS restricted if the player attempts to check another player's permissions. If run from the console, will always return true. 3.3.0
No
p mixed c Used internally by the compiler. 3.1.2
No
run void var1 FormatException Runs a command as the current player. Useful for running commands in a loop. Note that this accepts commands like from the chat; with a forward slash in front. 3.0.1
No
runas void player, command FormatException

PlayerOfflineException

Runs a command as a particular user. The special user '~op' is a user that runs as op. Be careful with this very powerful function. Commands cannot be run as an offline player. Returns void. If the first argument is an array of usernames, the command will be run in the context of each user in the array. 3.0.1
Yes
scriptas void player, [label], script PlayerOfflineException Runs the specified script in the context of a given player. A script that runs player() for instance, would return the specified player's name, not the player running the command. Setting the label allows you to dynamically set the label this script is run under as well (in regards to permission checking) 3.3.0
Yes

Minecraft

These functions provide a hook into game functionality.

Function Name Returns Arguments Throws Description Since Restricted
data_name string int
itemArray
CastException

FormatException

Performs the reverse functionality as data_values. Given 1, returns 'Stone'. Note that the enum value given in bukkit's Material class is what is returned as a fallback, if the id doesn't match a value in the internally maintained list. If a completely invalid argument is passed in, null is returned. 3.3.0
No
data_values int var1 Does a lookup to return the data value of a name. For instance, returns 1 for 'stone'. If an integer is given, simply returns that number. If the data value cannot be found, null is returned. 3.0.1
No
get_entity_health int entityID CastException

FormatException

Returns the entity's health, as a percentage. If the specified entity doesn't exist, or is not a LivingEntity, a format exception is thrown. 3.3.0
Yes
get_mob_owner string entityID UntameableMobException

CastException

Returns the owner's name, or null if the mob is unowned. An UntameableMobException is thrown if mob isn't tameable to begin with. 3.3.0
Yes
get_worlds array Returns the names of the worlds available in this server 3.1.0
No
is_tameable boolean entityID CastException Returns true or false if the specified entity is tameable 3.3.0
Yes
make_effect void xyzArray, effect, [radius] CastException

FormatException

Plays the specified effect (sound effect) at the given location, for all players within the radius (or 64 by default). The effect can be one of the following: BOW_FIRE, CLICK1, CLICK2, DOOR_TOGGLE, EXTINGUISH. 3.1.3
Yes
max_stack_size integer itemType
itemArray
CastException

FormatException

Given an item type, returns the maximum allowed stack size. This method will accept either a single data value (i.e. 278) or an item array like is returned from pinv(). Additionally, if a single value, it can also be in the old item notation (i.e. '35:11'), though for the purposes of this function, the data is unneccesary. 3.3.0
No
set_entity_health void entityID, healthPercent CastException Sets the specified entity's health (0 kills it), or ignores this call if the entityID doesn't exist or isn'ta LivingEntity. 3.3.0
Yes
spawn_mob array mobType, [qty], [location] CastException

RangeException
FormatException

(Currently only works with Bukkit) Spawns qty mob of one of the following types at location. qty defaults to 1, and location defaults to the location of the player. mobType can be one of: BLAZE, CAVESPIDER, CHICKEN, COW, CREEPER, ENDERDRAGON, ENDERMAN, GHAST, MAGMACUBE, MOOSHROOM, PIG, PIGZOMBIE, SHEEP, SILVERFISH, SKELETON, SLIME, SPIDER, SPIDERJOCKEY, SQUID, VILLAGER, WOLF, ZOMBIE. Spelling matters, but capitalization doesn't. At this time, the function is limited to spawning a maximum of 50 at a time. Further, SHEEP can be spawned as any color, by specifying SHEEP:COLOR, where COLOR is any of the dye colors: BLACK RED GREEN BROWN BLUE PURPLE CYAN SILVER GRAY PINK LIME YELLOW LIGHT_BLUE MAGENTA ORANGE WHITE. COLOR defaults to white if not specified. An array of the entity IDs spawned is returned. <p>GIANTs can also be spawned, if you are running craftbukkit. This is an experimental feature. Only one GIANT can be spawned at a time

3.1.2
Yes
tame_mob void [player], entityID UntameableMobException

CastException

Tames the entity specified to the player. Currently only wolves are supported. Offline players are supported, but this means that partial matches are NOT supported. You must type the players name exactly. Setting the player to null will untame the mob. If the entity doesn't exist, nothing happens. 3.3.0
Yes

Performance

This class provides functions for hooking into CommandHelper's powerful Performance measuring. To use the functions, you must have allow-profiling option set to true in your preferences file.

Function Name Returns Arguments Throws Description Since Restricted
enable_performance_logging void boolean SecurityException Enables performance logging. The allow-profiling option must be set to true in your preferences file, and play-dirty mode must be active. If allow-profiling is set to false, a SecurityException is thrown. The debug filters are used by the performance logger, if you choose to filter through the events. See the documenation for more details on performance logging. 3.3.0
Yes

Persistance

Allows scripts to store data from execution to execution. See the guide on persistance for more information. In all the functions, you may send multiple arguments for the key, which will automatically be concatenated with a period (the namespace separator). No magic happens here, you can put periods yourself, or combine manually namespaced values or automatically namespaced values with no side effects.

Function Name Returns Arguments Throws Description Since Restricted
clear_value void key[, namespace, ...] Completely removes a value from storage. Calling has_value(key) after this call will return false. 3.3.0
Yes
get_value Mixed key[, namespace, ...] Returns a stored value stored with store_value. If the key doesn't exist in storage, null is returned. On a more detailed note: If the value stored in the persistance database is not actually a construct, then null is also returned. 3.0.2
Yes
get_values array name[, space, ...] Returns all the values in a particular namespace as an associative array(key: value, key: value). Only full namespace matches are considered, so if the key 'users.data.username.hi' existed in the database, and you tried get_values('users.data.user'), nothing would be returned. The last segment in a key is also considered a namespace, so 'users.data.username.hi' would return a single value (in this case). 3.3.0
Yes
has_value boolean key[, namespace, ...] Returns whether or not there is data stored at the specified key in the Persistance database. 3.1.2
Yes
store_value void key[, namespace, ...], value FormatException Allows you to store a value, which can then be retrieved later. key must be a string containing only letters, numbers, underscores. Periods may also be used, but they form a namespace, and have special meaning. (See get_values()) 3.0.2
Yes

PlayerManagement

This class of functions allow players to be managed

Function Name Returns Arguments Throws Description Since Restricted
all_players array Returns an array of all the player names of all the online players on the server 3.0.1
Yes
get_compass_target array [player] PlayerOfflineException Gets the compass target of the specified player 3.3.0
Yes
give_pexp void [player], exp PlayerOfflineException

CastException

Gives the player the specified amount of xp. 3.3.0
Yes
kick void [playerName], [message] PlayerOfflineException Kicks the specified player, with an optional message. If no message is specified, "You have been kicked" is used. If no player is specified, the current player is used, with the default message. 3.1.0
Yes
kill void [playerName] PlayerOfflineException Kills the specified player, or the current player if it is omitted 3.0.1
Yes
pbanned boolean player Returns whether or not this player is banned. Note that this will work with offline players, but the name must be exact. At this time, this function only works with the vanilla ban system. If you use a third party ban system, you should instead run the command for that plugin instead. 3.3.0
Yes
pcursor array [player] PlayerOfflineException

RangeException

Returns an array with the (x, y, z, world) coordinates of the block the player has highlighted in their crosshairs. If player is omitted, the current player is used. If the block is too far, a RangeException is thrown. 3.0.2
Yes
pexp int [player] CastException

PlayerOfflineException

Gets the experience of a player within this level, as a percentage, from 0 to 99. (100 would be next level, therefore, 0.) 3.1.3
Yes
pfacing mixed F
yaw, pitch
player, F
player, yaw, pitch
player
<none>
PlayerOfflineException

RangeException
CastException

Sets the direction the player is facing. When using the first variation, expects an integer 0-3, which will set the direction the player faces using their existing pitch (up and down) but sets their yaw (left and right) to one of the cardinal directions, as follows: 0 - West, 1 - South, 2 - East, 3 - North, which corresponds to the directions given by F when viewed with F3. In the second variation, specific yaw and pitches can be provided. If the player is not specified, the current player is used. If just the player is specified, that player's yaw and pitch are returned as an array, or if no arguments are given, the player running the command's yaw and pitch are returned as an array. The function returns void when setting the values. (Note that while this function looks like it has ambiguous arguments, players cannot be named numbers.) A note on numbers: The values returned by the getter will always be as such: pitch will always be a number between 90 and -90, with -90 being the player looking up, and 90 being the player looking down. Yaw will always be a number between 0 and 359.9~. When using it as a setter, pitch must be a number between -90 and 90, and yaw may be any number. If the number given is not between 0 and 359.9~, it will be normalized first. 0 is dead west, 90 is north, etc. 3.1.3
Yes
pfood int [player] PlayerOfflineException Returns the player's current food level. 3.1.3
Yes
pgroup array [playerName] PlayerOfflineException Returns an array of the groups a player is in. If playerName is omitted, the current player is used. 3.0.1
Yes
pinfo mixed [pName], [value] PlayerOfflineException

RangeException
CastException

Returns various information about the player specified, or the current player if no argument was given.If value is set, it should be an integer of one of the following indexes, and only that information for that index will be returned. Otherwise if value is not specified (or is -1), it returns an array of information with the following pieces of information in the specified index:
  • 0 - player's name; This will return the player's exact name, even if called with a partial match.
  • 1 - player's location; an array of the player's xyz coordinates
  • 2 - player's cursor; an array of the location of the player's cursor, or null if the block is out of sight.
  • 3 - player's IP; Returns the IP address of this player.
  • 4 - Display name; The name that is used when the player's name is displayed on screen typically.
  • 5 - player's health; Gets the current health of the player, which will be an int from 0-20.
  • 6 - Item in hand; The value returned by this will be similar to the value returned by get_block_at()
  • 7 - World name; Gets the name of the world this player is in.
  • 8 - Is Op; true or false if this player is an op.
  • 9 - player groups; An array of the permissions groups the player is in.
  • 10 - The player's hostname (or IP if a hostname can't be found)
  • 11 - Is sneaking?
3.1.0
Yes
pisop boolean [player] PlayerOfflineException Returns whether or not the specified player (or the current player if not specified) is op 3.3.0
Yes
player string [playerName] PlayerOfflineException Returns the full name of the partial Player name specified or the Player running the command otherwise. If the command is being run from the console, then the string '~console' is returned. If the command is coming from elsewhere, null is returned, and the behavior is undefined. Note that most functions won't support the user '~console' (they'll throw a PlayerOfflineException), but you can use this to determine where a command is being run from. 3.0.1
No
plevel int [player] CastException

PlayerOfflineException

Gets the player's level. 3.1.3
Yes
ploc array [playerName] PlayerOfflineException Returns an array of x, y, z coords of the player specified, or the player running the command otherwise. Note that the y coordinate is in relation to the block the player is standing on. The array returned will also include the player's world in index 3 of the array. 3.0.1
Yes
pmode string [player] PlayerOfflineException Returns the player's game mode. It will be one of "CREATIVE" or "SURVIVAL". 3.1.3
Yes
ponfire int [player] PlayerOfflineException Returns the number of ticks remaining that this player will be on fire for. If the player is not on fire, 0 is returned, which incidentally is false. 3.3.0
Yes
ponline boolean player Returns whether or not the specified player is online. Note that the name must match exactly, but it will not throw a PlayerOfflineException if the player is not online, or if the player doesn't even exist. 3.3.0
Yes
ptexp int [player] CastException

PlayerOfflineException

Gets the total experience of a player. 3.1.3
Yes
pwhitelisted boolean player Returns whether or not this player is whitelisted. Note that this will work with offline players, but the name must be exact. 3.3.0
Yes
pworld string [playerName] PlayerOfflineException Gets the world of the player specified, or the current player, if playerName isn't specified. 3.1.0
Yes
reset_display_name void [playerName] PlayerOfflineException Resets a player's display name to their real name. If playerName isn't specified, defaults to the player running the command. 3.1.2
Yes
set_compass_target array [player], locationArray PlayerOfflineException

FormatException

Sets the player's compass target, and returns the old location. 3.3.0
Yes
set_display_name void playerName, newDisplayName
newDisplayName
PlayerOfflineException Sets a player's display name. If the second usage is used, it sets the display name of the player running the command. See reset_display_name also. playerName, as well as all CommandHelper commands expect the player's real name, not their display name. 3.1.2
Yes
set_pbanned void player, isBanned Sets the ban flag of the specified player. Note that this will work with offline players, but the name must be exact. At this time, this function only works with the vanilla ban system. If you use a third party ban system, you should instead run the command for that plugin instead. 3.3.0
Yes
set_peffect boolean player, potionID, strength, [seconds] PlayerOfflineException

CastException
RangeException

Not all potions work of course, but effect is 1-19. Seconds defaults to 30. If the potionID is out of range, a RangeException is thrown, because out of range potion effects cause the client to crash, fairly hardcore. See http://www.minecraftwiki.net/wiki/Potion_effects for a complete list of potions that can be added. To remove an effect, set the strength (or duration) to 0. It returns true if the effect was added or removed as desired. It returns false if the effect was not added or removed as desired (however, this currently only will happen if an effect is attempted to be removed, yet isn't already on the player). 3.3.0
Yes
set_pexp void [player], xp CastException

PlayerOfflineException

Sets the experience of a player within the current level, as a percentage, from 0 to 100. 3.1.3
Yes
set_pfood void [player], level PlayerOfflineException

CastException

Sets the player's food level. This is an integer from 0-? 3.1.3
Yes
set_phealth void [player], health CastException

RangeException
PlayerOfflineException

Sets the player's health. health should be an integer from 0-20. 3.2.0
Yes
set_plevel void [player], level CastException

PlayerOfflineException

Sets the level of a player. 3.1.3
Yes
set_ploc boolean [player], locationArray
[player], x, y, z
CastException

LengthException
PlayerOfflineException
FormatException

Sets the location of the player to the specified coordinates. If the coordinates are not valid, or the player was otherwise prevented from moving, false is returned, otherwise true. If player is omitted, the current player is used. Note that 1 is automatically added to the y component, which means that sending a player to x, y, z coordinates shown with F3 will work as expected, instead of getting them stuck inside the floor. 3.1.0
Yes
set_pmode void [player], mode PlayerOfflineException

FormatException

Sets the player's game mode. mode must be either "CREATIVE" or "SURVIVAL" (case doesn't matter) 3.1.3
Yes
set_ponfire void [player], ticks PlayerOfflineException

CastException

Sets the player on fire for the specified number of ticks. If a boolean is given for ticks, false is 0, and true is 20. 3.3.0
Yes
set_ptexp void [player], xp CastException

PlayerOfflineException

Sets the total experience of a player. 3.1.3
Yes
set_pwhitelisted void player, isWhitelisted Sets the whitelist flag of the specified player. Note that this will work with offline players, but the name must be exact. 3.3.0
Yes

Regex

This class provides regular expression functions. For more details, please see the page on regular expressions

Function Name Returns Arguments Throws Description Since Restricted
reg_count int pattern, subject FormatException Counts the number of occurances in the subject. 3.2.0
No
reg_match array pattern, subject FormatException Searches for the given pattern, and returns an array with the results. Captures are supported. If the pattern is not found anywhere in the subject, an empty array is returned. The indexes of the array follow typical regex fashion; the 0th element is the whole match, and 1-n are the captures specified in the regex. 3.2.0
No
reg_match_all array pattern, subject FormatException Searches subject for all matches to the regular expression given in pattern, unlike reg_match, which just returns the first match. 3.2.0
No
reg_replace string pattern, replacement, subject FormatException Replaces any occurances of pattern with the replacement in subject. Back references are allowed. 3.2.0
No
reg_split array pattern, subject FormatException Splits a string on the given regex, and returns an array of the parts. If nothing matched, an array with one element, namely the original subject, is returned. 3.2.0
No

Scheduling

This class contains methods for dealing with time and server scheduling.

Function Name Returns Arguments Throws Description Since Restricted
nano_time int Returns an arbitrary number based on the most accurate clock available on this system. Only useful when compared to other calls to nano_time(). The return is in nano seconds. See the Java API on System.nanoTime() for more information on the usage of this function. 3.1.0
No
time int Returns the current unix time stamp, in milliseconds. The resolution of this is not guaranteed to be extremely accurate. If you need extreme accuracy, use nano_time() 3.1.0
No

StringHandling

These class provides functions that allow strings to be manipulated

Function Name Returns Arguments Throws Description Since Restricted
concat string var1, [var2...] Concatenates any number of arguments together, and returns a string 3.0.1
No
length int str
array
Returns the character length of str, if the value is castable to a string, or the length of the array, if an array is given 3.1.2
No
parse_args array string Parses string into an array, where string is a space seperated list of arguments. Handy for turning $ into a usable array of items with which to script against. Extra spaces are ignored, so you would never get an empty string as an input. 3.0.1
No
read string file IOException

SecurityException

Reads in a file from the file system at location var1 and returns it as a string. The path is relative to the server, not CommandHelper. If the file is not found, or otherwise can't be read in, an IOException is thrown. If the file specified is not within base-dir (as specified in the preferences file), a SecurityException is thrown. The line endings for the string returned will always be \n, even if they originally were \r\n. 3.0.1
Yes
replace string main, what, that Replaces all instances of 'what' with 'that' in 'main' 3.0.1
No
sconcat string var1, [var2...] Concatenates any number of arguments together, but puts a space between elements 3.0.1
No
substr string str, begin, [end] RangeException

CastException

Returns a substring of the given string str, starting from index begin, to index end, or the end of the string, if no index is given. If either begin or end are out of bounds of the string, an exception is thrown. substr('hamburger', 4, 8) returns "urge", substr('smiles', 1, 5) returns "mile", and substr('lightning', 5) returns "ning". See also length(). 3.1.2
No
to_lower string str Returns an all lower case version of str 3.1.2
No
to_upper string str Returns an all caps version of str 3.1.2
No
trim string s Returns the string s with leading and trailing whitespace cut off 3.0.1
No

Weather

Provides functions to control the weather

Function Name Returns Arguments Throws Description Since Restricted
lightning void strikeLocArray, [safe]
x, y, z, [safe]
CastException

LengthException
InvalidWorldException
FormatException

Makes lightning strike at the x y z coordinates specified in the array(x, y, z). safe defaults to false, but if true, lightning striking a player will not hurt them. 3.0.1
Yes
storm void isStorming, [world] CastException

InvalidWorldException

Creates a storm if isStorming is true, stops a storm if isStorming is false 3.0.1
Yes

World

Provides functions for manipulating a world

Function Name Returns Arguments Throws Description Since Restricted
get_spawn array [world] InvalidWorldException

FormatException

Returns a location array for the specified world, or the current player's world, if not specified. 3.3.0
Yes
get_world_time int [world] InvalidWorldException Returns the time of the specified world, as an integer from 0 to 24000-1 3.3.0
Yes
refresh_chunk void [world], x, z
[world], locationArray
CastException

FormatException
InvalidWorldException

Resends the chunk to all clients, using the specified world, or the current players world if not provided. 3.3.0
Yes
set_world_time void [world], time InvalidWorldException

FormatException

Sets the time of a given world. Should be a number from 0 to 24000, if not, it is modulo scaled. Alternatively, common time notation (9:30pm, 4:00 am) is acceptable, and convenient english mappings also exist:
  • afternoon = 8000
3.3.0
Yes

WorldEdit

Provides various methods for programmatically hooking into WorldEdit

Function Name Returns Arguments Throws Description Since Restricted
sk_all_regions array [world] Returns all the regions in all worlds, or just the one world, if specified. 3.2.0
Yes
sk_current_regions mixed [player] PlayerOfflineException

PluginInternalException

Returns the list regions that player is in. If no player specified, then the current player is used. If region is found, an array of region names are returned, else null is returned 3.2.0
Yes
sk_pos1 mixed [player], locationArray
[player]
PlayerOfflineException

CastException

Sets the player's point 1, or returns it if the array to set isn't specified. If the location is returned, it is returned as a 4 index array:(x, y, z, world) 3.2.0
Yes
sk_pos2 mixed [player], array
[player]
PlayerOfflineException

CastException

Sets the player's point 2, or returns it if the array to set isn't specified 3.2.0
Yes
sk_region_info array region, world PluginInternalException Given a region name, returns an array of information about that region, as follows:
  • 0 - An array of points that define this region
  • 1 - An array of owners of this region
  • 2 - An array of members of this region
  • 3 - An array of arrays of this region's flags, where each array is: array(flag_name, value)
  • 4 - This region's priority
  • 5 - The volume of this region (in meters cubed)
If the region cannot be found, a PluginInternalException is thrown.
3.2.0
Yes
sk_region_overlaps boolean world, region1, array(region2, [regionN...]) PluginInternalException Returns true or false whether or not the specified regions overlap. 3.2.0
Yes
sk_region_volume int region, world PluginInternalException Returns the volume of the given region in the given world. 3.2.0
Yes

Errors in documentation

Please note that this documentation is generated automatically, if you notice an error in the documentation, please file a bug report for the plugin itself! For information on undocumented functions, see this page


Namespaces

Variants
Actions