Embedded scripts

V-REP is a highly customizable simulator: almost every step of a simulation is user-defined. This flexibility is allowed through an integrated script interpreter. The scripting language is Lua, which is an extension programming language designed to support general procedural programming. For more information on Lua, refer to the Lua crash course section and the online documentation. See here for acknowledgments and credits related to Lua.

[Lua logo]


V-REP extends Lua's commands and adds V-REP specific commands that can be recognized by their sim-prefixes (e.g. simHandleCollision). For a list of all V-REP specific Lua-commands, refer to the regular API. New, customized Lua-commands can also be registered from the main client application or from a plugin. Refer to the related API-functions for more information.

Lua's functionality itself can easily be extended by making use of a Lua extension library available online.

Two major types of embedded scripts are supported:

  • one main script: by default, each scene has a main script that handles all the functionality. Without main script, a simulation cannot run. The main script can be customized, but it is preferable to do all the customization work in a child script (see hereafter).
  • an unlimited number of child scripts: each scene object can be associated with a child script that will handle a specific part of a simulation. The most common use for child scripts is to have them control a model.
  • Following are the main differences between the main script and a child script:

  • there can only be one main script. There can be an unlimited number of child scripts.
  • the main script is independent and should preferably not be customized. Child scripts are associated with scene objects and should be customized.
  • the main script is never duplicated in a copy/paste operation of scene objects. Child scripts will duplicate themselves together with their associated scene object.
  • the main script cannot be threaded. Child scripts can launch their own thread if needed (threaded and non-threaded operation is supported).


  • An auxiliary type of embedded scripts is also supported: callback scripts. Callback scripts usually handle low-level control customization routines, typically the user-defined joint control loop.


    Next to embedded scripts, V-REP supports also add-ons, that allow to customize the simulator itself.


    Recommended topics

  • The main script
  • Child scripts
  • Callback scripts
  • Add-ons
  • Script dialog
  • Script editor
  • Script calling methodology
  • Script simulation parameters
  • Accessing objects programmatically
  • Explicit and non-explicit calls
  • Application Programming Interface