Tencent-Hunyuan/HY-WorldPlay

Tencent-Hunyuan/HY-WorldPlay

Description: HY-World 1.5: A Systematic Framework for Interactive World Modeling with Real-Time Latency and Geometric Consistency

Language: Python

License: NOASSERTION

Stars: 1520

Forks: 139

Open issues: 29

Created: 2025-12-10T06:46:39Z

Pushed: 2026-06-10T07:10:23Z

Default branch: main

Fork: no

Archived: no

README:

[//]: # ( )

[//]: # ( )

[//]: # ( )

"Hold Infinity in the Palm of Your Hand, and Eternity in an Hour"

🎥 Video

https://github.com/user-attachments/assets/9fd12b40-41ab-4201-8667-8b333db1123d

🔥 News

• April 16, 2026: 🤗 We release HY-World-2.0, state-of-the-art 3D world model!
• March 8, 2026: 🚀 We release the RL post-training code 🧭 [WorldCompass](worldcompass/README.md) for WorldPlay-8B model (based on HY Video)! Read more in our new paper.
• January 6, 2026: 🚀 We release the training code for WorldPlay-8B model (based on HY Video), enabling the community to train and fine-tune their own world models!
• January 6, 2026: 🎯 We open-source WorldPlay-5B model (based on WAN), a new lightweight model that fits into small-VRAM GPUs (but with compromised quality)!
• January 3, 2026: ⚡ We update the inference code with quantization and engineering optimization for even faster inference speeds!
• December 17, 2025: 👋 We present the technical report (and research paper) of HY-World 1.5 (WorldPlay), please check out the details and spark some discussion!
• December 17, 2025: 🤗 We release the first open-source, real-time interactive, and long-term geometric consistent world model, HY-World 1.5 (WorldPlay)!

> Join our [Wechat](#) and [Discord](https://discord.gg/dNBrdrGGMa) group to discuss and find help from us.

| Wechat Group | Xiaohongshu | X | Discord | |--------------------------------------------------|-------------------------------------------------------|---------------------------------------------|---------------------------------------------------| | | | | |

📋 Table of Contents

• [🎥 Video](#-video)
• [🔥 News](#-news)
• [📋 Table of Contents](#-table-of-contents)
• [📖 Introduction](#-introduction)
• [✨ Highlights](#-highlights)
• [📜 System Requirements](#-system-requirements)
• [🛠️ Dependencies and Installation](#️-dependencies-and-installation)
• [1. Create Environment](#1-create-environment)
• [2. Install Attention Libraries](#2-install-attention-libraries)
• [3. Install AngelSlim and DeepGEMM (Optional)](#3-install-angelslim-and-deepgemm-optional-for-quantizationfp8-acceleration)
• [4. Download All Required Models](#4-download-all-required-models)
• [🎮 Quick Start](#-quick-start)
• [🧱 Model Checkpoints](#-model-checkpoints)
• [🔑 Inference](#-inference)
• [Configure Model Paths](#configure-model-paths)
• [Configuration Options](#configuration-options)
• [Model Selection](#model-selection)
• [Camera Trajectory Control](#camera-trajectory-control)
• [Option 1: Pose String (Recommended for Quick Testing)](#option-1-pose-string-recommended-for-quick-testing)
• [Option 2: Custom JSON Files](#option-2-custom-json-files)
• [Prompt Rewriting (Optional)](#prompt-rewriting-optional)
• [Run Inference](#run-inference)
• [⚙️Training](#️training)
• [📊 Evaluation](#-evaluation)
• [🎬 More Examples](#-more-examples)
• [📝 TODO](#-todo)
• [📚 Citation](#-citation)
• [Contact](#contact)
• [🙏 Acknowledgements](#-acknowledgements)

📖 Introduction

While HY-World 1.0 is capable of generating immersive 3D worlds, it relies on a lengthy offline generation process and lacks real-time interaction. HY-World 1.5 bridges this gap with WorldPlay, a streaming video diffusion model that enables real-time, interactive world modeling with long-term geometric consistency, resolving the trade-off between speed and memory that limits current methods. Our model draws power from four key designs. 1) We use a Dual Action Representation to enable robust action control in response to the user's keyboard and mouse inputs. 2) To enforce long-term consistency, our Reconstituted Context Memory dynamically rebuilds context from past frames and uses temporal reframing to keep geometrically important but long-past frames accessible, effectively alleviating memory attenuation. 3) We design WorldCompass, a novel Reinforcement Learning (RL) post-training framework designed to directly improve the action-following and visual quality of the long-horizon, autoregressive video model. 4) We also propose Context Forcing, a novel distillation method designed for memory-aware models. Aligning memory context between the teacher and student preserves the student's capacity to use long-range information, enabling real-time speeds while preventing error drift. Taken together, HY-World 1.5 generates long-horizon streaming video at 24 FPS with superior consistency, comparing favorably with existing techniques. Our model shows strong generalization across diverse scenes, supporting first-person and third-person perspectives in both real-world and stylized environments, enabling versatile applications such as 3D reconstruction, promptable events, and infinite world extension.

✨ Highlights

• Systematic Overview

HY-World 1.5 has open-sourced a systematic and comprehensive training framework for real-time world models, covering the entire pipeline and all stages, including data, training, and inference deployment. The technical report discloses detailed training specifics for model pre-training, middle-training, reinforcement learning post-training, and memory-aware model distillation. In addition, the report introduces a series of engineering techniques aimed at reducing network transmission latency and model inference latency, thereby achieving a real-time streaming inference experience for users.

• Inference Pipeline

Given a single image or text prompt to describe a world, our model performs a next chunk (16 video frames) prediction task to generate future videos conditioned on action from users. For the generation of each chunk, we dynamically reconstitute context memory from past chunks to enforce long-term temporal and geometric consistency.

📜 System Requirements

• GPU: NVIDIA GPU with CUDA support
• GPU Memory cost:
• Inference with AR distilled models (based on HunyuanVideo1.5 with 125…