Adding Custom Hand Environment and Training Task Environment

[mizhou1213]

To whom it may concern,

I’ve been experimenting with MuJoCo Playground, and I’d like to know if it’s possible to integrate a custom environment under the manipulation folder. Specifically, I’ve built a tendon-driven robotic hand model and would like to contribute it as a new environment for training and testing.

Our plan is to:

Add the tendon-driven hand model and corresponding z-rotation task.

Contribute the asset and XML file to mujoco_menagerie.

Include the z-rotation training script in the manipulation folder.

Everything is currently working locally with MuJoCo Playground. Aside from following the PR guidelines and ensuring the required tests pass, are there any additional permissions or steps we should be aware of?

Also, could you share how long the PR review/merge process typically takes?

Thank you for your time and guidance!

[Nan-Tetheria]

Hi @btaba ,

We would like to propose adding a new example to MuJoCo Playground that demonstrates training and control of a tendon-driven model. This example aims to complement the existing collection by highlighting MuJoCo Playground’s ability to model and train policies for tendon-actuated systems, in addition to the more common joint-actuated ones.

We believe this could be an interesting and meaningful addition to the repository, showing that Playground supports both joint and tendon actuation paradigms, and serving as a reference for users who wish to build similar models.

We’ve included the proposed README document below for your review. Please let us know if this would be a good fit for a PR to MuJoCo Playground. Any feedback or suggestions are greatly appreciated.

Nan

Tetheria Aero Hand Open with Tendon-Driven Actuation

This directory introduces a tendon-driven manipulation example that extends MuJoCo Playground with support for tendon-level control and observation in reinforcement learning tasks.

The model is adapted from the Tetheria Aero Hand Open, featuring a physically accurate tendon system that emulates cable-driven actuation. In this setup, both the policy inputs and observations are defined in the tendon space, providing a complete example of training and deploying tendon-driven controllers in MuJoCo.

An overview of the hand is shown below:

Rock	Paper	Scissor

1. Tendon-Driven MuJoCo Model

1.1 Modeling

The mechanical design is derived from URDF files, ensuring accurate representation of the real hand structure. The actuation system in the simulator models the cable design in the real hand through three key components:

1.1.1 Tendon Drives

The tendons drive the hand to close the fingers and control the thumbs. These are modeled as spatial tendons in MuJoCo that follow the exact routing paths of the real cables.

1.1.2 Springs

The springs, which are also modeled by tendon components in MuJoCo, provide the forces to pull the fingers in the backward direction. This creates the restoring forces necessary for finger extension.

1.1.3 Pulleys

The pulleys, which are modeled as cylinders, organize the cables and springs to ensure they are routed in a similar way to the real hand. Careful placement of these pulleys ensures accurate tendon routing.

Front view	Close-up of index

1.2 Parameters

1.2.1 Mechanical Parameters

• Joint limits, mass, and inertia: Come directly from URDF and are accurate to the real hand
• Pulley placement: Positioned precisely where they are placed in the real hand, ensuring cable and spring routes match the real system
• Validation: The range of tendon between fully open and fully closed fingers in simulation (0.0459454) closely matches the real hand (0.04553) without manual adjustment

1.2.2 Tendon and Spring Specifications

• Tendon properties: Use the same specifications as those in the real hand
• Spring properties: Match real hand specifications, except for the spring on the DIP joint, which is adjusted as a compromise to achieve similar joint space behavior as the real hand

1.2.3 Control Parameters

All remaining parameters, including:

• Joint damping values
• Actuator gains
• Joint-specific damping coefficients

These are fine-tuned to satisfy both similar joint behaviors in simulation and the real world.

2. Training your own policy

We introduce a z-axis rotation task for the Tetheria Aero Hand Open, optimized using the following reward formulation:

$$ \text{reward} = 1.0 \times \text{angular velocity} - 1.0 \times \text{action rate} + \text{termination}(-100.0) $$

The optimization variables include the tendon lengths and the thumb abduction joint, which correspond to the real hand’s actuation system.
This setup ensures that the same control inputs and sensory data can be directly applied for sim-to-real deployment on the physical Tetheria Aero Hand Open.

To train policies for the Tetheria Hand:

# Run the training script
python learning/train_jax_ppo.py --env_name TetheriaCubeRotateZAxis

3. Running a pretrained policy

To test trained policies in simulation:

# Run the simulation rollout script
python learning/train_jax_ppo.py   --env_name TetheriaCubeRotateZAxis   --play_only   --load_checkpoint_path path/to/checkpoints

This will:

• Load the trained policy
• Run episodes in the MuJoCo simulation
• Display the hand performing manipulation tasks

Seed = 0:

Seed = 1:

Seed = 14:

Sim2real deployment on Tetheria Aero Hand Open:

File Structure

Core Implementation

• tetheria_hand_tendon_constants.py - Constants and configuration
• rotate_z.py - Cube rotation task implementation

XML Models

• xmls/right_hand.xml - Main hand model with tendon system
• xmls/scene_mjx_cube.xml - Manipulation scene
• xmls/reorientation_cube.xml - Cube reorientation task

Key Features

• Accurate tendon modeling: Direct translation from real hand cable system
• Precise pulley placement: Matches real hand routing exactly
• Validated parameters: Tendon ranges match real hand within 0.1%

---

This implementation provides a high-fidelity tendon-driven hand model that closely matches the real robotic hand, enabling effective sim-to-real transfer for manipulation tasks.

Acknowledgements

Our code is built upon

• MuJoCo playground - https://github.com/google-deepmind/mujoco_playground

[kevinzakka]

Kudos for the beautiful (soon to be) contribution and write up!

[kevinzakka]

Note your latex in section 2 is not rendering correctly.

[Nan-Tetheria]

@kevinzakka Thank you for the kind words and for catching the rendering issue! The LaTeX in Section 2 has been fixed and should now display correctly in the latest update.

[btaba]

Hello! This is an amazing contribution! It looks like this is a fairly localized change (just adding a single env), so it'll be easy to merge if that's indeed the case. Can you add some reward curves to the PR as well?

[Nan-Tetheria]

@btaba Thank you! I've really enjoyed using MuJoCo Playground and am very happy to contribute.

All the changes are contained within a new environment, along with a few minor updates to the registry and configuration files.

Below are the reward curves exported from wandb, showing the overall reward, angular velocity term, action-rate penalty, and termination penalty. I can also include these plots in the README for the new PR if that would be helpful.

Please let me know if there’s anything else you'd like me to clarify.

Regarding the PR process, since it seems I don’t have permission to create a branch directly on the main repository, should I fork the repo and open a PR from my fork, or would you prefer to create a branch for me?

Nan

overall reward:

angular velocity:

action rate penalty:

termination penalty: