project_superdex README

The project's README from github.com/facebookresearch/project_superdex. As one markdown file: README.md.

Project SuperDex

A unified platform for dexterous manipulation research

Welcome to Project SuperDex.

SuperDex brings together a purpose-built physics engine, robotics authoring tools, and a scalable reinforcement learning interface in a unified simulation platform, with VR-based teleoperation and additional capabilities planned for future releases.

Visit the Project SuperDex website for more.

Threaded Screw Manipulation
Threaded Screw Manipulation

Building blocks


The following videos were recorded in real-time using SuperDex Teleop (available in Q4 2026).

Soft Sponge Fruit Bag
Soft Sponge Fruit Bag
Cereal Box Rope Braid
Cereal Box Rope Braid
Contact Viz Puzzle Cube
Contact Viz Puzzle Cube
Compose Bots Soft Fingertips
Compose Bots Soft Fingertips

SuperDex Studio

SuperDex Studio is the desktop application where you turn raw CAD and robot descriptions into native SuperDex Assets - bots, prefabs, and scenes. This is the GUI toolkit of Project SuperDex.

Click to learn more about SuperDex Studio.

SuperDex Studio Apply Forces
SuperDex Studio Apply Forces

SuperDex Lab (early preview)

SuperDex Lab connects simulation and policy development through a Gymnasium-style API for reinforcement learning. It is currently in early preview and will receive substantial improvements.

Click to learn more about SuperDex Lab.

Reinforcement Learning


Q4 2026: SuperDex Teleop

SuperDex Teleop is the next major module coming to Project SuperDex. Initial components for Unreal Engine 5 based virtual teleoperation will be available in Q4 2026.

Ben Virtual Teleop

SuperDex Teleop runs natively on-device on Quest 3. No remote PC, no streaming. Includes support for both hand tracking and controllers including mixed mode. Runs in pure C++ for low-latency, real-time, scalable virtual teleop.

Android Teleop


Requirements

Get the Source Code and Examples

Quick Start (Python)

Project SuperDex has first-class support for Python across the board. The quickest way to get started is with uv and pypi wheels.

  1. Install pre-requisites
    • uv
    • Linux Only: SuperDex Studio and SuperDex Physics Debugger require an available X11 display (native X11 or XWayland), a graphics driver supporting OpenGL 4.1, and the following runtime components:
      • Ubuntu/Debian: sudo apt install libgl1 libx11-6 libx11-xcb1 libxcb1 libxext6 libxrandr2 libxinerama1 libxcursor1 libxi6 zenity
      • Fedora/RHEL: sudo dnf install libglvnd-glx libX11 libX11-xcb libxcb libXext libXrandr libXinerama libXcursor libXi zenity
  2. cd into the project_superdex source directory
  3. Create venv uv venv
  4. Pip Install: uv pip install superdex
  5. Run
    • Optional: To run Python examples in double precision (float64), set the environment variable SUPERDEX_PRECISION=double; otherwise, single precision is used.
    • Physics example: uv run --no-project superdex_physics/examples/example_tendon_comparison.py
    • Robotics example: uv run --no-project superdex_robotics/examples/control/example_osc_jsc_control.py
    • SuperDex Studio: uv run --no-project superdex-studio
    • Note: --no-project is required for uv run cmds within this repo or else it will build from source

Building from Source

Install Pre-requisites

Building from Source (Python)

  1. Get the source code and install pre-requisites (see above)
  2. Windows only: From the Start menu, launch the x64 Native Tools Command Prompt matching your installed Visual Studio version (e.g. x64 Native Tools Command Prompt for VS 2022).
  3. cd into the project_superdex source directory
  4. Build: uv sync --extra gui -v
  5. Run:
    • Physics example: uv run superdex_physics/examples/example_tendon_comparison.py
    • Robotics example: uv run superdex_robotics/examples/control/example_osc_jsc_control.py
    • SuperDex Studio: uv run superdex-studio

Flags for uv sync are:

uv sync flags (additive) Build targets
none build tools only
--extra core physics, robotics, lab
--extra gui core + physics-debugger, studio, mesh-cli
--extra double core + physics-fp64, robotics-fp64
--all-extras everything

NOTE: Running the examples above requires --extra gui.

NOTE: --extra double builds the double-precision bindings, but single precision is still the default at runtime. To run Python examples in double precision, set the environment variable SUPERDEX_PRECISION=double.

Building from Source (C++)

