PBHC is the KungfuBot pipeline: SMPL motions in, a trained humanoid policy out

The repository is the implementation of two papers, not a general framework

PBHC is the official implementation of the paper KungfuBot: Physics-Based Humanoid Whole-Body Control for Learning Highly-Dynamic Skills, and it supports the general motion tracking of the follow-up paper KungfuBot2: Learning Versatile Motion Skills for Humanoid Whole-Body Control.

The first paper introduces a physics-based control framework that enables humanoid robots to learn and reproduce challenging motions through multi-stage motion processing and adaptive policy training. The second paper is the one that adds general motion tracking, and the project page for it is hosted separately at kungfubot2-humanoid.github.io.

The news entries date the work. In June 2025 the code and paper for PBHC were released, in September 2025 KungfuBot was accepted by NeurIPS 2025, and in October 2025 support for general motion tracking was released.

The authorship is spread across five institutions: the Institute of Artificial Intelligence at China Telecom, which is the TeleAI group behind the repository, Shanghai Jiao Tong University, East China University of Science and Technology, the Harbin Institute of Technology and ShanghaiTech University. Weinan Zhang and Xuelong Li are names associated with the reinforcement learning and simulation side of this line of work.

This is worth stating plainly for anyone evaluating it. What is in the repository is the code that produced the paper's results, and the paper is the specification. The repository is at version 0.0.1 in the setup.py, and there are no GitHub releases, so this is research code released alongside a publication rather than a maintained library.

The pipeline is three stages and the folder names tell you the order

The README gives a five-step recipe for teaching a robot a new motion, and the folder structure is the same list.

Step one is collecting the motion data from the source and processing it into the SMPL format, in motion_source/. The sources named are video, LAFAN and AMASS, and the target is a unified SMPL format, which is the human body parameterisation the rest of the pipeline assumes.

Step two is retargeting that motion to the robot, in smpl_retarget/, and the README says to choose the Mink or PHC pipeline as you like. Mink is the differentiable quadratic programming based contact-implicit motion optimiser, and PHC is the perceptive, human-aware motion control formulation. Both appear in the dependency list, with mink and quadprog named explicitly.

Step three is visualising and checking the motion quality, in smpl_vis/ and robot_motion_process/. The robot_motion_process/ directory covers visualisation, interpolation and trajectory analysis for robot-format motion, and there is a separate smpl_vis/ directory for the SMPL side.

Step four is training the policy for the processed motion in IsaacGym, in humanoidverse/. Step five is deploying the policy in MuJoCo or on a real-world robot, also from humanoidverse/.

The folder list confirms the shape. There is a description/ directory providing description files for SMPL and the G1 robot, motion_source/ with docs for getting SMPL format data, smpl_retarget/ for the SMPL to G1 retargeting tools, smpl_vis/ for visualisation, robot_motion_process/ for processing robot format motion, humanoidverse/ for training the RL policy, and example/ with example motion and checkpoints.

The G1 robot is the target, and the README says the framework is designed for easy extension, with custom policies and real-world deployment modules pluggable with minimal effort.

IsaacGym for training, MuJoCo for verification, and why both

The RL framework, humanoidverse/, trains the policy in IsaacGym and deploys trained policies in MuJoCo for sim2sim verification.

That two-simulator arrangement is the interesting engineering decision in the project. Training in one simulator and verifying in another is a deliberate check: a policy that only works in the simulator it was trained in has learned that simulator's quirks rather than the task. Running the same policy in a second, independently implemented physics engine is a genuine test of whether the behaviour transferred.

The cost is that the repository needs both, and IsaacGym in particular is not a pip-installable package in the ordinary sense. The setup.py dependency list is long and includes mujoco 3.2.3 with mujoco-python-viewer, dm_control, onnx and onnxruntime for the deployment side, open3d and numpy-stl for geometry, tensorboard and wandb for logging, and hydra-core for configuration, along with typer for the command line, loguru, rich, easydict and einops.

Two version pins stand out. numpy is pinned to exactly 1.24.4 and mujoco to 3.2.3, and Python 3.8 or later is required. A pinned numpy is a strong signal that something in the stack, most likely the simulation or the learning code, is sensitive to the numpy version, and an exact pin in a research codebase is often there because a newer numpy breaks something in a way that is tedious to diagnose.

The README does not include the installation steps itself, and it says so. Refer to INSTALL.md for environment setup and installation instructions, and each module folder contains a dedicated README.md explaining its purpose and usage.

