---
license: apache-2.0
---
# motion-bricks.cpp

A C++23/GGML port of NVIDIA MotionBricks for CPU and Vulkan inference, with a stable C ABI for PureGo.

## What it is for

The repo holds the C++ source, a C header and C++ wrapper, a PureGo binding, a Go/Three.js demo, conversion scripts and parity tests.
It implements the batch-one G1 inference path end to end: strict GGUF loading, root and duration planning, pose-token prediction, VQ decoding, feature conversion, style alignment and skeletal animation output.
CPU and Vulkan use the same public API and make the same duration and pose-token decisions in the reference suite.
The C API uses only fixed-width scalars, pointers and opaque heap handles. No C++ exception crosses the ABI boundary.
At runtime a caller loads one model and one or more `.mbstyle` assets, creates an agent, sets movement, facing and style, then calls `mb_agent_plan` and `mb_agent_advance`.
The bundle loader checks the upstream revision, checkpoint identities, tensor and parameter counts and the joint topology before it accepts a model.

## Provenance

- Upstream source: NVIDIA MotionBricks in [NVlabs/GR00T-WholeBodyControl](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/a0732b642c0333077e127a2f56ab0014c196bca4/motionbricks), at revision `a0732b642c0333077e127a2f56ab0014c196bca4`.
- Converted weights and style primitives: [LocalAI-io/MotionBricks-G1-GGML](https://huggingface.co/LocalAI-io/MotionBricks-G1-GGML). The default build pins Hugging Face commit `cc2a47603dbc203a4f18f35dd06ed3611833f506`.
- Fork notes are in `FORK_PROVENANCE.md`. The pinned upstream reference is in `reference/README.md`.

## Build and run

```sh
cmake --preset debug
cmake --build --preset debug
ctest --preset debug
./build/debug/bin/motionbricks-cli abi
```

Configuration downloads and SHA-256-verifies the G1 F32 GGUF and style bundles into `generated/`. Use `-DMOTIONBRICKS_DOWNLOAD_MODELS=OFF` for an offline build. On NixOS, run `nix develop` first.
The Go binding and demo load `libmotionbricks` at runtime with PureGo, so they build with `CGO_ENABLED=0`:

```sh
cd demo
CGO_ENABLED=0 go build -o ../build/debug/bin/motionbricks-demo .
```

See `docs/DEMO.md` for the demo, `docs/FORMATS.md` for the file formats and `docs/IMPLEMENTATION.md` for the design.

## Licence

The source code is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) (`LICENSE`).
NVIDIA's model weights and the converted GGUF and style distributions stay under the NVIDIA Open Model License, reproduced with [LocalAI-io/MotionBricks-G1-GGML](https://huggingface.co/LocalAI-io/MotionBricks-G1-GGML) and in `scripts/hf/MotionBricks-G1-GGML/UPSTREAM_LICENSE`.
Bundled third-party parts keep their own licences. The vendored Three.js files are covered by `demo/web/vendor/THREE-LICENSE.txt`.