BlockLua

How to Install

• Install RedBlocklandLoader
• Copy BlockLua.dll and lua5.1.dll into the modules folder next to Blockland.exe
• Optional: Copy the lualib folder into modules

Quick Reference

From TorqueScript

'print('hello world') - Execute Lua code in the console by prepending a ' (single quote)
luaeval("code"); - Eval Lua code
luacall("funcName", %args); - Call a Lua global function
luaexec("fileName"); - Execute a Lua file
luaget("varName"); - Read a Lua global variable
luaset("varName"); - Write a Lua global variable

From Lua

bl.eval('code') - Eval TorqueScript code
bl.funcName(args) - Call a TorqueScript function
bl.varName - Read a TorqueScript global variable
bl['varName'] - Read a TorqueScript global variable (i.e. with special characters in the name, or from an array)
bl.set('varName', value) - Write a TorqueScript global variable

Accessing Torque Objects from Lua

bl.objectName - Access a Torque object by name
bl[objectID] - Access a Torque object by ID (or name)
object.fieldOrKey - Read a field or Lua key from a Torque object
object:set('field', value) - Write a field on a Torque object
object.key = value - Associate Lua data with a Torque object
object:method(args) - Call a Torque object method
object[index] - Access a member of a Torque set or group
for obj in object:iterate() do - Iterate members of a Torque set or group

Advanced

bl.schedule(function, args...) - Schedule a Lua function to be called later bl.raycast(vector{startPosX,y,z}, vector{endPosX,y,z}, 'typeMask'/{'typeMasks',...}, ignoreObject...?) - Same as containerRaycast in Torque. typeMasks are 'player', 'brick', etc for object in bl.boxSearch(vector{centerX,y,z}, vector{sizeX,y,z}, 'typeMask'/{'typeMasks',...}) do - Similar to containerBoxSearch, used as an iterator for object in bl.radiusSearch(vector{centerX,y,z}, radius, 'typeMask'/{'typeMasks',...}) do - Similar to containerBoxSearch, used as an iterator bl.servercmd('commandName', function(client, args...) code() end) - Register a /-command on the server bl.clientcmd('commandName', function(args...) code() end) - Register a client command on the client

Packages/Hooks

bl.hook('packageName', 'functionName', 'before'/'after'/'override', function(args...) code() end) - Hook a Torque function with a Lua function bl.unhook('packageName', 'functionName', 'before'/'after'/'override') - Remove a previously defined hook

Classes and Types

bl.bool(thing) - Convert a Torque boolean (0 or 1) into a Lua boolean. Done automatically for all built-in functions that return bools. bl.object(thing) - Convert a Torque object reference (object ID or name) into a Lua object. Done automatically for all built-in functions that return objects. bl.type('varName', 'type') - Register the type of a Torque global variable, for conversion when accessing from Lua. Valid types are 'bool', 'object', and nil - all other conversion is automatic. bl.type('funcName', 'type') - Register the return type of a Torque function, for conversion when calling from Lua. Valid types are 'bool', 'object', and nil - all other conversion is automatic. Already done for all built-in functions that return objects. bl.type('className::funcName', 'type') - Register the return type of a Torque object method. bl.class('className') - Register a Torque class to be used from Lua (Already done for all built-in classes) bl.class('className', 'parentClassName') - Same as above, with inheritance

Type Conversion

When a TorqueScript function is called from Lua or vice-versa, the arguments and return value must be converted between the two languages' type systems. TorqueScript has no type information; all values in TorqueScript are strings.
So, it's necessary to make some inferences when converting values between the two languages.

From TorqueScript to Lua

• Any numeric value becomes a Lua number, except as specified with ts.type, which may convert a value into a boolean or a Torque object container.
• The empty string "" becomes nil
• A string containing three numbers separated by spaces becomes a vector
• A string containing six numbers separated by spaces becomes a table of two vectors
• Any other string is passed directly as a string

From Lua to TorqueScript

• nil becomes the empty string ""
• true and false become "1" and "0" respectively
• Torque containers become their object ID
• A vector becomes a string containing three numbers separated by spaces
• A table of two vectors becomes a string containing six numbers separated by spaces
• Any string is passed directly as a string
• Tables cannot be passed and will throw an error

Unsafe Mode

BlockLua-Unsafe.dll can be used in place of BlockLua.dll, to remove the sandboxing of Lua code.
This allows Lua code to access any file and use any library, including ffi.