H3-World README

The project's README from github.com/Danzer1xxxxChan/H3-World. As one markdown file: README.md.

H3-World: Turning Language Understanding into World Control

H3-World is the first interactive world model built on MiniMax-H3. It generates action-controlled video from an initial frame by converting keyboard states into per-latent language instructions and binding each instruction to its corresponding future video latent through directed attention routing. Using 8,000 gameplay clips from ABot-World-Explorer-500h, H3-World learns 65.6M LoRA parameters, only 0.199% of the 33B backbone.

arXiv Hugging Face model Project page ModelScope

https://github.com/user-attachments/assets/1c862995-8809-447e-bade-2c47bfdb2738

H3-World: Turning Language Understanding into World Control
Danze Chen1,2, Zeqing Wang1,2, Ziyue Lin3, Xingyi Yang3, Yeying Jin1,2
1Tencent   2National University of Singapore   3The Hong Kong Polytechnic University

⚙️ Setup

Tested with Python 3.10 and CUDA 12.8.

conda create -n minimax_h3 python=3.10 -y
conda activate minimax_h3
pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt

# Use the exact DiffSynth revision and the H3-World attention patch.
git clone https://github.com/modelscope/DiffSynth-Studio.git DiffSynth-Studio-h3-v2
git -C DiffSynth-Studio-h3-v2 checkout "$(cat code/diffsynth_base_commit.txt)"
git -C DiffSynth-Studio-h3-v2 apply ../code/diffsynth_h3_action.patch

# Keep Hugging Face, Torch, and Triton caches inside this repository.
source env.sh

Download the required weights into the following locations:

Asset Required for Target location
MiniMax-H3 FL2VA base weights inference and training DiffSynth-Studio-h3-v2/models/MiniMax/MiniMax-H3/
H3-World LoRA inference checkpoints/H3-World/step-10000.safetensors
ABot-World-Explorer-500h training only any local path, passed through ABOT_SRC_ROOT 
python3 -c "
from huggingface_hub import snapshot_download
snapshot_download(
    'MiniMaxAI/MiniMax-H3',
    allow_patterns=['model_index.json', 'FL2VA/*'],
    local_dir='DiffSynth-Studio-h3-v2/models/MiniMax/MiniMax-H3'
)"

python3 -c "
from huggingface_hub import hf_hub_download
hf_hub_download(
    'DANNY621/H3-World',
    'step-10000.safetensors',
    local_dir='checkpoints/H3-World'
)"

H3-World uses the original FL2VA checkpoint layout released by MiniMax, rather than the root-level Diffusers checkpoint. No weight conversion or key remapping is required.

The patch is required for the released checkpoint. Do not install DiffSynth-Studio-h3-v2 in editable mode; the included training and inference scripts verify that they load the patched checkout.

🎬 Inference

The repository includes a held-out ABot test frame at examples/first_frame.png. The following fixed configuration generates a 5.2-second forward-motion video:

python3 code/abot/infer.py \
  --checkpoint checkpoints/H3-World/step-10000.safetensors \
  --first-frame examples/first_frame.png \
  --scene-prompt "A man in a yellow floral shirt stands in a dim, multi-level concrete parking garage." \
  --action-preset forward \
  --seed 2 \
  --steps 50 \
  --num-frames 124 \
  --cfg-scale 1.0 \
  --out outputs/example_forward.mp4

The included frame is sample d0b768c6 from the held-out test split. To use a custom image, replace examples/first_frame.png and describe its static scene and subject with --scene-prompt. Inputs are center-cropped to 832x480 when needed. The built-in presets are still, forward, back, strafe-left, strafe-right, tilt-up, tilt-down, pan-left, pan-right, pan-left-fast, and pan-right-fast. The full key-to-language mapping is defined in code/abot/action_script.py.

🏋️ Training

Prepare the 7,872-clip training split, cache its latents, inject the per-latent action instructions, then train LoRA:

# 1. Build clips and the fixed train/test split from ABot.
ABOT_SRC_ROOT=/path/to/ABot-World-Explorer-500h \
  python3 code/abot/build_abot_clips.py --num-clips 8000 --workers 48
