WildStar:UI Lua

Reference e
AddOns UI API UI Form UI XML UI Event WS Lua UI Macro CVars Changes Guides Snippets Categories

→ WildStar Lua

← [[WildStar Lua]]

This is the main reference for the WildStar Lua runtime, as implemented in the WildStar UI. See also UI API.

The WildStar Lua runtime is based on Lua 5.1, and generally uses the same standard Lua functions listed on the official Lua web site. Some functions differ slightly in WildStar's implementation and are documented here as well for consistency.

Reference

Nearly all of these functions are part of the default Lua 5.1 runtime environment, described here. Notable omissions are the operating system, and file I/O libraries.

/eval Print(_VERSION)
[debug]: Lua 5.1

Basic

assert(val[, sMsg]) returns (val) - returns val if true, else throws Lua error with sMsg

collectgarbage() - forces garbage collection

dofile([filename]) - opens the named file and executes its contents as a Lua chunk (stdio not usable in UI)

error(sMsg, level) - throws error with message. use pcall() to catch errors

gcinfo() returns (nAddOn,nLimit) - gets AddOn memory used and current GC threshold in kB

getfenv(any) returns (table) - gets stack frame of given function or stack level number

getmetatable(aObject) returns (mtable) - gets metatable for table or userdata

load(func [, chunkname]) returns (function) - gets Lua chunk from func stream, until empty, nil, no value

loadfile([filename]) returns (function) - similar to load, but gets from file (stdio not usable in UI)

loadstring(string [, chunkname]) returns (function) - gets Lua chunk for a Lua code string

newproxy(boolean or proxy) - creates a userdata with a sharable metatable

next(table, index) returns (key,value) - gets next key-value pair of the table, allowing you to walk a table

pcall(func, arg1, arg2, ...) returns (boolean, results or sMessage) - executes 'func' and returns true and values, otherwise false and error message

print(string) - prints to Lua stdio (stdio not usable from UI)

rawequal(v1, v2) returns (boolean) - checks if v1 and v2 are equal, bypassing any metamethods

rawget(table, index) - gets real value of table[index], bypassing any metamethods

rawset(table, index, value) - sets real table[index] to value, bypassing any metamethods

select(nIndex, list) returns (number or item) - gets count if 'index' is "#", or item at 'index'

setfenv(function or integer, table) - sets table representing the stack frame for given function or stack level

setmetatable(aObject, mtable) returns (any) - sets the metatable of a table or userdata, returns aObject

type(any) - gets type of variable as a string: "number", "string", "table", "function" or "userdata"

unpack(table[, nStart][, nEnd]) returns (...) - converts indexed values of table to an argument list

xpcall(function, fCallback) returns (boolean,results) - true if successfully executes function, or executes fCallback and returns false. results are return values of function or fCallback

WS UI offers these standard Lua global data vars

_G [table] - canonical list of variables in global scope, including ones in this reference

_VERSION [string] = "Lua 5.1" - printable Lua runtime version number

Strings

These string functions are Carbine custom, shorthand references to or a part of the Lua string library "string." See StringLibraryTutorial for more info.

tonumber(any[, base]) returns (number) - converts any. nil if fails. non-10 bases accept only unsigned ints

tostring(any) - converts to a string, or nil if fails.

These are custom string functions available in WS but not normal Lua.

strRound(any[, nPlaces]) returns (number) - converts to number and rounds, default places 0. (Carbine)

string

.byte(string[, index]) - gets internal Lua char (byte size number) of the i-th element of string

.char(nByte[, ...]) - compiles one or more Lua chars (byte size numbers) into a string

.dump(function) - returns a binary representation of the given function code as a string

.find(s, pattern[, start[, plain]]) - find match for pattern on s. optional offset or plain sub-string

.format(sFormat[, value[, ...]]) - gets string of values formatted by sFormat format string

.gfind(s, pattern) returns iterator function for pattern over the string s. (deprecated, same as gmatch)

.gmatch(s, pattern) gets iterator that returns the next captures each call, using pattern on string s