Core modules such as SuperDex Physics and SuperDex Robotics are written in C++ and exposed to Python. Full C++ examples will be shared in the future. Users who are interested in calling C++ directly can get started via CMake.

  1. Get the source code and install pre-requisites (see above)
  2. Windows only: From the Start menu, launch the x64 Native Tools Command Prompt matching your installed Visual Studio version (e.g. x64 Native Tools Command Prompt for VS 2022).
  3. cd into the project_superdex source directory
  4. Configure lean Release build: cmake -B build -DCMAKE_BUILD_TYPE=Release -DMOCHI_BUILD_DEBUGGER=OFF -DMOCHI_USE_PYBIND=OFF -G Ninja
  5. Build: cmake --build build --parallel

NOTE: To build the C++ libraries in double precision, add -DMOCHI_USE_DOUBLE_PRECISION=ON when configuring CMake. Otherwise, single precision will be used by default.


Documentation

Documentation, getting started guides, and examples are available for all modules.


How to Contribute

We welcome contributions! Go to CONTRIBUTING and our CODE OF CONDUCT for how to get started.

Reporting Issues

Please report issues via GitHub Issues.

License

First-party SuperDex source code is licensed under Apache 2.0. Assets and documentation are licensed under CC-BY-4.0 except where otherwise noted. Third-party and derived code and assets retain their own terms, recorded in their accompanying LICENSE and NOTICE files. superdex_mesh_cli is an optional, standalone mesh processing CLI tool released under GPLv3 due to use of OCCT and CGAL.

Third-party license families represented in this repository include Apache-2.0, BSD-2-Clause, BSD-3-Clause, BSL-1.0, CC-BY-4.0, CC0-1.0, GPL-3.0-or-later, LGPL-2.1 with the OCCT exception, LGPL-3.0-or-later, MIT, MPL-2.0, SIL OFL-1.1, HDF5, libpng, public-domain, zlib, Zstandard, and component-specific commercial or asset terms. The accompanying license and notice files are authoritative for each component or asset.

Certain third party dependencies and third party assets in this repo are licensed for non-commercial/academic uses only. You must ensure that you, as the user, access and use such third party dependencies and assets in compliance with their respective licenses.


Citation

Citation details will be added here upon publication.

project_superdex (facebookresearch/project_superdex)

Searching Database…

What is this?Project SuperDex is a unified simulation platform for dexterous manipulation research from Meta, combining a contact-first physics engine, robotics authoring tools, and a reinforcement learning interface, with VR-based teleoperation planned for Q4 2026.
Is this one tool or several modules bundled together?It is four building blocks under one platform: SuperDex Physics (the physics engine), SuperDex Robotics (the robot SDK), SuperDex Studio (a desktop GUI for authoring assets), and SuperDex Lab (the RL/MPC simulation harness).
How do I get it running?Install uv, then run 'uv venv' to create a virtual environment and 'uv pip install superdex' to pull the PyPI wheels; after that you can run the bundled physics, robotics, or SuperDex Studio examples with 'uv run --no-project'.
What do I need installed before trying this?You need Python 3.12 since pre-built wheels only target that version right now, plus the uv package manager; building from source additionally needs CMake 3.25+, Ninja, and a platform compiler (Clang on Linux, Xcode tools on macOS, MSVC Build Tools on Windows).
Is SuperDex Lab ready for serious RL work yet?SuperDex Lab, the Gymnasium-style RL interface, is explicitly in early preview and expected to change substantially; the VR teleoperation module isn't available at all yet and is slated for Q4 2026.
Which operating systems does it actually support?Only Linux x86_64, Windows x86_64, and macOS on Apple Silicon (ARM) are supported; there's no Intel Mac support.
Is the whole repo under one simple license?First-party SuperDex code is Apache-2.0 and assets/docs are CC-BY-4.0, but the bundled mesh-processing CLI tool is GPLv3 because it uses OCCT and CGAL, and some third-party dependencies and assets are restricted to non-commercial or academic use only.
What is SuperDex Teleop and when does it arrive?SuperDex Teleop is the upcoming VR teleoperation module, due in Q4 2026, built in pure C++ for low-latency real-time control. It runs natively on-device on a Quest 3 headset with no remote PC or streaming required, and supports hand tracking, controllers, and mixed mode.
What does SuperDex Studio actually do?SuperDex Studio is a lightweight desktop GUI app for creating, editing, and validating simulation assets like robots, meshes, task prefabs, and scenes before they're used in SuperDex Physics or Lab.
Can I run the simulation in double precision?Yes. Single precision is the default, but setting the environment variable SUPERDEXPRECISION=double switches Python examples to float64; building with --extra double compiles the double-precision bindings.
What does SuperDex Lab give you for RL training?It exposes a Gymnasium-style API that abstracts the underlying Markov decision process and dynamics-constrained optimization, so it can back reinforcement learning, MPC, and system identification workflows.
Size
761 MB
Stars
742
Age
1mo
Commits · 90 Days