ABOT_SRC_ROOT=/path/to/ABot-World-Explorer-500h \
  python3 code/abot/build_abot_clips.py --verify 8
python3 code/abot/split_abot_metadata.py \
  --input data/abot_meta_8000.jsonl \
  --train-output data/abot_meta_train_7872.jsonl \
  --test-output data/abot_meta_test_128.jsonl \
  --clips-dir data/clips

# 2. Cache the video, audio, and text latents, then add action text.
bash code/cache.sh
python3 code/abot/inject_abot_text.py \
  --meta data/abot_meta_train_7872.jsonl \
  --cache output/minimax_h3_abot/7872-cache \
  --device cuda:0

# 3. Train on four GPUs by default.
bash code/train.sh

code/train.sh uses rank-32 LoRA on qkv_proj and out_proj for 20 epochs, saving checkpoints every 2,000 steps. Override the visible devices with CUDA_VISIBLE_DEVICES=4,5,6,7 bash code/train.sh.

🙏 Acknowledgements

📚 Citation

@misc{chen2026h3worldturninglanguageunderstanding,
      title={H3-World: Turning Language Understanding into World Control},
      author={Danze Chen and Zeqing Wang and Ziyue Lin and Xingyi Yang and Yeying Jin},
      year={2026},
      eprint={2609.01560},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2609.01560},
}

H3-World (Danzer1xxxxChan/H3-World)

Searching Database…

318 ·GitHub
H3-World
Что это такое?H3-World — интерактивная модель мира на базе MiniMax-H3: даёте один стартовый кадр, и она генерирует видео, которым можно управлять с клавиатуры — как будто едешь по игровому миру с помощью клавиш.
Это готовое приложение или исследовательский код, который я запускаю сам?Исследовательский код: скрипты на Python для обучения и инференса, которые запускают небольшой LoRA-адаптер поверх модели MiniMax-H3 на 33B через пропатченную копию DiffSynth-Studio-h3-v2. Никакого графического интерфейса и установщика.
Как его запустить?Настройте Python 3.10 с CUDA 12.8, скачайте базовые веса MiniMax-H3 FL2VA и чекпоинт H3-World LoRA, затем запустите скрипт инференса — в репозитории есть тестовый кадр examples/firstframe.png, из которого получается 5,2-секундный ролик с движением вперёд.
Есть ли подводные камни при настройке, о которых стоит знать заранее?Да: для выпущенного чекпоинта нужен патч, устанавливать в режиме editable запрещено, и требуется оригинальная структура чекпоинта FL2VA от MiniMax, а не вариант из Diffusers — если следовать README, переназначать ключи не придётся.
Можно ли использовать своё стартовое изображение?Да — замените examples/firstframe.png и опишите статичную сцену и объект с помощью --scene-prompt. При необходимости ваше изображение будет обрезано по центру до 832x480.
Какие движения и перемещения камеры я могу задать?Одиннадцать встроенных пресетов: статика, вперёд, назад, стрейф влево/вправо, наклон вверх/вниз, панорама влево/вправо и быстрые панорамы. Полное соответствие клавиш и команд находится в code/abot/actionscript.py.
Насколько велика обучаемая часть по сравнению с полной моделью?Крошечная: 65,6 млн параметров LoRA — всего 0,199% от 33-миллиардной основы MiniMax-H3 — обучено на 8000 геймплейных клипов из датасета ABot-World-Explorer-500h.
Можно ли дообучить его на своих клипах?Да: подготовьте обучающий сплит из 7872 клипов, закэшируйте латенты, добавьте инструкции действий для каждого латента, затем запустите code/train.sh — LoRA ранга 32 на qkvproj/outproj, 20 эпох, чекпоинт каждые 2000 шагов.
What are similar projects?hyperflow, FreeVideo, SolarWM, EasyWAM, LTX-Video, Evoke, vdn-minimax-h3, Marionette
Which topics is it in?minimax-h3, world-models, keyboard, attention-mechanism, interactive, diffusion-models, lora, training, game, fine-tuning, video-generation, inference
Creator
Danzer1xxxxChan
Size
227.9 MB
Stars
318
Updated
CommitSep 17
Age
1mo
Commits · 90 Days