Expressions

Summary

UtilityBelt includes functionality to override the built-in expression language runner inside of VTank. This enables new meta expression functions and language features to be added while still running metas inside of VTank.

To enable this functionality, you need to set UtilityBelt optionVTank.PatchExpressionEngine to true, you can do that with /ub opt set VTank.PatchExpressionEngine true.

Once enabled, UtilityBelt will handle all meta conditions of type Chat Message Capture and Expression, meta actions of type Expression Action and Chat Expression, as well as meta view button expressions.

UtilityBelt is completely backwards compatible with VTank meta expressions, so any existing expressions should just work. Keeping that in mind, you can view documentation for VTank’s meta expressions here.

Language Overview

The expression language offers functionality to control and read game client state, as well as some basic logic operations. There is support for a number of data types, as well as operators and functions to use on those types.

Data Types

Number - Numbers are stored internally as doubles. They have a precision of 15-16 digits and can store a range from +-5.0 x 10^-324 to +-1.7 x 10³⁰⁸
- Numbers can also be defined in hexadecimal format, ie 0xff
String - A string of characters, can be any length.
- Strings containing anything other than letters and spaces need to be escaped with backslashes escaping individual characters, or backticks surrounding the entire string. Examples:
  - 123 test should be escaped as \1\2\3 test or `123 test`
  - some example string does not need escaping
  - p@cMan$) should be escaped as p\@cMan\$\) or `p@cMan$`
List - A set of items. Items can be of any type.
Coordinates - Represents a set of NS/EW/Z game coordinates.
WorldObject - Represents a game object (player, item, monster, npc, etc)
StopWatch - Time based counter, with the ability to stop/start.

Operators

== Checks if two objects are equal to each other. They must be of the same type.
> Checks if a value is greater than another. This only works with numbers.
< Checks if a value is less than another. This only works with numbers.
>= Checks if a value is greater than or equal to another. This only works with numbers.
<= Checks if a value is less than or equal to another. This only works with numbers.
/ Divides one value by another. This only works with numbers.
* Multiplies one value by another. This only works with numbers.
+ Adds one value to another. This only works with numbers and strings.
- Subtracts one value from another. This only works with numbers.
% Determines the remainder of the division of one value from another. This only works with numbers.
# Evaluates to true if the first value matches the passed regular expression. Example: test#s checks if the string test matches the regex s. Regexes used here are case-insensitive when matching. This only works with strings.
&& Evaluates to true if both the expression before and after the operator return true
|| Evaluates to true if either the expression before or after the operator returns true

Expressions (Functions)

Expression functions, also referred to as just expressions, are used to perform actions or operate on data passed to them. They are all called using the same syntax: expressionname[]. The square brackets are used to enclose arguments, even when there are no arguments they are required.

Some expressions will require arguments to be passed to them, like echo[hello, 15]. Passed arguments are separated with the , character. The echo expression expects two arguments to be passed: a string, and a number indicating the color the string will be printed in. In the example above, hello is the passed string, and 15 is the passed number. This expression echoes the passed string to the chat window in the specified color.

Other expressions may not require arguments and instead of performing an action, return data. For example, the expression wobjectgetplayer[] will refer to your currect player character. The wobjectgetplayer expression doesn’t expect any arguments to be passed to it. To indicate this, the brackets should still be present but should have nothing within them.

You can pass the return value of an expression to another expression and chain them together. For example, to get the name of the current player we need to pass the result of one expression to another: wobjectgetname[wobjectgetplayer[]]. In this example, the wobjectgetname expression expects to be passed a single argument of type WorldObject. Since the wobjectgetplayer expression returns a WorldObject we can pass the result of it to wobjectgetname.

Variables

Variables are used to store values, and retrieve them at a later time. There are three types of variables:

Memory - This is the default variable type. These variables only exist while the character is logged in. Once it is logged out, all variables of this type are lost.
Persistent - These variable types are only accessible by the character who set them, but they are serialized to a database so they can be restored when the client is restarted.
Global - These variable types can be accessed by any running client, and are stored to the database any time they are modified.

Memory variables are good for quickly storing the value of something to be used later in that same client session. If your meta needs to save state to be accessed even after the client has closed, use a persistent variable. If the variable needs to be accessed and shared with all clients/characters, use a global variable.

You can set a memory variable using the setvar expression. It expects two arguments, the first being a string of the name to store the variable under, and the second being the value to store. For example setvar[myVariable,123] would store the number value 123 as a variable named myVariable. All data types can be stored in a memory variable. To read the value stored in a variable, you use the expression getvar. It expects one argument: a string of the variable name. For example to retrieve the memory variable we stored above we can use getvar[myVariable], this will return the stored number 123. There is an alternate (shorter) syntax for getting a memory variable, $. For example to get the same value stored above, you could use the alternate syntax: $myVariable.

Persistent and global variables have their own methods/syntax for getting and setting. Persistent variables use setpvar to set, getpvar to read, and supports the alternate syntax @ for getting variables (@myPersistentVariable returns the persistent variable named myPersistentVariable). Global variables use setgvar to set, getgvar to read, and supports the alternate syntax & for getting variables (&myGlobalVariable returns the global variable named myGlobalVariable)

Expression Examples

coordinatedistancewithz[getplayercoordinates[], wobjectgetphysicscoordinates[wobjectgetselection[]]]
- Gets the distance from your player to the currently selected object
setvar[myList,createlist[1,2,3]]; listadd[$myList,4]
- Saves a newly created list with the values 1,2,3 as a memory variable called myList. Then adds the value 4 to that same list using the $ getvar syntax.

Notes

Although there are keywords for true/false, internally they represent number ¹⁄₀.
Methods that return WorldObject types will return 0 if no matching objects were found. This will throw an error when passing the results to another expression that expects a WorldObject. It is recommended to use the getobjectinternaltype expression to check the resulting type before usage.
The alternative get variable syntax ($, @, and &) supports expressions where the variable identifier is. For example you can do the following to get a variable named Sunnuj, assuming that is your current character name: $wobjectgetname[wobjectgetplayer[]]. It is equivalent to writing getvar[wobjectgetname[wobjectgetplayer[]]].

Expressions

dictsize[Dictionary dict]

Returns the size of the dictionary

Parameters:

Param #0: dict (Dictionary) - The dictionary to return size of

Returns: number - Returns a number size

Examples:

dictsize[dictcreate[a,b,c,d]] - Returns 2 as the example dict is a=>b, c=>d

dictclear[Dictionary dict]

Clears the dictionary contents and returns the dictionary

Parameters:

Param #0: dict (Dictionary) - The dictionary to clear

Returns: Dictionary - Returns the dictionary

Examples:

dictclear[getvar[myDict]] - Returns the empty dictionary myDict

dictcopy[Dictionary dict]

Creates a new dictionary and copies over all the key value pairs. This is a shallow copy.

Parameters:

Param #0: dict (Dictionary) - The dictionary copy

Returns: Dictionary - Returns the new copy

Examples:

setvar[myDict2,dictcopy[getvar[myDict]]] - Creates a shallow copy of myDict and stores it in myDict2

getregexmatch[string text, string regex]

Returns the part of the text that matches the specified regex

Parameters:

Param #0: text (string) - The text to check the regex against

Param #1: regex (string) - The regex

Returns: string - Returns the part of the text that matches the specified regex

Examples:

getregexmatch[`test 123`,`\d+`] - Returns the string 123

uboptget[string name]

Returns the value of a ub setting.

Parameters:

Param #0: name (string) - The name of the variable to get. Prepend global options with global..

Returns: Object - Returns the value of the setting, if valid. 0 if invalid setting.

Examples:

uboptget[`Plugin.Debug`] - Gets the current value for the Plugin.Debug setting

uboptset[string name, Object newValue]

Changes the value of a ub setting.

Parameters:

Param #0: name (string) - The name of the variable to set. Prepend global options with global..

Param #1: newValue (Object) - The new value to set.

Returns: Object - Returns 1 if successful, 0 if it failed.

Examples:

uboptset[`Plugin.Debug`, 1] - Sets the current value for the Plugin.Debug setting to true

vitae[]

