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 :

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 with alias Object is unique:
int objectHandle=simGetObject("/Object",-1,-1,0); 

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

// find all objects starting with 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 with alias Object is unique:
objectHandle=sim.getObject("/Object")

# handle of the first Robot, in a given tree:
robotHandle=sim.getObject("/Robot[0]") 

# handle of the second Robot, in a given tree:
robotHandle=sim.getObject("/Robot[1]")

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 ( :/ ) ):


// 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 tree, that starts with Object:
local objectHandle=sim.getObject("./Object*") 

-- returns the first Object in the current model tree:
local objectHandle=sim.getObject(":/Object") 

-- returns the 4th Leg in the current model tree:
legHandle=sim.getObject(":/Leg[3]") 

-- parse through all Leg objects the current model tree:
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 in the tree of AnotherObject:
local objectHandle=sim.getObject("./Object",{proxy=AnotherObject})