Accessing scene objects programmatically

When programming in and around CoppeliaSim, you will always need to reference scene objects. You do this with handles, that you obtain via sim.getObject, which expects an object path as input argument. The object path can be expressed in an absolute manner, but also in a relative manner in case of associated code.

In both cases, the path to the object can often be simplified. You may also use wildcards, and optionally specify the object sequence or order in a given scene hierarchy. Or simply fetch the n-th object that matches a specific path/alias.

Note: until CoppeliaSim V4.2.0, object access was based on object names (with sim.getObjectHandle), which are now deprecated (but still functional for backward compatibility). We however highly recommend to use object paths as described below, to retrieve object handles. Object paths can easily be identified since they start with one of following characters: / or . or :

Deprecated object names are not displayed anymore in the scene hierarchy (where object aliases are displayed instead). You can however still see the deprecated name of an object by selecting it: it will be displayed at the top of the rendering page.

Access from unassociated code

Unassociated code is code that is not attached to any scene object. This includes all the code written for plugins, add-ons, remote API clients, external ROS nodes, and the main script.

In that case, you simply specify the object's absolute path, in order to retrieve its handle. If the object alias is unique, the path to the object can be simplified. You may also use wildcards, and optionally specify the object sequence in a given scene hierarchy. Or simply fetch the n-th object that matches a specific path:

// e.g. inside of a c/c++ plugin:

// using the full Object path:
int objectHandle = simGetObject("/Path/to/Object", -1, -1, 0);

// if object has unique alias Object:
int objectHandle = simGetObject("/Object", -1, -1, 0); 

// handle of the first object with alias Robot, in a given hierarchy level:
int robotHandle = simGetObject("/Robot[0]", -1, -1, 0);
 
// handle of the second object with alias Robot, in a given hierarchy level:
int robotHandle = simGetObject("/Robot[1]", -1, -1, 0);

// handle of the fifth object with alias Robot, in the scene:
int robotHandle = simGetObject("/Robot{4}", -1, -1, 0);
// or
int robotHandle = simGetObject("/Robot", 4, -1, 0);

// find all objects starting with alias prefix Mobile:
int i = 0;
while (true)
{
    int objectHandle = simGetObject("/Mobile*", i++, -1, 1);
    if (objectHandle < 0)
        break;
}

# e.g. inside of a Python ZeroMQ remote API client:

# using the full Object path:
objectHandle = sim.getObject("/Path/to/Object")

# if object has unique alias Object:
objectHandle = sim.getObject("/Object")

# handle of the first object with alias Robot, in a given hierarchy level:
robotHandle = sim.getObject("/Robot[0]") 

# handle of the second object with alias Robot, in a given hierarchy level:
robotHandle = sim.getObject("/Robot[1]") 

# handle of the fifth object with alias Robot, in the scene:
robotHandle = sim.getObject("/Robot{4}")

Access from associated code

Associated code is code that is associated with a scene object (i.e. attached to a scene object). This includes all the code written for child scripts or customization scripts.

In that case, objects can also be accessed in an absolute manner, but additionally, object access can also operate in a relative manner (relative to the current script/object ( ./ ), or relative to the model containing current script ( :/ ) ):

#python

# e.g. inside of child or customization script:

# returns the object this script is attached to:
objectHandle = sim.getObject(".") 

# returns the parent object this script is attached to:
parentHandle = sim.getObject("..") 

# returns the model this script is contained in:
modelHandle = sim.getObject(":") 

# returns the parent model this script is contained in:
parentModelHandle = sim.getObject("::") 

# returns the first object in the current hierarchy, that starts with Object:
objectHandle = sim.getObject("./Object*") 

# returns the first object with alias Object, in the current model hierarchy:
objectHandle = sim.getObject(":/Object") 

# returns the 4th object with alias Leg, within a same hierarchy level, in the current model hierarchy:
legHandle = sim.getObject(":/Leg[3]") 

# returns the 5th object with alias Leg, in the current model hierarchy:
legHandle = sim.getObject(":/Leg{4}") 

# parse through all Leg objects in the current model hierarchy:
i = 0
while True:
    legHandle = sim.getObject(":/Leg", {'index': i, 'noError': True})
    if legHandle < 0:
        break
    i = i + 1

# returns the first object with alias Object, in the hierarchy of anotherObject:
local objectHandle = sim.getObject("./Object", {'proxy': anotherObject})

--lua

-- e.g. inside of child or customization script:

-- returns the object this script is attached to:
local objectHandle = sim.getObject(".") 

-- returns the parent object this script is attached to:
local parentHandle = sim.getObject("..") 

-- returns the model this script is contained in:
local modelHandle = sim.getObject(":") 

-- returns the parent model this script is contained in:
local parentModelHandle = sim.getObject("::") 

-- returns the first object in the current hierarchy, that starts with Object:
local objectHandle = sim.getObject("./Object*") 

-- returns the first object with alias Object, in the current model hierarchy:
local objectHandle = sim.getObject(":/Object") 

-- returns the 4th object with alias Leg, within a same hierarchy level, in the current model hierarchy:
legHandle = sim.getObject(":/Leg[3]") 

-- returns the 5th object with alias Leg, in the current model hierarchy:
legHandle = sim.getObject(":/Leg{4}") 

-- parse through all Leg objects in the current model hierarchy:
local i = 0
while true do
    local legHandle = sim.getObject(":/Leg", {index = i, noError = true})
    if legHandle < 0 then
        break
    end
    i = i + 1
end

-- returns the first object with alias Object, in the hierarchy of anotherObject:
local objectHandle = sim.getObject("./Object", {proxy = anotherObject})