Gets your character’s current vitae percentage as a number

Returns: number - Returns a number

Examples:

vitae[] - returns your current vitae % as a number

getworldname[]

Gets the name of the currently connected world/server

Returns: string - Returns the name of the current world/server

Examples:

getworldname[] - Returns the name of the current world/server

getdatetimelocal[string text]

Gets the local date and time using the format provided

Parameters:

Param #0: text (string) - The format to return the date/time

Returns: string - Returns the local date and time

Examples:

getdatetimelocal[`hh:mm:ss tt`] - Returns current local time ‘06:09:01 PM’

getdatetimeutc[string text]

Gets the universal date and time using the format provided

Parameters:

Param #0: text (string) - The format to return the date/time

Returns: string - Returns the universal date and time

Examples:

getdatetimeutc[`hh:mm:ss tt`] - Returns current universal time ‘06:09:01 PM’

wobjectfindnearestbytemplatetype[number templatetype]

Attempted to find the nearest landscape world object with the specified template type

Parameters:

Param #0: templatetype (number) - templatetype to filter by

Returns: WorldObject - Returns a worldobject

Examples:

wobjectfindnearestbytemplatetype[42137] - Returns a worldobject with templaye type 42137 (level 10 ice tachi warden)

wobjectgetintprop[WorldObject obj, number property]

Returns an int property from a specific world object, or 0 if it’s undefined

Parameters:

Param #0: obj (WorldObject) - World object to get int property of

Param #1: property (number) - IntProperty to return

Returns: number - Returns an int property value

Examples:

wobjectgetintprop[wobjectgetselection[],218103808] - Returns the template type of the currently selected object

wobjectgetdoubleprop[WorldObject obj, number property]

Returns a double property from a specific world object, or 0 if it’s undefined

Parameters:

Param #0: obj (WorldObject) - World object to get double property of

Param #1: property (number) - DoubleProperty to return

Returns: number - Returns a double property value

Examples:

wobjectgetdoubleprop[wobjectgetselection[],167772169] - Returns the salvage workmanship of the currently selected object

wobjectgetboolprop[WorldObject obj, number property]

Returns a bool property from a specific world object, or 0 if it’s undefined

Parameters:

Param #0: obj (WorldObject) - World object to get bool property of

Param #1: property (number) - BoolProperty to return

Returns: number - Returns a bool property value

Examples:

wobjectgetboolprop[wobjectgetselection[],99] - Returns 1 if the currently selected object is ivoryable

wobjectgetstringprop[WorldObject obj, number property]

Returns a string property from a specific world object, or and empty string if it’s undefined

Parameters:

Param #0: obj (WorldObject) - World object to get string property of

Param #1: property (number) - StringProperty to return

Returns: string - Returns a string property value

Examples:

wobjectgetstringprop[wobjectgetselection[],1] - Returns the name of the currently selected object

wobjecthasdata[WorldObject obj]

Checks if a wobject has assess data from the server

Parameters:

Param #0: obj (WorldObject) - World object to check if we have assess data for

Returns: number - Returns 1 if we have assess data for the object

Examples:

wobjecthasdata[wobjectgetselection[]] - Returns 1 if the currently selected object has assess data from the server

wobjectrequestdata[WorldObject obj]

Requests assess data for a wobject from the server

Parameters:

Param #0: obj (WorldObject) - World object to request assess data for

Returns: number - Returns 1

Examples:

wobjectrequestdata[wobjectgetselection[]] - Requests assess data from the server for the currently selected object

getheadingto[WorldObject obj]

Calculates the heading in degrees (0-360 clockwise, 0 is north) from your player to the target object

Parameters:

Param #0: obj (WorldObject) - World object to calculate heading towards

Returns: number - Returns the heading in degrees from your player to the target object

Examples:

getheadingto[wobjectgetselection[]] - Returns the heading in degrees from your player to the target object

getheading[WorldObject obj]

Returns the heading in degrees (0-360 clockwise, 0 is north) the target object is facing

Parameters:

Param #0: obj (WorldObject) - World object to get the heading of

Returns: number - Returns the heading in degrees that the target object is facing

Examples:

getheading[wobjectgetselection[]] - Returns the heading in degrees that your current selection is facing

acos[number d]

Returns the angle whos cosine is the specified number

Parameters:

Param #0: d (number) - A number representing a cosine, where d must be greater than or equal to -1, but less than or equal to 1.

Returns: number - Returns the angle whos cosine is the specified number

asin[number d]

Returns the angle whose sine is the specified number

Parameters:

Param #0: d (number) - A number representing a sine, where d must be greater than or equal to -1, but less than or equal to 1.

Returns: number - Returns the angle whose sine is the specified number

atan[number d]

Returns the angle whose tangent is the specified number.

Parameters:

Param #0: d (number) - A number representing a tangent.

Returns: number - Returns the angle whose tangent is the specified number.

atan2[number y, number x]

Returns the angle whose tangent is the quotient of two specified numbers.

Parameters:

Param #0: y (number) - The y coordinate of a point.

Param #1: x (number) - The x coordinate of a point.

Returns: number - Returns the angle whose tangent is the quotient of two specified numbers.

cos[number d]

Returns the cosine of the specified angle.

Parameters:

Param #0: d (number) - An angle, measured in radians.

Returns: number - Returns the cosine of the specified angle.

cosh[number d]

Returns the hyperbolic cosine of the specified angle.

Parameters:

Param #0: d (number) - An angle, measured in radians.

Returns: number - Returns the hyperbolic cosine of the specified angle.

sin[number d]

Returns the sine of the specified angle.

Parameters:

Param #0: d (number) - An angle, measured in radians.

Returns: number - Returns the sine of the specified angle.

sinh[number d]

Returns the hyperbolic sine of the specified angle.

Parameters:

Param #0: d (number) - An angle, measured in radians.

Returns: number - Returns the hyperbolic sine of the specified angle.

sqrt[number d]

Returns the square root of a specified number.

Parameters:

Param #0: d (number) - The number whose square root is to be found

Returns: number - Returns the square root of a specified number.

tan[number d]

Returns the tangent of the specified angle.

Parameters:

Param #0: d (number) - An angle, measured in radians.

Returns: number - Returns the tangent of the specified angle.

tanh[number d]

Returns the hyperbolic tangent of the specified angle.

Parameters:

Param #0: d (number) - An angle, measured in radians.

Returns: number - Returns the hyperbolic tangent of the specified angle.

listcreate[…items items]

Creates a new list object. The list is empty by default.

Parameters:

Param #0: items (…items) - items to isntantiate the list with

Returns: List - Creates and returns a new list

Examples:

listcreate[] - Returns a new empty list

listcreate[1,2,3] - Returns a new list with 3 items: 1,2,3

setvar[myList,listcreate[]] - Creates a new list and stores it in myList variable

listadd[List list, Object item]

Adds an item to the end of a list

Parameters:

Param #0: list (List) - The list to add the item to

Param #1: item (Object) - Item to add to list, can be any type. Lists cannot contain references to themselves.

Returns: List - Returns the list object

Examples:

listadd[getvar[myList],`some value`] - Adds some value string to the list stored in myList variable

listinsert[List list, Object item, number index]

Inserts an item at the specified index of the list

Parameters:

Param #0: list (List) - The list to add the item to

Param #1: item (Object) - Item to add to list, can be any type. Lists cannot contain references to themselves.

Param #2: index (number) - The index in the list where the item should be inserted

Returns: List - Returns the list object

Examples:

listinsert[getvar[myList],`some value`,1] - Inserts some value at index 1 (second item) in the list

listremove[List list, Object item]

Removes the first occurance of an item from the list

Parameters:

Param #0: list (List) - The list to remove the item from

Param #1: item (Object) - Item to remove from the list.

Returns: List - Returns the list object

Examples:

listremove[getvar[myList],`some value`] - Removes the first occurance of some value string from the list stored in myList variable

listremoveat[List list, number index]

Removes the specified index from the list

Parameters:

Param #0: list (List) - The list to remove the item from

Param #1: index (number) - Index to remove from the list.

Returns: List - Returns the list object

Examples:

