---
license: apache-2.0
library_name: onnx
pipeline_tag: reinforcement-learning
tags:
  - forge
  - muzero
  - minecraft
  - onnx
  - model-based-rl
---

# FORGE MuZero (Minecraft) — ONNX bundle

> [!WARNING]
> **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](https://github.com/ianshank/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

```bash
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](https://github.com/ianshank/FORGE).