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 are supported 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 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:

#python

def sysCall_init():
    # Do some initialization here.
    pass

def sysCall_thread():
    # Entry point for threaded scripts.
    pass

def sysCall_cleanup():
    # Do some clean-up here.
    pass

def sysCall_nonSimulation():
    # Is executed when simulation is not running.
    # Not for simulation scripts or the main script.
    pass

def sysCall_beforeSimulation():
    # Simulation is about to start.
    # Not for simulation scripts or the main script.
    pass

def sysCall_afterSimulation():
    # Simulation has just ended.
    # Not for simulation scripts or the main script.
    pass

def sysCall_actuation():
    # Put some actuation code here.
    pass

def sysCall_sensing():
    # Put some sensing code here.
    pass

def sysCall_suspend():
    # Simulation is about to be suspended.
    pass

def sysCall_suspended():
    # Simulation is suspended.
    pass

def sysCall_resume():
    # Simulation is about to resume.
    pass

def sysCall_realTimeIdle():
    # Is executed when idle in real-time mode
    pass

def sysCall_beforeInstanceSwitch():
    # About to switch to another scene.
    # Not for simulation scripts or the main script.
    pass

def sysCall_afterInstanceSwitch():
    # Switched to another scene.
    # Not for simulation scripts or the main script.
    pass

def sysCall_beforeSave():
    # About to save the scene, or about to set an undo/redo point
    pass

def sysCall_afterSave():
    # After the scene was saved, or after an undo/redo point was set
    pass

def sysCall_selChange(inData):
    # After selection was changed
    for handle in inData['sel']:
        print(f"Object with handle {handle} is selected")

def sysCall_beforeCopy(inData):
    # Before one or several objects will be copied. Can be reentrant
    for handle in inData['objects']:
        print(f"Object with handle {handle} will be copied")

def sysCall_afterCopy(inData):
    # After one or several objects were copied. Can be reentrant
    for handle in inData['objects']:
        print(f"Object with handle {handle} was copied")

def sysCall_afterCreate(inData):
    # After one or several objects were created. Can be reentrant
    for handle in inData['objects']:
        print(f"Object with handle {handle} was created")

def sysCall_beforeDelete(inData):
    # Before one or several objects will be deleted. Can be reentrant
    for handle in inData['objects']:
        print(f"Object with handle {handle} will be deleted")
    # inData['allObjects'] indicates if all objects in the scene will be deleted

def sysCall_afterDelete(inData):
    # After one or several objects were deleted. Can be reentrant
    for handle in inData['objects']:
        print(f"Object with handle {handle} was deleted")
    # inData['allObjects'] indicates if all objects in the scene were deleted

def sysCall_beforeMainScript():
    # Can be used to step a simulation in a custom manner.
    outData = {"doNotRunMainScript": False}  # when true, then the main script won't be executed
    return outData

def sysCall_addOnScriptSuspend():
    # Add-on execution is about to be suspended.
    # Only for add-ons.
    pass

def sysCall_addOnScriptResume():
    # Add-on execution is about to be resumed.
    # Only for add-ons.
    pass

def sysCall_dyn(inData):
    # See the dynamics callback function section for details
    return {...}

def sysCall_joint(inData):
    # See the joint callback function section for details
    return {...}

def sysCall_contact(inData):
    # See the contact callback function section for details
    return {...}

def sysCall_vision(inData):
    # See the vision callback function section for details
    # Only for customization scripts and simulation scripts.
    return {...}

def sysCall_trigger(inData):
    # See the trigger callback function section for details
    # Only for customization scripts and simulation scripts.
    return {...}

def sysCall_userConfig():
    # See the user config callback function section for details.
    # Only for customization scripts.
    pass

def sysCall_moduleEntry(inData):
    # Called when a user module menu entry is selected, e.g.
    print(f"Following module menu entry was selected: {inData['handle']}")
    # See sim.moduleEntry for details.

def sysCall_msg(msg, origin):
    # Synchronously called when sim.broadcastMsg is called, or when sysCall_init, sysCall_cleanup,
    # sysCall_addOnScriptSuspend, sysCall_addOnScriptResume or sysCall_userConfig is called. Can be reentrant
    pass