listremoveat[getvar[myList],1] - Removes the second item from the list stored in myList variable

listgetitem[List list, number index]

Retrieves the item at the specified list index. Lists are zero based, so the first item in the list is at index 0. If the index does not exist, it throws an error

Parameters:

Param #0: list (List) - The list to retrieve the item from

Param #1: index (number) - Index to retrieve from the list. Lists are zero based, so the first item is at index 0

Returns: Object - Returns the item at the specified list index

Examples:

listgetitem[getvar[myList],0] - Retrieves the first item from the list stored in myList variable

listcontains[List list, Object item]

Checks if the specified item is contained in the list

Parameters:

Param #0: list (List) - The list to check

Param #1: item (Object) - The item to check if the list contains

Returns: number - Returns 1 if found, 0 otherwise

Examples:

listcontains[getvar[myList],`some value`] - Checks if the list stored in myList variable contains the string some value

listindexof[List list, Object item]

Finds the index of the first occurance of an item in a list. Indexes are zero based.

Parameters:

Param #0: list (List) - The list to check

Param #1: item (Object) - The item to check if the list contains

Returns: number - Returns the index of the first occurence of the specified item, or -1 if not found

Examples:

listindexof[getvar[myList],`some value`] - Returns the index of the first occurence of the string some value

listlastindexof[List list, Object item]

Finds the index of the last occurance of an item in a list. Indexes are zero based.

Parameters:

Param #0: list (List) - The list to check

Param #1: item (Object) - The item to check if the list contains

Returns: number - Returns the index of the last occurence of the specified item, or -1 if not found

Examples:

listlastindexof[getvar[myList],`some value`] - Returns the index of the last occurence of the string some value

listcopy[List list]

Creates a copy of a list

Parameters:

Param #0: list (List) - The list to copy

Returns: List - Returns a copy of the specified list

Examples:

