make readme more comprehensive

readme.md

@@ -10,27 +10,69 @@
 
 ### From TorqueScript
 `'print('hello world')` - Execute Lua code in the console by prepending a `'` (single quote)  
-`luaeval("code");` - Eval Lua code from Torque  
+`luaeval("code");` - Eval Lua code  
-`luacall("funcName", %args);` - Eval Lua code from Torque  
+`luacall("funcName", %args);` - Call a Lua global function  
-`luaexec("fileName");` - Execute a Lua file from Torque  
+`luaexec("fileName");` - Execute a Lua file  
-`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  
 
 ### 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 (with special characters in the name, or from an array)  
+`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)  
-`bl.objectName.field` - Read a field or Lua key from a Torque object  
+`object.fieldOrKey` - Read a field or Lua key from a Torque object  
-`bl.objectName:set('field', value)` - Write a field on a Torque object  
+`object:set('field', value)` - Write a field on a Torque object  
-`bl.objectName.key = value` - Associate Lua data with a Torque object  
+`object.key = value` - Associate Lua data with a Torque object  
-`bl.objectName: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  
+`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
 
-### Unsafe Mode
+### 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.