From a6d7fd2c982ae97ba19b4f56ee8d414307212ebc Mon Sep 17 00:00:00 2001 From: Redo Date: Wed, 1 Oct 2025 20:36:03 -0700 Subject: [PATCH] improve readme, rename :iterate to :members --- readme.md | 43 +++++++++++++++++++++---------------------- src/util/libbl.lua | 8 ++++---- 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/readme.md b/readme.md index e386739..0b92e27 100644 --- a/readme.md +++ b/readme.md @@ -12,7 +12,7 @@ `'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 +`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 @@ -31,33 +31,33 @@ `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 +`for childIndex, child in object:members() do` - Iterate objects within of a Torque set or group. Indices start at 0 like in Torque. ### 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 +`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 +`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 +`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. +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` @@ -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 ## 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. +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. diff --git a/src/util/libbl.lua b/src/util/libbl.lua index 12aef27..4670399 100644 --- a/src/util/libbl.lua +++ b/src/util/libbl.lua @@ -306,10 +306,10 @@ local tsObjectMeta = { error('ts object __len: object has no getCount method', 2) end return tonumber(_bllua_ts.callobj(t._tsObjectId, 'getCount')) end, - -- object:iterate() + -- object:members() -- Return an iterator for Torque objects with the getCount and getObject methods - -- for index, object in group:iterate() do ... end - iterate = function(t) + -- for index, object in group:members() do ... end + members = function(t) if t==nil then error('ts object method: be sure to use :func() not .func()', 2) end if t._deleted then @@ -317,7 +317,7 @@ local tsObjectMeta = { if not ( tsIsFunctionNs(t._tsNamespace, 'getCount' ) and tsIsFunctionNs(t._tsNamespace, 'getObject')) then - error('ts object :iterate() - '.. + error('ts object :members() - '.. 'Object does not have getCount and getObject methods', 2) end local count = tonumber(_bllua_ts.callobj(t._tsObjectId, 'getCount')) local idx = 0