Simulated world definition

Simulation happens inside a World object. This is the central class for usage from user code, running the simulation, loading XML models, managing GUI visualization, etc. The ROS node acts as a bridge between this class and the ROS subsystem.

Simulated worlds are described via configuration files called “world” files, defined in the XML file format.

Many examples can be found in the mvsim_tutorial directory.

The next sections explain possible XML elements in a world file.

1. Global XML tags

World definition begins with tag <mvsim_world>. To define simulation timestep, use <simul_timestep> with float value specified in seconds.

<mvsim_world version="1.0">
        <!-- General simulation options -->
        <simul_timestep>0</simul_timestep> <!-- Simulation fixed-time interval for numerical integration [s], or 0 to auto-determine -->

2. GUI options

GUI options are specified with tag gui. gui has several nested tags:

<mvsim_world version="1.0">
        <!-- GUI options -->
                <!-- Is camera orthographic or projective? -->

                <!-- Show reaction forces on wheels with lines -->
                <force_scale>0.01</force_scale> <!-- (Newtons to meters draw scale) -->

                <!-- default camera distance in world units -->

                <!-- camera vertical field of view in degrees -->

                <!-- <follow_vehicle>r1</follow_vehicle> -->

3. “World elements”

Scenario defines the “level” where the simulation takes place.

<element class=”occupancy_grid”> depicts MRPT occupancy map which can be specified with both image file (black and while) and MRPT grid maps. <file> specifies file path to image of the map.

<element class=”ground_grid”> is the metric grid for visual reference.

<element class=”elevation_map”> is an elevation map (!experimental). Mesh-based map is build of elevation map in simple bitmap where whiter means higher and darker - lower.

This tag has several subtags:

  • <elevation_image> - path the elevation bitmap itself
  • <elevation_image_min_z> - minimum height in world units
  • <elevation_image_max_z> - maximum height in world units
  • <texture_image> - path texture image for elevation bitmap. Mus not be used with mesh_color simultaneously
  • <mesh_color> - mesh color in HEX RGB format
  • <resolution> - mesh XY scale

4. Vehicle class descriptions

Tag <vehicle:class> depictd description of vehicle class. The attribute name will be later referenced when describing vehicle exemplars.

Inside <vehicle:class> tag, there are tags <dynamics>, <friction> and exemplars of <sensor>.

Vehicle dynamics

At the moment, there are three types of vehicle dynamics implemented. Refer [vehicle_models] for more information.

<dynamics> with attribute class specifies class of dynamics used. Currently available classes:

  • differential
  • car_ackermann
  • ackermann_drivetrain

Each class has specific inner tags structure for its own configuration.


Every dynamics has wheels specified with tags <i_wheel> where i stand for wheel position index (r, l for differential drive and fr, fl, rl, rr for Ackermann-drive)

Wheel tags have following attributes:

  • pos - two floats representing x an y coordinate of the wheel in local frame
  • mass - float value for mass of the wheel
  • width - float value representing wheel width [fig:wheel_forces]
  • diameter - float value to represent wheel diameter [fig:wheel_forces]

Ackermann models also use <max_steer_ang_deg> to specify maximum steering angle.

<chassis> is also common for all dynamics, it has attributes:

  • mass - mass of chassis
  • zmin - distance from bottom of the robot to ground
  • zmax - distance from top of the robot to ground


There are controllers for every dynamics type [sec:controllers]. In XML their names are

  • raw - control raw forces
  • twist_pid - control with twist messages
  • front_steer_pid - [Ackermann only] - control with PID for velocity and raw steering angles

Controllers with pid in their names use PID regulator which needs to be configured. There are tags <KP><KI><KD> for this purpose. Also they need the parameter <max_torque> to be set.

Twist controllers need to set initial <V> and <W> for linear and angular velocities respectively.

Steer controllers need to set initial <V> and <STEER_ANG> for linear velocity and steering angle respectively.

Ackermann-drivetrain model

needs a differential type and split to be configured. For this purpose there is a tag <drivetrain> with argument type. Supported types are defined in [sec:ackermann_drivetrain]. In XML their names are:

  • open_front
  • open_rear
  • open_4wd
  • torsen_front
  • torsen_rear
  • torsen_4wd

<drivetrain> has inner tags describing its internal structure:

  • <front_rear_split>
  • <front_rear_bias>
  • <front_left_right_split>
  • <front_left_right_bias>
  • <rear_left_right_split>
  • <rear_left_right_bias>

which are pretty self-explanatory.


Friction models are described in [sec:friction_models] and defined outside of <dynamics>. The tag for friction is <friction> with attribute class.

Class names in XML are:

  • wardiagnemma
  • default

Default friction [sec:default_friction] uses subtags:

  • <mu> - the friction coefficient
  • <C_damping> - damping coefficient

In addition to default, Ward-Iagnemma friction includes subtags:

  • A_roll
  • R1
  • R2

that are described in [sec:wi_friction].


Sensors are defined with <sensor> tag. It has attributes type and name.

At the moment, only laser scanner sensor is implemented, its type is laser. Subtags are:

  • <pose> - an MRPT CPose3D string value
  • <fov_degrees> - FOV of the laser scanner
  • <sensor_period> - period in seconds when sensor sends updates
  • <nrays> - laser scanner rays per FOV
  • <range_std_noise> - standard deviation of noise in distance measurements
  • <angle_std_noise_deg> - standatd deviation of noise in angles of rays
  • <bodies_visible> - boolean flag to see other robots or not

5. Vehicle instances

For each vehicle class, an arbitrary number of vehicle instances can be created in a given world.

Vehicle instances are defined with the <vehicle> tag that has attributes name and class. class must match one of the classes defined earlier with <vehicle:class> tag.

Subtags are:

  • <init_pose> - in global coordinates: \(x\), \(y\), \(\gamma\) (deg)
  • <init_vel> - in local coordinates: \(v_x\),\(v_y\), \(\omega\) (deg/s)

6. “Obstacle block” classes

Write me!

7. “Obstacle block” instances

Write me!

8. Vehicles and blocks parameters

Vehicles and obstacles blocks share common C++ mvsim::Simulable and mvsim::VisualObject interfaces that provide the common parameters below.


The following parameters can appear in either the {vehicle,block} class definitions or in a particular instantiation block, depending on whether you want parameters to be common to all instances or not, respectively.

Simulation execution

Simulation executes step-by-step with user-defined \(\Delta t\) time between steps. Each step has several sub steps:

  • Before time step - sets actions, updates models, etc.
  • Actual time step - updates dynamics
  • After time step - everything needed to be done with updated state


Each vehicle is equipped with parameters logger(s). This logger is not configurable and can be rewritten programmaticaly.

Logger are implemented via CsvLogger class and make log files in CSV format which then can be opened via any editor or viewer.

Loggers control is introduced via robot controllers, each controller controls only loggers of its robot.

Best results in visualizing offers QtiPlot [fig:qtiplot_example1].

At the moment, following characteristics are logged:

  • Pose (\(x, y, z, \alpha, \beta, \gamma\))
  • Body velocity (\(\dot{x}, \dot{z}, \dot{z}\))
  • Wheel torque (\(\tau\))
  • Wheel weight (\(m_{wp}\))
  • Wheel velocity (\(v_x, v_y\))

Loggers support runtime clear and creating new session. The new session mode finalizes current log files and starts to write to a new bunch of them.


  • A limitation of box2d is that no element can be thinner than 0.05 units, or the following assert will be raised while loading the world model: