BrickSim

A Physics-Based Simulator for Manipulating Interlocking Brick Assemblies

Website • Paper • Quickstart • Video

Quickstart

Prerequisites

• x86-64 Linux platform. Support for other platforms is coming.
• Ubuntu 22.04+ or another Linux distribution with GLIBC >= 2.35, GLIBCXX >= 3.4.30, and CXXABI >= 1.3.13
• uv package manager
• A working NVIDIA driver compatible with Isaac Sim requirements

Installation

We use uv for package management. If you don't have it installed, please refer to Installing uv.

# Install host tools (for Debian/Ubuntu)
sudo apt install build-essential wget xz-utils zstd git

# Clone the repository
git clone --recursive https://github.com/intelligent-control-lab/BrickSim BrickSim
cd BrickSim

# Set up the Python environment
# This will also install Isaac Sim 5.1, Isaac Lab, and the BrickSim package
uv sync --locked

Run Demos

# Launch the assembly demo in Isaac Sim
./scripts/launch_isaacsim.sh demos/demo_assembly.py

Other demos include:

• demos/demo_inhand.py for in-hand manipulation experiments
• demos/demo_keyboard_teleop.py for keyboard-driven interaction
• demos/demo_teleop.py for teleoperation, recording, and replay workflows
  • The teleoperation demo expects the lerobot package plus a configured leader device path inside demos/demo_teleop.py.

Development

Repository Layout

Path	Purpose
native/	C++26 core
exts/bricksim/	Python extension and API
demos/	Demos
resources/	USD assets, robot assets, and brick datasets
scripts/	Utility scripts

Generating Type Checker Configuration

Generate the Pyright and ty configuration for type analysis and completion in editors like VSCode:

uv run python scripts/generate_type_configs.py

We recommend installing the ty extension for VSCode auto-completion, as it's much faster at handling Isaac Sim's many dependencies.

Building the C++ Extension

If you make changes to the C++ code in native/, you need to re-compile the native extension for the changes to take effect.

./scripts/build.sh

# To also build & run the tests, use:
RUN_TESTS=1 ./scripts/build.sh