hytale-networking

Hytale Networking API

Complete guide for handling network packets and client-server communication.

When to use this skill

Use this skill when:

• Sending data to clients
• Receiving data from clients
• Creating custom packet types
• Implementing custom UI synchronization
• Handling real-time player input
• Syncing custom game state

Network Architecture Overview

Hytale uses a packet-based networking system:

Client <---> Server
   |           |
   Packet      Packet
   Encoder     Decoder
   |           |
   ByteBuf <-> ByteBuf

Protocol Components

Component	Description
Packet	Data structure with serialization
PacketRegistry	Maps packet IDs to classes
PacketHandler	Processes incoming packets
PacketEncoder	Serializes packets to bytes
PacketDecoder	Deserializes bytes to packets

Packet Structure

Packet Interface

All packets implement the Packet interface:

public interface Packet {
    int getId();
    void serialize(ByteBuf buffer);
    int computeSize();
}

Built-in Packet Categories

Category	Direction	Examples
auth	Bidirectional	AuthToken, ConnectAccept
connection	Bidirectional	Connect, Disconnect, Ping
setup	S→C	WorldSettings, AssetInitialize
player	C→S	ClientMovement, MouseInteraction
entities	S→C	EntityUpdates, PlayAnimation
world	S→C	SetChunk, ServerSetBlock
inventory	Bidirectional	MoveItemStack, SetActiveSlot
window	Bidirectional	OpenWindow, CloseWindow
interface	S→C	ChatMessage, Notification
interaction	Bidirectional	SyncInteractionChains
camera	S→C	CameraShakeEffect

Registering Packet Handlers

SubPacketHandler Pattern

Create modular packet handlers:

public class MyPacketHandler implements SubPacketHandler {
    private final MyPlugin plugin;
    
    public MyPacketHandler(MyPlugin plugin) {
        this.plugin = plugin;
    }
    
    @Override
    public void registerHandlers(IPacketHandler handler) {
        // Register by packet ID
        handler.registerHandler(108, this::handleClientMovement);
        handler.registerHandler(111, this::handleMouseInteraction);
        
        // Or by packet class
        handler.registerHandler(CustomPacket.ID, this::handleCustomPacket);
    }
    
    private void handleClientMovement(Packet packet) {
        ClientMovement movement = (ClientMovement) packet;
        Vector3d position = movement.getPosition();
        // Process movement
    }
    
    private void handleMouseInteraction(Packet packet) {
        MouseInteraction interaction = (MouseInteraction) packet;
        // Process mouse input
    }
}