World

The raisim::World class is responsible for the creation and management of all simulation resources. All objects within a single World instance are capable of collision with one another, provided their collision mask and group settings do not explicitly disable such interactions (refer to the Contact and Collision section).

A World instance can be instantiated in two ways. The first method involves loading a RaiSim world configuration file in XML format. Further details regarding the XML format are available in the World Configuration File section.

The second method is to dynamically generate the world via code.

These methods can be combined by loading an initial XML configuration and subsequently adding objects dynamically.

An experimental MJCF (MuJoCo file format) reader is also available, allowing for the loading of simple models.

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 represents a pointer to the internal resource. It facilitates access to and modification of internal variables.

Most object-creation methods accept optional material, collisionGroup, and collisionMask arguments. Static objects such as ground and heightmaps use a fixed collision group and expose only a collision mask. Collision variables are detailed in the “Contact and Collision” section. The material argument specifies the material governing contact dynamics, as further explained in the “Material System” chapter.

A comprehensive list of objects is provided in the “Object” chapter.

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.

Saving the World to an XML File

raisim::World::exportToXml(dir, file) (or exportToXml(path)) saves the current world state to an XML file. EXAMPLES

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)

Example 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. See the “Contact and Collision” section for the group/mask rules and the default static collision group.

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 2) and their maximum linear and angular velocities stay below the configured thresholds (defaults: linear 0.001, angular 0.005).

Notes:

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.001, /*angular*/ 0.005, /*quietSteps*/ 2);
world.setSleepingVelocityThresholds(0.001, 0.005);
world.wakeObject(obj);   // wakes the object's island
world.wakeAll();

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

API

class World

Public Functions

explicit World(): Create an empty world

inline explicit World(const std::string &configFile, const std::vector<ParameterContainer> &params = {}): Create an world as specified in the xml config file

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

inline void setTimeStep(double dt)

set the time step

Parameters:: dt – [in] the time step

inline double getTimeStep() const

Returns:: the time step

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

Parameters:

radius – [in] radius
mass – [in] mass
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 box

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

Parameters:

xLength – [in] x dimension
yLength – [in] y dimension
zLength – [in] z dimension
mass – [in] mass
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 box

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

Parameters:

radius – [in] radius
height – [in] center-to-center distance
mass – [in] mass
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 cylinder

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

Parameters:

radius – [in] radius
height – [in] center-to-center distance
mass – [in] mass
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 capsule

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

Parameters:

zHeight – [in] height of the terrain
material – [in] material of the height map (which defines the contact dynamics)
collisionMask – [in] read “Contact and Collision/ Collision Group and Mask”. Note that collision group of a static object is CollisionGroup(1) << 61ul

Returns:

pointer to the created ground

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))

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 center of the height map
centerY – [in] y coordinate of the center of the height map
height – [in] a vector of doubles representing heights. the size should be xSample X ySamples
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: