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.

4.9 KiB Raw Blame History