# 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/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

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
• redone generator for ouster-64 as default
• fix sensorPose
• remove unused headers
• fix mrpt3 deprecated API
• demo lidar odom benchmark
• mvsim-dataset-gen: implement 2D+terrain-following trajectory input
• tests: fix -Wshadow warnings in dataset-gen e2e test
• docs: add mvsim-dataset-gen page, sync agents.md
• mvsim-dataset-gen: add IMU and wheel-odometry generation
• mvsim-dataset-gen: new CLI tool for ray-traced LiDAR dataset generation
• simulator: expose read-only geometry accessors for SceneBuilder
• raytracer: fix HeightField to match ElevationMap's row=X/col=Y convention
• raytracer: Lidar3DModel ray-generation model (Phase 2)
• raytracer: exact analytic ray casting library (Phase 1)
• Merge branch 'mrpt3' into develop: port the whole codebase to MRPT 3.x
• Address CodeRabbit review findings (thread safety, XML validation, mrpt-viz docs)
• Update version.h
• Port to mrpt3: fix getSensorPose() and WorldElementBase includes
• Support for multiple lights of the different types
• Fix build with mrpt_viz API changes
• tune jackal PID for better rotations
• FIX: race in actors
• Fix camera sensor pose bug
• Safer multhreads
• Fix bug in collision shape port to mrpt3
• port tclap ->cli11; pid tuner for rotations too
• All lib port done
• Progress porting opengl to mrpt3
• Port code to mrpt3
• Contributors: Jose Luis Blanco-Claraco

1.4.0 (2026-07-17)

• fix(ros): populate twist in /odom topic
• add custom icon
• feat(ros): add disable_sim_time_clock param to opt out of sim clock
• ci: add ubuntu-26.04 build matrix jobs (gcc, clang)
• feat(ros): use simulation time for stamps and publish /clock; show achieved real-time factor in GUI
• feat: allow sensors' GUI preview subwindow to start minimized
• fix: GNSS ROS publisher never set NavSatFix.status.status
• feat: add exactly reproducible trajectories controller for offline experiments
• feat: visualize trajectory paths in 3D GUI
• fix: avoid duplicated text when rebuilding mixed-content XML nodes
• build: auto-enable ccache when available

File truncated at 100 lines see the full file