What should you check first in this article?

Hunyuan-GameCraft takes a reference image, text prompt, and ordered movement inputs to generate video with a moving game camera. The official Linux CUDA example lists 24GB as the minimum GPU memory for its 704×1216 setup, but warns that it is very slow and recommends an 80GB GPU. Follow the steps to create an MP4 from the example village image with the default 50-step checkpoint.

Image and video generation

Generate an action-controlled clip with Hunyuan-GameCraft on a 24 GB GPU

It turns a village image and keyboard-direction actions into a generated MP4 scene.

Hunyuan-GameCraft takes a reference image, text prompt¹, and ordered movement inputs to generate video with a moving game camera. The official Linux CUDA² example lists 24GB as the minimum GPU³ memory for its 704×1216 setup, but warns that it is very slow and recommends an 80GB GPU. Follow the steps to create an MP4 from the example village image with the default 50-step checkpoint⁴.

Contents

Requirements and key details

Inputs are a reference image, scene description, and ordered keyboard-camera actions.
The official 24 GB single-GPU example uses CPU offload and FP8 and is very slow at 704×1216.
The base checkpoint uses 50 inference steps; the 8-step distilled model has separate weights and settings.

Continue a game scene from an image and movement inputs

Hunyuan-GameCraft does not launch a game engine or simulate a playable game's physics. It takes a reference image, prompt, and camera actions derived from keyboard or mouse input, then generates the next scene as video. This example starts from the repository's asset/village.png and applies w, a, d, and s in order to create a clip moving through a village. It generates frame⁵ segments for the action sequence and saves an MP4. Official Hunyuan-GameCraft repository

The authors' single-GPU path targets Linux, NVIDIA CUDA, and at least 24 GB of GPU memory. It uses 704×1216 output, CPU⁶ offload⁷, and FP8⁸ together. They describe the 24 GB minimum configuration as very slow and recommend an 80 GB GPU for better generation quality. The command below follows their low-memory example.

GPU-memory guidance stated in the repository
Setting	Authors' guidance
Single GPU, 704×1216	24 GB minimum; very slow
For better generation quality	80 GB GPU recommended

A monitor compares a noisy mountain-road clip with a clearer version side by side. — Generated frames continue from the composition of the reference scene.

Set up the Linux environment with CUDA 12.4

The repository's manual setup specifies CUDA 12.4, Python 3.10, and PyTorch⁹ 2.5.1. Run these commands on Linux with an NVIDIA driver compatible with the CUDA 12.4 runtime¹⁰. FlashAttention¹¹ 2 is the additional acceleration package listed by the repository. Official installation guide

Create and activate the environment from the repository root, then install PyTorch, the pinned dependencies, and FlashAttention. Continue running the next steps from the Hunyuan-GameCraft-1.0 directory.

Install the Linux environment and repository dependencies

git clone https://github.com/Tencent-Hunyuan/Hunyuan-GameCraft-1.0.git
cd Hunyuan-GameCraft-1.0
conda create -n HYGameCraft python==3.10 -y
conda activate HYGameCraft
conda install pytorch==2.5.1 torchvision==0.20.0 torchaudio==2.5.1 pytorch-cuda=12.4 -c pytorch -c nvidia -y
python -m pip install -r requirements.txt
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

Download the checkpoints and locate the village image

Check available storage before downloading the weights. The public Hugging Face download places the model files and standard components under weights/. Confirm that the required checkpoint paths exist; the input is the repository's asset/village.png, so no separate image file is needed. Weight layout and download instructions

The commands enter weights, download the model repository, and check for both released checkpoints. If the first run reports a missing file, verify that the file names and directories match the documented layout.

Download the GameCraft weights and check their paths

python -m pip install 'huggingface_hub>=0.34,<1.0'
cd weights
hf download tencent/Hunyuan-GameCraft-1.0 --local-dir ./
cd ..
test -f weights/gamecraft_models/mp_rank_00_model_states.pt
test -f weights/stdmodels/vae_3d/hyvae/pytorch_model.pt
test -f asset/village.png

A monitor shows a side-by-side coastal scene, with a film reel and a disconnected external SSD beside it. — One generation extends a still image into a sequence of moving frames.

Generate a clip with the base 50-step checkpoint

