| # Go and Three.js demo |
|
|
| The initial demo is a local Go application that calls `libmotionbricks` |
| through the PureGo binding and serves an embedded Three.js viewer. It renders |
| the released 34-joint G1 hierarchy directly from MotionBricks root |
| translations and local XYZW joint rotations; it does not require MuJoCo or a |
| skinned mesh. Solid cyan cylinders and round joints identify the generated |
| character. An orange diamond-jointed ghost skeleton identifies a selected |
| placed style-pose constraint supplied to the planner; all four constraints can |
| be overlaid for inspection. |
|
|
| ## Build and run |
|
|
| First build the native project and create the model/style assets described in |
| the main README. Then build the Go application: |
|
|
| ```sh |
| cmake --build --preset debug |
| cd demo |
| CGO_ENABLED=0 go build -o ../build/debug/bin/motionbricks-demo . |
| cd .. |
| ``` |
|
|
| The demo and reusable Go binding call the native shared library through |
| PureGo. They contain no cgo bridge and do not require a C compiler during the |
| Go build, so cgo can be disabled. This does not remove the separate C++/CMake |
| build that produces `libmotionbricks`. |
|
|
| Run it from the repository root: |
|
|
| ```sh |
| ./build/debug/bin/motionbricks-demo \ |
| -listen 127.0.0.1:8080 \ |
| -library ./build/debug/libmotionbricks.so \ |
| -model ./generated/g1-f32 \ |
| -styles ./generated/styles \ |
| -device cpu |
| ``` |
|
|
| Open `http://127.0.0.1:8080/`. Hold physical W/A/S/D keys to move, or tap an |
| on-screen direction to latch it; tap the active pad direction again to stop. |
| Space or Escape also stops movement. Left/right arrow keys rotate the facing |
| direction without changing the current travel vector. The selector switches |
| among all `.mbstyle` files found in the style directory, including the 15 |
| converted upstream styles. Drag over the viewport to orbit, use the wheel to |
| zoom, and use **Reset camera** to restore the automatically framed view. The |
| camera follows only the animated skeleton, so target placement never pulls the |
| view away from the character. The T0–T3 slider selects one fully visible target |
| pose. **Overlay all four consecutive poses** reveals the complete constraint |
| window. These are adjacent 30 FPS constraint frames rather than four distant |
| waypoints, so their exact world positions are intentionally close together. |
|
|
| `-device` accepts `cpu`, `vulkan`, or `auto`. The server deliberately binds to |
| localhost by default. Model inference is serialized while sessions keep |
| independent agent/context state. |
|
|
| ## Runtime shape |
|
|
| The browser creates a session, receives a 30 FPS animation chunk, and asks for |
| a replacement chunk when controls change or playback approaches the end. |
| Each request contains movement, facing, style, seed, and the number of frames |
| already consumed. The Go server advances that session's native agent and |
| returns owned animation data and target constraints as JSON: |
|
|
| - root translations: `[frames, 3]`; |
| - local joint rotations: `[frames, 34, 4]`, XYZW; |
| - placed target roots: `[4, 3]`; |
| - placed target local rotations: `[4, 34, 4]`, XYZW; |
| - G1 joint names, parent indices, and neutral positions from the loaded model. |
|
|
| The native target data is captured after style-frame sampling, spring-based |
| world placement, and heading correction. The ghosts therefore visualize the |
| actual planner inputs. The viewer does not force them in front: forward travel |
| normally places them ahead, while stops and turns can make them overlap the |
| character or move sideways. |
|
|
| The browser builds `THREE.Bone` objects from the returned hierarchy and draws |
| solid cylinders/spheres for the generated skeleton and translucent |
| cylinders/diamonds for target poses. It also draws generated and target root |
| paths on the floor. Animation chunks are immutable in JavaScript; a later |
| version can replace JSON with a binary streaming protocol without changing |
| the native API. |
|
|
| Three.js r180 is vendored under `demo/web/vendor` so the demo has no runtime |
| CDN dependency. |
|
|
| ## Tests |
|
|
| With the generated assets present, CTest registers `motionbricks-go-demo` when |
| Go and Chromium are available. The test starts an in-process HTTP server, |
| loads the real native model, plans an initial `walk` chunk, then uses headless |
| Chromium to select `walk_zombie`, turn right, plan another chunk, render the |
| 34-joint generated hierarchy plus the target inspector, and capture initial, |
| forward-motion, and style-and-turn screenshots. It uses real Chrome click and |
| keyboard events and asserts forward-pad movement, pad stop, keyboard movement, |
| keyboard stop, animated-skeleton camera anchoring, individual target selection, |
| and the four-pose overlay before the visual self-test. |
|
|
| The Go tests can also be run directly: |
|
|
| ```sh |
| cd demo |
| MOTIONBRICKS_LIB=../build/debug/libmotionbricks.so \ |
| MOTIONBRICKS_MODEL=../generated/g1-f32 \ |
| MOTIONBRICKS_STYLES=../generated/styles \ |
| MOTIONBRICKS_CHROME="$(command -v chromium)" \ |
| CGO_ENABLED=0 go test -v ./... |
| ``` |
|
|
| Without the native asset environment variables, the parser test still runs |
| and the native/browser integration cases are skipped. |
|
|
| ## Initial limitations |
|
|
| - G1 is the only skeleton supported by the released model. |
| - The viewer intentionally shows a bone skeleton, not a skinned avatar. |
| - HTTP JSON carries whole planned chunks; binary streaming and client-side |
| overlap blending are future work. |
| - Sessions are in-memory and intended for a trusted local demo, not an |
| internet-facing multi-user service. |
|
|
