# MultiVehicle Simulator (MVSim) **Lightweight, realistic 2.5D dynamics simulator for mobile robots and multi-agent research** [](https://github.com/MRPT/mvsim/actions/workflows/build-linux.yml) [](https://github.com/MRPT/mvsim/actions/workflows/ci-ros2.yml) [](https://github.com/MRPT/mvsim/actions/workflows/check-clang-format.yml) [](https://mvsimulator.readthedocs.io/en/latest/?badge=latest) [](LICENSE) [**Documentation**](https://mvsimulator.readthedocs.io) · [**Installation**](https://mvsimulator.readthedocs.io/en/latest/install.html) · [**Demo worlds**](https://mvsimulator.readthedocs.io/en/latest/demo_worlds.html) · [**Cite**](#citation)

Overview

MVSim simulates wheeled robots and vehicles with realistic physics, sensors, and multi-agent support. It is designed to be fast enough for large-scale experiments while remaining accurate enough for dynamics and sensor research.

Key properties:

• Fully configured via XML world files — no code changes needed for most experiments.
• Works standalone, as a ROS 2 node, or embedded in a C++ / Python application.
• Headless mode for CI pipelines and Docker containers.
• Multi-vehicle worlds with mutual sensing (robots see each other in LiDAR).

https://github.com/user-attachments/assets/766db164-2d16-44f4-acbf-2f15b73c1ab3

https://github.com/user-attachments/assets/93c95aeb-71e9-4c35-b1dc-ba895c79daf7

Features

Vehicle dynamics

| Model | Description | |—|—| | differential | 2-wheel or 4-wheel differential drive (e.g. TurtleBot, Jackal) | | ackermann | Car-like Ackermann steering with kinematic or dynamic control | | ackermann_drivetrain | Ackermann + realistic mechanical differentials (open / Torsen, 2WD / 4WD) | | Articulated | Trailer-style articulated vehicles |

Controllers available: raw torque, twist PID, ideal twist.

Friction models: default Coulomb, Ward-Iagnemma (off-road), ellipse (slip angle + slip ratio).

Sensors

| Sensor | Notes | |—|—| | 3D LiDARs | Velodyne VLP-16, Ouster OS1, Hesai Helios-32 (26°/31°/70° FOV) | | 2D LiDAR | Generic + RPLidar A2; optional GPU-based 3D ray-tracing | | RGB camera | Pinhole model, configurable intrinsics | | RGBD camera | Depth + color (RealSense / Xtion-style), publishes pointcloud, depth image | | IMU | White noise + bias random-walk (Forster 2016 model) | | GNSS / GPS | Requires georeferenced world; configurable noise |

World elements

• Occupancy grid maps (image or MRPT binary)
• Elevation meshes (terrain with height)
• Textured 3D blocks and custom meshes (.dae, .obj)
• Friction zones (spatially-varying mu, rolling resistance)
• Multi-storey environments
• Lighting configuration
• Remote resource caching

Interfaces

• ROS 2 — full topic / TF / parameter interface (see mvsim_node docs)
• ZMQ / Protobuf — language-agnostic pub/sub for custom clients
• Python — direct API access
• C++ library — embed the simulator in your application

Installation

ROS 2 (recommended)

sudo apt install ros-$ROS_DISTRO-mvsim

Then follow the first-steps guide.

Build from source

git clone https://github.com/MRPT/mvsim.git --recursive

See full installation instructions for cmake and colcon build options.

Quick start

Standalone:

