Callback functions

Callbacks or callback functions are script functions that are triggered by a specific event. They represent the only entrance into 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 switching 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()
    -- Lua only. Can be used to specify initial configuration data. E.g. in case of an add-on: 
    return {autoStart=false,menu='menu1\nmenu2\nadd-on name',menuEnabled=true}
end

function sysCall_init()
    -- Do some initialization here. 
    -- Either sysCall_init or sysCall_thread is required with Python scripts.
end

function sysCall_thread()
    -- Python only. Entry point for threaded scripts.
    -- Either sysCall_thread or sysCall_init is required.
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_realTimeIdle()
    -- Is executed when idle in real-time mode
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_beforeSave()
    -- About to save the scene, or about to set an undo/redo point
end

function sysCall_afterSave()
    -- After the scene was saved , or after an undo/redo point was set
end

function sysCall_beforeCopy(inData)
    -- Before one or several objects will be copied. Can be reentrant. Disabled by default for Python.
    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 copied. Can be reentrant. Disabled by default for Python.
    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. Can be reentrant. Disabled by default for Python.
    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. Can be reentrant. Disabled by default for Python.
    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. Can be reentrant. Disabled by default for Python.
    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()
    -- Lua only. Can be used to step a simulation in a custom manner.
    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. Disabled by default for Python.
    -- Only for customization scripts and child scripts.
end

function sysCall_jointCallback(inData)
    -- See the joint callback function section for details. Disabled by default for Python.
    -- Only for customization scripts and child scripts.
    return outData
end

function sysCall_contactCallback(inData)
    -- See the contact callback function section for details. Disabled by default for Python.
    -- Only for customization scripts and child scripts.
    return outData
end

function sysCall_vision(inData)
    -- See the vision callback function section for details. Disabled by default for Python.
    -- Only for customization scripts and child scripts.
    return outData
end

function sysCall_trigger(inData)
    -- See the trigger callback function section for details. Disabled by default for Python.
    -- 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

function sysCall_moduleEntry(inData)
    -- Called when a user module menu entry is selected, e.g.
    print('Following module menu entry was selected: '..inData.handle)
    -- See the sim.moduleEntry for details.
end

function sysCall_msg(message,origin)
    -- Synchronously called when sim.broadcastMsg is called. Can be reentrant. Disabled by default for Python. 
end

function sysCall_event(inData)
    -- Called when something (mainly visual for now) changes. Can be reentrant. Disabled by default for Python. 
    -- Mainly used to synchronize an external viewer/renderer with CoppeliaSim.
    -- See also sim.getGenesisEvents
end

function sysCall_ext(string funcName,inData)
    -- Lua only. When this function is present, then all external calls to a script function, i.e. user callbacks,
    -- will be intercepted (the original function will be shadowed). If only monitoring is desired,
    -- then one should use sim.registerScriptFuncHook on this function.
end