Explicit and non-explicit calls
CoppeliaSim's main functionality is handled with calls or commands of following type: sim.handleXXX or sim.resetXXX (e.g. sim.handleCollision, sim.resetCollision, etc.). The regular argument that the command is expecting is a handle of a general-type object (e.g. a handle of a collision object, a handle of a distance object, etc.). Imagine you have registered a collision object "robotCollision" through the collision detection dialog. If you now wish to check the collision state of that object, you can write following code:
The first line retrieves the handle of the collision object named "robotCollision" (for the exact mode of operation of handle retrieval, refer to the section on accessing objects programmatically). The second line handles the collision object explicitely (i.e. it performs collision detection on that specific collision object). In that case the collision object has to be flagged as explicit handling, otherwise an error is generated.
Above same two commands can also handle objects in a non-explicit way: instead of using the collision object handle as argument, one can also use the sim.handle_all argument:
The sim.handle_all argument allows handling all registered collision objects at once. Here, collision objects are handled in a non-explicit way.
When registering general-type objects (e.g. collision objects), then you don't need any specific line of code to handle the objects, because the main script is taking care of that (register a new collision object by specifying two entities that should be checked for collision, run the simulation and move one of the two entities over the other: collision will be detected and the two entities will appear in a different color to indicate collision). Indeed, the main script contains following default code:
The commands' argument is sim.handle_all_except_explicit. It has the same effect as sim.handle_all, with following exception: objects marked as explicit handling will not be handled. Most general-type objects can be marked as explicit handling. When marked so, they will be handled only if the command is called using the object handle (e.g. sim.handleCollision(collisionObjectHandle)) or if the command is called with the sim.handle_all argument (e.g. sim.handleCollision(sim.handle_all)).
By default, the explicit handling flag is disabled, which means that by default general-type objects are handled by the main script. However if a child script wishes (or needs) to handle objects itself, then the explicit handling flag should be enabled, otherwise an error is generated. Usually objects are handled explicitely only if a child script requires a fresh result of a calculation several times in a same simulation pass (otherwise the child script can use commands like sim.readCollision, sim.readDistance, sim.readProximitySensor, etc.). One the other hand, child scripts should never use the sim.handle_all or sim.handle_all_except_explicit argument without a good reason! Following figures illustrate explicit and non-explicit calls:
[CollisionObject1 handled (i.e. calculated) by the default main script (non-explicit handling), and result read in a child script]
[CollisionObject1 handled (i.e. calculated) by a child script (explicit handling)]