```bash mvsim launch mvsim_tutorial/demo_warehouse.world.xml

File truncated at 100 lines see the full file

Changelog for package mvsim

2.0.0 (2026-11-01)

• GUI: ported from nanogui to Dear ImGui, with dockable panels, custom application panels and a lights window
• Vehicle dynamics overhaul: friction circle and Ellipse static grip, wheel loads from force and moment balance, vehicles stop on zero twist, stable wheel control
• Ackermann: Torsen differentials, steering rate limit; differential: swiveling caster, wheel_separation_multiplier
• Optional chassis suspension, with vehicle definitions, demo world and docs
• Ideal and new trajectory controllers follow the commanded twist exactly (exactly reproducible trajectories)
• ros2_control integration for differential vehicles (Humble and Jazzy)
• Insert and remove entities at runtime from world XML (C++, ZMQ and ROS 2 simulation_interfaces services); runtime visual objects and ground decals
• Video recording of the 3D view, in simulation time
• As fast as possible simulation mode (realtime_factor <= 0); performance diagnostics (per-sensor time and rate, physics time, achieved RTF)
• Camera: plumb_bob lens distortion and pixel noise, also for RGB-D cameras (MRPT >= 3.6.0)
• RGB-D in ROS: depth image in the optical frame, millimeters, optional 32FC1; faster RGB-D and 3D LiDAR simulation
• 2D LiDAR: fix 3D ray tracing for apertures under 150 deg, support tilted scans
• GNSS fix type and degradation events; IMU covariances in ROS
• Lights: switchable light groups, shadow-casting point/spot lights, per-light range, emissive models
• Horizontal plane: north-up texture placed by geodetic corners
• New tools: mvsim-urdf2xml (vehicle XML from a URDF, #136), mvsim-pid-tuner (closed-loop tuning), mvsim slice (2D occupied cells at a height)
• mvsim_node: fake localization publishes map->odom from the ground truth
• XML: <include> and <if> at any depth inside vehicles, blocks and actors; empty default values in ${var|}; per-axis model scale
• Headless rendering with one EGL context per World; docs for EGL and Xvfb
• Faster world loading and physics steps with many static blocks
• Demos: warehouse, home and greenhouse improvements; pickup with separate wheel models; retuned vehicle definitions
• Fix crashes and lost output when shutting down; fix builds without ZeroMQ or ros2_control
• CI: ROS 2 builds and tests for humble, jazzy and lyrical; release workflow
• Contributors: Jose Luis Blanco-Claraco

1.6.0 (2026-10-04)

• Demo worlds:
  • New demo_home world, and a much richer demo_warehouse (rooms, dock doors, floor markings, lamps and new props).
  • Normal maps for textured planes (<normal_map>) and elevation maps (<normal_map_image>). Demo worlds use official cgbookcase and Poly Haven normal maps.
  • Nicer default wheel and chassis visuals.
  • demo_elevation_map: seeded random placement of trees and rocks.
  • New demo videos for all worlds in the docs and README.
• GUI:
  • New <gui> options show_gui_panels, show_sensor_previews and shadow_cascades, and per-sensor preview_depth.
  • Honor <gui><headless> from the world file in mvsim launch and the ROS node.
• Performance:
  • Faster elevation queries, using a 2D spatial index of world elements.
  • Faster camera sensors: fewer shadow cascades (new <sensor_shadow_cascades>, default 1), and no shadow pass for depth images.
  • Remove model_split_size, no longer needed with alpha cutout rendering. Elevation maps are now a single mesh.
• Communications: fail fast if the ZMQ port is busy. mvsim launch falls back to a free port, the port can be set with the new MVSIM_SERVER_PORT env var, and mvsim topic/mvsim node honor --port.
• World variables are now expanded in <visual> parameters.
• Fixes: texture rotation of elevation maps, Block::getElevationAt() quick discard of far points, camera viewport shadow settings restored if rendering throws, RViz camera image topics, floating boxes in the warehouse demo, and mismatched XML tags.
• CI: Linux jobs moved to MRPT 3.x PPAs (Ubuntu 24.04 and 26.04).
• Contributors: Jose Luis Blanco-Claraco

1.5.0 (2026-09-25)

• Fix walls loaded from model files having no segments
• Fix Still2DLidarRanges test hanging forever
• Merge pull request #112 from MRPT/feature/lidar-raytracer-dataset-gen: LiDAR raytracer dataset generator CLI
• Make TBB an optional dependency of mvsim-dataset-gen
• fix formatting
• mvsim-dataset-gen: show progress bar with ETA during simulation
• address review comments; add TBB parallelization

File truncated at 100 lines see the full file