functNameAtPluginName: 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 simXX. prefix (e.g. simMyPlugin.myCustomFunction) 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 simExtMyPlugin.dll, this should be MyPlugin).
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 nullptr, in which case no call tips will be displayed, nor syntax highlighting used.
callback: callback address that is called when the "functName" function is called from Lua. Can be nullptr, in which case the command will only register the function for call tips and syntax highlighting. See further down for a simple way to call above function, using a helper class. The callback's first argument is a SScriptCallBack 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
simInt scriptID: handle of the calling script
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.
simChar* raiseErrorWithMessage: max. 256 bytes are available here for an error message. This buffer is allocated by CoppeliaSim and initially contains a zero length string. If the length of the string is not zero, a script error will be raised and the message displayed in the status bar.
|
