From de9992aa2c0334836443eadfa6715684ada929f2 Mon Sep 17 00:00:00 2001 From: Redo Date: Wed, 1 Oct 2025 21:28:39 -0700 Subject: [PATCH] add i/o to readme --- readme.md | 55 +++++++++++++++++++++++++++++++++++++++------- src/util/libts.lua | 6 ++++- 2 files changed, 52 insertions(+), 9 deletions(-) diff --git a/readme.md b/readme.md index 0b92e27..ceea7f1 100644 --- a/readme.md +++ b/readme.md @@ -1,9 +1,10 @@ # 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` +- Install RedBlocklandLoader +- Copy `lua5.1.dll` into your Blockland install folder, next to `Blockland.exe` +- Copy `BlockLua.dll` into the `modules` folder within the Blockland folder +- Optional: Copy the `lualib` folder into `modules` ## Quick Reference @@ -36,9 +37,9 @@ ### 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 +`hitObject, hisPos, hitNormal = bl.raycast(vector{startPosX,y,z}, vector{endPosX,y,z}, 'objtype'/{'objtypes',...}, ignoreObjects...?)` - 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. See the Types section for a list of valid object types. +`for object in bl.boxSearch(vector{centerX,y,z}, vector{sizeX,y,z}, 'objtype'/{'objtypes',...}) do` - Find all objects in the world of the specified type(s) whose bounding box overlaps with the specified box. See the Types section for a list of valid object types. +`for object in bl.radiusSearch(vector{centerX,y,z}, radius, 'objtype'/{'objtypes',...}) do` - Find all objects of the specified type(s) whose bounding box overlaps with the specified sphere. See the Types section for a list of valid object types. `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 @@ -55,9 +56,31 @@ `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 +### File I/O +Lua's builtin file I/O is emulated, and is confined to the same directories as TorqueScript file I/O. +Relative paths (`./`) are allowed. `..` is not allowed. +`file = io.open('./file.txt', 'r'/'w'/'a'/'rb'/'wb'/'ab')` - Open a file +`file:read(numberOfChars/'*a')` - Read an opened file (must be opened in 'r' (read) or 'rb' (read binary) mode) +`file:write(string)` - Write an opened file (must be opened in 'w' (write), 'a' (append), 'wb' or 'ab' mode) +`file:close()` - Close an opened file +Reading files from ZIPs is supported, with caveats. Null characters are not allowed, and \r\n becomes \n. Generally, text formats work, and binary formats don't. + +### Modules and Dependencies +`dofile('Add-Ons/Path/file.lua')` - Execute a Lua file. Relative paths (`./file.lua`) are allowed. `..` is not allowed. +`require('modulePath.moduleName')` - Load a Lua file or or external library. +Require replaces `.` with `/` in the path, and then searches for files in the following order: +- `./modulePath/moduleName.lua` +- `./modulePath/moduleName/init.lua` +- `modulePath/moduleName.lua` (Relative to game directory) +- `modulePath/moduleName/init.lua` (Relative to game directory) +- `modules/lualib/modulePath/moduleName.lua` +- `modules/lualib/modulePath/moduleName/init.lua` +- `modules/lualib/modulePath/moduleName.dll` +Like in standard Lua, modules loaded using `require` are only executed the first time `require` is called with that path. Subsequent calls simply return the result from the initial execution. To allow hot reloading, use `dofile`. + ## 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. +TorqueScript stores 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` @@ -73,5 +96,21 @@ TorqueScript has no type information; all values in TorqueScript are strings. So - Any `string` is passed directly as a string - Tables cannot be passed and will throw an error -## Unsafe Mode +## I/O and Safety +All Lua code is sandboxed, and file access is confied to the default directories in the same way TorqueScript is. +BlockLua also has access to any C libraries installed in the `modules/lualib` folder, so be careful throwing things in there. +### 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. +Please do not publish add-ons that require unsafe mode. + +## Other Reference + +### List of Object Types +'all' - Any object +'brick' - Bricks with Ray-Casting enabled +'brickalways' - All bricks including those with Ray-Casting disabled +'player' - Players or bots +'item' - Items +'vehicle' - Vehicles +'projectile' - Projectiles +Other types: 'static', 'environment', 'terrain', 'water', 'trigger', 'marker', 'gamebase', 'shapebase', 'camera', 'staticshape', 'vehicleblocker', 'explosion', 'corpse', 'debris', 'physicalzone', 'staticts', 'staticrendered', 'damagableitem' diff --git a/src/util/libts.lua b/src/util/libts.lua index 5b2daa9..2f00ce2 100644 --- a/src/util/libts.lua +++ b/src/util/libts.lua @@ -166,7 +166,9 @@ local function file_exists(fn, errn) return nil end end +local require_memo = {} function require(mod) + if require_memo[mod] then return unpack(require_memo[mod]) end local fp = mod:gsub('%.', '/') local fns = { './'..fp..'.lua', -- local file @@ -182,7 +184,9 @@ function require(mod) for _,fn in ipairs(fns) do local fne = file_exists(fn, 2) if fne then - return dofile(fne, 2) + local res = {dofile(fne, 2)} + require_memo[mod] = res + return unpack(res) end end return _bllua_requiresecure(mod)