MATRiX

<div align="center"> <a href="#"> <img alt="Forest" src="demo_gif/Forest.png" width="800" height="450"/> </a> </div> <div align="center">

</div>

Last Updated: 2026-01-06

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.

💬 Community

Join our WeChat group for MATRiX simulation discussions:

<div align="center"> <img src="demo_gif/wechat.png" alt="WeChat Group QR Code" style="height: 280px; width: auto; margin: 0 12px;"/> <p><em>Scan to join MATRiX simulation community</em></p> </div>

---

📂 Directory Structure

matrix/
├── bin/                         # Executable binaries (created after build)
├── config/                      # System configuration files
│   └── config.json              # Core sensor and system settings
├── demo_gif/                    # Visual assets for documentation
│   ├── Maps/                    # Preview images for different maps
│   ├── Robot/                   # Preview images for supported robots
│   └── Scene/                   # Demos for custom scene setups
├── deps/                        # Third-party dependencies (.deb packages)
│   ├── ecal_*.deb               # eCAL communication library
│   ├── mujoco_*.deb             # MuJoCo simulation engine
│   └── ...                      # Other essential dependencies
├── docs/                        # Project documentation
│   ├── README_CN.md             # Chinese version of README
│   ├── CHUNK_PACKAGES_GUIDE.md  # Guide for modular chunk packages
│   └── ...                      # Development and maintenance guides
├── dynamicmaps/                 # Resources for dynamic map loading
├── releases/                    # Storage for downloaded chunk packages
│   ├── assets-*.tar.gz          # Assets package (binaries, models, libraries)
│   ├── base-*.tar.gz            # Base package (core files and default map)
│   ├── shared-*.tar.gz          # Shared resources for multiple maps
│   ├── *-*.tar.gz               # Individual map data packages
│   └── manifest-*.json          # Package version manifest
├── rviz/                        # ROS visualization (RViz) configurations
│   └── matrix.rviz              # Preconfigured RViz layout
├── scene/                       # Custom scene description files (JSON)
│   ├── scene.json               # Currently active scene configuration
│   └── scene_example_*.json     # Templates for custom scenes
├── scripts/                     # Utility and build scripts
│   ├── build.sh                 # One-click build and setup (Entry point)
│   ├── run_sim.sh               # Simulation launch script (CLI)
│   ├── install_deps.sh          # Dependency installation tool
│   └── release_manager/         # Release and package management tools
├── src/                         # Source code
│   ├── robot_mc/                # Motion control core logic
│   ├── robot_mujoco/            # MuJoCo simulation interface
│   └── UeSim/                   # Unreal Engine high-fidelity interface
├── LICENSE                      # Project license
└── README.md                    # Project documentation (this file)

---

⚙️ Environment Dependencies

• Operating System: Ubuntu 22.04
• Recommended GPU: NVIDIA RTX 4060 or above (NVIDIA Driver >= 535 recommended)
• Unreal Engine: Integrated (no separate installation required)
• Build Environment:
  • GCC/G++ ≥ C++11
  • CMake ≥ 3.16
• MuJoCo: 3.3.0 open-source version (integrated)
• Remote Controller: Required (Recommended: Logitech Wireless Gamepad F710)
• Python Dependency: gdown (for downloading chunk packages from Google Drive)
• ROS Dependency: ROS_humble

---

🚀 Installation & Build

1. LCM Installation

   sudo apt update
   sudo apt install -y cmake-qt-gui gcc g++ libglib2.0-dev python3-pip
   

   Download the source code from LCM Releases and extract it.

   Build and install:

   cd lcm-<version>
   mkdir build
   cd build
   cmake ..
   make -j$(nproc)
   sudo make install
   

   Note: Replace <version> with the actual extracted LCM directory name.

2. Clone MATRiX Repository

   git clone https://github.com/zsibot/matrix.git
   cd matrix
   

