CommandHelperAPI

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.

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