User parameters

Each object that is also associated with a script can have user parameters attached. Those parameters can be used as a quick way of adjusting values of a specific model for example (e.g. the maximum velocity of a mobile robot or the resolution of a sensor). When enabled, a user parameter icon will display next to the script icon in the scene hierarchy:

[User parameter icon]

Double-clicking the icon opens the user parameter dialog:

[User parameter dialog]

If the user modifies a value in the parameter list, scripts can react to that modification and adjust their behavior accordingly. A script can use the sim.getUserParameter function to retrieve the value of a parameter, or the sim.setUserParameter function to modify the value of a parameter. When the user parameter list for an object is empty, the user parameter icon won't show. To enable it for a specific object, just type sim.setUserParameter(objectHandle,'@enable',''), and make sure the object is associated with a script.

Following are the items in the user parameter dialog:

  • Add new parameter: adds a new parameter to the list.
  • User parameters: list of parameters. Individual parameters can be renamed with a double-click, and their values modified.
  • Value: string value of the parameter. The string can contain any value, including embedded zeros.
  • Unit: the unit of the value (if applicable). The unit is merely intended to inform the user.
  • Parameter is private: if enabled, then the selected parameter is not shown during a simulation (in that case the parameter is probably not meant to be modified during a simulation).
  • Parameter is persistent: if enabled, then the selected parameter will not be restored to its original value at simulation end.
  • User parameters represent a simple way to adjust specific values via a dialog. A more flexible behaviour can be achieved by using user config callback functions: if such a callback function is defined in a customization script attached to an object, then double-clicking the user parameter icon will instead call that callback function, where the user can prepare a more elaborate user interaction dialog for instance.

    Recommended topics

  • Related API functions
  • User config callback functions