This command follows the repository's single-GPU low-memory path. The 24 GB example enables CPU offload and FP8, starts from the reference image, and applies w, a, d, and s in order. Each action uses the repository example's speed value of 0.2. This is the base checkpoint with 50 inference¹² steps. Official low-memory inference example

Generate village.mp4 with the official 24 GB CPU-offload example

export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"
export MODEL_BASE=weights/stdmodels
export DISABLE_SP=1
export CPU_OFFLOAD=1
torchrun --nnodes=1 --nproc_per_node=1 --master_port 29605 hymm_sp/sample_batch.py \
  --image-path asset/village.png \
  --prompt "A charming medieval village with cobblestone streets, thatched-roof houses, and vibrant flower gardens under a bright blue sky." \
  --add-neg-prompt "overexposed, low quality, deformation, a poor composition, bad hands, bad teeth, bad eyes, bad limbs, distortion, blurring, text, subtitles, static, picture, black border." \
  --ckpt weights/gamecraft_models/mp_rank_00_model_states.pt \
  --video-size 704 1216 \
  --cfg-scale 2.0 \
  --image-start \
  --action-list w a d s \
  --action-speed-list 0.2 0.2 0.2 0.2 \
  --seed 250160 \
  --sample-n-frames 33 \
  --infer-steps 50 \
  --flow-shift-eval-video 5.0 \
  --cpu-offload \
  --use-fp8 \
  --save-path ./results_poor/

If the first GPU run runs out of memory, check whether a file is already present under results_poor/, then retry with a shorter frame setting as a small test. The authors describe the 24 GB configuration as very slow. First verify whether the system is closer to their 80 GB recommendation and that both CPU_OFFLOAD and --cpu-offload are set. This model generates video offline.

Inspect the saved village video

ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height,nb_frames,r_frame_rate -of default=noprint_wrappers=1 results_poor/village.mp4

The 8-step distilled version pairs mp_rank_00_model_states_distill.pt with --infer-steps 8, --cfg-scale 1.0, and --use-fp8. The command below uses the base checkpoint and 50-step setting. Distilled example in the repository

A paper boat starts beside a stream and reaches a bridge in the final frame. — The starting image and movement actions jointly shape how the scene continues.

Terminology notes

Prompt — The input text sent to a model. For generative models it describes the desired result and strongly shapes the output.
Back to the text
CUDA — A software platform for general-purpose computing on NVIDIA GPUs.
Back to the text
GPU — A processor designed to handle many calculations in parallel. It performs model computations during AI inference.
Back to the text
Checkpoint — A file containing saved model weights and related state. Versions or tasks in one model family may use different checkpoints.
Back to the text
Frame — A single image that makes up part of a video.
Back to the text
CPU — The central processor that runs the operating system and general-purpose instructions; in AI workloads it also handles tasks such as preprocessing and data movement.
Back to the text
Offloading — Moving some model data from GPU memory to system RAM or storage when capacity is limited. This adds data transfer.
Back to the text
FP8 — A floating-point format that represents each value with 8 bits.
Back to the text
PyTorch — A software framework for building and running AI models. Check the compatible PyTorch version and hardware support along with the model.
Back to the text
Runtime — The software environment that provides facilities needed while a program runs. In local AI, it can also refer to a model execution engine.
Back to the text
FlashAttention — An attention algorithm that computes in tiles, keeps intermediate values in fast on-chip memory, and reduces GPU-memory traffic without storing the full attention matrix.
Back to the text
Inference — The process of using a trained model to compute an output for an input. Here, local inference means running the model on the user’s device.
Back to the text

Frequently asked questions

What should you check first in this article?: Hunyuan-GameCraft takes a reference image, text prompt, and ordered movement inputs to generate video with a moving game camera. The official Linux CUDA example lists 24GB as the minimum GPU memory for its 704×1216 setup, but warns that it is very slow and recommends an 80GB GPU. Follow the steps to create an MP4 from the example village image with the default 50-step checkpoint.
How much memory does it need?: The authors' single-GPU path targets Linux, NVIDIA CUDA, and at least 24 GB of GPU memory. It uses 704×1216 output, CPU offload, and FP8 together. They describe the 24 GB minimum configuration as very slow and recommend an 80 GB GPU for better generation quality. The command below follows their low-memory example.