def sysCall_data(inData):
    # Asynchronously called when custom data attached to this script's parent object is modified
    # Only for simulation- and customization scripts
    pass

def sysCall_event(cborBuffer):
    # Asynchronously called when something (mainly visual for now) changes. Can be reentrant
    # Mainly used to synchronize an external viewer/renderer with CoppeliaSim.
    # See also sim.getGenesisEvents
    pass

--lua

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. 
end

function sysCall_thread()
    -- Entry point for threaded scripts.
end

function sysCall_cleanup()
    -- Do some clean-up here.
end

function sysCall_nonSimulation()
    -- Is executed when simulation is not running. 
    -- Not for simulation scripts or the main script.
end

function sysCall_beforeSimulation()
    -- Simulation is about to start. 
    -- Not for simulation scripts or the main script.
end

function sysCall_afterSimulation()
    -- Simulation has just ended. 
    -- Not for simulation scripts or the main script.
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 or the main script.
end

function sysCall_afterInstanceSwitch()
    -- Switched to another scene. 
    -- Not for simulation scripts or the main script.
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_selChange(inData)
    -- After selection was changed
    for i = 1, #inData.sel, 1 do
        print("Object with handle " .. inData.sel[i] .. " is selected")
    end
end

function sysCall_beforeCopy(inData)
    -- Before one or several objects will be copied. Can be reentrant
    for i = 1, #inData.objects, 1 do
        print("Object with handle " .. inData.objects[i] .. " will be copied")
    end
end

function sysCall_afterCopy(inData)
    -- After one or several objects were copied. Can be reentrant
    for i = 1, #inData.objects, 1 do
        print("Object with handle " .. inData.objects[i] .. " was copied")
    end
end

function sysCall_afterCreate(inData)
    -- After one or several objects were created. Can be reentrant
    for i = 1, #inData.objects, 1 do
        print("Object with handle " .. inData.objects[i] .. " was created")
    end
end

function sysCall_beforeDelete(inData)
    -- Before one or several objects will be deleted. Can be reentrant
    for i = 1, #inData.objects, 1 do
        print("Object with handle " .. inData.objects[i] .. " 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
    for i = 1, #inData.objects, 1 do
        print("Object with handle " .. inData.objects[i] .. " 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.
    local outData = {doNotRunMainScript = false} -- when true, then the main script won't be executed
    return outData
end

function sysCall_addOnScriptSuspend()
    -- Add-on execution is about to be suspended.
    -- Only for add-ons.
end

function sysCall_addOnScriptResume()
    -- Add-on execution is about to be resumed.
    -- Only for add-ons.
end

function sysCall_dyn(inData)
    -- See the dynamics callback function section for details
    return outData
end

function sysCall_joint(inData)
    -- See the joint callback function section for details
    return outData
end

function sysCall_contact(inData)
    -- See the contact callback function section for details
    return outData
end

function sysCall_vision(inData)
    -- See the vision callback function section for details
    -- Only for customization scripts and simulation scripts.
    return outData
end

function sysCall_trigger(inData)
    -- See the trigger callback function section for details
    -- Only for customization scripts and simulation 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 sim.moduleEntry for details.
end

function sysCall_msg(msg, origin)
    -- Synchronously called when sim.broadcastMsg is called, or when sysCall_init, sysCall_cleanup,
    -- sysCall_addOnScriptSuspend, sysCall_addOnScriptResume or sysCall_userConfig is called. Can be reentrant 
end

function sysCall_data(inData)
    -- Asynchronously called when custom data attached to this script's parent object is modified
    -- Only for simulation- and customization scripts
end

function sysCall_event(cborBuffer)
    -- Asynchronously called when something (mainly visual for now) changes. Can be reentrant 
    -- Mainly used to synchronize an external viewer/renderer with CoppeliaSim.
    -- See also sim.getGenesisEvents
end

function sysCall_ext(funcName, inData)
    -- 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