| --- |
| 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`. |
|
|
