Implementation:Haosulab ManiSkill MJCFLoaderInternal

Knowledge Sources	Haosulab_ManiSkill
Domains	Robotics, Simulation, MJCF Parsing
Last Updated	2026-02-15 08:00 GMT

Overview

Concrete tool for parsing and loading MJCF (MuJoCo XML) model files into the SAPIEN simulation engine.

Description

The internal MJCF loader (_mjcf_loader.py) provides a comprehensive parser that converts MJCF XML files -- the format used by the MuJoCo physics simulator -- into SAPIEN articulation and actor structures. The code is partially adapted from NVIDIA Warp's MJCF import module.

The loader handles the full MJCF specification including: kinematic trees defined by <body> tags (mapped to SAPIEN articulations), standalone geoms in <worldbody> (built as static actors), defaults/class inheritance, mesh and texture assets, joint properties, material properties, and tendon/equality constraints. It processes XML elements recursively, resolving asset references, coordinate transformations (including Euler angles and quaternions), and collision/visual grouping.

Key design decisions:

Geom groups 0 and 2 are rendered by default (matching MuJoCo behavior); other groups are treated as invisible unless explicitly configured.
If contype is 0, no collision shape is created for that geom.
Joint solver/stiffness/actuator properties are not directly imported; they must be implemented via controllers.
Contact tags are not supported; tendon/equality constraints have partial support.

The module defines a MJCFTexture dataclass for texture metadata and an MJCFLoader class that orchestrates the full loading pipeline via parse().

Usage

This is an internal module. Users should import the public MJCFLoader from mani_skill.utils.building.mjcf_loader which wraps this class to add parallelization support. Direct usage of this internal loader is only necessary for advanced low-level MJCF manipulation.

Code Reference

Source Location

Repository: Haosulab_ManiSkill
File: mani_skill/utils/building/_mjcf_loader.py

Signature

@dataclass
class MJCFTexture:
    name: str
    type: Literal["skybox", "cube", "2d"]
    rgb1: list
    rgb2: list
    file: str

class MJCFLoader:
    def parse(self, mjcf_file, package_dir=None) -> tuple[list[ArticulationBuilder], list[ActorBuilder], list]: ...

Import

from mani_skill.utils.building._mjcf_loader import MJCFLoader

I/O Contract

Inputs

Name	Type	Required	Description
mjcf_file	str	Yes	Path to the MJCF XML file to load
package_dir	str	No	Base directory for resolving asset file references in the MJCF

Outputs

Name	Type	Description
articulation_builders	list[ArticulationBuilder]	Builders for each kinematic tree found in the MJCF
actor_builders	list[ActorBuilder]	Builders for standalone geoms (static actors)
cameras	list	Camera definitions extracted from the MJCF

Usage Examples

Basic Usage

from mani_skill.utils.building._mjcf_loader import MJCFLoader

loader = MJCFLoader()
loader.scene = scene  # a SAPIEN scene
articulation_builders, actor_builders, cameras = loader.parse("model.xml")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment