Network Protocol
The Hytale server uses a custom binary protocol built on top of Netty for client-server communication.
Architecture
Section titled “Architecture”The protocol stack from bottom to top:
- Transport - QUIC over UDP (primary) or TCP fallback
- Security - TLS 1.3 with mutual authentication
- Compression - Zstd for large payloads
- Framing - Length-prefixed binary packets
Packet Categories
Section titled “Packet Categories”Hytale defines 156 packets organized by ID ranges:
| ID Range | Category | Purpose |
|---|---|---|
| 0-3 | Connection | Connect, Disconnect, Ping/Pong |
| 10-18 | Authentication | Auth tokens, password, referrals |
| 20-34 | Setup | World settings, assets, features |
| 40-85 | Assets | Block types, items, particles, effects |
| 100-119 | Player | Movement, teleport, game mode, input |
| 131-161 | World | Chunks, blocks, fluids, time, weather |
| 160-166 | Entities | Entity sync, animations, knockback |
| 170-179 | Inventory | Items, hotbar, creative mode |
| 200-234 | Interface | Windows, chat, HUD, player list |
| 240-252 | World Map | Map data, markers, server access |
| 260-294 | Special | Machinima, camera, interactions |
| 300-355 | Asset Editor | In-game asset editing |
| 400-423 | Builder Tools | World editing, selection, clipboard |
Documentation
Section titled “Documentation”Core Protocol
Section titled “Core Protocol”- Transport Layer - QUIC/TCP, TLS, channel pipeline
- Packet Structure - Binary format, framing, VarInt, compression
- Authentication - Handshake flow, session service, JWT tokens
Reference
Section titled “Reference”- Packet List - Complete list of all 156 packets
- Server Transfer - Transfer players between servers
Quick Reference
Section titled “Quick Reference”Byte Order
Section titled “Byte Order”All multi-byte integers use little-endian byte order.
Session Service
Section titled “Session Service”Authentication flows through Hytale’s session service at https://sessions.hytale.com. See Authentication for endpoints.
Protocol Version
Section titled “Protocol Version”The protocol version is a 64-character hash in the Connect packet. Mismatched versions result in disconnection.