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, at revision a0732b642c0333077e127a2f56ab0014c196bca4.
• Converted weights and style primitives: 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

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:

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