.gsub(s, pattern, replacement[, nLimit]) - globally substitute pattern for replacement in string

.len(string) - return length of the string in Lua chars (byte size numbers)

.lower(string) - return string converted to all lower case

.match(string, pattern[, initpos]) - similar to strfind, but only returns the matches, not the positions

.rep(string, n [, sep]) - return a string which is n copies of s, with optional delimeter sep

.reverse(string) - reverses a string

.sub(string, index[, endIndex]) - return a substring of string starting at index

.upper(string) - return string converted to all upper case

Tables

These table functions are shorthand references to the Lua table library (which is available via "table.", see TableLibraryTutorial for more info). Be aware that some table functions only work with tables with proper numerical indexes, where {[1] = "x", [3] = "y"} would have only one indexed value at 1. Not being aware of this fact is one major causes for bugs in code written in Lua.

ipairs(table) - gets an iterator of type integer to traverse a table

pairs(table) - gets an iterator to traverse a table

table

.concat(table [, sep [, i [, j]]]) returns (string) - build a string from table elements

.foreach(table, function) - runs function for each name-value in table. (deprecated, use pairs)

.foreachi(table, function) - runs function for each index in table, in order. (deprecated, use ipairs)

.getn(table) returns (number) - gets cached size of table array values. (deprecated, use #table operator)

.insert(table[, pos], value) - insert value into table at pos. default is end of table

.maxn(table) returns (number) - last positive numerical index. requires scan of whole table

.remove(table[, pos]) returns (any) - remove and return element at pos. default is last entry in table

.setn(table, number) - attempts to set cached table size value. (deprecated, like getn)

.sort(table[, comp]) - sort the elements in the table in-place, optionally using a custom comparator.

Arithmetic

math

.abs(value) - returns the absolute value of the number

.acos(value) - returns the arc cosine of the value in degrees

.asin(value) - returns the arc sine of the value in degrees

.atan(value) - returns the arc tangent of the value in degrees

.atan2(y, x) - returns the arc tangent of Y/X in degrees

.ceil(value) - returns the ceiling of value

.cos(degrees) - returns the cosine of the degree value

.cosh(value) - returns the hyperbolic cosine of value

.deg(radians) - returns the degree equivalent of the radian value

.exp(value) - returns the exponent of value

.floor(value) - returns the floor of value

.fmod(x, y) - returns remainder of division of x by y, rounding quotient toward zero

.frexp(num) - Extract mantissa and exponent from a floating point number

.huge = 1.#INF

.ldexp(value, exponent) - Load exponent of a floating point number

.log(value) - returns the natural logarithm (log base e) of value

.log10(value) - returns the base-10 logarithm of value

.max(value[, values...]) - returns the numeric maximum of the input values

.min(value[,values...]) - returns the numeric minimum of the input values

.mod(a, b) - returns the integer remainder of a divided by b

.modf(x) - returns two numbers. integral part of x, and fractional part of x

.pi = 3.1415926535898

.pow(x, y) - returns x to power of y. can also use operator ^, as expression x^y

.rad(degrees) - returns the radian equivalent of the degree value

.random([ [lower,] upper]) - returns a random number, optionally bounded integer value

.randomseed(x) - sets x "seed" for random generator. seed always makes same sequence

.sin(degrees) - returns the sine of the degree value

.sinh(value) - returns the hyperbolic sine of value

.sqrt(x) - returns the square root of x

.tan(degrees) - returns the tangent of the degrees value

.tanh(x) - returns the hyperbolic tangent of x

Bitwise

WildStar includes the Lua BitLib library, which is available via "bit32." table, which provides access to C-style bitwise manipulation operators. This library uses the 32-bit integer size, e.g. bit32.lshift(2147483648, 1) = 0, because 1000 0000 0000 0000 0000 0000 0000 0000 -> 0000 0000 0000 0000 0000 0000 0000 0000.

bit32

.arshift(a, b) - returns a shifted arithmetically right b places

.band(w1, ...) - returns the bitwise and of the w's

.bnot(a) - returns the one's complement of a

.bor(w1, ...) - returns the bitwise or of the w's

.btest(···) returns (boolean) - true if bitwise and of all operands is not zero

.bxor(w1, ...) - returns the bitwise exclusive or of the w's

.extract(n, start[, width]) - gets set of bits from n. start is 0-31. default width is 1

.lrotate(x, disp) - returns x rotated left disp places

.lshift(a, b) - returns a shifted left b places

.replace(n, v, start [, width]) - gets copy n with bits set from value v. start is 0-31. default width is 1

.rrotate(x, disp) - returns x rotated right disp places

.rshift(a, b) - returns a shifted logically right b places

System

The system functions whaich are generally just a subset of the Lua standard os library. Alternatively the {{../api||Apollo}} and {{../api|GameLib}} libraries offer standard WS UI date and time functions, like {{../api||GameLib|GetLocalTime}}, {{../api||GameLib|GetServerTime}} and {{../api||Apollo|GetTickCount}}.

os

clock() - returns an approximation in seconds of CPU time used by the program

difftime(t2, t1) - returns diff in seconds between t1 and t2. in Windows and others is exactly t2-t1

time([table]) returns (number) - current machine time, or from date table, in secs since 00:00 Jan 1 1970

date([format[, time]]) returns (table or string) - gets table or format string, of current or time date

Debugging

The debugging functions which are generally just a subset of the Lua stardard debug library.

debug

.debug() enters an interactive mode with the user (not useable from UI)

.gethook([thread]) - gets thread's hook settings: function, mask, count

.getinfo([thread,] f [, what]) - gets table of information about a function f as: nups, what, func, lastlinedefined, source, currentline, namewhat, linedefined, short_src

.getlocal([thread,] nLevel, nLocal) - gets name and value of the variable at nLocal in stack nLevel

.getmetatable(obj) returns (mtable) - gets metatable for table or userdata (same as _G.getmetatable)

.getregistry() - returns the registry table (not useable from UI)

.getupvalue(f, nUp) - gets name, value of upvalue nUp of function f. nil if no upvalue

.sethook([thread,] f, sMask [, count]) - sets function f as to be called for event sMask

.setlocal([thread,] nLevel, nLocal, value) - assigns value to nLocal at stack nLevel. gets name, or nil if no nLocal. throws if no nLevel

.setmetatable(obj, mtable) returns (obj) - sets metatable for table or userdata (same as _G.setmetatable)

.setupvalue(f, nUp, value) - assigns value to upvalue nUp of function f. gets name or nil if no upvalue

.traceback([thread,] [sMessage [, nLevel]]) - gets string with a trace of call stack, starting at nLevel.

References added to debug. in WildStar

.getfenv(any) returns (table) - stack frame of given function or stack level (same as _G.getfenv)

.setfenv(function or nLevel, table) - sets table for stack frame for func or level (same as _G.setfenv)

Modules

The modules functions which are generally just a subset of the Lua stardard package library. Other than using the require keyword to access standard Carbine WS modules, the Apollo library should be used instead for AddOns and Lua libraries, like Apollo.RegisterAddon and Apollo.RegisterPackage.

module(name [, ···]) - sets this Lua chunk as named Lua module, in package.loaded[name] and _G[name]

require(modname) - loads a module as reference in this Lua chunk, from package.loaded[name] or loader

package

.config [string] = "\\\n;\n?\n!\n-" - list of chunk string seperators (undocumented)

.cpath [string] = ".\?.dll;!\?.dll;!\loadall.dll" - require path for C loader

.loaded [table] - table used by require for modules are already loaded

.loaders [table] - table used by require for how to load modules

.loadlib(libname, sFunc) - loads and links a C Lua library

.path [string] = ".\?.lua;!\lua\?.lua;!\lua\?\init.lua;!\?.lua;!\?\init.lua" - require path for Lua loader

.preload [table] - table to store loaders for specific modules

.seeall(module) - sets metatable on module so inherits from global environment. option to module()

See also

• Lua - which has plenty of links to other reference material
• API types - with a list of Lua types and 'psudo-types' used in WS