Regular API function

simRegisterCustomLuaFunction (DEPRECATED)

Description This function is deprecated. Use simRegisterScriptCallbackFunction instead.

Registers a customized lua function. This function is useful for plugins (or the main client application) that wish to provide their own or customized Lua functions. See also simRegisterScriptVariable.
C synopsis simInt simRegisterCustomLuaFunction(const simChar* funcName,const simChar* callTips,const simInt* inputArgumentTypes,simVoid(*callBack)(struct SLuaCallBack* p))
C parameters
functName: name of the function, combined with the plugin name: functionName@pluginName. Avoid using too simple function names, otherwise they might clash with other plugins. Also, always use the simExt prefix (e.g. simExtMyCustomFunction) for the function name. The plugin name should be the exact same name used while loading the plugin via simLoadModule (if the plugin name is v_repExtMyPlugin.dll, this should be MyPlugin). If the @pluginName is omitted, unloading the plugin dynamically might lead to a crash.
callTips: call tips: string (or several strings separated by '@') that indicates the input/output argument type/size. Call tips appear in the script editor when the function was typed followed by "(". callTips Can be NULL
inputArgumentTypes: array indicating the desired input arguments. This is important so that the simulator knows how to convert between Lua types (e.g. Lua value"4.2" can be converted to int 4, to float 4.2, to string "4.2" or to Boolean 1). Can be NULL, in that case no input argument is forwarded to the callback address. inputArgumentTypes[0] represents the number of input arguments we wish to be forwarded, inputArgumentTypes[1] is the type of the first argument, inputArgumentTypes[2] is the type of the second argument, etc. An input argument type can be sim_lua_arg_bool, sim_lua_arg_int, sim_lua_arg_float, sim_lua_arg_string or sim_lua_arg_charbuff, that can be combined (|) with sim_lua_arg_table if table values are desired. And exception to this is sim_lua_arg_charbuff, which cannot be combined with sim_lua_arg_table.
callback: callback address that is called when the "functName" function is called from Lua with the right arguments. See further down for a simple way to call above function, using a helper class. The callback's first argument is a SLuaCallBack structure that holds:

simInt objectID: handle of the object that the calling script is attached to, or -1 if the calling script is not a child script
simChar* inputBool: pointer to all Boolean input arguments
simInt* inputInt: pointer to all integer input arguments
simFloat* inputFloat: pointer to all single precision floating point input arguments
simDouble* inputDouble: pointer to all double precision floating point input arguments
simChar* inputChar: pointer to all string input arguments. Strings are separated by the "zero-char"
simChar* inputCharBuff: pointer to all char buffer input arguments.
simInt inputArgCount: number of input arguments.
simInt* inputArgTypeAndSize: pointer to input argument's type and size (e.g. with "inputArgCount==2" we could have "inputArgTypeAndSize[0]==sim_lua_arg_int|sim_lua_arg_table", "inputArgTypeAndSize[1]==3", "inputArgTypeAndSize[2]==sim_lua_arg_char", "inputArgTypeAndSize[3]==1". This would mean that we have two input arguments: (1) an integer table of size 3 and (2) a string)
simChar* outputBool: similar to inputBool, but for output values. The user is in charge of allocating the buffer with correct size with simCreateBuffer (outputBool=new char[n] will not work!!). The simulator will automatically release the buffer when the callback returns.
simInt* outputInt: similar to inputInt, but for output values. The user is in charge of allocating the buffer with correct size with simCreateBuffer (outputInt=new int[n] will not work!!). The simulator will automatically release the buffer when the callback returns.
simFloat* outputFloat: similar to inputFloat, but for output values. The user is in charge of allocating the buffer with correct size with simCreateBuffer (outputFloat=new float[n] will not work!!). The simulator will automatically release the buffer when the callback returns.
simFloat* outputDouble: similar to inputDouble, but for output values. The user is in charge of allocating the buffer with correct size with simCreateBuffer (outputDouble=new double[n] will not work!!). The simulator will automatically release the buffer when the callback returns.
simChar* outputChar: similar to inputChar, but for output values. The user is in charge of allocating the buffer with correct size with simCreateBuffer (outputChar=new char[n] will not work!!). The simulator will automatically release the buffer when the callback returns. If you return 2 strings "ab" and "cde", the buffer should look like: "ab@cde@" (@ being the zero char).
simChar* outputCharBuff: similar to inputCharBuff, but for output values. The user is in charge of allocating the buffer with correct size with simCreateBuffer (outputCharBuff=new char[n] will not work!!). The simulator will automatically release the buffer when the callback returns. If you return 2 char buffers, they should lay appended to each other in this buffer.
simInt outputArgCount: similar to inputArgCount, but for output values
simInt* outputArgTypeAndSize: similar to inputArgTypeAndSize, but for output values. The user is in charge of allocating the buffer with correct size with simCreateBuffer (outputArgTypeAndSize=new int[n] will not work!!). The simulator will automatically release the buffer when the callback returns.

Values are stored in input or output arrays in the order they appear as arguments or return values e.g. with input arguments: number_int 1,table_2_float {2.0,3.0},string 'hello',number_int 4,string 'bye' we would have following input arrays:

inputBool==NULL
inputInt=={1,4}
inputFloat=={2.0,3.0}
inputChar=="hello@bye@"
inputArgCount==5
inputArgTypeAndSize=={sim_lua_arg_int,1,sim_lua_arg_float|sim_lua_arg_table,
            2,sim_lua_arg_string,1, sim_lua_arg_int,1, sim_lua_arg_string,1}
simChar waitUntilZero: this value can be used when threaded scripts call a custom Lua function in a plugin that shouldn't return until a condition is met (e.g. until the robot movement finished). For that purpose, the plugin should write a value different from zero to indicate a "wait" state. When the callback returns, the control is not given back to the script until some other thread calling the plugin writes zero to that location. Once zero was written, the memory location should not be used anymore (because it might be released anytime by the simulator). Also, when the user stops a simulation before zero was written to that location, the wait state is aborted. In that case however the memory location stays valid (i.e. writing zero will not result in a crash) until the simulation ended.

Reading and writing arguments from/to the SLuaCallBack structure can be quite complicated and is error prone. Use instead the helper classes CLuaFunctionData and CLuaFunctionDataItem located in programming/common and programming/include: they will greatly simplify the task. Make sure to also have a look at the various plugin projects (in the programming folder) and the plugin tutorial to get an idea how to register custom Lua commands.

Use following 4 functions in the helper class: readDataFromLua, getInDataPtr, pushOutData and writeDataToLua.
C return value
1 if function was registered, 0 if function was replaced (when that function name already existed), -1 in case of an error
Lua synopsis -
Lua parameters
-
Lua return values
-

All regular API functions on one page