Child scripts

A child script is a simulation script. CoppeliaSim supports an unlimited number of child scripts per scene. Each child script represents specific code that handles a particular function in a simulation. Child scripts are attached to (or associated with) scene objects, and they can be easily recognized from their script icon in the scene hierarchy:

[A child script associated with object Robot]

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

A child script's association with a scene object has following benefits:

  • Very good portability: child scripts will be saved/loaded together with their associated object. Using child scripts, you are able to create extremely portable code and simulation models that do not need to rely on any system specific plugin. A fully functional model can be contained in a single file (usable without modification across various platforms), which is not the case when relying on plugins for model control. Additionally, and for the same reason, models relying on child scripts require no maintenance over time (e.g. a new OS version will not require you to adjust portions of code or recompilation, as you might have to do when using plugins).
  • Inherent scalability: if an object that has an attached child script is duplicated, its child script will also be duplicated. The duplicated child script's content will be identical to the original child script's content, however, the duplicated child script will know that is was duplicated and redirect object access correctly, if relative paths were used for object access. Refer to the section on accessing scene objects programmatically for more details.
  • No conflict between different model versions: if you modify the child script of a given model (e.g. to customize it to your needs), this will have no consequence on other similar models. This is a much more critical aspect when relying on plugins instead of child scripts for model control: indeed, with plugins you always run the risk of having conflicts with previous plugin versions.
  • Very easy synchronization with the simulation loop: child scripts can run threaded or non-threaded, and can be easily synchronized with the simulation loop, which represents a powerful feature.
  • Child scripts should exclusively be used to handle simulation-time tasks, since they only run when simulation is running. Their entrance functions are callback functions. Functions that are not running threaded should not be blocking. This means that every time they are called, they should perform some task and then return control. If control is not returned, then the whole simulation halts. Child script functions are called by the main script at least twice per simulation step from the main script's actuation and sensing functions. The system will also call other system callback functions where appropriate (e.g. during child script initialization, clean-up, etc).

    Child scripts follow a precise calling or execution order: they are called starting with scripts attached to leaf objects (or childless objects), and ending with scripts attached to root objects (or parentless objects). They are 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). This can be at the beginning of a simulation, but also in the middle of a simulation: remember that objects associated with child scripts can be copy/pasted into a scene at any time, also when a simulation is running. 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_actuation. This function is executed in each simulation step, during the actuation phase of a simulation step. Refer to the main script default code for more details about the actuation phase, but typically, you would do some actuation in this part (no sensing).
  • sysCall_sensing. This function is executed in each simulation step, during the sensing phase of a simulation step. Refer to the main script default code for more details about the sensing phase, but typically, you would only do sensing in this part (no actuation).
  • sysCall_cleanup. This function is executed one time just before a simulation ends, or before the script is destroyed.