Callback functions

Callbacks or callback functions are script functions that are triggered by a specific event. They represent the only entrance into a script code. They can be categorized into user callbacks, and system callbacks:

  • user callback functions are directly triggered by user code, or a plugin. This happens for instance when the user calls a script function in a different script via sim.callScriptFunction, or when the user clicks a custom UI button, which triggers a custom event. User callback functions can usually run in any type of script.
  • system callback functions on the other hand are triggered by CoppeliaSim when a certain event happens, for instance when a script is initialized, or before the switch to another scene. System callback functions have fixed function names, such as sysCall_init or sysCall_beforeInstanceSwitch. Not all system callback functions can be handled by all types of scripts, e.g. some can only run in an add-on. (e.g. sysCall_addOnScriptSuspend)
  • While most system callback functions operate in a relatively straight-forward manner and are easy to understand (see further down for a complete list of system callback functions), some require a little bit more explanations:

  • Dynamics callback functions are called by the physics engine before and after each dynamics simulation step.
  • The contact callback function is called by the physics engine for each contact pair.
  • Joint callback functions are called by the physics engine for custom joint control.
  • Vision callback functions are called whenever an new image is acquires or applied.
  • Trigger callback functions are called when a certain trigger event is fired.
  • User config callback functions are called when the user double-clicks a user parameter icon.

  • Following is a list of all supported system callback functions. Most support returning {cmd='cleanup'} or {cmd='restart'} to end or restart the script. Refer to the comments in the code below for details about individual functions:

    function sysCall_info()
        -- Can be used to specify initial configuration data. E.g. in case of an add-on: 
        return {autoStart=false}
    end
    
    function sysCall_init()
        -- Do some initialization here. 
        -- Required for every type of script.
    end
    
    function sysCall_cleanup()
        -- Do some clean-up here.
    end
    
    function sysCall_nonSimulation()
        -- Is executed when simulation is not running. 
        -- Not for simulation scripts.
    end
    
    function sysCall_beforeSimulation()
        -- Simulation is about to start. 
        -- Not for simulation scripts.
    end
    
    function sysCall_afterSimulation()
        -- Simulation has just ended. 
        -- Not for simulation scripts.
    end
    
    function sysCall_actuation()
        -- Put some actuation code here.
    end
    
    function sysCall_sensing()
        -- Put some sensing code here.
    end
    
    function sysCall_suspend()
        -- Simulation is about to be suspended.
    end
    
    function sysCall_suspended()
        -- Simulation is suspended.
    end
    
    function sysCall_resume()
        -- Simulation is about to resume.
    end
    
    function sysCall_beforeInstanceSwitch()
        -- About to switch to another scene.
        -- Not for simulation scripts.
    end
    
    function sysCall_afterInstanceSwitch()
        -- Switched to another scene. 
        -- Not for simulation scripts.
    end
    
    function sysCall_beforeCopy(inData)
        -- Before one or several objects will be copied.
        for key,value in pairs(inData.objectHandles) do
            print("Object with handle "..key.." will be copied")
        end
    end
    
    function sysCall_afterCopy(inData)
        -- After one or several objects were be copied.
        for key,value in pairs(inData.objectHandles) do
            print("Object with handle "..key.." was copied")
        end
    end
    
    function sysCall_afterCreate(inData)
        -- After one or several objects were created.
        for i,#inData.objectHandles,1 do
            print("Object with handle "..inData.objectHandles[i].." was created")
        end
    end
    
    function sysCall_beforeDelete(inData)
        -- Before one or several objects will be deleted.
        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)
        -- After one or several objects were deleted.
        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
    
    function sysCall_beforeMainScript()
        -- Can be used to step a simulation in a custom manner.
        -- Not for simulation scripts.
        local outData={doNotRunMainScript=false} -- when true, then the main script won't be executed
        return outData
    end
    
    function sysCall_addOnScriptSuspend()
        -- Add-on script execution is about to be suspended.
        -- Only for add-on scripts.
    end
    
    function sysCall_addOnScriptResume()
        -- Add-on script execution is about to be resumed.
        -- Only for add-on scripts.
    end
    
    function sysCall_dynCallback(inData)
        -- See the dynamics callback function section for details.
        -- Only for customization scripts and child scripts.
    end
    
    function sysCall_jointCallback(inData)
        -- See the joint callback function section for details.
        -- Only for customization scripts and child scripts.
        return outData
    end
    
    function sysCall_contactCallback(inData)
        -- See the contact callback function section for details.
        -- Only for customization scripts and child scripts.
        return outData
    end
    
    function sysCall_vision(inData)
        -- See the vision callback function section for details.
        -- Only for customization scripts and child scripts.
        return outData
    end
    
    function sysCall_trigger(inData)
        -- See the trigger callback function section for details.
        -- Only for customization scripts and child scripts.
        return outData
    end
    
    function sysCall_userConfig()
        -- See the user config callback function section for details.
        -- Only for customization scripts.
    end