The sandbox script

The sandbox script is quite similar to an add-on script: it is automatically loaded at program start-up, and allows V-REP's functionality to be extended by user-written functionality or functions. In addition to that, the sandbox script is extensively used in V-REP's Lua commander plugin (read-eval-print loop), that adds a text input to the V-REP 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:

  • The sandbox script cannot call API functions that require the caller to run in a thread. This is because the sandbox script operates in a non-threaded fashion.
  • While simulation is not running, the sandbox script should not call API functions that make sense only when simulation is running.


  • Recommended topics

  • Lua
  • Add-ons
  • Regular API functions