Skip to content

Installation

Requirements

  • CMake 3.20+
  • C++17 compiler (Clang, GCC, or MSVC)
  • Python 3.9+ with NumPy and Gymnasium
  • Vulkan SDK (optional, for the renderer)

All C++ dependencies are fetched automatically via CMake FetchContent:

Dependency Purpose
Jolt Physics Physics engine
tinyxml2 MJCF XML parsing
SDL2 Windowing (renderer)
Dear ImGui Debug UI overlay
vk-bootstrap Vulkan initialization
VMA Vulkan memory allocation

The simplest way to install JoltGym is as a Python package using pip:

pip install -e .

This uses scikit-build-core to build the C++ extension module and install the Python package in one step.

Optional Dependencies

For development and testing:

pip install -e ".[dev]"

This installs additional packages:

  • pytest -- for running the test suite
  • mujoco -- for comparison benchmarks

For training with PPO (used in demos):

pip install stable-baselines3 tensorboard

For video recording:

pip install matplotlib
# Optional: install ffmpeg for MP4 output (otherwise GIF)
brew install ffmpeg    # macOS
sudo apt install ffmpeg  # Ubuntu/Debian

CMake Build (C++ Development)

For working on the C++ source directly:

Full Build (with renderer)

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Without Vulkan Renderer

cmake -B build -DCMAKE_BUILD_TYPE=Release -DJOLTGYM_BUILD_RENDERER=OFF
cmake --build build -j$(nproc)

CMake Options

Option Default Description
JOLTGYM_BUILD_RENDERER ON Build Vulkan renderer (requires Vulkan SDK)
JOLTGYM_BUILD_PYTHON ON Build pybind11 Python module
JOLTGYM_BUILD_TESTS OFF Build C++ test executables

Verifying the Installation

import joltgym

env = joltgym.make("JoltGym/HalfCheetah-v0")
obs, info = env.reset(seed=42)
print(f"Observation shape: {obs.shape}")  # (17,)
print(f"Action space: {env.action_space}")  # Box(-1.0, 1.0, (6,))
env.close()
print("JoltGym is working!")

Platform Notes

macOS

Vulkan rendering uses MoltenVK. Install the Vulkan SDK for macOS if you want the renderer.

Linux

Install the Vulkan SDK and development headers:

sudo apt install libvulkan-dev vulkan-tools

Windows

Install the Vulkan SDK and ensure Visual Studio 2019+ is available with C++17 support.