A Godot 4 viewer for MH-FLOCKE. Visualisation only.
This repository does not simulate anything. Physics stays in MuJoCo in the
MH-FLOCKE work repo; Godot renders state that was recorded there. Nothing here
writes to the SNN, to brain.pt, or to any file in that repo — the tools open
it read-only.
- replays a finished training run: recorded joint state, frame by frame
- draws the recorded SNN spike raster in the MH-FLOCKE cerebellar layout
- renders vertical clips for social media through Godot's Movie Maker
See docs/VIDEO_WORKFLOW.md for the full path from a training run to a
finished clip.
Inherited unchanged from MH-FLOCKE and binding here: every value on screen
traces to a real frame in the training log. No derived, guessed,
default-as-real or interpolated numbers, not as a fallback. A missing value is
shown as — or the element is not drawn.
Concretely, in the picture:
| shown | status |
|---|---|
| body pose | recorded — every pose is a logged qpos vector |
| which neuron fired | recorded — from the logged spike raster |
| population membership | recorded — from the layout the raster is built in |
| neuron positions | schematic — an SNN has no coordinates of its own |
| individual connections | schematic — the log carries no weight matrix |
| a lit connection | derived — its source neuron fired; nothing is known about transmission |
| playback rate | viewer setting, labelled as such in the HUD |
| floor colour | presentation — height and pattern come from the model |
Frames are not interpolated. A run logged every 10 steps plays as discrete
frames at that cadence, with the cadence on screen. Smooth motion requires a
run logged with --log-every 1 --record-interval 1; it is not manufactured
here.
tools/ Python side (converters, probes) — run with py -3.11
godot/ Godot 4 project
docs/ workflow documentation
Three generated files are not in the repo and have to be built from a run
(see the workflow doc): rig.json, trace.json, brain_layout.json. The
robot meshes are included.
- Godot 4.7, standard build, not .NET. There is no installer: the download is a ZIP containing a single executable, no admin rights needed. https://godotengine.org/download
- Python 3.11 for the tools, with
msgpack - a checkout of MH-FLOCKE with at least one completed training run
- ffmpeg, only if you want an MP4 rather than Godot's MJPEG AVI
Tested on Windows 11 with Godot 4.7.1 and Python 3.11. Nothing in here is
platform specific, but the commands below are written for cmd.exe.
git clone https://github.com/MarcHesse/mhflocke-godot.git
cd mhflocke-godot
py -3.11 -m pip install msgpack
Unpack Godot wherever you like; the executable runs from there.
The Bittle meshes are included, so nothing else has to be fetched for the robot to appear.
None of these are in the repository; they are generated from a run and from the model.
set WORK=path\to\mhflocke
py -3.11 tools\mjcf2rig.py %WORK%\creatures\bittle\scene_mhflocke.xml godot\assets\bittle\rig.json
py -3.11 tools\flog2trace.py %WORK%\creatures\bittle\<run-id>\training_log.bin godot\assets\bittle\trace.json
py -3.11 tools\brain_layout.py %WORK% godot\assets\bittle\trace.json godot\assets\bittle\brain_layout.json
rig.json and brain_layout.json only need rebuilding when the model or the
network topology changes. trace.json is per run.
For a clip, record the run with --log-every 1 --record-interval 1. Those are
two independent intervals; at the default the body pose is logged ten times
less often than the spikes and the robot visibly stutters.
Start Godot, choose Import, pick godot/project.godot, then press F5. The
first import takes a moment because it processes 41 OBJ files.
[space] play/pause [<-/->] step one frame [R] restart [F] follow
[1-4] camera presets [5] panel [6] connections [7] labels [8] flight
[H] hud
Mouse: left drag orbits, right drag pans, wheel zooms.
See docs/VIDEO_WORKFLOW.md for the full path, including the vertical
two-part clip and the ffmpeg calls.
| symptom | cause |
|---|---|
rig.json could not be loaded in the HUD |
file not generated yet, or generated by an older tool version — the viewer refuses a format it does not know rather than drawing it wrong |
trace rejected: qpos_len N |
the trace is from a different model than the rig |
| robot stutters while the network is smooth | run was recorded with the default --record-interval |
| network shown without population colours | the layout did not match the raster length, so it fell back to unlabelled rather than guessing which neuron is which |
This project is Apache 2.0, see LICENSE.
The Bittle meshes under godot/assets/bittle/meshes_obj/ are not mine. They
come from the Petoi Bittle URDF by way of gravesreid/mujoco_mpc_bittle. The
original licence is kept next to them in
godot/assets/bittle/LICENSE_BITTLE_URDF.txt and applies unchanged. They are
included here so the viewer runs on its own; the same files also live in the
MH-FLOCKE repo and in the upstream project.