World

The raisim::World class owns simulation resources: objects, constraints, materials, collision detection, contact solving, sensors, time, and gravity. All objects within a single World instance can collide with one another unless their collision group and mask settings disable that pair. See Contact and Collision and Collision Detection and Colliders for contact and collision details.

A raisim::World can be instantiated in four ways. The constructor that takes a path chooses the loader from the file extension and content.

From a USD file. Pass a .usd, .usda, .usdc, or .usdz path to the constructor. RaiSim opens the USD stage and imports one USD Physics articulation (the default prim if it has PhysicsArticulationRootAPI, otherwise the first such prim) as an ArticulatedSystem, with its rigid bodies, joints, and supported collision shapes, and applies the stage’s physics-scene gravity and physics materials when present. Other prims, such as free rigid bodies outside that articulation, are not imported, so add the ground and other objects in code. A stage without an articulation root throws std::runtime_error. See OpenUSD Loading for the full import semantics and tooling.
```
raisim::World world("robot.usd");
world.addGround();
```
Use this entry point for robots authored in USD-native tools such as Isaac Sim, Omniverse, and Blender.
From a RaiSim XML or MuJoCo MJCF configuration file. Pass the file path to the same constructor. The file content, a <raisim> or a <mujoco> element, selects the loader; the extension does not matter. Use this when the scene is hand-edited, template-driven, or already lives in one of those formats. See World Configuration File for the RaiSim XML schema and the MJCF notes below.
From a RaiSim Engine scene file (from v2.8.0; earlier packages do not include the reader). Pass a .rscene path to the same constructor. RaiSim reads the solver settings and contact materials, sampled terrain, primitive, mesh and .rasset bodies, and wires; .rscene File documents the format. The parsed scene stays available through World::getRscene(), so rayrai can apply the rest of the scene, as RaiSim Engine 2’s viewport shows it (render settings, sky, lights, fog, visual-only objects, instanced visuals, terrain foliage and textures, and the camera). From v2.8.2 (not yet released), a RayraiWindow applies it when it is constructed:
```
auto world = std::make_shared<raisim::World>("forest.rscene");
raisin::RayraiWindow viewer(world, 1280, 800);  // shows the whole scene
```
To change the file’s render settings in C++:
```
auto render = raisin::rsceneRenderSettings(*world->getRscene());
render.quality.viewerMsaaSamples = 8;
raisin::setRsceneRenderSettings(viewer, render);
```
Content the reader cannot reproduce exactly, such as articulated systems, compounds or nodes that inherit another node’s transform, is a fatal error naming the line rather than being dropped. The scene’s solver settings replace the world’s defaults; Engine 2’s defaults differ from raisim::World’s (see Solver defaults). See Rayrai Example: Forest From .rscene for a complete example. An XML world configuration file can include a scene (<include value="[THIS_DIR]/scene.rscene"/>) and add a robot to it; see A robot in a scene.

Programmatically. Default-construct an empty world and add objects in code:

raisim::World world;
world.addGround();
auto* box = world.addBox(1.0, 1.0, 1.0, 1.0);

These methods can be combined: load an initial file and then add or remove objects in code before stepping.

MJCF files

The MJCF (MuJoCo file format) reader is experimental. MJCF files are loaded with the same raisim::World constructor used for RaiSim XML:

raisim::World world("rsc/mjcf/gymnasium/hopper.xml");

The reader supports the subset used by the bundled MJCF examples: static worldbody geoms, articulated bodies (each top-level body becomes one ArticulatedSystem), free, ball, slide, and hinge joints, primitive geoms, mesh assets, inertial tags, defaults, compiler angle/eulerseq settings, compiler meshdir, material colors, option timestep, equality connect constraints between bodies of the same top-level body, and tendons (see Tendon API and model files). Mesh asset paths are resolved relative to the MJCF file directory, or relative to compiler meshdir when it is provided. MJCF files without an asset block are accepted. Following the MJCF default, a geom with no type attribute is treated as a sphere and must provide at least one size value for its radius.

It is not a complete MuJoCo replacement. <actuator> elements are not imported (the example programs apply joint torques from C++), <include> is not supported, equality types other than connect and tendon equalities are fatal errors, and integrators other than Euler are ignored with a warning. Validate other MuJoCo features before relying on them.

Example targets:

mjcf_gymnasium_hopper loads and actuates Gymnasium’s Hopper model.
mjcf_gymnasium_walker2d loads and actuates Gymnasium’s Walker2d model.
mjcf_gymnasium_humanoid loads Gymnasium’s Humanoid model and drops it from a raised arbitrary configuration.

For callers that already hold a constructed raisim::World and want to populate it from an MJCF file at runtime (instead of constructing the world from the file path), use World::loadMjcfFile:

raisim::World world;
world.loadMjcfFile("rsc/mjcf/gymnasium/hopper.xml");

This is the same loader that World(configFile) calls internally for a <mujoco> file. The world should normally be empty before the call: MJCF files often declare ground planes, worldbody geoms, and option blocks that change world-level state such as the time step. The rayrai TCP viewer uses this entry point in its drag-and-drop articulated-system inspector mode (see Rayrai TCP Viewer).

Adding New Objects

To add a new object of type X, utilize the addX method. For example, to add a sphere:

raisim::World world;
auto sphere = world.addSphere(0.5, 1.0);

sphere is a pointer to the object, which the world owns. Use it to read and modify the object’s state. The pointer becomes invalid when the object is removed with World::removeObject.

Most object-creation methods accept optional material, collisionGroup, and collisionMask arguments. A ground (addGround) has a fixed collision group and exposes only a collision mask. Height maps (addHeightMap) accept a group that defaults to the static collision group RAISIM_STATIC_COLLISION_GROUP. Collision groups and masks are described in Contact and Collision. The material argument names the material that governs contact dynamics; see Material System.

The object types are described in Objects.

Upon object addition, a name may be assigned:

sphere->setName("ball");

An object pointer can be retrieved by name:

auto* ball = world.getObject("ball");

An object may consist of multiple bodies (e.g., an articulated system). A local index is used to designate individual bodies. To maintain API consistency, many methods require the local index argument even for single-body objects. For single-body objects, the local index is ignored, and users may pass 0 to comply with the API.

Stable object identifiers

Object::Id (a uint64_t) is assigned when an object is added to a world and remains valid for the lifetime of that object even when other objects are removed; ids are not reused within a world. World::getObjectById(id) returns a pointer, or nullptr when the object has been removed; isObjectAlive(id) returns the same information as a bool. getIndexInWorld() is fine for steady-state lookups, but in code that adds and removes objects (RL resets, asset streaming) prefer the stable id: when an object is removed, the last object in the world’s list moves into the removed object’s index.

Snapshots, checkpoints, and cloning

Single-body objects support a fast capture/restore workflow for RL resets and rollback debugging. captureSingleBodySnapshot(obj, snapshotOut) fills a SingleBodySnapshot (object id, type, body type, pose, linear/angular velocity, material, and collision group/mask). restoreSingleBodySnapshot reapplies it later, either by pointer to the same object or by stable ObjectId; pass restoreCollisionProperties=false to skip material and collision filter restoration. The snapshot is plain data and cheap to copy and reuse. cloneSingleBodyObject(source, name) produces a new single-body object with the same primitive shape, mass, pose, velocity, body type, material, collision filter, and appearance. It supports spheres, boxes, cylinders, and capsules and returns nullptr for other types.

To rewind the whole world, World::captureCheckpoint() returns an in-memory World::Checkpoint of the runtime state, including controls, pending forces, sensors, sleeping islands, and contact-solver history, and restoreCheckpoint(checkpoint) restores it. Capture between complete steps (not between integrate1() and integrate2()) and keep the object/constraint/sensor topology unchanged until the restore; otherwise the restore is rejected and returns false. Checkpoints belong to the world that captured them and are not files.

raisim::World::SingleBodySnapshot snapshot;
world.captureSingleBodySnapshot(sphere, snapshot);
// ... simulate, then reset:
world.restoreSingleBodySnapshot(sphere, snapshot);

auto* twin = world.cloneSingleBodyObject(sphere, "sphere_copy");

Saving the World to an XML File

raisim::World::exportToXml(dir, file) (or exportToXml(path)) saves the current world to a RaiSim XML file that raisim::World(path) can load again. The file stores gravity, the time step, solver, contact and sleeping settings, materials, objects with their current state, and tendons (see World Configuration File). Unnamed objects receive generated names. An articulated system that was not loaded from a file is written as a URDF file (model_<index>.urdf) in dir, next to the XML file.

Stepping and time

