A simulation in CoppeliaSim can be started, paused and stopped with [Menu bar --> Simulation --> Start/Pause/Stop simulation] or through the related toolbar buttons:

[Simulation start/pause/stop toolbar buttons]

Internally, the simulator will use additional intermediate states in order to correctly inform scripts or programs about what will happen next. Following state diagram illustrates the simulator's internal states:

[Simulation state diagram]

Scripts and programs should alwaysreact according to the current system call function and possibly the simulation state in order to behave correctly. It is good practice to divide each control code into at least 4 system call functions (e.g. for non-threaded child scripts):

  • Initialization function: sysCall_init: the function is called only when the script is initialized.
  • Actuation function: sysCall_actuation: the function is called when actuation should happen.
  • Sensing function: sysCall_sensing: this function is called when sensing should happen.
  • Clean-up function: sysCall_cleanup: the function is called just before the script is de-initialized (e.g. at simulation end, or when the script is destroyed).
  • For examples on how to arrange a typical script, refer to the main script, the child scripts and customization scripts pages.

    Simulation loop

    The simulator operates by advancing the simulation time at constant time steps. Following figure illustrates the main simulation loop:

    [Main simulation loop]

    Real-time simulation is supported by trying to keep the simulation time synchronized with the real time:

    [Real-time simulation loop]

    Following represents a very simplified main client application (messaging, plugin handling and other details have been omitted for clarity purpose):

    void initializationCallback
    // do some initialization here } void loopCallback
    if ( (simGetSimulationState()&sim_simulation_advancing)!=0 )
    if ( (simGetRealTimeSimulation()!=1)||(simIsRealTimeSimulationStepNeeded()==1) )
    if ((simHandleMainScript()&sim_script_main_script_not_called)==0)
    } void deinitializationCallback
    // do some clean-up here }

    Depending on the simulation complexity, performance of the computer and simulation settings, real-time simulation might not always be possible.

    Simulation speed

    In non real-time simulations, the simulation speed (i.e. the perceived speed) is mainly dependent on two factors: the simulation time step and the number of simulation passes for one rendering pass (see the simulation dialog for more details). In the case of a real-time simulation, the simulation speed mainly depends on the real-time multiplication coefficient, but also to a certain degree of the simulation time step (a too small simulation time step might not be compatible with the real-time character of a simulation because of the limited calculation power of the computer). During simulation, the simulation speed can be adjusted with following toolbar buttons:

    [Simulation speed adjustment toolbar buttons]

    The simulation speed is adjusted in a way so that the initial simulation time step is never increased (because this might have as consequence the breaking of a mechanism for example). Following two figures illustrate the simulation speed adjustment mechanisms:

    [Simulation speed adjustment mechanism for non real-time simulations]

    [Simulation speed adjustment mechanism for real-time simulations]

    By default, each simulation cycle is composed by following sequential operations:

  • Executing the main script
  • Rendering the scene

  • Threaded rendering

    The rendering operation will always increase the simulation cycle duration, thus also slowing down simulation speed. The number of main script executions per scene rendering can be defined (see further up), but this is not enough in some situations, because rendering will still slow down every xth simulation cycle (which can be handicapping with real-time requirements). For those situations, a threaded rendering mode can be activated via the user settings, or via the following toolbar button:

    [Threaded rendering toolbar button]

    When the threaded rendering mode is activated, a simulation cycle will only consist in execution of the main script, thus simulations will run at maximum speed. Rendering will happen via a different thread, and not slow down the simulation task. The drawbacks have however to be considered. When threaded rendering is activated, then:

  • Rendering will happen asynchronously to the simulation loop, and visual glitches might appear
  • The video recorder will not operate at constant speed (some frames might get skipped)
  • The stability of the application might be reduced
  • Some operations (e.g. erasing an object, etc.) require to wait for the rendering thread to finish work, before being able to execute, and vice-versa. In those situations, cycles could take more time than in the sequential rendering mode.

  • Recommended topics

  • Related API functions
  • Simulation settings dialog
  • Scripts
  • The main client application
  • Plugins