Guide

This guide is designed for users who want to understand RoboVerse’s core concepts and get started quickly.

RoboVerse is built around three key components that work together:

Handler → (Task, Optional) → Algorithm/Script

Let’s understand each component:

---

1. Handler: The Physics Engine Interface

A Handler is the core component that directly interfaces with physics engines (like MuJoCo, IsaacSim, PyBullet, etc.). Think of it as a translator that speaks the language of different simulators.

# Get current simulation state, including RGB Data
state = handler.get_state()

# Set simulation state (for resets)
handler.set_state(new_state)

# Apply robot actions
handler.set_dof_targets(actions)

# Step physics simulation
handler.simulate()

# Get robot joint/body names
joint_names = handler.get_joint_names()
body_names = handler.get_body_names()

---

2. Scenario: The Configuration Blueprint

A Scenario (ScenarioCfg) is a configuration that tells the Handler what to simulate. It’s like a blueprint that describes everything needed for a simulation.

Here’s how to create a basic scenario:

from metasim.scenario.scenario import ScenarioCfg

# Simple scenario with just a robot
scenario = ScenarioCfg(
    robots=["franka"],
    simulator="mujoco",
    num_envs=1
)

Fields include: robots (robot configurations), objects (scene objects), simulator (physics engine), num_envs (number of parallel environments), headless (run without GUI), cameras (camera sensors), lights (lighting setup), and sim_params (physics parameters like timestep).

3. Task: The High-Level Interface

A Task is a wrapper built on top of a Handler that provides Gym-style APIs (step, reset, observation_space, action_space). It adds task-specific logic like rewards, termination conditions, and observations.

Aspect	Handler	Task
Purpose	Direct physics engine interface	High-level learning interface
API	Low-level (get_state, simulate…)	Gym-style (step, reset)
Logic	No task logic, Only simulator-related	Contains reward, termination, etc.
Usage	For custom control	For training, data collection, evaluation

Use RoboVerse as Unified Simulator

Steps:

1. Choose a simulator based on your needs

2. Define your scenario with robots, objects, cameras

3. Integrate with your workflow using Handler methods:

Example:

from metasim.scenario.scenario import ScenarioCfg
from metasim.utils.setup_util import get_handler

# Define your scenario
scenario = ScenarioCfg(
    robots=["franka"],
    simulator="mujoco",
    num_envs=1
)

# Create handler directly - one step
handler = get_handler(scenario)

# Control loop
states = ...
handler.set_state(states)     # Set state (for resets)

actions = ...  # Your control actions
handler.set_dof_targets(actions)     # Apply actions to robot

handler.simulate()                  # Step physics
obs = handler.get_state(mode="tensor")  # Get updated state

Use Pre-built Tasks

What Tasks Provide:

• Pre-configured scenarios (robots, objects, cameras)

• Task logic (max episode length, initial states)

• Reward functions (For RL tasks) and termination conditions

---

。

from metasim.task.registry import get_task_class
import torch

# Get task class by name
task_cls = get_task_class(args.task)  # e.g., "example.reaching"

# Get default scenario and update with specific parameters
scenario = task_cls.scenario.update(
    robots=[args.robot], 
    simulator=args.sim, 
    num_envs=args.num_envs, 
    headless=args.headless, 
    cameras=[]
)

# Create task environment
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
env = task_cls(scenario=scenario, device=device)

obs, info = env.reset()
action = ...
obs, reward, terminated, truncated, info = env.step(action)

---

Next Steps

For more detailed information, you can explore the concept tutorials which cover advanced topics such as state system content and format, domain randomization techniques, handler implementation details, task system architecture, and configuration management.

---