WildStar:UI Lua

Template:Wslua 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 Apollo and GameLib libraries offer standard WS UI date and time functions, like GameLib, GameLib and Apollo.

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 and Apollo.

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