Last Updated: 2026-07-20
MATRiX is an advanced simulation platform that integrates MuJoCo, Unreal Engine 5, and CARLA to provide high-fidelity, interactive environments for quadruped robot research. Its software-in-the-loop architecture enables realistic physics, immersive visuals, and optimized sim-to-real transfer for robotics development and deployment.
- OS: Ubuntu 22.04
- GPU: NVIDIA RTX 4060 or above (Driver >= 535)
- Tools: GCC/G++ ≥ C++11, CMake ≥ 3.16
- ROS:
ROS_humble
# Clone
git clone https://github.com/zsibot/matrix.git
cd matrix
# Install system/runtime dependencies, including required local deb packages in deps/.
# The script configures the ROS 2 Humble apt source automatically if it is missing.
bash scripts/install_deps.sh
# Install release assets (base package, runtime assets, shared resources, and selected maps)
bash scripts/release_manager/install_chunks.sh
# Verify after dependencies and assets are installed
bash scripts/check_env.sh runtimescripts/run_sim.sh and scripts/run_custom_urdf.sh run runtime environment checks automatically before launch.
If the ROS apt source is blocked, rerun with ROS_APT_REPO_URL=<reachable-ros2-apt-mirror> bash scripts/install_deps.sh.
If your network hits aria2/wget TLS errors, rerun the chunk installer with SKIP_ARIA2=1 to force the fallback download path.
Full offline package: matrix_0.1.2.zip (Artifactory) / Google Drive / Baidu Netdisk, code: jbk3.
See Chunk Packages Guide for offline/manual installation.
./bin/sim_launcher(Select your robot and map in the launcher interface.)
To keep this README concise, detailed guides have been organized into the docs/ folder:
Basics & Setup
- 📦 Chunk Packages Guide - Modular package deployment & offline install
- 🎮 Controller Guide - Gamepad & Keyboard control mappings
- 🛠️ Scripts Guide - Detailed CLI scripts usage
Simulation & Customization
- 🤖 Robot Types & Maps - IDs and visual previews of all robots and maps
- ⚙️ Sensor Configuration - Adjusting cameras, LiDAR, and RViz visualization
- 🌍 Custom Scene Guide - Building custom JSON-based environments
- 🐕 Custom Robot Tutorial - Importing your own MuJoCo URDF models
Advanced Features
- 🌐 Multi-Robot Tutorial - Simulating multiple robots simultaneously
- 🐳 Docker Tutorial - Running MATRiX in a container
- 📡 RoamerX Open Integration - ROS2 Nav2 stack integration
- 🎥 Pixel Streaming - Web browser streaming
Add the GENISOM AI WeChat assistant for MATRiX simulation discussions and support:
Scan to add XinQi Robo; mention MATRiX to join the simulation community.
Bug reports, documentation improvements, and runtime tooling changes are welcome. Start with CONTRIBUTING.md, and review the architecture and maintainer guide before changing launch or release scripts. Security issues should follow SECURITY.md rather than being filed as public issues.
This project builds upon the incredible work of the following open-source projects: