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. Path rules are the same as executing .cs files.
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 childIndex, child in object:members() do - Iterate objects within of a Torque set or group. Indices start at 0 like in Torque.

Advanced

sched = bl.schedule(timeMs, function, args...) - Schedule a Lua function to be called later, similar to schedule in Torque
sched:cancel() - Cancel a previously scheduled timer
hitObject, hisPos, hitNormal = bl.raycast(vector{startPosX,y,z}, vector{endPosX,y,z}, 'typeMask'/{'typeMasks',...}, ignoreObject...?) - Cast a ray in the world over objects of the specified type(s) (possibly excluding some objects), and return the object hit, the position of the hit, and the normal vector to the surface hit. for object in bl.boxSearch(vector{centerX,y,z}, vector{sizeX,y,z}, 'typeMask'/{'typeMasks',...}) do - Find all objects in the world of the specified type(s) whose bounding box overlaps with a specific box
for object in bl.radiusSearch(vector{centerX,y,z}, radius, 'typeMask'/{'typeMasks',...}) do - Find all objects of the specified type(s) whose bounding box overlaps with a specified sphere
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.

5.3 KiB Raw Blame History