The main script

A main script is a simulation script. By default, each scene in V-REP will have one main script. It contains the basic code that allows a simulation to run. Without main script, a running simulation won't do anything.

The main script is called at each simulation step exactly one time. In addition to that, it is called once during initialization (at the start of a simulation), and once during restoration (at the end of a simulation). Thus, the default main script is segmented in 3 parts:

  • the initialization part: this part will be executed one time just at the beginning of a simulation. The code is in charge of preparing a simulation, etc.
  • the regular part: this part will be executed at each simulation pass. The code is in charge of handling all the functionality of the simulator (inverse kinematics, proximity sensors, collision detection, dynamics, etc.) in a generic way. Two commands are of particular interest: simLaunchThreadedChildScripts and simHandleChildScripts. simLaunchThreadedChildScripts launches threaded child scripts, while simHandleChildScripts runs non-threaded child scripts. Without those commands, child scripts won't be executed, and specific model functionality or behavior won't operate. The regular part is divided into an actuation (or action/reaction) section and a sensing (or probing) section.
  • the restoration part: this part will be executed one time just before a simulation ends. The code is in charge of restoring object's initial configuration, clearing sensor states, collision states, etc.
  • Following is the typical main script, slightly simplified:

    if (sim_call_type==sim_mainscriptcall_initialization) then
        -- Initialization part:
        simHandleSimulationStart()
        simOpenModule(sim_handle_all)
        simHandleGraph(sim_handle_all_except_explicit,0)
    end
    
    if (sim_call_type==sim_mainscriptcall_regular) then
        -- Actuation part:
        simResumeThreads(sim_scriptthreadresume_default)
        simResumeThreads(sim_scriptthreadresume_actuation_first)
        simLaunchThreadedChildScripts()
        simHandleChildScripts(sim_childscriptcall_actuation)
        simResumeThreads(sim_scriptthreadresume_actuation_last)
        simHandleCustomizationScripts(sim_customizationscriptcall_simulationactuation)
        simHandleModule(sim_handle_all,false)
        simResumeThreads(2)
        simHandleJoint(sim_handle_all_except_explicit,simGetSimulationTimeStep()) -- DEPRECATED
        simHandlePath(sim_handle_all_except_explicit,simGetSimulationTimeStep()) -- DEPRECATED
        simHandleMechanism(sim_handle_all_except_explicit)
        simHandleIkGroup(sim_handle_all_except_explicit)
        simHandleDynamics(simGetSimulationTimeStep())
        simHandleMill(sim_handle_all_except_explicit)
    
        -- Sensing part:
        simHandleSensingStart()
        simHandleCollision(sim_handle_all_except_explicit)
        simHandleDistance(sim_handle_all_except_explicit)
        simHandleProximitySensor(sim_handle_all_except_explicit)
        simHandleVisionSensor(sim_handle_all_except_explicit)
        simResumeThreads(sim_scriptthreadresume_sensing_first)
        simHandleChildScripts(sim_childscriptcall_sensing)
        simResumeThreads(sim_scriptthreadresume_sensing_last)
        simHandleCustomizationScripts(sim_customizationscriptcall_simulationsensing)
        simHandleModule(sim_handle_all,true)
        simResumeThreads(sim_scriptthreadresume_allnotyetresumed)
        simHandleGraph(sim_handle_all_except_explicit,simGetSimulationTime()+simGetSimulationTimeStep())
    end
    
    if (sim_call_type==sim_mainscriptcall_cleanup) then
        -- Clean-up part:
        simResetMilling(sim_handle_all)
        simResetMill(sim_handle_all_except_explicit)
        simResetCollision(sim_handle_all_except_explicit)
        simResetDistance(sim_handle_all_except_explicit)
        simResetProximitySensor(sim_handle_all_except_explicit)
        simResetVisionSensor(sim_handle_all_except_explicit)
        simCloseModule(sim_handle_all)
    end

    The main script is not supposed to be modified. The reason for this is following: one of V-REP's strength is that any model (robot, actuator, sensor, etc) can be copied into a scene and is immediately operational. When modifying the main script, you run the risk that models won't perform as expected anymore (e.g. if your main script lacks the command simHandleChildScripts then all models copied into the scene won't operate at all). Another reason is that keeping a default main script allows old scenes to easily adjust for new functionality (e.g. if a new V-REP version introduces a neat command simDoMagic(), then old scenes will automatically be updated to have that command also automatically called in their main script).

    If however, for a reason or another you really need to modify the main script of a scene, you can do this by double-clicking the light-red script icon next to the world icon at the top of the scene hierarchy:

    [Main script icon]


    From the moment when you opened the main script, it will be marked as customized and won't be automatically updated anymore.

    Most commands in the main script behave or operate in a similar way. If we take for example the distance calculation functionality, we have in the regular part:

  • simHandleDistance(sim_handle_all_except_explicit): the effect of this command is to calculate minimum distances for all distance objects that have been registered and that are listed in the distance calculation dialog (handling distance calculation for a distance object will compute its minimum distance, set the distance variable and the minimum distance segment will be displayed in the scene). All distance objects are handled (i.e. calculated) with that command, except those that have been marked as explicit handling.
  • Any new distance object will automatically be handled with above command (as long as it is not marked as explicit handling). The exact same mechanism is applied to collision detection, proximity sensor and vision sensor simulations, inverse kinematics, etc. This is a powerful mechanism that allows running simple simulations without writing a single line of code.

    The most important command in the main script is simHandleChildScripts, which is called at two distinct locations, inside of the actuation section, and inside of the sensing section. Without this command, non-threaded child scripts will not be executed. If you look at the default main script and focus at the regular part, you can notice that the first section (the actuation section) allows actuating or modifying the scene content (e.g. simHandleIkGroup, simHandleDynamics, etc.), while the second section (the sensing or probing section) allows sensing and probing the scene content (e.g. simHandleCollision, simHandleDistance, simHandleProximitySensor, etc.). Following illustrates what happens in the default main script when a mobile robot equipped with a proximity sensor is simulated:

    [Default actuation - sensing - display sequence]


    With above's sequence in mind, child scripts will always read (with simReadProximitySensor) the proximity sensor's state from previous sensing (which happened at the end of previous simulation pass, inside of the main script, with simHandleProximitySensor), then react to obstacles.

    If you need to explicitely handle a sensor, then make sure to always do it while in the sensing section, otherwise you might end-up with situations where the display appears wrong as illustrated in following figure:

    [Sensing - actuation - display sequence]


    As does the main script have an actuation and sensing section, so do non-threaded child scripts. Threaded child scripts on the other hand can be squeduled to run while the main script is in the actuation or sensing phase, refer to the API function simSetThreadResumeLocation.

    The main script code is of type pass through, this means that at each simulation step, the main script is executed, then control is returned to the simulator, without spending too much time in complicated loops.


    Recommended topics

  • Child scripts