3. Install Dependencies

   ./scripts/build.sh
   

   (This script will automatically install all required dependencies.)

4. Install Chunk Packages (Modular Installation)

   MATRiX uses a modular chunk package system that allows you to download only what you need:

   • Assets Package (Required): Runtime binaries, shared libraries, ONNX models, 3D models, and other essential files
   • Base Package (Required): Core files and EmptyWorld map
   • Shared Resources (Recommended): Shared resources used by multiple maps
   • Map Packages (Optional): Individual maps that can be downloaded on demand

   Quick Installation:

   bash scripts/release_manager/install_chunks.sh 0.1.1
   

   📖 For Details: For complete information about the chunk package system, including package sizes, map list, installation verification, and FAQs, see the Chunk Packages Guide.

   Alternative: Manual Installation (via Cloud Storage)

   If GitHub access is slow, follow these steps to install manually:

   1. Download the package archive:

      • Google Drive: Download Link
      • Baidu Netdisk: Download Link

   2. Extract all .tar.gz and .json files into the matrix/releases/ directory.

   3. Install using the local script:

      bash scripts/release_manager/install_chunks_local.sh 0.1.1
      

      ⚠️ Important: Ensure all files (base, assets, shared, etc.) are placed directly in matrix/releases/ before running the installation script.

---

▶️ Running the Simulation

<div align="center"> <img src="demo_gif/Launcher.png" alt="Simulation Running Example" width="640" height="360"/> </div>

🐕 Simulation Setup Guide

1. Run the launcher

   cd matrix
   ./bin/sim_launcher
   

2. Select Robot Type Choose the type of quadruped robot for the simulation.

3. Select Environment Pick the desired simulation environment or map.

4. Choose Control Device Select your preferred control device:

   • Gamepad Control
   • Keyboard Control

5. Enable Headless Mode (Optional) Toggle the Headless Mode option for running the simulation without a graphical interface.

6. Launch Simulation Click the Launch Simulation button to start the simulation.

During simulation, if the UE window is active, you can press ALT + TAB to switch out of it. Then, use the control-mode toggle button on the launcher to switch between gamepad and keyboard control at any time.

🎮 Remote Controller Instructions (Gamepad Control Guide)

| Action | Controller Input | |--------------------------------------|-----------------------------------------| | Stand / Sit | Hold LB + Y | | Move Forward / Back / Left / Right | Left Stick (up/down/left/right) | | Rotate Left / Right | Right Stick (left / right) | | Jump Forward | Hold RB + Y | | Jump in Place | Hold RB + X | | Somersault | Hold RB + B |

⌨️ Remote Controller Instructions (Keyboard Control Guide)

| Action | Controller Input | |--------------------------------------|-----------------------------------------| | Stand | U | | Sit | Space | | Move Forward / Back / Left / Right | W / S / A / D | | Rotate Left / Right | Q / E | | Start | Enter |

Press the V key to toggle between free camera and robot view.

Hold the left mouse button to temporarily switch to free camera mode.

---

🏞️ Demo Environments

<div align="center">

| Map | Demo Screenshot | Map | Demo Screenshot | |:---------------:|:-------------------------------------------:|:---------------:|:-------------------------------------------:| | Venice | <img src="demo_gif/Venice.gif" alt="Matrix Demo Screenshot" width="350" height="200"/> | Warehouse | <img src="demo_gif/whmap.gif" alt="Matrix Warehouse Demo" width="350" height="200"/> | | Town10 | <img src="demo_gif/Town10.gif" alt="Matrix Town Demo" width="350" height="200"/> | Yard | <img src="demo_gif/Yardmap.gif" alt="Matrix Yardmap Demo" width="350" height="200"/> |

</div>

Note: Map Descriptions.

Note: The above screenshots showcase high-fidelity UE5 rendering for robotics and reinforcement learning experiments.

---

🛠️ Script Usage Guide

MATRiX provides various scripts to help you build, install, and run the simulator. Here's how to u