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 ResizableFloor_5_25]

Double-clicking the script icon allows opening 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 [menu bar --> Add --> Associated customization script].

Following are customization script's main properties:

  • they run non-threaded.
  • they are executed all the time: 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 V-REP'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 contain a collection of blocking functions. 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 application halts. Customization script functions are called by the system very often, but also by the main script. Special callback functions are also supported by customization scripts: a joint callback function or a contact callback function.

    A customization script should be segmented in several functions, as following skeleton script illustrates:

    -- This is a customization script. It is intended to be used to customize a scene in
    -- various ways, mainly when simulation is not running. When simulation is running,
    -- do not use customization scripts, but rather child scripts if possible
    
    function sysCall_init()
        -- do some initialization here
    end
    
    function sysCall_nonSimulation()
        -- is executed when simulation is not running
    end
    
    function sysCall_cleanup()
        -- do some clean-up here
    end
    
    -- You can define additional system calls here:
    function sysCall_beforeSimulation()
    end
    
    function sysCall_actuation()
    end
    
    function sysCall_sensing()
    end
    
    function sysCall_suspend()
    end
    
    function sysCall_suspended()
    end
    
    function sysCall_resume()
    end
    
    function sysCall_afterSimulation()
    end
    
    function sysCall_beforeInstanceSwitch()
    end
    
    function sysCall_afterInstanceSwitch()
    end
    
    function sysCall_jointCallback(inData)
        -- See the joint callback function section in the user manual for details about input/output arguments
        return outData
    end
    
    function sysCall_contactCallback(inData)
        -- See the contact callback function section in the user manual for details about input/output arguments
        return outData
    end
    
    function sysCall_beforeCopy(inData)
        for key,value in pairs(inData.objectHandles) do
            print("Object with handle "..key.." will be copied")
        end
    end
    
    function sysCall_afterCopy(inData)
        for key,value in pairs(inData.objectHandles) do
            print("Object with handle "..key.." was copied")
        end
    end
    
    function sysCall_beforeDelete(inData)
        for key,value in pairs(inData.objectHandles) do
            print("Object with handle "..key.." will be deleted")
        end
        -- inData.allObjects indicates if all objects in the scene will be deleted
    end
    
    function sysCall_afterDelete(inData)
        for key,value in pairs(inData.objectHandles) do
            print("Object with handle "..key.." was deleted")
        end
        -- inData.allObjects indicates if all objects in the scene were deleted
    end

    If possible, do not use customization scripts to run simulation code, which is anyway best handled via child scripts.


    Recommended topics

  • Main script
  • Child scripts
  • Add-ons