redo/BlockLua
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

improve readme, rename :iterate to :members

Browse Source
This commit is contained in:
Redo
2025-10-01 20:36:03 -07:00
parent b5dc7988f5
commit a6d7fd2c98
2 changed files with 25 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
readme.md
View File

@@ -12,7 +12,7 @@
`'print('hello world')` - Execute Lua code in the console by prepending a `'` (single quote) `'print('hello world')` - Execute Lua code in the console by prepending a `'` (single quote)
`luaeval("code");` - Eval Lua code `luaeval("code");` - Eval Lua code
`luacall("funcName", %args);` - Call a Lua global function `luacall("funcName", %args);` - Call a Lua global function
`luaexec("fileName");` - Execute a Lua file `luaexec("fileName");` - Execute a Lua file. Path rules are the same as executing .cs files.
`luaget("varName");` - Read a Lua global variable `luaget("varName");` - Read a Lua global variable
`luaset("varName");` - Write a Lua global variable `luaset("varName");` - Write a Lua global variable
@@ -31,33 +31,33 @@
`object.key = value` - Associate Lua data with a Torque object `object.key = value` - Associate Lua data with a Torque object
`object:method(args)` - Call a Torque object method `object:method(args)` - Call a Torque object method
`object[index]` - Access a member of a Torque set or group `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 `for childIndex, child in object:members() do` - Iterate objects within of a Torque set or group. Indices start at 0 like in Torque.
### Advanced ### Advanced
`bl.schedule(function, args...)` - Schedule a Lua function to be called later `sched = bl.schedule(timeMs, function, args...)` - Schedule a Lua function to be called later, similar to schedule in Torque
`bl.raycast(vector{startPosX,y,z}, vector{endPosX,y,z}, 'typeMask'/{'typeMasks',...}, ignoreObject...?)` - Same as containerRaycast in Torque. typeMasks are 'player', 'brick', etc `sched:cancel()` - Cancel a previously scheduled timer
`for object in bl.boxSearch(vector{centerX,y,z}, vector{sizeX,y,z}, 'typeMask'/{'typeMasks',...}) do` - Similar to containerBoxSearch, used as an iterator `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.radiusSearch(vector{centerX,y,z}, radius, 'typeMask'/{'typeMasks',...}) do` - Similar to containerBoxSearch, used as an iterator `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
`bl.servercmd('commandName', function(client, args...) code() end)` - Register a /-command on the server `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.clientcmd('commandName', function(args...) code() end)` - Register a client command on the client `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 ### Packages/Hooks
`bl.hook('packageName', 'functionName', 'before'/'after'/'override', function(args...) code() end)` - Hook a Torque function with a Lua function `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 `bl.unhook('packageName', 'functionName', 'before'/'after'/'override')` - Remove a previously defined hook
### Classes and Types ### 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.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.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('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('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.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')` - 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 `bl.class('className', 'parentClassName')` - Same as above, with inheritance
## Type Conversion ## 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. 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. 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.
So, it's necessary to make some inferences when converting values between the two languages.
### From TorqueScript to Lua ### 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. - 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` - The empty string "" becomes `nil`
@@ -74,5 +74,4 @@ So, it's necessary to make some inferences when converting values between the tw
- Tables cannot be passed and will throw an error - Tables cannot be passed and will throw an error
## Unsafe Mode ## Unsafe Mode
BlockLua-Unsafe.dll can be used in place of BlockLua.dll, to remove the sandboxing of Lua code. 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.
This allows Lua code to access any file and use any library, including ffi.

8
src/util/libbl.lua
View File

@@ -306,10 +306,10 @@ local tsObjectMeta = {
error('ts object __len: object has no getCount method', 2) end error('ts object __len: object has no getCount method', 2) end
return tonumber(_bllua_ts.callobj(t._tsObjectId, 'getCount')) return tonumber(_bllua_ts.callobj(t._tsObjectId, 'getCount'))
end, end,
-- object:iterate() -- object:members()
-- Return an iterator for Torque objects with the getCount and getObject methods -- Return an iterator for Torque objects with the getCount and getObject methods
-- for index, object in group:iterate() do ... end -- for index, object in group:members() do ... end
iterate = function(t) members = function(t)
if t==nil then if t==nil then
error('ts object method: be sure to use :func() not .func()', 2) end error('ts object method: be sure to use :func() not .func()', 2) end
if t._deleted then if t._deleted then
@@ -317,7 +317,7 @@ local tsObjectMeta = {
if not ( if not (
tsIsFunctionNs(t._tsNamespace, 'getCount' ) and tsIsFunctionNs(t._tsNamespace, 'getCount' ) and
tsIsFunctionNs(t._tsNamespace, 'getObject')) then tsIsFunctionNs(t._tsNamespace, 'getObject')) then
error('ts object :iterate() - '.. error('ts object :members() - '..
'Object does not have getCount and getObject methods', 2) end 'Object does not have getCount and getObject methods', 2) end
local count = tonumber(_bllua_ts.callobj(t._tsObjectId, 'getCount')) local count = tonumber(_bllua_ts.callobj(t._tsObjectId, 'getCount'))
local idx = 0 local idx = 0