Regular API function


Description Retrieves a main script's or child script's parameter from its simulation parameter list. Useful for simple interaction with the user, or for simple parameter exchange with other scripts. See also simSetScriptSimulationParameter, simUnpackInts and simUnpackFloats.
C synopsis simChar* simGetScriptSimulationParameter(simInt scriptHandle,const simChar* parameterName,simInt* parameterLength)
C parameters
scriptHandle: handle of the main script or child script, or sim_handle_main_script or sim_handle_all. When scriptHandle is sim_handle_all, the function returns only one matching parameter encountered (other matching parameters might be different)
parameterName: name of the parameter to retrieve
parameterLength: the number of bytes that compose the value of the parameter (excluding the terminal zero)
C return value
value of the parameter or NULL if parameterName does not exist for the given script, or in case of an error. The user is in charge of releasing the returned value with simReleaseBuffer. The returned pointer points to parameterLength byte values, terminated by a terminal zero (the returned buffer may however contain several embedded zeros).
Lua synopsis
(1) boolean/number/string parameterValue=simGetScriptSimulationParameter(number scriptHandle,string parameterName,boolean forceStringReturn=false)
2) table parameterValues,table scriptHandles=simGetScriptSimulationParameter(number targetScripts,string parameterName,boolean forceStringReturn=false)
Lua parameters
(1) scriptHandle: handle of the script, or sim_handle_main_script or sim_handle_self.
(2) targetScripts: sim_handle_all, sim_handle_tree or sim_handle_chain (with sim_handle_tree and sim_handle_chain the calling script is excluded).
parameterName: name of the parameter to retrieve.
forceStringReturn: forces the return of a string (i.e. raw value). False by default. If false, then the returned string will be converted to nil, false, true, a number or a string as appropriate (and in that order).
Lua return values
(1) parameterValue: value of the parameter, or nil in case of an error (or if that value is nil!).
(2) parameterValues: table of parameter values or nil if no such parameter was found or in case of an error. scriptHandles: table of script handles associated with the parameter values (i.e. parameterValue[i] comes from the script with handle scriptHandles[i]) or nil if no such parameter was found or in case of an error.

If the returned parameter value is a string, then it might contain any values (also embedded zeros)

All regular API functions on one page