setvar[myListTwo,listcopy[getvar[myList]] - Copies the list stored in myList variable to a variable called myListTwo

listreverse[List list]

Creates a copy of a list, and reverses the order

Parameters:

Param #0: list (List) - The list to reverse

Returns: List - Returns a copy of the specified list, but the order is reversed

Examples:

setvar[myListReversed,listreverse[getvar[myList]] - Copies the list stored in myList variable, reverses it, and stores it to a variable called myListReversed

listpop[List list, number index=-1]

Removes the value at the specified index of the array and returns the item. If no index is passed, it uses the index of the last item in the array. Indexes are zero based.

Parameters:

Param #0: list (List) - The list to pop the item from

Param #1: index (number) (Default: -1) - Optional index to remove, if not provided, uses the index of the last item in the array

Returns: Object - Returns the value removed from the array

Examples:

listpop[getvar[myList]] - Removes and returns the last item in the list stored in myList variable

listpop[getvar[myList],0] - Removes and returns the first item in the list stored in myList variable

listcount[List list]

Counts the number of items contained in a list

Parameters:

Param #0: list (List) - The list to count the items in

Returns: number - Returns a count of how many items are contained in the list

Examples:

listcount[getvar[myList]] - Returns the number of items stored in the list stored in myList variable

listclear[List list]

Clears all items from the specified list

Parameters:

Param #0: list (List) - The list to clear

Returns: List - Returns the list

Examples:

listclear[getvar[myList]] - Removes all items from the list stored in the variable myList

dictcreate[…items items]

Creates a new dictionary object. The dictionary is empty by default. The list of arguments must be even and broken in key-value pairs. Keys must be strings. Values may be any type.

Parameters:

Param #0: items (…items) - items to instantiate the dictionary with. alternates keys and values

Returns: Dictionary - Creates and returns a new dictionary

Examples:

dictcreate[] - Returns a new empty dictionary

dictcreate[a,2,b,listcreate[4,5]] - Returns a new dictionary with 2 items: a=>2,b=>[4,5]

setvar[myDict,dictcreate[]] - Creates a new empty dictionary and stores it in myDict variable

dictgetitem[Dictionary dict, string key]

Retrieves the item at the specified dictionary key. If the key does not exist, it throws an error

Parameters:

Param #0: dict (Dictionary) - The dict to retrieve the item from

Param #1: key (string) - Key to retrieve from the dict.

Returns: Object - Returns the item for the specified key

Examples:

dictgetitem[getvar[myDict],foo] - Retrieves the item stored in myDict for the key foo

dictadditem[Dictionary dict, string key, Object value]

Adds the Key Value pair to the dictionary. Returns true if it overwrote a key, false otherwise. Will throw an exception if the key is not a string

Parameters:

Param #0: dict (Dictionary) - The dict to add key item pair to

Param #1: key (string) - Key to add to the dict

Param #2: value (Object) - Value to add to the dict

Returns: number - Returns True if it overwrote a key, False otherwise

Examples:

dictadditem[getvar[myDict],foo,1] - adds a key foo to myDict and sets the value to 1

dicthaskey[Dictionary dict, string key]

Checks if the dictionary contains the key. Returns true if it does, false otherwise

Parameters:

Param #0: dict (Dictionary) - The dict to check for a key

Param #1: key (string) - Key to look for

Returns: number - Returns True if dictionary has the key, False otherwise

Examples:

dicthaskey[getvar[myDict],foo] - Returns true if myDict has the key foo, false otherwise

dictremovekey[Dictionary dict, string key]

Deletes the specified key from the dictionary.

Parameters:

Param #0: dict (Dictionary) - The dict to delete the key from

Param #1: key (string) - Key to remove

Returns: number - Returns True if dictionary had the key, False otherwise

Examples:

dictremovekey[getvar[myDict],foo] - Removes the key foo from the dictionary myDict

dictkeys[Dictionary dict]

Returns a list of keys

Parameters:

Param #0: dict (Dictionary) - The dictionary to return keys from

Returns: List - Returns a list of keys

Examples:

dictkeys[getvar[myDict]] - Returns a list of all the keys in myDict

dictvalues[Dictionary dict]

Returns a list of keys

Parameters:

Param #0: dict (Dictionary) - The dictionary to return values from

Returns: List - Returns a list of values

Examples:

dictkeys[getvar[myDict]] - Returns a list of all the values in myDict

getgameyear[]

Gets the current ingame year

Returns: number - Returns the current ingame year. Years have 360 days.

Examples:

getgameyear[] - Returns the current ingame year, ie 249

getgamemonth[]

Gets the current ingame month as a number. Months are: 0=Morningthaw, 1=Solclaim, 2=Seedsow, 3=Leafdawning, 4=Verdantine, 5=Thistledown, 6=Harvestgain, 7=Leafcull, 8=Frostfell, 9=Snowreap, 10=Coldeve, 11=Wintersebb

Returns: number - Returns the current ingame month as a number

Examples:

getgamemonth[] - Returns the current ingame month as a number, ie 8

getgamemonthname[number monthIndex]

Returns the name of a month index. Months are: 0=Morningthaw, 1=Solclaim, 2=Seedsow, 3=Leafdawning, 4=Verdantine, 5=Thistledown, 6=Harvestgain, 7=Leafcull, 8=Frostfell, 9=Snowreap, 10=Coldeve, 11=Wintersebb

Parameters:

Param #0: monthIndex (number) - month index to get the name of

Returns: string - Returns the name of a month index

Examples:

getmonthname[1] - Returns Solclaim

getgameday[]

Returns the current ingame day of the month. 1-30.

Returns: number - Returns the current ingame day of the month. 1-30

Examples:

getgamemonth[] - returns the current ingame day of the month, ie 8

getgamehourname[number hourIndex]

Returns the name of a hour index.

Parameters:

Param #0: hourIndex (number) - hour index to get the name of

Returns: string - Returns the name of a hour index

Examples:

getgamehourname[1] - Returns Darktide-and-Half

getgamehour[]

Returns the current ingame hour of the day. Days have 16 hours

Returns: number - Returns the current ingame hour. 0-16

Examples:

getgamehour[] - returns the current ingame hour of the day, ie 3

getminutesuntilday[]

Returns real world minutes left until the next day cycle

Returns: number - Returns real world minutes left until the next day cycle

Examples:

getminutesuntilday[] - gets the number of real world minutes left until the next day cycle

getminutesuntilnight[]

Returns real world minutes left until the next night cycle

Returns: number - Returns real world minutes left until the next night cycle

Examples:

getminutesuntilnight[] - gets the number of real world minutes left until the next night cycle

getgameticks[]

Returns the current ingame ticks.

Returns: number - Returns the current ingame ticks

Examples:

getgameticks[] - returns the current ingame ticks

getisday[]

Returns 1 if it is currently day time, 0 otherwise

Returns: number - Returns 1 if it is currently day time, 0 otherwise

Examples:

getisday[] - returns 1 if it is currently day time

getisnight[]

Returns 1 if it is currently night time, 0 otherwise

Returns: number - Returns 1 if it is currently night time, 0 otherwise

Examples:

getisnight[] - returns 1 if it is currently night time

getfellowshipstatus[]

Checks if you are currently in a fellowship

Returns: number - Returns 1 if you are in a fellowship, 0 otherwise

Examples:

getfellowshipstatus[] - returns 1 if you are in a fellowship, 0 otherwise

getfellowshipname[]

Gets the name of your current fellowship

Returns: string - Returns the name of a fellowship, or an empty string if none

Examples:

getfellowshipname[] - returns the name of your current fellowship

getfellowshipcount[]

Gets the name of your current fellowship

Returns: number - Returns the number of members in your fellowship, or 0 if you are not in a fellowship

Examples:

getfellowshipcount[] - Returns the number of members in your fellowship, or 0 if you are not in a fellowship

getfellowshipleaderid[]

Returns the character id of the fellowship leader

Returns: number - Returns the character id of the fellowship leader

Examples:

getfellowshipleaderid[] - Returns the character id of the fellowship leader

getfellowid[number iterator]

Returns a fellowship member’s character id. It is recommended to save the output to a variable.

Parameters:

Param #0: iterator (number) - fellowship member to return (0-8)

Returns: number - Character ID of requested Fellowship Member, or 0

Examples:

getfellowid[0] - Returns the id of the first Fellowship Member

getfellowname[number iterator]

Returns a fellowship member’s character name. It is recommended to save the output to a variable.

Parameters:

Param #0: iterator (number) - fellowship member to return (0-8)

Returns: string - Character name of requested Fellowship Member, or “”

Examples:

getfellowname[0] - Returns the name of the first Fellowship Member

getfellowshiplocked[]

Returns 1 if your fellowship is Locked

Returns: number - Returns 1 if your fellowship is Locked, 0 otherwise

Examples:

getfellowshipmembercount[] - Returns 1 if your fellowship is Locked

getfellowshipisleader[]

Returns 1 if you are the leader of your fellowship

Returns: number - Returns 1 if you are the leader of your fellowship, 0 otherwise

Examples:

getfellowshipisleader[] - Returns 1 if you are the leader of your fellowship

getfellowshipisopen[]

Returns 1 if your fellowship is open

Returns: number - Returns 1 if your fellowship is open, 0 otherwise

Examples:

getfellowshipisopen[] - Returns 1 if your fellowship is open

getfellowshipisfull[]

Returns 1 if you’re in a fellowship, and it is full

Returns: number - Returns 1 if you’re in a fellowship and it is full. 0 otherwise

Examples:

getfellowshipisfull[] - Returns 1 if you’re in a fellowship, and it is full

getfellowshipcanrecruit[]

Returns 1 if your fellowship is open, or you are the leader, and the fellowship is not full

Returns: number - Returns 1 if you’re in a fellowship, and are the leader, or the fellowship is open, and the fellowship is not full

Examples:

getfellowshipcanrecruit[] - Returns 1 if you’re in a fellowship, and are the leader, or the fellowship is open, and the fellowship is not full

getfellownames[]

Returns a list of character names in your current fellowship, sorted alphabetically.

Returns: List - List of character names in the fellowship, sorted alphabetically

Examples:

getfellownames[] - Returns a list of character names in your current fellowship, sorted alphabetically

getfellowids[]

Returns a list of character ids in your current fellowship, sorted numerically.

Returns: List - List of character ids in the fellowship, sorted numerically

Examples:

getfellowids[] - Returns a list of character ids in your current fellowship, sorted numerically

wobjectgethealth[WorldObject obj]

Gets the specified mob/player wobject current health percentage. Note: You must have the wobject selected in order to receive health updates

Parameters:

Param #0: obj (WorldObject) - World object to get health of

Returns: number - Returns a value from 0-1 representing the objects current health percentage. If the objects health is not currently being tracked this will return -1

Examples:

wobjectgethealth[wobjectgetselection[]] - Returns the health of the currently selected mob/player

getitemcountininventorybyname[string name]

Counts how many items you have in your inventory exactly matching name. Stack sizes are counted

Parameters:

Param #0: name (string) - Exact item name to match

Returns: number - Returns a count of the number of items found. stack size is counted

Examples:

getitemcountininventorybyname[Prismatic Taper] - Returns total count of prismatic tapers in your inventory

getitemcountininventorybynamerx[string namerx]

Counts how many items you have in your inventory matching regex namerx. Stack sizes are counted

Parameters:

Param #0: namerx (string) - Regex item name to match

Returns: number - Returns a count of the number of items found. stack size is counted

Examples:

getitemcountininventorybynamerx[Scarab] - Returns total count of scarabs in your inventory

getinventorycountbytemplatetype[number templatetype]

Counts how many items you have in your inventory of a certain template type. Stack sizes are counted

Parameters:

Param #0: templatetype (number) - templatetype to filter by

Returns: number - Returns a count of the number of items found. stack size is counted

Examples:

getinventorycountbytemplatetype[42137] - Returns total count of inventory items with templaye type 42137 (level 10 ice tachi warden)

actiontrygiveprofile[string lootprofile, string target]

Gives all items matching the specified loot profile to a character or npc

Parameters:

Param #0: lootprofile (string) - loot profile to give

Param #1: target (string) - target npc/player name to give to

Returns: number - Returns 1 if an attempt was made, 0 if it was not (busy)

Examples:

actiontrygiveprofile[salvage\.utl,My Salvage Mule] - Gives all items matching loot profile salvage.utl to a character named My Salvage Mule

testquestflag[string questflag]

Checks if a quest flag has ever been completed. You must manually refresh /myquests after completing a quest, for these values to be up to date. UB will call /myquests once on login automatically.

Parameters:

Param #0: questflag (string) - quest flag to check

Returns: number - Returns 1 if you have ever completed this quest flag, 0 otherwise

Examples:

testquestflag[spokenbobo] - Checks if your character is flagged for bobo

getqueststatus[string questflag]

Checks if a quest flag has a timer on it. If there is a timer it returns 0, if it’s ready it returns 0. You must manually refresh /myquests after completing a quest, for these values to be up to date. UB will call /myquests once on login automatically.

Parameters:

Param #0: questflag (string) - quest flag to check

Returns: number - Returns status of a quest flag. 0 = Not Ready, 1 = Ready

Examples:

getqueststatus[blankaug] - Checks if your character is ready to run the blankaug quest again.

getquestktprogress[string questflag]

Checks progress of a killtask quest. You must manually refresh /myquests after completing a quest, for these values to be up to date. UB will call /myquests once on login automatically.

Parameters:

Param #0: questflag (string) - quest flag to check

Returns: number - Returns a progress count

Examples:

getquestktprogress[totalgolemmagmaexarchdead] - Checks how many exarch kills you currently have

getquestktrequired[string questflag]

Checks total required solves of a killtask quest. If you have not started the killtask, this will return 0. You must manually refresh /myquests after completing a quest, for these values to be up to date. UB will call /myquests once on login automatically.

Parameters:

Param #0: questflag (string) - quest flag to check

Returns: number - Returns a required count

Examples:

getquestktrequired[totalgolemmagmaexarchdead] - Checks required total exarch kills for this kill task

isrefreshingquests[]

Checks if quests are currently being fetched or processed

Returns: number - Returns 1 if quests are currently being fetched and processed, 0 otherwise

Examples:

isrefreshingquests[] - Returns 1 if quests are currently being fetched and processed

strlen[string tocheck]

Gets the length of a string

Parameters:

Param #0: tocheck (string) - string to check

Returns: number - Returns the length of tocheck string

Examples:

strlen[test] - Returns a length of 4

getobjectinternaltype[Object tocheck]

Gets internal type of an object, as a number

Parameters:

Param #0: tocheck (Object) - object to check

Returns: number - Values are: 0=none, 1=number, 3=string, 7=object

Examples:

getobjectinternaltype[test] - Returns a length of 4

cstrf[number number, string format]

Converts a number to a string using a specified format

Parameters:

Param #0: number (number) - number to convert

Param #1: format (string) - string format. See: http://msdn.microsoft.com/en-us/library/kfsatb94.aspx

Returns: string - formatted string, from a number

Examples:

cstrf[3.14159,`N3`] - Formats 3.14159 to a string with 3 decimal places

cnumber[string number]

Converts a string to a floating point number

Parameters:

Param #0: number (string) - string number to convert

Returns: number - floating point number from a string

Examples:

cnumber[`3.14159`] - Converts 3.14159 to a number

floor[number number]

returns the largest integer less than or equal to a given number.

Parameters:

Param #0: number (number) - number to floot

Returns: number - Returns a whole number

Examples:

floor[3.14159] - returns 3

ceiling[number number]

rounds a number up to the next largest whole number or integer

Parameters:

Param #0: number (number) - number to ceil

Returns: number - Returns a whole number

Examples:

ceiling[3.14159] - returns 3

round[number number]

returns the value of a number rounded to the nearest integer

Parameters:

Param #0: number (number) - number to round

Returns: number - Returns a whole number

Examples:

round[3.14159] - returns 3

abs[number number]

Returns the absolute value of a number

Parameters:

Param #0: number (number) - number to get absolute value of

Returns: number - Returns a positive number

Examples:

abs[-3.14159] - returns 3.14159

vtsetmetastate[string state]

Changes the current vtank meta state

Parameters:

Param #0: state (string) - new state to switch to

Returns: number - Returns 1

Examples:

vtsetmetastate[myState] - sets vtank meta state to myState

vtgetmetastate[]

Gets the current vtank meta state as a string

Returns: string - Returns the current vt meta state as a string

Examples:

vtgetmetastate[] - Returns the current vt meta state as a string

ord[string character]

returns an integer representing the Unicode character

Parameters:

Param #0: character (string) - string to convert

Returns: number - number representing unicode character

Examples:

ord[c] - Converts ‘c’ to a number representing its unicode character (99)

chr[number character]

returns a string representing a character whose Unicode code point is an integer.

Parameters:

Param #0: character (number) - number to convert

Returns: string - string representing unicode character

Examples:

chr[99] - Converts 99 to a strin representing its unicode character ‘c’

stopwatchcreate[]

Creates a new stopwatch object. The stopwatch object is stopped by default.

Returns: Stopwatch - Returns a stopwatch object

Examples:

stopwatchcreate[] - returns a new stopwatch

stopwatchstart[Stopwatch watch]

Starts a stopwatch if not already started

Parameters:

Param #0: watch (Stopwatch) - stopwatch to start

Returns: Stopwatch - Returns a stopwatch object

Examples:

stopwatchstart[stopwatchcreate[]] - starts a new stopwatch

stopwatchstop[Stopwatch watch]

Stops a stopwatch if not already stopped

Parameters:

Param #0: watch (Stopwatch) - stopwatch to stop

Returns: Stopwatch - Returns a stopwatch object

Examples:

stopwatchstop[stopwatchcreate[]] - stops a new stopwatch

stopwatchelapsedseconds[Stopwatch watch]

Gets the amount of seconds a stopwatch has been running for

Parameters:

Param #0: watch (Stopwatch) - stopwatch to check

Returns: Stopwatch - Returns a int elapsed seconds

Examples:

stopwatchelapsedseconds[stopwatchcreate[]] - Returns the amount of a seconds a new stopwatch has been running for (0 obv)

uigetcontrol[string windowName, string controlName]

Gets a reference to the named control in the named window

Parameters:

Param #0: windowName (string) - Name of the window the control belongs to

Param #1: controlName (string) - Name of the control to get

Returns: UIControl - Returns a UIControl, or 0 if not found

Examples:

uigetcontrol[myWindow, myControl] - Gets a reference to the control myControl in the view myWindow

uisetlabel[UIControl control, string label]

Changes the label text for the given UIControl. Currently only supports buttons.

Parameters:

Param #0: control (UIControl) - UIControl of the control to change

Param #1: label (string) - The new label text for the control

Returns: number - Returns 1 on success, 0 on failure

Examples:

uisetlabel[uigetcontrol[myWindow, myControl], new label] - Changes the control myControl label in the view myWindow to new label

uisetvisible[UIControl control, number visible]

Changes the visibility for the given UIControl. Currently only supports buttons.

Parameters:

Param #0: control (UIControl) - UIControl of the control to change

Param #1: visible (number) - pass 1 to make the control visible, 0 to make it hidden

Returns: number - Returns 1 on success, 0 on failure

Examples:

uisetvisible[uigetcontrol[myWindow, myControl], 0] - Changes the control myControl visibility in the view myWindow to hidden

uiviewexists[string windowName]

Checks if a meta view exists

Parameters:

Param #0: windowName (string) - Name of the window to check the existence of

Returns: UIControl - Returns 1 if it exists, 0 if not

Examples:

uiviewexists[myWindow] - returns true if a view with the title myWindow exists

uiviewvisible[string windowName]

Checks if a meta view is visible

Parameters:

Param #0: windowName (string) - Name of the window to check the visibilty of

Returns: UIControl - Returns 1 if it exists, 0 if not

Examples:

uiviewvisible[myWindow] - returns true if a view with the title myWindow is visible

testvar[string varname]

Checks if a variable is defined

Parameters:

Param #0: varname (string) - Variable name to check

Returns: number - Returns 1 if the variable is defined, 0 if it isn’t

Examples:

testvar[myvar] - Returns 1 if myvar variable is defined

getvar[string varname]

Returns the value stored in a variable

Parameters:

Param #0: varname (string) - Variable name to get

Returns: number - Returns the value of a variable, or 0 if undefined

Examples:

getvar[myvar] - Returns the value stored in myvar variable

setvar[string varname, Object value]

Stores a value in a variable

Parameters:

Param #0: varname (string) - Variable name to set

Param #1: value (Object) - Value to store

Returns: Object - Returns the newly set value

Examples:

setvar[myvar,1] - Stores the number value 1 inside of myvar variable

touchvar[string varname]

Sets the value of a variable to 0 if the variable was previously undefined

Parameters:

Param #0: varname (string) - Variable name to touch

Returns: number - Returns 1 if the variable was previously defined, 0 otherwise

Examples:

touchvar[myvar] - Ensures that myvar has a value set

clearallvars[]

Unsets all variables

Returns: number - Returns 1

Examples:

clearallvars[] - Unset all variables

clearvar[string varname]

Clears the value of a variable

Parameters:

Param #0: varname (string) - Variable name to clear

Returns: number - Returns 1 if the variable was defined, 0 otherwise

Examples:

clearvar[myvar] - Clears the value stored in myvar variable

testpvar[string varname]

Checks if a persistent variable is defined

Parameters:

Param #0: varname (string) - Variable name to check

Returns: number - Returns 1 if the variable is defined, 0 if it isn’t

Examples:

testpvar[myvar] - Returns 1 if myvar persistent variable is defined

getpvar[string varname]

Returns the value stored in a variable

Parameters:

Param #0: varname (string) - Variable name to get

Returns: number - Returns the value of a variable, or 0 if undefined

Examples:

getpvar[myvar] - Returns the value stored in myvar variable

setpvar[string varname, Object value]

Stores a value in a persistent variable that is available ever after relogging. Persistent variables are not shared between characters.

Parameters:

Param #0: varname (string) - Variable name to set

Param #1: value (Object) - Value to store

Returns: Object - Returns the newly set value

Examples:

setpvar[myvar,1] - Stores the number value 1 inside of myvar variable

touchpvar[string varname]

Sets the value of a persistent variable to 0 if the variable was previously undefined

Parameters:

Param #0: varname (string) - Variable name to touch

Returns: number - Returns 1 if the variable was previously defined, 0 otherwise

Examples:

touchpvar[myvar] - Ensures that myvar has a value set

clearallpvars[]

Unsets all persistent variables

Returns: number - Returns 1

Examples:

clearallpvars[] - Unset all persistent variables

clearpvar[string varname]

Clears the value of a persistent variable

Parameters:

Param #0: varname (string) - Variable name to clear

Returns: number - Returns 1 if the variable was defined, 0 otherwise

Examples:

clearpvar[myvar] - Clears the value stored in myvar persistent variable

testgvar[string varname]

Checks if a global variable is defined

Parameters:

Param #0: varname (string) - Variable name to check

Returns: number - Returns 1 if the variable is defined, 0 if it isn’t

Examples:

testgvar[myvar] - Returns 1 if myvar global variable is defined

getgvar[string varname]

Returns the value stored in a variable

Parameters:

Param #0: varname (string) - Variable name to get

Returns: number - Returns the value of a variable, or 0 if undefined

Examples:

getgvar[myvar] - Returns the value stored in myvar global variable

setgvar[string varname, Object value]

Stores a value in a global variable. This variable is shared between all characters on the same server.

Parameters:

Param #0: varname (string) - Variable name to set

Param #1: value (Object) - Value to store

Returns: Object - Returns the newly set value

Examples:

setgvar[myvar,1] - Stores the number value 1 inside of myvar variable

touchgvar[string varname]

Sets the value of a global variable to 0 if the variable was previously undefined

Parameters:

Param #0: varname (string) - Variable name to touch

Returns: number - Returns 1 if the variable was previously defined, 0 otherwise

Examples:

touchgvar[myvar] - Ensures that myvar global variable has a value set

clearallgvars[]

Unsets all global variables

Returns: number - Returns 1

Examples:

clearallgvars[] - Unset all global variables

cleargvar[string varname]

Clears the value of a global variable

Parameters:

Param #0: varname (string) - Variable name to clear

Returns: number - Returns 1 if the variable was defined, 0 otherwise

Examples:

cleargvar[myvar] - Clears the value stored in myvar global variable

chatbox[string message]

Sends a message to the chatbox as if you had typed it in

Parameters:

Param #0: message (string) - Message to send

Returns: string - Returns the string sent to the charbox

Examples:

chatbox[test] - sends ‘test’ to the chatbox

chatboxpaste[string message]

Pastes a message to the chatbox, leaving focus, so that the user can complete typing it

Parameters:

Param #0: message (string) - Message to paste

Returns: number - Returns 1 if successful

Examples:

chatboxpaste[test] - pastes test to the chatbox, without sending

echo[string message, number color]

Echos chat to the chatbox with a color. Use /ub printcolors to view all colors

Parameters:

Param #0: message (string) - Message to echo

Param #1: color (number) - Message color

Returns: number - Returns 1 on success, 0 on failure

Examples:

echo[test,15] - echos ‘test’ to the chatbox in red (Help)

getcharintprop[number property]

Returns an int property from your character, or 0 if it’s undefined

Parameters:

Param #0: property (number) - IntProperty to return

Returns: number - Returns an int property from your character

Examples:

getcharintprop[25] - Returns your character’s current level

getchardoubleprop[number property]

Returns a double property from your character, or 0 if it’s undefined

Parameters:

Param #0: property (number) - DoubleProperty to return

Returns: number - Returns a double property from your character

Examples:

getchardoubleprop[25] - Returns your character’s current level

getcharquadprop[number property]

Returns a quad property from your character, or 0 if it’s undefined

Parameters:

Param #0: property (number) - QuadProperty to return

Returns: number - Returns a quad property from your character

Examples:

getcharquadprop[1] - Returns your character’s TotalExperience

getcharboolprop[number property]

Returns a bool property from your character, or 0 if it’s undefined

Parameters:

Param #0: property (number) - BoolProperty to return

Returns: number - Returns a bool property from your character

Examples:

getcharboolprop[110] - Returns your character’s AwayFromKeyboard status

getcharstringprop[number property]

Returns a string property from your character, or false if it’s undefined

Parameters:

Param #0: property (number) - StringProperty to return

Returns: string - Returns a string property from your character

Examples:

getcharstringprop[1] - Returns your character’s name

getisspellknown[number spellId]

Checks if your character knowns a spell by id

Parameters:

Param #0: spellId (number) - Spell ID to check

Returns: number - Returns 1 if your character knows this spell, 0 otherwise

Examples:

getisspellknown[2931] - Checks if your character knowns the Recall Aphus Lassel spell

getcancastspell_hunt[number spellId]

Checks if your character is capable of casting spellId while hunting

Parameters:

Param #0: spellId (number) - Spell ID to check

Returns: number - Returns 1 if your character can cast this spell while hunting, 0 otherwise

Examples:

getcancastspell_hunt[2931] - Checks if your character is capable of casting the Recall Aphus Lassel spell while hunting

getcancastspell_buff[number spellId]

Checks if your character is capable of casting spellId while buffing

Parameters:

Param #0: spellId (number) - Spell ID to check

Returns: number - Returns 1 if your character can cast this spell while buffing, 0 otherwise

Examples:

getcancastspell_hunt[2931] - Checks if your character is capable of casting the Recall Aphus Lassel spell while buffing

getcharvital_base[number vitalId]

Gets your characters base (unbuffed) vital value

Parameters:

Param #0: vitalId (number) - Which vital to get. 1 = Health, 2 = Stamina, 3 = Mana.

Returns: number - Returns the base (unbuffed) vital value

Examples:

getcharvital_base[1] - Returns your character’s base health

getcharvital_current[number vitalId]

Gets your characters current vital value

Parameters:

Param #0: vitalId (number) - Which vital to get. 1 = Health, 2 = Stamina, 3 = Mana.

Returns: number - Returns the current vital value

Examples:

getcharvital_current[2] - Returns your character’s current stamina

getcharvital_buffedmax[number vitalId]

Gets your characters buffed maximum vital value

Parameters:

Param #0: vitalId (number) - Which vital to get. 1 = Health, 2 = Stamina, 3 = Mana.

Returns: number - Returns the buffed maximum vital value

Examples:

getcharvital_current[3] - Returns your character’s buffed maximum mana

getcharskill_traininglevel[number skillId]

Gets your characters training level for a specified skill

Parameters:

Param #0: skillId (number) - Which skill to check.

Returns: number - Returns current training level of a skill. 0 = Unusable, 1 = Untrained, 2 = Trained, 3 = Specialized

Examples:

getcharskill_traininglevel[23] - Returns your character’s LockPick skill training level

getcharskill_base[number skillId]

Gets your characters base skill level for a speficied skill

Parameters:

Param #0: skillId (number) - Which skill to check.

Returns: number - Returns base skill level of the specified skill

Examples:

getcharskill_base[43] - Returns your character’s base Void skill level

getcharskill_buffed[number skillId]

Gets your characters buffed skill level for a speficied skill

Parameters:

Param #0: skillId (number) - Which skill to check.

Returns: number - Returns buffed skill level of the specified skill

Examples:

getcharskill_buffed[33] - Returns your character’s buffed Life Magic skill level

getcharattribute_buffed[number attributeId]

Gets your characters buffed attribute level for a speficied attribute

Parameters:

Param #0: attributeId (number) - Which attribute to check. 1 = Strength, 2 = Endurance, 3 = Quickness, 4 = Coordination, 5 = Focus, 6 = Self

Returns: number - Returns buffed attribute level of the specified attribute

Examples:

getcharattribute_buffed[1] - Returns your character’s buffed Strength attribute level

getcharattribute_base[number attributeId]

Gets your characters base attribute level for a speficied attribute

Parameters:

Param #0: attributeId (number) - Which attribute to check. 1 = Strength, 2 = Endurance, 3 = Quickness, 4 = Coordination, 5 = Focus, 6 = Self

Returns: number - Returns base attribute level of the specified attribute

Examples:

getcharattribute_base[1] - Returns your character’s base Strength attribute level

getplayerlandcell[]

Gets the landcell your character is currently standing in, including the landblock

Returns: number - Returns the landcell your character is currently standing in, including the landblock

Examples:

getplayerlandcell[] - Returns your character’s current landblock as in int

getplayercoordinates[]

Gets the a coordinates object representing your characters current global position

Returns: Coordinates - Returns your character’s global coordinates object

Examples:

getplayercoordinates[] - Returns your character’s current position as coordinates object

coordinategetns[Coordinates obj]

Gets the NS position of a coordinates object as a number

Parameters:

Param #0: obj (Coordinates) - coordinates object to get the NS position of

Returns: number - Returns the NS position of a coordinates object as a number

Examples:

coordinategetns[getplayercoordinates[]] - Returns your character’s current NS position

coordinategetwe[Coordinates obj]

Gets the EW position of a coordinates object as a number

Parameters:

Param #0: obj (Coordinates) - coordinates object to get the EW position of

Returns: number - Returns the EW position of a coordinates object as a number

Examples:

coordinategetwe[getplayercoordinates[]] - Returns your character’s current EW position

coordinategetz[Coordinates obj]

Gets the Z position of a coordinates object as a number

Parameters:

Param #0: obj (Coordinates) - coordinates object to get the Z position of

Returns: number - Returns the Z position of a coordinates object as a number

Examples:

coordinategetz[getplayercoordinates[]] - Returns your character’s current Z position

coordinatetostring[Coordinates obj]

Converts a coordinates object to a string representation

Parameters:

Param #0: obj (Coordinates) - coordinates object to convert to a string

Returns: number - Returns a string representation of a coordinates object, like 1.2N, 34.5E

Examples:

coordinatetostring[getplayercoordinates[]] - Returns your character’s current coordinates as a string, eg 1.2N, 34.5E

coordinateparse[string coordstring]

Converts a coordinate string like 1.2N, 3.4E to a coordinates object

Parameters:

Param #0: coordstring (string) - coordinates string to parse

Returns: Coordinates - Returns a coordinates object

Examples:

coordinateparse[`1.2N, 3.4E`] - Returns a coordinates object representing 1.2N, 3.4E

coordinatedistancewithz[Coordinates obj1, Coordinates obj2]

Gets the 3d distance in meters between two coordinates objects

Parameters:

Param #0: obj1 (Coordinates) - first coordinates object

Param #1: obj2 (Coordinates) - second coordinates object

Returns: number - Returns the 3d distance in meters between obj1 and obj2

Examples:

coordinatedistancewithz[coordinateparse[`1.2N, 3.4E`], coordinateparse[`5.6N, 7.8E`]] - Returns the 3d distance between 1.2N, 3.4E and 5.6N, 7.8E

coordinatedistanceflat[Coordinates obj1, Coordinates obj2]

Gets the 2d distance in meters between two coordinates objects (ignoring Z)

Parameters:

Param #0: obj1 (Coordinates) - first coordinates object

Param #1: obj2 (Coordinates) - second coordinates object

Returns: number - Returns the 2d distance in meters between obj1 and obj2 (ignoring Z)

Examples:

coordinatedistancewithz[coordinateparse[`1.2N, 3.4E`], coordinateparse[`5.6N, 7.8E`]] - Returns the 2d distance between 1.2N, 3.4E and 5.6N, 7.8E (ignoring Z)

wobjectgetphysicscoordinates[WorldObject wo]

Gets a coordinates object representing a world objects current position

Parameters:

Param #0: wo (WorldObject) - world object to get coordinates of

Returns: Coordinates - Returns a coordinates object representing the passed wobject

Examples:

wobjectgetphysicscoordinates[wobjectgetplayer[]] - Returns a coordinates object representing the current player’s position

wobjectgetname[WorldObject wo]

Gets the name string of a wobject

Parameters:

Param #0: wo (WorldObject) - world object to get the name of

Returns: string - Returns a string of wobject’s name

Examples:

wobjectgetname[wobjectgetplayer[]] - Returns a coordinates object representing the current player’s position

wobjectgetid[WorldObject wo]

Gets the id of a wobject

Parameters:

Param #0: wo (WorldObject) - world object to get the id of

Returns: number - Returns the id of the passed wobject

Examples:

wobjectgetid[wobjectgetplayer[]] - Returns the id of the current player

wobjectgetobjectclass[WorldObject wo]

Gets the objectclass as a number from a wobject

Parameters:

Param #0: wo (WorldObject) - world object to get the objectclass of

Returns: number - Returns a number representing the passed wobjects objectclass

Examples:

wobjectgetobjectclass[wobjectgetplayer[]] - Returns 24 (Player ObjectClass)

wobjectgettemplatetype[WorldObject wo]

Gets the template type as a number from a wobject

Parameters:

Param #0: wo (WorldObject) - world object to get the template type of

Returns: number - Returns a number representing the passed wobjects template type

Examples:

wobjectgettemplatetype[wobjectgetplayer[]] - Returns 1 (Player template type)

wobjectgetisdooropen[WorldObject wo]

Checks if a door wobject is open

Parameters:

Param #0: wo (WorldObject) - door world object to check

Returns: number - Returns 1 if the wo door is open, 0 otherwise

Examples:

wobjectgetisdooropen[wobjectfindnearestdoor[]] - Returns 1 if the door is open, 0 otherwise

wobjectfindnearestmonster[]

Gets a worldobject representing the nearest monster, or 0 if none was found

Returns: WorldObject - Returns a worldobject representing the nearest monster

Examples:

wobjectfindnearestmonster[] - Returns a worldobject representing the nearest monster

wobjectfindnearestdoor[]

Gets a worldobject representing the nearest door, or 0 if none was found

Returns: WorldObject - Returns a worldobject representing the nearest door

Examples:

wobjectfindnearestdoor[] - Returns a worldobject representing the nearest door

wobjectfindnearestbyobjectclass[number objectclass]

Gets a worldobject representing the nearest object matching objectclass, or 0 if none was found

Parameters:

Param #0: objectclass (number) - objectclass to filter by

Returns: WorldObject - Returns a worldobject representing the nearest matching objectclass

Examples:

wobjectfindnearestbyobjectclass[24] - Returns a worldobject of the nearest matching objectclass

wobjectfindininventorybytemplatetype[number templatetype]

Gets a worldobject representing the first inventory item matching template type, or 0 if none was found

Parameters:

Param #0: templatetype (number) - templatetype to filter by

Returns: WorldObject - Returns a worldobject

Examples:

wobjectfindininventorybytemplatetype[9060] - Returns a worldobject of the first inventory item that is a Titan Mana Charge (template type 9060)

wobjectfindininventorybyname[string name]

Gets a worldobject representing the first inventory item matching an exact name, or 0 if none was found

Parameters:

Param #0: name (string) - exact name to filter by

Returns: WorldObject - Returns a worldobject

Examples:

wobjectfindininventorybyname[Massive Mana Charge] - Returns a worldobject of the first inventory item that is named Massive Mana Charge

wobjectfindininventorybynamerx[string namerx]

Gets a worldobject representing the first inventory item matching name regex, or 0 if none was found

Parameters:

Param #0: namerx (string) - name regex to filter by

Returns: WorldObject - Returns a worldobject

Examples:

wobjectfindininventorybynamerx[`Massive.*`] - Returns a worldobject of the first inventory item that matches regex Massive.*

wobjectgetselection[]

Gets a worldobject representing the currently selected object

Returns: WorldObject - Returns a worldobject representing the currently selected object, or 0 if none

Examples:

wobjectgetselection[] - Returns a worldobject representing the currently selected object

wobjectgetplayer[]

Gets a worldobject representing the current player

Returns: WorldObject - Returns a worldobject representing the current player

Examples:

wobjectgetplayer[] - Returns a worldobject representing the current player

wobjectfindnearestbynameandobjectclass[number objectclass, string namerx]

Gets a worldobject representing the first object matching objectclass and name regex, or 0 if none was found

Parameters:

Param #0: objectclass (number) - objectclass to filter by

Param #1: namerx (string) - name regex to filter by

Returns: WorldObject - Returns a worldobject

Examples:

wobjectfindnearestbynameandobjectclass[24,`Crash.*`] - Returns a worldobject of the first object found matching objectlass 24 (player) and name regex Crash.*

wobjectfindbyid[number id]

Gets a worldobject representing the object with the passed id

Parameters:

Param #0: id (number) - object id to find

Returns: WorldObject - Returns a worldobject

Examples:

wobjectfindbyid[123412] - Returns a worldobject of the object with id 123412

wobjectgetopencontainer[]

Gets a worldobject representing the currentlty opened container, or 0 if none

Returns: WorldObject - Returns a worldobject representing the currently opened container

Examples:

wobjectgetopencontainer[] - Returns a worldobject representing the currently opened container

actiontryselect[WorldObject obj]

Attempts to select a worldobject

Parameters:

Param #0: obj (WorldObject) - wobject to select

Returns: number - Returns 0

Examples:

actiontryselect[wobjectgetplayer[]] - Attempts to select the current player

actiontryuseitem[WorldObject obj]

Attempts to use a worldobject

Parameters:

Param #0: obj (WorldObject) - wobject to try to use

Returns: number - Returns 0

Examples:

actiontryuseitem[wobjectgetplayer[]] - Attempts to use the current player (opens backpack)

actiontryapplyitem[WorldObject useObj, WorldObject onObj]

Attempts to use a worldobject on another worldobject

Parameters:

Param #0: useObj (WorldObject) - wobject to use first

Param #1: onObj (WorldObject) - wobject to be used on

Returns: number - Returns 0 if failed, and 1 if it could succeed

Examples:

actiontryapplyitem[wobjectfindininventorybynamerx[`.* Healing Kit`],wobjectwobjectgetplayer[]] - Attempts to use any healing kit in your inventory, on yourself

actiontrygiveitem[WorldObject give, WorldObject destination]

Attempts to give a worldobject to another worlobject, like an npc

Parameters:

Param #0: give (WorldObject) - wobject to give

Param #1: destination (WorldObject) - wobject to be given to

Returns: number - Returns 0 if failed, and 1 if it could succeed

Examples:

actiontrygiveitem[wobjectfindininventorybynamerx[`.* Healing Kit`],wobjectgetselection[]] - Attempts to to give any healing kit in your inventory to the currently selected object

actiontryequipanywand[]

Attempts to take one step towards equipping any wand from the current profile’s items list

Returns: number - Returns 1 if a wand is already equipped, 0 otherwise

Examples:

actiontryequipanywand[] - Attempts to equip any wand

actiontrycastbyid[number spellId]

Attempts to cast a spell by id. Checks spell requirements as if it were a vtank ‘hunting’ spell. If the character is not in magic mode, one step is taken towards equipping any wand

Parameters:

Param #0: spellId (number) - spellId to cast

Returns: number - Returns 1 if the attempt has begun, 0 if the attempt has not yet been made, or 2 if the attempt is impossible

Examples:

actiontrycastbyid[2931] - Attempts to cast Recall Aphus Lassel

actiontrycastbyidontarget[number spellId, WorldObject target]

Attempts to cast a spell by id on a worldobject. Checks spell requirements as if it were a vtank ‘hunting’ spell. If the character is not in magic mode, one step is taken towards equipping any wand

Parameters:

Param #0: spellId (number) - spellId to cast

Param #1: target (WorldObject) - target to cast on

Returns: number - Returns 1 if the attempt has begun, 0 if the attempt has not yet been made, or 2 if the attempt is impossible

Examples:

actiontrycastbyidontarget[1,wobjectgetselection[]] - Attempts to cast Strength Other, on your currently selected target

statushud[string key, string value]

Updates an entry in the Virindi HUDs Status HUD.

Parameters:

Param #0: key (string) - key to update

Param #1: value (string) - value to update with

Returns: number - Returns 1

Examples:

statushud[test,my value] - Updates the V Status Hud key test to my value

statushudcolored[string key, string value, number color]

Updates an entry in the Virindi HUDs Status HUD with color

Parameters:

Param #0: key (string) - key to update

Param #1: value (string) - value to update with

Param #2: color (number) - The color, in RGB number format. For example, pure red is 16711680 (0xFF0000)

Returns: number - Returns 1

Examples:

statushudcolored[test,my value,16711680] - Updates the V Status Hud key test to my value in red

isfalse[Object value]

Checks if a value is equal to false (0)

Parameters:

Param #0: value (Object) - value to check

Returns: number - Returns 1 if value is false, 0 otherwise

Examples:

isfalse[0] - Checks that 0 is false, and returns true because it is

istrue[Object value]

Checks if a value is equal to true (1)

Parameters:

Param #0: value (Object) - value to check

Returns: number - Returns 1 if value is true, 0 otherwise

Examples:

istrue[1] - Checks that 0 is true, and returns true because it is

iif[number value, Object truevalue, Object falsevalue]

Checks if the first parameter is true, if so returns the second argument. If the first parameter is false or not a number, returns the second argument

Parameters:

Param #0: value (number) - value to check

Param #1: truevalue (Object) - value to return if value is true

Param #2: falsevalue (Object) - value to return if value is false

Returns: number - Returns 1 if value is true, 0 otherwise

Examples:

iif[1,2,3] - Returns 2 (second param) because 1 (first param) is true

randint[number min, number max]

Generates a random number between min and (max-1)

Parameters:

Param #0: min (number) - minimum value to return

Param #1: max (number) - maximum value to return (-1)

Returns: number - Returns a number between min and (max-1)

Examples:

randint[0,2] - Returns a random number, 0 or 1, but not 2

cstr[number number]

Converts a number to a string

Parameters:

Param #0: number (number) - number to convert

Returns: string - Returns a string representation of number

Examples:

cstr[2] - Returns a string of 2

General

Tools

Summary

Language Overview

Data Types

Operators

Expressions (Functions)

Variables

Expression Examples

Notes

Expressions

dictsize[Dictionary dict]

dictclear[Dictionary dict]

dictcopy[Dictionary dict]

getregexmatch[string text, string regex]

uboptget[string name]

uboptset[string name, Object newValue]

vitae[]

getworldname[]

getdatetimelocal[string text]

getdatetimeutc[string text]

wobjectfindnearestbytemplatetype[number templatetype]

wobjectgetintprop[WorldObject obj, number property]

wobjectgetdoubleprop[WorldObject obj, number property]

wobjectgetboolprop[WorldObject obj, number property]

wobjectgetstringprop[WorldObject obj, number property]

wobjecthasdata[WorldObject obj]

wobjectrequestdata[WorldObject obj]

getheadingto[WorldObject obj]

getheading[WorldObject obj]

acos[number d]

asin[number d]

atan[number d]

atan2[number y, number x]

cos[number d]

cosh[number d]

sin[number d]

sinh[number d]

sqrt[number d]

tan[number d]

tanh[number d]

listcreate[…items items]

listadd[List list, Object item]

listinsert[List list, Object item, number index]

listremove[List list, Object item]

listremoveat[List list, number index]

listgetitem[List list, number index]

listcontains[List list, Object item]

listindexof[List list, Object item]

listlastindexof[List list, Object item]

listcopy[List list]

listreverse[List list]

listpop[List list, number index=-1]

listcount[List list]

listclear[List list]

dictcreate[…items items]

dictgetitem[Dictionary dict, string key]

dictadditem[Dictionary dict, string key, Object value]

dicthaskey[Dictionary dict, string key]

dictremovekey[Dictionary dict, string key]

dictkeys[Dictionary dict]

dictvalues[Dictionary dict]

getgameyear[]

getgamemonth[]

getgamemonthname[number monthIndex]

getgameday[]

getgamehourname[number hourIndex]

getgamehour[]

getminutesuntilday[]

getminutesuntilnight[]

getgameticks[]

getisday[]

getisnight[]

getfellowshipstatus[]

getfellowshipname[]

getfellowshipcount[]

getfellowshipleaderid[]

getfellowid[number iterator]

getfellowname[number iterator]

getfellowshiplocked[]