KangEngine

A lightweight C++ engine for computer graphics and robotics research, with a Python interface for simulation and control experiments.

Features

• Rendering — OpenGL/GLFW renderer with ImGui panels, camera controls, materials, shadows, post-processing, and mesh instancing. (TODO : WebGPU support)
• Scene — A lightweight native scene graph with USD-style prim paths, transforms, mesh data, visibility, and display color attributes.
• Physics — Optional NVIDIA PhysX integration for rigid bodies, articulations, and robot simulation examples.
• Animation — Skeleton data structures, forward kinematics, MJCF loading, and bridges from skeleton/physics state to scene visuals.
• Simulation — Experimental XPBD cloth simulation utilities.
• OpenUSD — Optional OpenUSD backend when configured with -DUSE_USD=ON.
• Python — Optional pybind11 module for using the engine, scene, animation, and physics APIs from Python.

How to build

Install CMake first, then follow the platform steps below.

vcpkg

KangEngine uses vcpkg manifest mode for most third-party C++ dependencies.

1. Clone and bootstrap vcpkg.

   git clone https://github.com/microsoft/vcpkg.git
   cd vcpkg && ./bootstrap-vcpkg.sh

2. Export VCPKG_ROOT and add vcpkg to PATH.

   export VCPKG_ROOT=/path/to/vcpkg
   export PATH=$VCPKG_ROOT:$PATH

Linux (tested with Ubuntu 24.04)

1. Install system packages.

   sudo apt install clang ninja-build unzip libxinerama-dev libxcursor-dev xorg-dev libglu1-mesa-dev pkg-config autoconf autoconf-archive automake libtool

2. Download NVIDIA Omniverse PhysX under $HOME/Physics/PhysX.

   mkdir -p ~/Physics
   cd ~/Physics
   wget https://github.com/NVIDIA-Omniverse/PhysX/archive/refs/tags/104.1-physx-5.1.2.zip
   unzip 104.1-physx-5.1.2.zip
   mv PhysX-104.1-physx-5.1.2 PhysX

3. Build PhysX with clang.

   cd ~/Physics/PhysX/physx
   ./buildtools/packman/packman update -y
   ./generate_projects.sh
   
   cd compiler/linux-release
   cmake . \
     -DCMAKE_C_COMPILER=clang \
     -DCMAKE_CXX_COMPILER=clang++ \
     -DCMAKE_CXX_FLAGS="-Wno-error=unsafe-buffer-usage -Wno-unsafe-buffer-usage -Wno-error=switch-default -Wno-switch-default -Wno-error=invalid-offsetof -Wno-invalid-offsetof -Wno-error=unused-but-set-variable -Wno-unused-but-set-variable"
   cmake --build . --config release # (debug|checked|profile|release)

   Do not run the PhysX configure/build commands with sudo. If files were created as root, fix ownership first.

   sudo chown -R "$USER:$USER" ~/Physics/PhysX/physx

   The PhysX snippet executables may fail to link against the bundled OpenGL package, but KangEngine only needs the PhysX static libraries in ~/Physics/PhysX/physx/bin/linux.clang/release.
4. Configure KangEngine with clang.

   CC=clang CXX=clang++ cmake --preset=vcpkg

5. Build KangEngine.

   cmake --build build/release

6. Run KangEngine.

   make run2

macOS (tested with M4 mac)

1. Clone o3de PhysX under $HOME/Physics/PhysX.

   mkdir -p ~/Physics
   cd ~/Physics
   git clone -b 104.1 https://github.com/o3de/PhysX.git

2. Install build tools.

   brew install coreutils ninja autoconf automake autoconf-archive

3. Build PhysX.

   cd ~/Physics/PhysX/physx
   ./buildtools/packman/packman update -y
   ./generate_projects.sh
   
   # Note: The O3DE PhysX build system uses the 'mac.x86_64' directory name for all macOS builds, including M-chips.
   cd compiler/mac.x86_64
   cmake --build . --config release # (debug|checked|profile|release)

4. Configure KangEngine.

   cmake --preset=vcpkg

5. Build KangEngine.

   cmake --build build/release

OpenUSD (Optional)

OpenUSD is only needed when configuring KangEngine with -DUSE_USD=ON.

1. Clone OpenUSD.

   cd ~
   git clone https://github.com/PixarAnimationStudios/OpenUSD.git

2. Build OpenUSD into ~/usd_build.

   mkdir -p ~/usd_build
   python3 ~/OpenUSD/build_scripts/build_usd.py ~/usd_build

3. If you build OpenUSD somewhere else, pass -Dpxr_DIR=/path/to/usd_build to your CMake configure command instead of modifying CMakeLists.txt.

Python Bindings (Optional)

KangEngine exposes a Python module (`kangengine`) via pybind11. The extension is built by CMake and must be compiled against the same Python that will run it.

1. Create a virtual environment with Python 3.12 using uv.

   cd python
   uv venv .venv --python 3.12
   source .venv/bin/activate

2. Build the extension with CMake from the repo root.

   cd ..
   make build_python
   # or with USD support:
   # make build_usd_python

3. Install the Python package in editable mode.

   cd python
   uv pip install -e .

4. Run an example.

   python examples/control_demo.py

RL with MimicKit

KangEngine can be used as a backend engine of MimicKit through KangEngine's Python package. Use the backend_kangengine branch of MimicKit and keep MimicKit in a separate Python environment.

1. Clone the KangEngine-enabled MimicKit fork branch.

   git clone -b backend_kangengine https://github.com/Gudegi/MimicKit.git

2. Create and activate a MimicKit Python environment with uv.

   cd MimicKit
   uv venv .venv --python 3.12
   source .venv/bin/activate

3. Build KangEngine's Python extension from the KangEngine repo.

   cd /path/to/KangEngine
   make build_python

4. Install KangEngine's Python package into the MimicKit environment.

   cd python
   uv pip install -e .

5. Install MimicKit dependencies.

   cd /path/to/MimicKit
   source .venv/bin/activate
   uv pip install -r requirements.txt

6. Run a small motion visualize test.

   python mimickit/run.py \
     --mode test \
     --num_envs 1 \
     --engine_config data/engines/kangengine_engine.yaml \
     --env_config data/envs/view_motion_humanoid_env.yaml \
     --visualize true \
     --devices cpu \
     --test_episodes 10

7. Run pretrained policy inference with KangEngine.

   python mimickit/run.py \
     --mode test \
     --num_envs 4 \
     --engine_config data/engines/kangengine_engine.yaml \
     --env_config data/envs/amp_humanoid_env.yaml \
     --agent_config data/agents/amp_humanoid_agent.yaml \
     --visualize true \
     --model_file data/models/amp_humanoid_spinkick_model.pt

   Currently, KangEngine has only been tested with pretrained MimicKit policy inference, not full RL training.

For reference, the MimicKit KangEngine backend uses an engine config like this:

engine_name: "kangengine"

control_mode: "pos"
control_freq: 30
sim_freq: 120
env_spacing: 5
enable_self_collisions: false

The backend_kangengine branch already includes data/engines/kangengine_engine.yaml, so you usually do not need to create it manually.