The sandbox script

The sandbox script is quite similar to an add-on script: it is automatically loaded at program start-up, and allows CoppeliaSim's functionality to be extended by user-written functionality or functions. In addition to that, the sandbox script is extensively used in CoppeliaSim's Lua commander plugin (read-eval-print loop), that adds a text input to the CoppeliaSim status bar, allowing entering and executing Lua code on the fly, like in a terminal. It is persistent across all opened scenes, and is executed constantly, effectively running in the background. For that reason, it should only execute minimalistic code everytime called, since the whole application would otherwise slow down. The sandbox script is called frequently by the system, with a precise order.

The sandbox script is loaded from system/sndbxscpt.txt at start-up, and should be segmented in several functions, as following skeleton script illustrates:

function sysCall_init()
end

function sysCall_cleanup()
end

function sysCall_nonSimulation()
end

function sysCall_beforeSimulation()
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_actuation()
end

function sysCall_sensing()
end

function sysCall_afterSimulation()
end

function sysCall_suspend()
end

function sysCall_suspended()
end

function sysCall_resume()
end

function sysCall_beforeInstanceSwitch()
end

function sysCall_afterInstanceSwitch()
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

function sysCall_afterCreate(inData)
    for i=1,#inData.objectHandles,1 do
        print("Object with handle "..inData.objectHandles[i].." was created")
    end
end

The sandbox script can call any of the regular API functions, as long as not stated otherwise in the documentation. It can even call custom Lua functions registered by plugins. It however has two restrictions:

Recommended topics