ianshank/forge-muzero-minecraft

FORGE MuZero (Minecraft) — ONNX bundle

Random-init bundle — NOT a trained model. These weights come from the bootstrap random initializer and exist to validate the publish/warm-start pipeline. Do not expect useful play behaviour.

MuZero world-model bundle for the FORGE self-improving Minecraft loop: a Rust episode runner drives a live Minecraft environment over a WebSocket bridge, records flat-tensor trajectories, trains this model in Python, and hot-reloads the exported ONNX back into the runner's latent MCTS between episodes.

Files

The three MuZero networks are exported as separate ONNX graphs (opset 17) so the Rust runner can load them independently. The Rust runner binds inputs/outputs by name:

File	Inputs	Outputs
representation.onnx	observation [B, obs_dim]	latent_state [B, latent_dim]
dynamics.onnx	latent_action [B, latent_dim + action_dim]	next_latent, reward_logits
prediction.onnx	latent_state [B, latent_dim]	policy_logits, value_logits

model_manifest.json records per-file SHA-256s, the bundle version, and the environment schema_id (manifest schema_version 1 — byte-compatible with the Rust runner's ModelManifest).

Contract

• schema_id: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa (sha256 over the canonical action_map + rewards configs; the runner refuses bundles whose schema_id mismatches its env handshake)
• obs_dim: unspecified · action_dim: unspecified
• Bundle version: 1 · exported 2026-08-12T21:12:04.106989+00:00

Checksums

Role	SHA-256
representation	cfa5ba6c97a3a1a173ccc2b635b4c9be0de356d35b98c68ca1500246c74a2759
dynamics	9bdef1beec652fd4f28333c98ba7628b01b8acb7345afdffbcb6e8c92e5179b3
prediction	680fe95e8960e30a95c878974df936cbc5419c3e42c9ef85dd780b67c3ebdfb2

Usage — warm-start a FORGE bundle

pip install -e ".[minecraft]"
python -m forge.training.muzero_mc.cli bootstrap \
    --from-hf ianshank/forge-muzero-minecraft \
    --obs-dim unspecified --action-dim unspecified \
    --schema-id aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
    --out models/

The runner's HotReloadWatcher picks up the bundle between episodes; see the repository's docs/hf/README.md for the full pipeline.

Training configuration

Defaults from python/forge/models/muzero_config.py: latent_dim 256, hidden_dim 256, 4 residual blocks, reward/value support 31, discount 0.997, 5 unroll steps, TD-10, lr 3e-4. Observation layout: 11×11×1×7 block grid + 73-dim state vector → obs_dim 920.

Published by scripts/hf_publish_model.py from ianshank/FORGE.