World::integrate() advances the world by one timestep. It is equivalent to calling integrate1() and then integrate2().

Method	Work performed
`setTimeStep(dt)`	Updates the world timestep, contact solver timestep, and object-local timestep state. A non-finite or non-positive `dt` is a fatal error.
`integrate1()`	Clears previous contacts, runs collision detection, registers contacts, and calls each object’s first pre-solver update hook.
`integrate2()`	Runs the second pre-solver update hook, solves contacts, integrates object state, and advances the world time.
`integrate()`	Runs `integrate1(); integrate2();`.
`integrateNoContactDetection()`	Replaces `integrate1()` when contacts are not needed: clears previous contacts and updates collision geometry and the first pre-solver hook, but skips collision detection and contact-problem construction. Call `integrate2()` afterwards to complete the step.

getWorldTime() returns the integrated simulation time, and setWorldTime(time) can manually adjust it. For visualization through RaisimServer, prefer RaisimServer::integrateWorldThreadSafe() so the server’s background reader and user interactions are synchronized.

Collision Detection and Broadphase

RaiSim performs collision detection in two stages: a broadphase pass that filters candidate pairs using axis-aligned bounding boxes (AABBs), followed by a narrowphase pass (analytic tests, SAT, MPR, and GJK/EPA depending on the shape pair) to generate contact points. You can configure the contact detector via setContactSettings or adjust only the broadphase via setBroadphaseSettings. These settings should be updated when the world is not stepping.

Broadphase options are defined by contact::BroadphaseType:

None (brute-force pairs, useful for debugging or very small scenes)
Sap3Axis (sweep-and-prune, default)
MultiBoxPrune (grid-based broadphase for large worlds)

The current contact::ContactSettings defaults are:

Setting	Default
`gjkMaxIterations`, `gjkTolerance`	`32`, `1e-6`
`epaMaxIterations`, `epaTolerance`	`64`, `1e-4`
`maxContactsPerPair`	`8`
`sweptCcdEnabled`	`false`
`sweptCcdMinSpeed`	`0.0`
`sweptCcdSpeculativeMargin`	`1e-4`
`broadphase.type`	`Sap3Axis`
`broadphase.mbpUseWorldBounds`	`false` (the grid covers the padded bounds of all bodies)
`broadphase.mbpWorldMin` / `mbpWorldMax`	`{-100, -100, -100}` / `{100, 100, 100}`; used only when `mbpUseWorldBounds` is `true`
`broadphase.mbpCellSize`	`{1, 1, 1}`
`broadphase.mbpPadding`	`0.5`
`broadphase.mbpMaxCellsPerAxis` / `mbpMaxCellsPerObject`	`128` / `64`

Example broadphase configuration (MultiBoxPrune):

#include <raisim/World.hpp>
#include <raisim/contact_engine/contact_engine.h>

raisim::World world;
auto settings = world.getContactSettings();
settings.broadphase.type = contact::BroadphaseType::MultiBoxPrune;
settings.broadphase.mbpWorldMin = {-50.0, -50.0, -2.0};
settings.broadphase.mbpWorldMax = { 50.0,  50.0, 10.0};
settings.broadphase.mbpCellSize = {  1.0,   1.0,  1.0};
settings.broadphase.mbpUseWorldBounds = true;
world.setContactSettings(settings);

Collision groups and masks still gate which pairs are considered in both broadphase and narrowphase.

Contact Solver Settings

World::setERP(erp, erp2) updates the contact solver’s error-reduction parameters. World::setContactSolverParam(alpha_init, alpha_min, alpha_decay, maxIter, threshold) updates the solver configuration. The alpha arguments are kept for compatibility and ignored; the effective parameters are maxIter and threshold. The solver defaults are maxIteration = 150 and error_to_terminate = 1e-8.

The contact solver sweeps through the contacts forward or backward and flips the direction after every solve, so consecutive steps alternate. World::setContactSolverIterationOrder(order) sets the direction of the next solve (true: forward). Call it before a step when the result must not depend on how many solves preceded it, for example when replaying from a restored state; see Determinism. Articulated-system loop constraints (pins and equality constraints) are eliminated before the solve and do not affect the sweep; only pin rows added directly to the solver force forward sweeps.

Sleeping islands

RaiSim can skip simulation for sleeping islands: groups of dynamic objects connected by contacts. Sleeping is enabled by default. An island goes to sleep when all objects in the island remain quiet for a configurable number of consecutive steps (quietSteps, default 5) and their maximum linear and angular velocities stay below the configured thresholds (defaults: linear 0.002 m/s, angular 0.01 rad/s). Disabling sleeping wakes every sleeping object.

Notes:

The quiet counter resets whenever either speed threshold is exceeded.
The quiet duration is quietSteps * timeStep (5 ms at a 1 ms timestep). A pendulum can remain below both thresholds near a turning point for five steps and go to sleep. Use a longer window for slower oscillations or smaller timesteps when this occurs.
Only dynamic objects participate in sleeping islands.
Any user modification (e.g., changing state) keeps the island awake.
Contacts between awake and sleeping islands will wake the sleeping island on the next step.

Configuration API:

world.setSleepingEnabled(true);
world.setSleepingParameters(/*linear*/ 0.002, /*angular*/ 0.01, /*quietSteps*/ 5);
world.setSleepingVelocityThresholds(0.002, 0.01);
world.wakeObject(obj);   // wakes the object's island
world.wakeAll();

You can query whether a specific object is sleeping with isObjectSleeping.

API

class World

The simulation world. It owns every object, wire and tendon added to it: the raw pointers returned by the add* methods stay valid until the object is removed (removeObject()) or the world is destroyed, and must not be deleted by the caller. Advance the simulation with integrate() (or integrate1() followed by integrate2()). A World is not thread-safe; see lockMutex() for sharing it with another thread (e.g. a visualizer server).

Public Types

using ObjectId = Object::Id : Stable runtime object id (Object::getId()). Ids are not reused within a World.

Public Functions

explicit World(uint64_t headerLayoutStamp = detail::headerLayoutStamp())

Create an empty world. The defaulted parameter is an ABI guard: it is evaluated in the caller’s translation unit from the headers the application compiled with, and the library compares it with its own value. A mismatch means the application was built against headers whose object layout differs from the loaded libraisim (e.g. stale object files after a reinstall) — a state that otherwise corrupts memory silently. Do not pass this argument manually.

Parameters:: headerLayoutStamp – [in] ABI guard value; leave it defaulted

inline explicit World(const std::string &configFile, const std::vector<ParameterContainer> &params = {})

Create a world from a file. The format is chosen from the extension and content: .usd/.usda/.usdc/.usdz (USD articulation, see addUsdArticulatedSystem()), .rscene (RaiSim Engine scene, see getRscene()), otherwise an XML file whose content contains a <mujoco> (MJCF) or <raisim> (RaiSim world config) element. A RaiSim world config can include one .rscene scene with <include value=”scene.rscene”/>, e.g. to keep a robot separate from the scene it runs in.

Parameters:

configFile – [in] path to the file
params – [in] template parameters substituted into a RaiSim XML config (@@name tokens). Ignored for other formats

void exportToXml(const std::string &dir, const std::string &fileName)

export the world to an xml config file, which can be loaded using a constructor

Parameters:

dir – [in] directory to save the xml file
fileName – [in] file name

inline void exportToXml(const std::string &pathIn)

export the world to an xml config file, which can be loaded using a constructor

Parameters:: pathIn – [in] path to save the xml file

std::vector<std::string> exportMeshAssetsToObj(const std::string &directory, const std::string &prefix = "mesh") const

Exports every Mesh object in the world as an OBJ file named “\<prefix\>_\<object name or index\>_\<mesh index\>.obj”. The directory is created if needed.

Parameters:

directory – [in] output directory
prefix – [in] file name prefix

Returns:

paths of the written files, in the world’s object list order

inline void setTimeStep(double dt)

set the time step. Fatal if dt is not finite and positive.

Parameters:: dt – [in] the time step (s)

inline double getTimeStep() const

Returns:: the time step (s)

