Customization scripts

Customization scripts are embedded scripts that can be used to customize a simulation scene to a great extent. They are attached to (or associated with) scene objects, and they can be easily recognized from their dark script icon in the scene hierarchy:

[A customization script associated with object Robot]

Double-clicking the script icon opens the script editor. You can change properties of a given script, or associate it with another object via the script dialog. You can attach a new customization script to an object by selecting the object, then navigating to [Add > Associated customization script].

Following are customization scripts' main properties:

  • they are executed all the time (within a same scene): when simulation is running, as well as when simulation is not running.
  • they are attached to (or associated with) scene objects (i.e. they are associated scripts). Associated scripts form the basis of CoppeliaSim's distributed control architecture, and share the convenient property to be automatically duplicated if their associated object is duplicated.

    • Above properties allow customization scripts to share some of the best features of add-ons and child scripts. Customization scripts allow the creation of customizable models for instance: imagine a model that was dropped into a scene, and that is able to configure or adapt itself, even when simulation is not running. This could be a robot where the user can adjust the various link lengths with a single slider repositioning.

    Customization scripts follow a precise calling or execution order and can run threaded or non-threaded. If possible, do not use this type of script to run simulation code, which is anyway best handled via child scripts.

    A customization script is typically segmented into a collection of system callback functions, the most important ones are:

  • sysCall_init. This function is executed just one time (the first time the child script is called). Usually you would put some initialization code in this part.
  • sysCall_thread. This function is the entrance to the script's threaded execution code. Threaded code is interrupted (and later resumed) on a regular basis by CoppeliaSim, by default. This behaviour can however be adjusted via sim.setStepping. See also the other thread-related API functions for more details.
  • sysCall_nonSimulation. This function is executed on a regular basis, when simulation is not running.
  • sysCall_beforeSimulation. This function is executed once just before simulation starts.
  • sysCall_afterSimulation. This function is executed once just after simulation ended.