Example checkpoints cover three different motions

The example/ directory ships data rather than just code, and the names of the checkpoints show what the system can already do.

There is example/motion_data/, described as the sample motion data from the experiments, which you can visualise with the tools in robot_motion_process/. Then there are three pretrained checkpoint directories: example/pretrained_hors_stance_pose/, example/pretrained_horse_stance_pose_2/ and example/pretrained_horse_stance_punch/.

The first two are variations on a horse stance pose, and the third is a punch. That set is a good indicator of what the framework was built to demonstrate, because a horse stance is a quadruped-like posture that has to be held in balance on two legs by a humanoid, and a punch is a highly dynamic movement with a large centre-of-mass excursion. Both are the cases where a whole-body controller either works or visibly does not.

The practical value of shipping checkpoints is that they let a user verify their environment before spending a GPU-week on training. If the pretrained horse stance policy does not reproduce in your IsaacGym build, you know the problem is the environment rather than your training setup.

The example motion data serves the same purpose one stage earlier. Retargeting is a step with many failure modes, and having a known-good input lets you check that the retargeting pipeline produces the motion you expect before training anything.

The licence is the adoption blocker, and the metadata disagrees with it

The README's License section states that the codebase is under the CC BY-NC 4.0 license, and that you may not use the material for commercial purposes. The repository root confirms it with a file named LICENSE-CC-BY-NC-4.0.md, and a LICENSE-CC-BY-NC-4.0.md is the only licence file in the top-level listing.

This is the single most consequential line in the README for an adopter. CC BY-NC 4.0 is a Creative Commons licence with a NonCommercial condition, which is not a standard open source licence and is incompatible with the Open Source Definition's requirement that licences allow commercial use. So despite the repository being on GitHub and freely readable, this is source-available for non-commercial use rather than open source in the strict sense.

There is a discrepancy worth flagging. The setup.py in the repository declares license="MIT" for the package named pbhc, while the README and the licence file say CC BY-NC 4.0, and the licence is not one GitHub can classify. A packaging manifest that says MIT while the licence file says CC BY-NC 4.0 is at best an oversight, and anyone using this in a commercial context needs to resolve which terms actually govern before shipping.

The attribution requirement of CC BY-NC also applies to academic use, so a paper or a talk using this code needs the citation the README provides.

Where PBHC is the wrong tool

The first wrong-tool case is a commercial deployment. The licence forbids commercial use outright, and that is a hard boundary rather than a negotiation. A company building a humanoid product cannot take this code as a starting point without a separate agreement, and there is no indication in the repository that one is offered.

The second is a team without the hardware and the simulation stack. The pipeline assumes a working IsaacGym installation for training and a MuJoCo setup for verification, and the dependency list is heavy enough that a plain pip install on a laptop is not the first step. The environment setup lives in INSTALL.md, and the research groups behind it clearly had GPU clusters.

The third is a team that wants a general-purpose humanoid control library rather than a paper reproduction. The module structure is organised around the stages of the KungfuBot pipeline, and the code is written to be extended for custom policies and real-world deployment modules, which is a researcher's framing rather than a library's. There is no stability promise, the version is 0.0.1, and there are no releases.

The fourth is the dependency surface itself. numpy pinned to 1.24.4, mujoco 3.2.3, dm_control, onnx, open3d, tensorboard, wandb, mujoco-python-viewer, opencv-python and meshcat is a large and partly dated stack, and some of it is commented out in the setup.py, including rerun-sdk, trimesh and a git dependency on SMPLSim, which suggests the dependency set is still being adjusted. A team intending to maintain this code long term will own that work.

The last push was on 2026-07-01, so the project is being worked on, and the two papers and their arXiv identifiers, 2506.12851 and 2509.16638, are the primary references for anyone evaluating the approach.

Editorial conclusion

PBHC fits a robotics researcher or lab that wants to reproduce the KungfuBot and KungfuBot2 results, or to reuse the retargeting and sim2sim tooling, and it does not fit a commercial deployment, because the codebase is under CC BY-NC 4.0 and may not be used for commercial purposes. Before using it, read INSTALL.md, because the setup involves IsaacGym and a pinned numpy and mujoco, and check the licence position for your case, since the setup.py metadata and the LICENSE file in the repository disagree about which terms apply.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. TeleHuman/PBHC on GitHub