Sphere *addSphere(double radius, double mass, const std::string &material = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Add a dynamic sphere centered at the origin. Set its pose with SingleBodyObject::setPosition() etc.

Parameters:

radius – [in] radius (m)
mass – [in] mass (kg)
material – [in] material of the sphere (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”.

Returns:

pointer to the created sphere, owned by the world

Box *addBox(double xLength, double yLength, double zLength, double mass, const std::string &material = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Add a dynamic box centered at the origin.

Parameters:

xLength – [in] full length along the body x axis (m)
yLength – [in] full length along the body y axis (m)
zLength – [in] full length along the body z axis (m)
mass – [in] mass (kg)
material – [in] material of the box (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”.

Returns:

pointer to the created box, owned by the world

Cylinder *addCylinder(double radius, double height, double mass, const std::string &material = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Add a dynamic cylinder centered at the origin, with its axis along the body z axis.

Parameters:

radius – [in] radius (m)
height – [in] full height (m)
mass – [in] mass (kg)
material – [in] material of the cylinder (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”.

Returns:

pointer to the created cylinder, owned by the world

Capsule *addCapsule(double radius, double height, double mass, const std::string &material = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Add a dynamic capsule centered at the origin, with its axis along the body z axis.

Parameters:

radius – [in] radius of the hemispheres and the cylinder (m)
height – [in] distance between the two hemisphere centers (m)
mass – [in] mass (kg)
material – [in] material of the capsule (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”.

Returns:

pointer to the created capsule, owned by the world

Ground *addGround(double zHeight = 0.0, const std::string &material = "default", CollisionGroup collisionMask = CollisionGroup(-1))

Add an infinite static ground plane (a half space below z = zHeight).

Parameters:

zHeight – [in] height of the plane (m)
material – [in] material of the ground (which defines the contact dynamics)
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”. The collision group of the ground is always RAISIM_STATIC_COLLISION_GROUP

Returns:

pointer to the created ground, owned by the world

HeightMap *addHeightMap(size_t xSamples, size_t ySamples, double xSize, double ySize, double centerX, double centerY, const std::vector<double> &height, const std::string &material = "default", CollisionGroup collisionGroup = (CollisionGroup(1) << 63), CollisionGroup collisionMask = CollisionGroup(-1))

Create a heightmap, copying every height sample unchanged, including NaN and infinity. The sample count and geometry must be valid.

Parameters:

xSamples – [in] how many points along x axis
ySamples – [in] how many points along y axis
xSize – [in] x width of the height map
ySize – [in] y length of the height map
centerX – [in] x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
centerY – [in] y coordinate of the grid center in the height map frame
height – [in] heights (m), which may be NaN or infinity. Its size must be xSamples * ySamples (fatal otherwise).
material – [in] material of the height map (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created height map, owned by the world

DeformableTerrain *addDeformableTerrain(size_t xSamples, size_t ySamples, double xSize, double ySize, double centerX, double centerY, const std::vector<double> &heights, const DeformableTerrain::Material &soil = DeformableTerrain::Material(), const std::string &material = "default", CollisionGroup collisionGroup = (CollisionGroup(1) << 63), CollisionGroup collisionMask = CollisionGroup(-1)): Create a triangulated deformable soil surface. See DeformableTerrain for the material model, units and spatial accuracy. The world owns it; it is a HEIGHTMAP for rendering. Heights must be finite. The terrain is static in pose and deforms along its local Z axis.

HeightMap *addHeightMap(const std::string &raisimHeightMapFileName, double centerX, double centerY, const std::string &material = "default", CollisionGroup collisionGroup = (CollisionGroup(1) << 63), CollisionGroup collisionMask = CollisionGroup(-1))

Parameters:

raisimHeightMapFileName – [in] the raisim text file which will be used to create the height map
centerX – [in] x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
centerY – [in] y coordinate of the grid center in the height map frame
material – [in] material of the height map (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created height map

HeightMap *addHeightMap(const std::string &pngFileName, double centerX, double centerY, double xSize, double ySize, double heightScale, double heightOffset, const std::string &material = "default", CollisionGroup collisionGroup = (CollisionGroup(1) << 63), CollisionGroup collisionMask = CollisionGroup(-1))

Parameters:

pngFileName – [in] the png file which will be used to create the height map
centerX – [in] x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
centerY – [in] y coordinate of the grid center in the height map frame
xSize – [in] x width of the height map
ySize – [in] y length of the height map
heightScale – [in] a png file (if 8-bit) has pixel values from 0 to 255. This parameter scales the pixel values to the actual height
heightOffset – [in] height of the 0-value pixel
material – [in] material of the height map (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created height map

HeightMap *addHeightMap(double centerX, double centerY, TerrainProperties &terrainProperties, const std::string &material = "default", CollisionGroup collisionGroup = (CollisionGroup(1) << 63), CollisionGroup collisionMask = CollisionGroup(-1))

Parameters:

centerX – [in] x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
centerY – [in] y coordinate of the grid center in the height map frame
terrainProperties – [in] perlin noise parameters which will be used to create the height map
material – [in] material of the height map (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created height map

HeightMap *addHeightMap(const HeightMap *heightmapToBeCloned, CollisionGroup collisionGroup = (CollisionGroup(1) << 63), CollisionGroup collisionMask = CollisionGroup(-1))

Create a copy of another height map (samples, size, center, heights and material) with the same pose.

Parameters:

heightmapToBeCloned – [in] Another height map to be cloned. Fatal if nullptr
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created height map

ArticulatedSystem *addArticulatedSystem(const std::string &filePathOrURDFScript, const std::string &resPath = "", const std::vector<std::string> &jointOrder = {}, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1), ArticulatedSystemOption options = ArticulatedSystemOption())

Parameters:

filePathOrURDFScript – [in] Path to urdf file or a URDF string. Depending on the contents of the string, RaiSim will interpret it as an xml string or a file path.
resPath – [in] Path to the resource directory. Leave it empty (“”) if it is the urdf file directory
jointOrder – [in] this can be used to redefine the joint order. A child cannot precede its parent. Leave it empty ({}) to use the joint order defined in the URDF file.
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”
options – [in] Supports “doNotCollideWithParent” and “convexifyCollisionMeshes”

Returns:

pointer to the articulated system

ArticulatedSystem *addArticulatedSystem(const std::string &filePathOrURDFScript, const std::vector<std::string> &modules, const std::string &resPath = "", const std::vector<std::string> &jointOrder = {}, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1), ArticulatedSystemOption options = ArticulatedSystemOption())

Parameters:

filePathOrURDFScript – [in] Path to urdf file or a URDF string. Depending on the contents of the string, RaiSim will interpret it as an xml string or a file path.
modules – [in] Optional URDF modules to include (URDF fragments).
resPath – [in] Path to the resource directory. Leave it empty (“”) if it is the urdf file directory
jointOrder – [in] this can be used to redefine the joint order. A child cannot precede its parent. Leave it empty ({}) to use the joint order defined in the URDF file.
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”
options – [in] Supports “doNotCollideWithParent” and “convexifyCollisionMeshes”

Returns:

pointer to the articulated system

ArticulatedSystem *addArticulatedSystem(const std::string &xmlFileTemplate, const std::vector<ParameterContainer> &params, const std::string &resPath = "", const std::vector<std::string> &jointOrder = {}, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1), ArticulatedSystemOption options = ArticulatedSystemOption())

Parameters:

xmlFileTemplate – [in] xml template file.
params – [in] parameters for the xml file.
resPath – [in] Path to the resource directory. Leave it empty (“”) if it is the urdf file directory
jointOrder – [in] this can be used to redefine the joint order. A child cannot precede its parent. Leave it empty ({}) to use the joint order defined in the URDF file.
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”
options – [in] Supports “doNotCollideWithParent” and “convexifyCollisionMeshes”

Returns:

pointer to the articulated system

ArticulatedSystem *addArticulatedSystem(const Child &child, const std::string &resPath = "", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1), ArticulatedSystemOption options = ArticulatedSystemOption())

This method programmatically creates an articulated system without an URDF file.

Parameters:

child – [in] an instance of Child class which has an articulated system structure.
resPath – [in] Path to the resource directory. Leave it empty (“”) if it is the urdf file directory
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”
options – [in] Supports “doNotCollideWithParent” and “convexifyCollisionMeshes”

Returns:

pointer to the articulated system

ArticulatedSystem *addUsdArticulatedSystem(const std::string &usdPath, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1), ArticulatedSystemOption options = ArticulatedSystemOption())

Imports a USD Physics articulation scene.

Parameters:

usdPath – [in] Path to a .usd/.usda/.usdc/.usdz file with a PhysicsArticulationRootAPI.
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”
options – [in] Supports “doNotCollideWithParent” and “convexifyCollisionMeshes”

Returns:

pointer to the imported articulated system

Compound *addCompound(const std::vector<Compound::CompoundObjectChild> &children, double mass, Vec<3> COM, const Mat<3, 3> &inertia, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Add a single body which is composed of multiple primitive collision shapes

Parameters:

children – [in] a vector of CompoundObjectChild which contains each primitive shape’s position, orientation, material and shape parameters
mass – [in] mass of the composite body
COM – [in] center of mass of the composite body, in the body frame
inertia – [in] inertia of the composite body about its center of mass, in the body frame
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created compound object

Mesh *addMesh(const std::string &meshFileInObjFormat, double mass, const Mat<3, 3> &inertia, const Vec<3> &COM, double scale = 1, const std::string &material = "", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

create mesh collision body. Any mesh format supported by Assimp can be used; USD files are loaded through OpenUSD.

Parameters:

meshFileInObjFormat – [in] mesh file of the object
mass – [in] mass
inertia – [in] inertia
COM – [in] the center of the mass
scale – [in] rescale the mesh
material – [in] material of the mesh (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created convexified mesh, or original mesh if CoACD fails

Mesh *addMesh(const std::string &meshFileInObjFormat, double mass, const Mat<3, 3> &inertia, const Vec<3> &COM, double scale, const std::string &material, MeshCollisionMode collisionMode, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1), const CoacdOptions &coacdOptions = CoacdOptions())

create mesh collision body with an explicit mesh collision mode. Any mesh format supported by Assimp can be used; USD files are loaded through OpenUSD. MeshCollisionMode::ORIGINAL_MESH keeps the non-convex triangle mesh. MeshCollisionMode::CONVEX_HULL creates one convex hull. MeshCollisionMode::CONVEXIFY creates a CoACD convex decomposition using coacdOptions; if the decomposition fails, it warns and uses one convex hull instead.

Parameters:

meshFileInObjFormat – [in] mesh file of the object
mass – [in] mass
inertia – [in] inertia
COM – [in] the center of the mass
scale – [in] rescale the mesh
material – [in] material of the mesh (which defines the contact dynamics)
collisionMode – [in] original mesh, convex hull, or convex decomposition
coacdOptions – [in] convex decomposition parameters. Used only with MeshCollisionMode::CONVEXIFY.
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created mesh

Mesh *addMesh(const std::string &meshFileInObjFormat, double mass, const Mat<3, 3> &inertia, const Vec<3> &COM, double scale, const std::string &material, const CoacdOptions &coacdOptions, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

create mesh collision body approximated by CoACD convex decomposition.

Parameters:

meshFileInObjFormat – [in] mesh file of the object
mass – [in] mass
inertia – [in] inertia
COM – [in] the center of the mass
scale – [in] rescale the mesh
material – [in] material of the mesh (which defines the contact dynamics)
coacdOptions – [in] convex decomposition parameters
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created mesh

Mesh *addMesh(const std::string &meshFileInObjFormat, double mass, double scale = 1, const std::string &material = "", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

create mesh collision body. Any mesh format supported by Assimp can be used; USD files are loaded through OpenUSD. Inertia and COM are estimated by computing the axis-aligned bounding box of the (scaled) mesh and treating it as a uniform-density box.

Parameters:

meshFileInObjFormat – [in] mesh file of the object
mass – [in] mass
scale – [in] rescale the mesh
material – [in] material of the mesh (which defines the contact dynamics)
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created convexified mesh, or original mesh if CoACD fails

Mesh *addMesh(const std::string &meshFileInObjFormat, double mass, double scale, const std::string &material, MeshCollisionMode collisionMode, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1), const CoacdOptions &coacdOptions = CoacdOptions())

create mesh collision body with an explicit mesh collision mode. Inertia and COM are estimated by computing the axis-aligned bounding box of the (scaled) mesh and treating it as a uniform-density box. MeshCollisionMode::ORIGINAL_MESH keeps the non-convex triangle mesh. MeshCollisionMode::CONVEX_HULL creates one convex hull. MeshCollisionMode::CONVEXIFY creates a CoACD convex decomposition using coacdOptions; if the decomposition fails, it warns and uses one convex hull instead.

Parameters:

meshFileInObjFormat – [in] mesh file of the object
mass – [in] mass
scale – [in] rescale the mesh
material – [in] material of the mesh (which defines the contact dynamics)
collisionMode – [in] original mesh, convex hull, or convex decomposition
coacdOptions – [in] convex decomposition parameters. Used only with MeshCollisionMode::CONVEXIFY.
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created mesh

Mesh *addMesh(const std::string &meshFileInObjFormat, double mass, double scale, const std::string &material, const CoacdOptions &coacdOptions, CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

create mesh collision body approximated by CoACD convex decomposition. Inertia and COM are estimated by computing the axis-aligned bounding box of the (scaled) mesh and treating it as a uniform-density box.

Parameters:

meshFileInObjFormat – [in] mesh file of the object
mass – [in] mass
scale – [in] rescale the mesh
material – [in] material of the mesh (which defines the contact dynamics)
coacdOptions – [in] convex decomposition parameters
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created mesh

Mesh *addMesh(const Mesh *meshToClone, const std::string &material = "", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

create a mesh collision body that copies another mesh object

Parameters:

meshToClone – [in] mesh to copy (file, mass, inertia, COM and scale are reused)
material – [in] material of the new mesh; empty uses the source mesh’s material
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created mesh, owned by the world

DeformableObject *addDeformableCloth(const std::vector<Vec<3>> &vertices, const std::vector<DeformableObject::Triangle> &triangles, const std::vector<unsigned int> &pinnedVertices = {}, const DeformableObject::Material &material = DeformableObject::Material(), const std::string &contactMaterial = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Create a deformable cloth/shell object from vertices and triangle indices. The first implementation uses XPBD/PBD distance constraints generated from triangle edges and one spherical collision proxy per vertex.

Parameters:

vertices – [in] particle positions in world coordinates
triangles – [in] triangle vertex indices
pinnedVertices – [in] vertices held fixed in world coordinates
material – [in] deformable solver and material parameters
contactMaterial – [in] material used by collision proxies
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created deformable object

DeformableObject *addDeformableCloth(const std::string &meshFileInObjFormat, double scale = 1.0, const std::vector<unsigned int> &pinnedVertices = {}, const DeformableObject::Material &material = DeformableObject::Material(), const std::string &contactMaterial = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Create a deformable cloth/shell object from an OBJ triangle mesh. Polygon faces are triangulated as a fan. Texture and normal indices are ignored.

Parameters:

meshFileInObjFormat – [in] OBJ file path
scale – [in] vertex scale
pinnedVertices – [in] vertices held fixed in world coordinates
material – [in] deformable solver and material parameters
contactMaterial – [in] material used by collision proxies
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created deformable object

DeformableObject *addDeformableVolume(const std::vector<Vec<3>> &vertices, const std::vector<DeformableObject::Tetrahedron> &tetrahedra, const std::vector<unsigned int> &pinnedVertices = {}, const DeformableObject::Material &material = DeformableObject::Material(), const std::string &contactMaterial = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Create a deformable solid from a tetrahedral mesh (see DeformableObject::createVolume()). With a positive DeformableObject::Material::youngsModulus it is an elastic solid.

Parameters:

vertices – [in] particle positions in the world frame (m)
tetrahedra – [in] vertex indices of the tetrahedra
pinnedVertices – [in] vertices held fixed in world coordinates
material – [in] deformable solver and material parameters
contactMaterial – [in] material used by collision proxies
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created deformable object, owned by the world

DeformableObject *addDeformableObject(const std::string &meshFileInObjFormat, const DeformableObject::Material &material, const DeformableObject::MeshBuildOptions &options, const std::vector<unsigned int> &pinnedVertices = {}, const std::string &contactMaterial = "default", CollisionGroup collisionGroup = 1, CollisionGroup collisionMask = CollisionGroup(-1))

Create a deformable object from an OBJ mesh and particle generation options. Surface mode uses the mesh vertices as particles. Filled mode requires a closed triangle mesh and adds interior particles (an elastic solid of tetrahedra when the material has a Young’s modulus). Internal struts can be generated automatically through DeformableObject::MeshBuildOptions.

Parameters:

meshFileInObjFormat – [in] OBJ file path
material – [in] deformable solver and material parameters
options – [in] particle generation options
pinnedVertices – [in] vertices held fixed in world coordinates
contactMaterial – [in] material used by collision proxies
collisionGroup – [in] read “Contact and Collision/ Collision Group and Mask”
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”

Returns:

pointer to the created deformable object, owned by the world

GranularSystem *addGranularParticles(const std::vector<Vec<3>> &positions, const std::vector<double> &radii, const GranularSystem::Material &material = GranularSystem::Material())

Create a native granular particle system. Particles are stored and stepped as one object instead of thousands of independent Sphere objects. Particle-particle DEM contacts are handled internally; particles also collide with the world’s spheres, boxes, capsules, cylinders, compounds, meshes, height maps and articulated systems, and optionally with a horizontal ground plane (GranularSystem::setGroundPlane(); the world’s Ground object is not used) or a box container.

Parameters:

positions – [in] initial particle positions in the world frame (m)
radii – [in] particle radii (m), one per position
material – [in] particle material parameters

Returns:

pointer to the created granular system, owned by the world

GranularSystem *addGranularBox(const GranularSystem::BoxOptions &options, const GranularSystem::Material &material = GranularSystem::Material())

Create a granular system filled with equal particles on a regular grid inside an axis-aligned box (see GranularSystem::BoxOptions). Every particle gets the options’ velocity, angular velocity, material id and fixed flag.

Parameters:

options – [in] box extent, particle radius, grid spacing and initial particle state
material – [in] particle material parameters

Returns:

pointer to the created granular system, owned by the world

Object *getObject(const std::string &name)

Parameters:: name – [in] object name, set by Object::setName()
Returns:: the first object with the given name, or nullptr if none exists

StiffLengthConstraint *addStiffWire(Object *obj1, size_t localIdx1, Vec<3> pos1_b, Object *obj2, size_t localIdx2, Vec<3> pos2_b, double length)

Stiff unilateral constraint. It cannot push. It can only pull.

Parameters:

obj1 – [in] the first object the wire is attached to
localIdx1 – [in] the body index (0 for a SingleBodyObject) for the first object
pos1_b – [in] location of the cable attachment on the first object
obj2 – [in] the second object the wire is attached to
localIdx2 – [in] the body index (0 for a SingleBodyObject) for the second object
pos2_b – [in] location of the cable attachment on the second object
length – [in] length of the wire

Returns:

pointer to the created wire

CompliantLengthConstraint *addCompliantWire(Object *obj1, int localIdx1, Vec<3> pos1_b, Object *obj2, int localIdx2, Vec<3> pos2_b, double length, double stiffness)

soft unilateral constraint. It cannot push. It can only pull.

Parameters:

obj1 – [in] the first object the wire is attached to
localIdx1 – [in] the body index (0 for a SingleBodyObject) for the first object
pos1_b – [in] location of the cable attachment on the first object
obj2 – [in] the second object the wire is attached to
localIdx2 – [in] the body index (0 for a SingleBodyObject) for the second object
pos2_b – [in] location of the cable attachment on the second object
length – [in] length of the wire
stiffness – [in] stiffness of the wire

Returns:

pointer to the created wire

CustomLengthConstraint *addCustomWire(Object *obj1, int localIdx1, Vec<3> pos1_b, Object *obj2, int localIdx2, Vec<3> pos2_b, double length)

Custom wire that applies user-set tension between two points.

Parameters:

obj1 – [in] the first object the wire is attached to
localIdx1 – [in] the body index (0 for a SingleBodyObject) for the first object
pos1_b – [in] location of the cable attachment on the first object
obj2 – [in] the second object the wire is attached to
localIdx2 – [in] the body index (0 for a SingleBodyObject) for the second object
pos2_b – [in] location of the cable attachment on the second object
length – [in] length of the wire. You can use this to compute how much it stretched from a nominal length. It might not be necessary for some wire types.

Returns:

pointer to the created wire

Tendon *addSpatialTendon(const std::string &name, const std::vector<Tendon::PathElement> &path, const Tendon::Properties &properties = Tendon::Properties())

Adds a spatial tendon: a massless cable routed through sites and wrapped around sphere or cylinder obstacles, optionally split into pulley branches. Spatial branches start/end at sites; consecutive obstacles require a via site.

Parameters:

name – [in] unique tendon name. Used by getTendon() and in exported XML
path – [in] ordered route elements (see Tendon::PathElement)
properties – [in] spring, limit, friction, armature and visualization settings

Returns:

pointer to the created tendon. The world owns it

Tendon *addFixedTendon(const std::string &name, const std::vector<Tendon::JointTerm> &joints, const Tendon::Properties &properties = Tendon::Properties())

Adds a fixed tendon whose length is a weighted sum of scalar joint coordinates.

Parameters:

name – [in] unique tendon name
joints – [in] joint terms (articulated system, joint name, coefficient)
properties – [in] spring, limit, friction, armature and visualization settings

Returns:

pointer to the created tendon. The world owns it

TendonCoupling *addTendonCoupling(const std::string &name, Tendon *first, Tendon *second = nullptr, const TendonCoupling::Properties &properties = TendonCoupling::Properties())

Couples the lengths of two tendons through a polynomial relation (see TendonCoupling::Properties).

Parameters:

name – [in] unique coupling name
first – [in] the tendon whose length is constrained
second – [in] the driving tendon. nullptr fixes the first tendon’s length
properties – [in] polynomial coefficients, compliance and error correction

Returns:

pointer to the created coupling. The world owns it

Tendon *getTendon(const std::string &name) const

Parameters:: name – [in] tendon name
Returns:: the tendon with the given name, or nullptr if none exists

const std::vector<std::unique_ptr<Tendon>> &getTendons() const

Returns:: all tendons in the world, in creation order

void onGranularParticleRemoved(GranularSystem *grains, size_t removedIndex, size_t lastIndex)

Internal: keep tendon attachments valid when granular storage swaps a particle.

Parameters:

grains – [in] the granular system
removedIndex – [in] removed particle
lastIndex – [in] particle moved into removedIndex

const std::vector<std::unique_ptr<TendonCoupling>> &getTendonCouplings() const

Returns:: all tendon couplings in the world, in creation order

void removeTendon(Tendon *tendon)

removes a tendon, every coupling that references it, and any legacy wire adapter bound to it

Parameters:: tendon – [in] the tendon to be removed

void removeTendonCoupling(TendonCoupling *coupling)

removes a tendon coupling

Parameters:: coupling – [in] the coupling to be removed

Constraints *getConstraint(const std::string &name)

Parameters:: name – [in] wire name, set by LengthConstraint::setName()
Returns:: a constraint (e.g., wires) with the given name. returns nullptr if it doesn’t exist. This is equivalent to getWire(const std::string&)

LengthConstraint *getWire(const std::string &name)

Parameters:: name – [in] wire name, set by LengthConstraint::setName()
Returns:: a wire with the given name. returns nullptr if it doesn’t exist

inline std::vector<std::unique_ptr<LengthConstraint>> &getWires()

Returns:: the legacy wire adapters (stiff, compliant and custom wires). Their physics runs on tendons

void removeObject(LengthConstraint *wire)

removes a wire (i.e., LengthConstraint) and the tendon that implements it

Parameters:: wire – [in] the wire to be removed

inline Object *getObject(std::size_t worldIndex)

World indices change when an object is removed (the last object takes the removed index); use getObjectById() for a stable handle.

Parameters:: worldIndex – [in] index in [0, getObjectCount()). Not bounds-checked
Returns:: object with the given index. This index can be retrieved by Object::getIndexInWorld()

inline std::size_t getObjectCount() const

Returns:: the number of objects in the world

Object *getObjectById(ObjectId id)

Parameters:: id – [in] stable runtime id (Object::getId())
Returns:: object with the stable runtime id, or nullptr if the object no longer exists.

const Object *getObjectById(ObjectId id) const

Parameters:: id – [in] stable runtime id (Object::getId())
Returns:: object with the stable runtime id, or nullptr if the object no longer exists.

bool isObjectAlive(ObjectId id) const

Parameters:: id – [in] stable runtime id (Object::getId())
Returns:: true if an object with the stable runtime id currently exists in the world.

std::vector<Object*> &getObjList()

Returns:: returns a non-const vector of the objects

inline unsigned long getConfigurationNumber()

Returns:: the configuration number. this number is updated every time an object is added or removed

inline const CollisionCounters &getLastCollisionCounters() const

Returns:: the collision counters of the last step. Only updated while counters are enabled

inline void setCollisionCountersEnabled(bool enabled)

Enable or disable collection of CollisionCounters (disabled by default).

Parameters:: enabled – [in] true to collect counters

inline bool getCollisionCountersEnabled() const

Returns:: true if CollisionCounters are being collected

Checkpoint captureCheckpoint() const

Capture between complete integration steps. Includes controls, pending forces, sensors, sleeping islands and solver history. Object/constraint/sensor topology must remain unchanged until restore. Checkpoints belong to this World instance; they are not portable files. Throws std::logic_error during a split step (between integrate1() and integrate2()).

Returns:: the captured checkpoint

bool restoreCheckpoint(const Checkpoint &checkpoint, std::string *error = nullptr)

Restore a checkpoint for rewind/resume. Rejected checkpoints leave the world unchanged and return an explanation in error. External controllers, renderer state and application-owned random generators are outside the World. Rejected when called during a split step, for an empty checkpoint, a checkpoint of another World, or after the object/constraint/sensor/collision topology changed.

Parameters:

checkpoint – [in] checkpoint captured from this World
error – [out] if not nullptr, receives the reason of a rejection

Returns:

true if the checkpoint was restored

bool setObjectCollisionFilter(Object *object, CollisionGroup collisionGroup, CollisionGroup collisionMask, size_t localIdx = size_t(-1))

Updates collision group and mask for all collision bodies on an object, or for a specific local body. Call this between simulation steps.

Parameters:

object – [in] object in this world
collisionGroup – [in] new collision group
collisionMask – [in] new collision mask
localIdx – [in] local body index, or size_t(-1) for all bodies of the object

Returns:

false if the object is not in this world or no collision body matched

bool setObjectMaterial(Object *object, const std::string &material, size_t localIdx = size_t(-1))

Updates the collision material for all collision bodies on an object, or for a specific local body. Call this between simulation steps.

Parameters:

object – [in] object in this world
material – [in] new material name
localIdx – [in] local body index, or size_t(-1) for all bodies of the object

Returns:

false if the object is not in this world or no collision body matched

bool captureSingleBodySnapshot(const SingleBodyObject *object, SingleBodySnapshot &snapshot) const

Captures a single-body runtime state snapshot.

Parameters:

object – [in] object in this world
snapshot – [out] receives the state

Returns:

false (snapshot untouched) if the object is not in this world

bool restoreSingleBodySnapshot(SingleBodyObject *object, const SingleBodySnapshot &snapshot, bool restoreCollisionProperties = true)

Restores a single-body runtime state snapshot. If restoreCollisionProperties is true, collision group, mask, and material are restored as well.

Parameters:

object – [in] object in this world, of the same ObjectType as the snapshot
snapshot – [in] state to restore
restoreCollisionProperties – [in] also restore material, collision group and mask

Returns:

false if the object is not in this world or its type differs from the snapshot

bool restoreSingleBodySnapshot(ObjectId id, const SingleBodySnapshot &snapshot, bool restoreCollisionProperties = true)

Restores a single-body runtime state snapshot by stable object id.

Parameters:

id – [in] stable object id
snapshot – [in] state to restore
restoreCollisionProperties – [in] also restore material, collision group and mask

Returns:

false if no single-body object with the id exists or its type differs from the snapshot

SingleBodyObject *cloneSingleBodyObject(const SingleBodyObject *source, const std::string &name = "")

Clones primitive single-body objects with pose, velocity, mass, body type, material, collision filter, and appearance. Supported types are sphere, box, cylinder and capsule.

Parameters:

source – [in] object in this world
name – [in] name of the clone; empty keeps the default name

Returns:

the new object (owned by the world), or nullptr for unsupported types or an object not in this world

const RayCollisionList &rayTest(const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &start, const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &direction, double length, size_t objectId = size_t(-10), size_t localId = size_t(-10), CollisionGroup collisionMask = CollisionGroup(-1))

Casts a ray and returns the closest hit. The returned list holds zero or one item, and it is overwritten by the next ray test.

Parameters:

start – [in] The start position of the ray in the world frame (m).
direction – [in] The direction of the ray in the world frame. It is normalized internally; a zero vector is treated as +z.
length – [in] The length of the ray (m). A non-positive length returns no hit.
objectId – [in] Collision with the body whose object world index (Object::getIndexInWorld()) and local body index match objectId and localId is ignored. Both must be set (not size_t(-10)) for this to take effect. This can be useful if the sensor is attached to a robot.
localId – [in] Local body index of the ignored body. See objectId.
collisionMask – [in] Collision mask to filter collisions. By default, it records collisions with all collision groups.

Returns:

A reference to the world’s internal hit list.

inline const RayCollisionList &rayTest(std::initializer_list<double> start, std::initializer_list<double> direction, double length, size_t objectId = size_t(-10), size_t localId = size_t(-10), CollisionGroup collisionMask = CollisionGroup(-1))

Same as the Eigen overload, with start and direction given as {x, y, z}. Fatal if a list does not have 3 elements.

Parameters:

start – [in] ray start in the world frame (m)
direction – [in] ray direction in the world frame
length – [in] ray length (m)
objectId – [in] world index of the object whose body is ignored (see the Eigen overload)
localId – [in] local index of the ignored body
collisionMask – [in] collision mask to filter hits

Returns:

the world’s internal hit list (zero or one item)

inline const RayCollisionList &rayTest(std::initializer_list<double> start, const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &direction, double length, size_t objectId = size_t(-10), size_t localId = size_t(-10), CollisionGroup collisionMask = CollisionGroup(-1))

Same as the Eigen overload, with start given as {x, y, z}. Fatal if start does not have 3 elements.

Parameters:

start – [in] ray start in the world frame (m)
direction – [in] ray direction in the world frame
length – [in] ray length (m)
objectId – [in] world index of the object whose body is ignored (see the Eigen overload)
localId – [in] local index of the ignored body
collisionMask – [in] collision mask to filter hits

Returns:

the world’s internal hit list (zero or one item)

inline const RayCollisionList &rayTest(const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &start, std::initializer_list<double> direction, double length, size_t objectId = size_t(-10), size_t localId = size_t(-10), CollisionGroup collisionMask = CollisionGroup(-1))

Same as the Eigen overload, with direction given as {x, y, z}. Fatal if direction does not have 3 elements.

Parameters:

start – [in] ray start in the world frame (m)
direction – [in] ray direction in the world frame
length – [in] ray length (m)
objectId – [in] world index of the object whose body is ignored (see the Eigen overload)
localId – [in] local index of the ignored body
collisionMask – [in] collision mask to filter hits

Returns:

the world’s internal hit list (zero or one item)

void rayTestLidar(const Mat<3, 3> &rot, const Vec<3> &pos, double yawStartAngle, double yawIncrement, size_t yawCount, double pitchStartAngle, double pitchIncrement, size_t pitchCount, double rangeMin, double rangeMax, size_t objectId, size_t localId, CollisionGroup collisionMask, std::vector<Vec<3>, AlignedAllocator<Vec<3>, 32>> &scan)

Ray-cast helper for spinning lidar scans. Applies a frustum-based broadphase before running per-ray collision tests.

Parameters:

rot – [in] Sensor orientation (sensor frame to world frame).
pos – [in] Sensor position in world frame.
yawStartAngle – [in] First yaw angle in radians.
yawIncrement – [in] Signed yaw increment in radians.
yawCount – [in] Number of yaw samples.
pitchStartAngle – [in] First pitch angle in radians.
pitchIncrement – [in] Pitch increment in radians.
pitchCount – [in] Number of pitch samples.
rangeMin – [in] Minimum range in meters.
rangeMax – [in] Maximum range in meters.
objectId – [in] Object id to ignore (sensor owner).
localId – [in] Local body id to ignore (sensor owner).
collisionMask – [in] Collision mask to filter collisions.
scan – [out] Output scan points in the sensor frame.

void getRayCastBodies(std::vector<RayCastBody> &bodies)

Collects the collision bodies that ray tests see, with their current world poses. A ray test with collision mask m skips a body when (body.collisionGroup & m) == 0 or body.collisionMask == 0. The referenced mesh and heightmap data stay valid until the owning object is removed or changed.

Parameters:: bodies – [out] cleared, then filled with one entry per collision body

void captureDepthCamera(const Vec<3> &pos, const Mat<3, 3> &rot, const DepthCameraProperties &properties, DepthCameraFrame &frame, size_t objectId = size_t(-10), size_t localId = size_t(-10), CollisionGroup collisionMask = CollisionGroup(-1))

Captures a deterministic CPU ray-based depth camera frame. The camera uses the same convention as RaiSim depth sensors: +X is forward, +Y is left, and +Z is up in the camera frame. Depth is the distance along the camera forward axis, segmentation is the hit object’s world index, and -1 denotes background. Each pixel is one rayTest() call, so this is costly for large images. Fatal if the properties are invalid (see DepthCameraProperties).

Parameters:

pos – [in] camera position in the world frame (m)
rot – [in] camera orientation (camera frame to world frame)
properties – [in] image size, clipping, field of view, outputs and noise
frame – [out] receives the captured buffers
objectId – [in] world index of an object body to ignore (see rayTest())
localId – [in] local index of the body to ignore (see rayTest())
collisionMask – [in] collision mask to filter hits

void removeObject(Object *obj)

removes and deletes an object. Wires attached to it and tendon references to it are removed as well. The last object in the world list takes the removed object’s world index. Prints a message and does nothing else if the object is not in this world.

Parameters:: obj – [in] object to be removed. The pointer is invalid afterwards

void integrate(): integrate the world It is equivalent to “integrate1(); integrate2();”

void integrate1(): It performs 1) deletion contacts from previous time step 2) collision detection 3) register contacts to each body 4) calls “preContactSolverUpdate1()” of each object

void integrate2(): It performs 1) calls “preContactSolverUpdate2()” of each body 2) run collision solver 3) calls “integrate” method of each object

void integrateNoContactDetection(): It performs 1) deletion contacts from previous time step 2) updates collision objects 3) calls “preContactSolverUpdate1()” of each object It skips contact detection and contact problem construction.

inline const contact::ContactProblems *getContactProblem() const

Returns:: the contact problems (one per contact) built in the last integrate1() call. Owned by the world and overwritten in the next step

void setGravity(const Vec<3> &gravity)

Set gravity

Parameters:: gravity – [in] gravitational acceleration of the world in the world frame (m/s^2)

void updateMaterialProp(const MaterialManager &prop)

this deletes the existing material props and replace them with the argument

Parameters:: prop – [in] new material prop

void setMaterialPairProp(const std::string &mat1, const std::string &mat2, double friction, double restitution, double resThreshold)

Add a new material pair property. In RaiSim, material property is defined by the pair. The static friction coefficient is set to friction and the static friction velocity threshold to 1e-3 m/s.

Parameters:

mat1 – [in] name of the first material (the order of mat1 and mat2 is not important)
mat2 – [in] name of the second material
friction – [in] the coefficient of friction
restitution – [in] the coefficient of restitution
resThreshold – [in] the minimum impact velocity (m/s) to make the object bounce

void setMaterialPairProp(const std::string &mat1, const std::string &mat2, double friction, double restitution, double resThreshold, double staticFriction, double staticFrictionThresholdVelocity)

Add a new material pair property. In RaiSim, material property is defined by the pair.

Parameters:

mat1 – [in] name of the first material (the order of mat1 and mat2 is not important)
mat2 – [in] name of the second material
friction – [in] the dynamic coefficient of friction
restitution – [in] the coefficient of restitution
resThreshold – [in] the minimum impact velocity (m/s) to make the object bounce
staticFriction – [in] the static coefficient of friction
staticFrictionThresholdVelocity – [in] if the relative velocity of two points is bigger than this value, then the dynamic coefficient of friction is applied. Otherwise, the coefficient of friction is interpolated between the static and dynamic one proportional to the relative velocity.

void setMaterialPairProp(const std::string &mat1, const std::string &mat2, double friction, double restitution, double resThreshold, double staticFriction, double staticFrictionThresholdVelocity, double rollingFriction, double spinningFriction)

Add a material pair property with rolling and spinning friction. The rolling and spinning coefficients are zero by default in existing overloads, which keeps the standard contact solver path unchanged.

Parameters:

mat1 – [in] name of the first material (the order of mat1 and mat2 is not important)
mat2 – [in] name of the second material
friction – [in] the dynamic coefficient of friction
restitution – [in] the coefficient of restitution
resThreshold – [in] the minimum impact velocity (m/s) to make the object bounce
staticFriction – [in] the static coefficient of friction
staticFrictionThresholdVelocity – [in] static-to-dynamic friction transition speed (m/s), see the overload above
rollingFriction – [in] the coefficient of rolling friction
spinningFriction – [in] the coefficient of spinning friction

void setDefaultMaterial(double friction, double restitution, double resThreshold)

this default material property is used if a material pair property is not defined for the specific collision. The static friction coefficient is set to friction and the static friction velocity threshold to 1e-3 m/s.

Parameters:

friction – [in] the coefficient of friction
restitution – [in] the coefficient of restitution
resThreshold – [in] the minimum impact velocity (m/s) to make the object bounce

void setDefaultMaterial(double friction, double restitution, double resThreshold, double staticFriction, double staticFrictionThresholdVelocity)

this default material property is used if a material pair property is not defined for the specific collision

Parameters:

friction – [in] the coefficient of friction
restitution – [in] the coefficient of restitution
resThreshold – [in] the minimum impact velocity (m/s) to make the object bounce
staticFriction – [in] the static coefficient of friction
staticFrictionThresholdVelocity – [in] if the relative velocity of two points is bigger than this value, then the dynamic coefficient of friction is applied. Otherwise, the coefficient of friction is interpolated between the static and dynamic one proportional to the relative velocity.

void setDefaultMaterial(double friction, double restitution, double resThreshold, double staticFriction, double staticFrictionThresholdVelocity, double rollingFriction, double spinningFriction)

Same as above, with rolling and spinning friction for the default material.

Parameters:

friction – [in] the coefficient of friction
restitution – [in] the coefficient of restitution
resThreshold – [in] the minimum impact velocity (m/s) to make the object bounce
staticFriction – [in] the static coefficient of friction
staticFrictionThresholdVelocity – [in] static-to-dynamic friction transition speed (m/s)
rollingFriction – [in] the coefficient of rolling friction
spinningFriction – [in] the coefficient of spinning friction

inline const Vec<3> &getGravity() const

Returns:: gravitational acceleration of the world in the world frame (m/s^2)

void setERP(double erp, double erp2 = 0)

Changes the Error Reduction Parameter. It often has very minimalistic impact on simulation

Parameters:

erp – [in] spring constant between object. This constant is scaled by the apparent inertia so it has no well-defined physical meaning
erp2 – [in] damping constant between object. This constant is scaled by the apparent inertia so it has no well-defined physical meaning

void setContactSolverParam(double alpha_init, double alpha_min, double alpha_decay, int maxIter, double threshold)

Changes the contact solver parameter. For details, please check “Hwangbo, Jemin, Joonho Lee, and Marco Hutter. “Per-contact iteration method for solving contact dynamics.” IEEE Robotics and Automation Letters 3.2 (2018): 895-902.” We found that the three default alpha values are always the best. So they are hardcoded now. So only the maxIter and threshold will affect the simulation. The three input alpha values will be ignored

Parameters:

alpha_init – [in] NOT_USED_ANYMORE (default: 1.0) how aggressive the solver is initially
alpha_min – [in] NOT_USED_ANYMORE (default: 1.0) how aggressive the solver is after an infinite number of solver iterations
alpha_decay – [in] NOT_USED_ANYMORE (default: 1.0) how fast alpha converges from alpha_init to alpha_min
threshold – [in] (default: 1e-8) error threshold for termination
maxIter – [in] (default: 150) the maximum number of iterations allowed

void setContactSettings(const ::contact::ContactSettings &settings)

Configure contact detection (broadphase/narrowphase) settings. Call this when the world is not stepping.

Parameters:: settings – [in] Contact detector settings.

void setSleepingEnabled(bool enabled)

Enable or disable sleeping islands. Disabling wakes every sleeping object.

Parameters:: enabled – [in] true to enable

bool isSleepingEnabled() const

Returns:: true if sleeping islands are enabled.

void setSleepingParameters(double linearVelThreshold, double angularVelThreshold, int quietSteps)

Configure sleeping thresholds. Both speed thresholds must be satisfied for quietSteps consecutive steps. Motion above either threshold or a user modification resets the counter. The quiet duration is quietSteps times the simulation time step.

Parameters:

linearVelThreshold – [in] linear speed threshold (m/s); negative values are clamped to 0
angularVelThreshold – [in] angular speed threshold (rad/s); negative values are clamped to 0
quietSteps – [in] required consecutive quiet steps; values below 1 are clamped to 1

const SleepSettings &getSleepingParameters() const

Returns:: the current sleeping configuration.

void setSleepingVelocityThresholds(double linearVelThreshold, double angularVelThreshold)

Update only the sleeping velocity thresholds.

Parameters:

linearVelThreshold – [in] linear speed threshold (m/s); negative values are clamped to 0
angularVelThreshold – [in] angular speed threshold (rad/s); negative values are clamped to 0

void wakeObject(Object *object)

Wake a specific object (and its island) on the next step.

Parameters:: object – [in] object in this world

void wakeAll(): Wake all objects.

bool isObjectSleeping(const Object *object) const

Parameters:: object – [in] object in this world
Returns:: true if the object is currently sleeping. Always false while sleeping is disabled.

bool isObjectSleeping(std::size_t objectIndex) const

Parameters:: objectIndex – [in] world index of the object
Returns:: true if the object is currently sleeping. False for an out-of-range index or while sleeping is disabled.

void setBroadphaseSettings(const ::contact::BroadphaseSettings &settings)

Configure broadphase settings only. Call this when the world is not stepping.

Parameters:: settings – [in] Broadphase settings.

inline const ::contact::ContactSettings &getContactSettings() const

Returns:: current contact detection settings.

inline const ::contact::BroadphaseSettings &getBroadphaseSettings() const

Returns:: current broadphase settings.

inline double getWorldTime() const

Returns:: the total integrated time (s), advanced by the time step at every integrate2() call

inline void setWorldTime(double time)

manually adjust the world time

Parameters:: time – [in] the world time (s)

inline raisim::contact::BisectionContactSolver &getContactSolver()

Returns:: a non-const ref of the contact solver. contact::BisectionContactSolver::setOrder(bool) can be used to make the solver deterministic

inline void setContactSolverIterationOrder(bool order)

This sets the iteration order (e.g., forward and backward) of the contact solver. Given this order, Raisim is deterministic. Without an explicit order, the order flips in every integrate call.

Parameters:: order – [in] True to keep a fixed iteration order for determinism.

inline const raisim::contact::BisectionContactSolver &getContactSolver() const

Returns:: a const ref of the contact solver. Internal states can be retrieved using this method

inline const std::string &getConfigFile()

get the config file if the world was created from a file (World(const std::string&, …))

Returns:: the path to the config file, or an empty string

inline const rscene::Scene *getRscene() const

The scene read by World(path) from a RaiSim Engine .rscene file, or included by a RaiSim world config (<include value=”scene.rscene”/>), or null. It carries the render settings and instanced visuals a viewer applies (rayrai: a raisin::RayraiWindow on this world shows them by itself); the physics bodies are already in the world.

Returns:: the parsed scene, owned by the world, or nullptr if the world has no .rscene scene

inline const MaterialPairProperties &getMaterialPairProperties(const std::string &mat1, const std::string &mat2) const

get the material pair properties. The order of materials does not matter. Unknown material names are treated as “default”.

Parameters:

mat1 – [in] material name
mat2 – [in] material name

Returns:

material pair properties, or the default material properties if no pair is defined

inline void lockMutex(): locks the world mutex. This can be used if you use raisim in a multi-threaded environment. The world does not lock it itself; every thread that accesses the world must lock it.

inline void lock(): Same as lockMutex(). Lets World be used with std::lock_guard / std::unique_lock.

inline bool try_lock()

Returns:: true if the world mutex was acquired without blocking (Lockable requirement)

inline void unlockMutex(): unlock the world mutex. This can be used if you use raisim in a multi-threaded environment.

inline void unlock(): Same as unlockMutex(). Lets World be used with std::lock_guard / std::unique_lock.

void updateSelfCollisionCache(): Refresh contact body metadata after collision filter changes.

inline void loadMjcfFile(const std::string &configFile)

Load a single self-contained MuJoCo XML file into this world. Equivalent to the dispatch that World(configFile) does internally when the file’s root is <mujoco>; intended for callers (e.g. the rayrai TCP viewer’s drag-drop inspector) that already have a constructed World and want to populate it from an MJCF path. The world should normally be empty before calling — MJCF files often declare ground planes, worldbody lights, and option blocks that overwrite world-level state.

Parameters:: configFile – [in] path to the MJCF file

Public Static Functions

static inline void setActivationKey(const std::string &activationKey)

Set the path of the license (activation key) file. Call it before creating a World.

Parameters:: activationKey – [in] path to the license file

static void abiGuard(uint64_t headerLayoutStamp)

Internal: fatals when the caller’s header layout stamp disagrees with the library’s (header/library ABI mismatch). Called from constructors.

Parameters:: headerLayoutStamp – [in] the caller’s detail::headerLayoutStamp()

struct DepthCameraProperties

Settings of the CPU ray-cast depth camera used by captureDepthCamera().

Public Types

enum class DepthNoiseType : int

Noise added to each valid depth sample.

Values:

enumerator NONE: no noise

enumerator GAUSSIAN: normal noise with mean depthNoiseMean and standard deviation depthNoiseStd

enumerator UNIFORM: uniform noise in [depthNoiseMean - depthNoiseStd, depthNoiseMean + depthNoiseStd]

Public Members

int width: Image width in pixels. Must be positive.

int height: Image height in pixels. Must be positive.

int xOffset: Horizontal pixel offset added to the column index when computing ray directions.

int yOffset: Vertical pixel offset added to the row index when computing ray directions.

double clipNear: Near clipping distance along the camera forward axis (m). Must satisfy 0 <= clipNear < clipFar.

double clipFar: Far clipping distance (m). Also the maximum ray length.

double hFOV: Horizontal field of view (rad). Must be in (0, pi). The vertical field follows from the aspect ratio.

bool captureDepth: Fill DepthCameraFrame::depth.

bool captureSegmentation: Fill DepthCameraFrame::segmentation.

bool capturePoints: Fill DepthCameraFrame::points.

DepthNoiseType depthNoiseType: Noise model applied to depth values.

double depthNoiseMean: Noise mean (m).

double depthNoiseStd: Noise standard deviation (GAUSSIAN) or half range (UNIFORM) (m).

std::uint32_t depthNoiseSeed: Seed of the noise generator. The generator is re-seeded on every capture, so identical scenes give identical noise.

struct DepthCameraFrame

Output of captureDepthCamera(). Pixel buffers are row-major (index = row * width + column), starting at the top-left pixel.

Public Members

int width: Image width in pixels.

int height: Image height in pixels.

double timeStamp: World time (s) at capture.

std::vector<float> depth: Depth along the camera forward axis (m); NaN where nothing was hit within the clip range. Empty if not captured.

std::vector<int> segmentation: World index (Object::getIndexInWorld()) of the hit object; -1 for background. Empty if not captured.

std::vector<Vec<3>, AlignedAllocator<Vec<3>, 32>> points: Hit positions in the world frame (m); NaN where nothing was hit. Empty if not captured.

struct CollisionCounters

Diagnostic collision counters of the last integration step. Collected only while setCollisionCountersEnabled(true); reset at the start of every contact detection.

Public Members

std::uint64_t deformableParticleCandidates: Deformable-particle collision candidates considered.

std::uint64_t deformableParticleAabbTests: Deformable-particle AABB tests performed.

std::uint64_t deformableParticleContacts: Deformable-particle contacts generated.

std::uint64_t deformableParticleGridCells: Occupied cells of the deformable-particle grid.

std::uint64_t sweptCcdCandidates: Swept continuous-collision candidates considered.

std::uint64_t sweptCcdContacts: Swept continuous-collision contacts generated.

struct ParameterContainer

A template parameter: every @@name token in the template text is replaced by param.

Public Members

std::string name: Parameter name (without the leading @@).

struct SingleBodySnapshot

Snapshot of a single-body object’s runtime state and collision properties. It is intended for fast RL reset/randomization workflows between simulation steps.

Public Members

ObjectId objectId: Stable id of the captured object.

ObjectType objectType: Object type; restore fails if the target’s type differs.

BodyType bodyType: Body type (static/kinematic/dynamic).

Vec<3> position: Position in the world frame (m).

Vec<4> quaternion: Orientation quaternion (w, x, y, z), body to world.

Vec<3> linearVelocity: Linear velocity in the world frame (m/s).

Vec<3> angularVelocity: Angular velocity in the world frame (rad/s).

std::string material: Collision material name.

CollisionGroup collisionGroup: Collision group.

CollisionGroup collisionMask: Collision mask.

class Checkpoint

An immutable, reusable in-memory checkpoint of this world’s runtime state.

Public Functions

inline explicit operator bool() const

Returns:: true if this checkpoint holds captured data (false for a default-constructed one)

double getWorldTime() const

Returns:: the world time (s) at capture, or 0 for an empty checkpoint

struct RayCastBody

Collision geometry of one body, exactly as rayTest() and rayTestLidar() test it.

Public Members

const ::contact::Shape *shape: Shape type and dimensions; mesh and heightmap shapes reference data owned by the world.

Vec<3> position: Body origin in the world frame (m).

Mat<3, 3> rotation: Body-to-world rotation.

const Object *object: Owning object.

size_t localIdx: Local body index within the object (the localId of rayTest()).

std::uint64_t collisionGroup: Collision group bits of the body.

std::uint64_t collisionMask: Collision mask bits of the body.

struct SleepSettings

Sleeping-island configuration (see setSleepingParameters()).

Public Members

bool enabled: Whether sleeping islands are enabled.

double linearVelThreshold: Linear speed below which a body counts as quiet (m/s).

double angularVelThreshold: Angular speed below which a body counts as quiet (rad/s).

int quietSteps: Number of consecutive quiet steps before an island sleeps.