Client Synchronization

Client Synchronization

The client synchronization system replicates server state to connected clients. It uses delta encoding to send only changed data and visibility culling to reduce bandwidth.

Package Location

• Entity Tracker: com.hypixel.hytale.server.core.modules.entity.tracker
• Chunk Systems: com.hypixel.hytale.server.core.universe.world.chunk.systems
• Protocol: com.hypixel.hytale.protocol.packets

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                  Synchronization Pipeline                        │
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ State Change │───►│ Visibility   │───►│ Queue Updates    │  │
│  │ (Component)  │    │ Detection    │    │ (Delta Encoding) │  │
│  └──────────────┘    └──────────────┘    └────────┬─────────┘  │
│                                                    │            │
│                                          ┌─────────▼─────────┐  │
│                                          │   SendPackets     │  │
│                                          │   (Batch Send)    │  │
│                                          └─────────┬─────────┘  │
│                                                    │            │
│                                          ┌─────────▼─────────┐  │
│                                          │     Client        │  │
│                                          └───────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Entity Synchronization

NetworkId Component

Each networked entity has a unique identifier:

package com.hypixel.hytale.server.core.modules.entity.tracker;

public class NetworkId {
    private int id;  // Unique network identifier
}

Visibility System

The system tracks which entities are visible to each player:

Component	Description
EntityViewer	Tracks visible entities for a player
Visible	Tracks which players can see an entity

System Groups

Entity synchronization runs in ordered system groups:

Group	Purpose
FIND_VISIBLE_ENTITIES_GROUP	Spatial queries for visibility
QUEUE_UPDATE_GROUP	Queue component changes
SEND_PACKET_GROUP	Send packets to clients

Synchronization Flow

1. State Change: Entity component is modified
2. Mark Dirty: EffectControllerComponent marks entity as “network outdated”
3. Visibility Check: Systems determine which players can see the entity
4. Queue Update: QueueComponentUpdates creates delta update objects
5. Build Packet: Updates collected into EntityUpdates packet
6. Send: Packet sent to player clients

EntityUpdates Packet

The main packet for entity state synchronization:

// Packet ID: 161 (compressed)
public class EntityUpdates {
    int[] removed;           // Entity IDs to remove
    EntityUpdate[] updates;  // State updates
}

public class EntityUpdate {
    int networkId;                    // Entity network ID
    ComponentUpdateType[] removed;    // Components to remove
    ComponentUpdate[] updates;        // Component updates
}

Component Update Types

25 component types can be synchronized:

Type	Description
Nameplate	Display names
UIComponents	Health bars, indicators
CombatText	Damage numbers
Model	Entity model
PlayerSkin	Player skin data
Item	Held/displayed item
Block	Block-form entity
Equipment	Equipment loadout
EntityStats	Stats and attributes
Transform	Position, rotation, scale
MovementStates	Movement flags
EntityEffects	Active effects/buffs
Interactions	Interaction options
DynamicLight	Light emission
Interactable	Can be interacted with
Intangible	No collision
Invulnerable	Cannot be damaged
RespondToHit	Hit response behavior
HitboxCollision	Collision settings
Repulsion	Entity repulsion
Prediction	Client prediction ID
Audio	Attached audio
Mounted	Mount state
NewSpawn	Newly spawned flag
ActiveAnimations	Playing animations

ComponentUpdate Fields

Each ComponentUpdate can contain:

public class ComponentUpdate {
    // Display
    Nameplate nameplate;
    EntityUIComponent[] uiComponents;
    CombatText combatText;

    // Visuals
    Model model;
    PlayerSkin playerSkin;
    Item item;
    Block block;
    Equipment equipment;

    // State
    EntityStats entityStats;
    Transform transform;
    MovementStates movementStates;
    EntityEffect[] entityEffects;

    // Interactions
    Interaction[] interactions;
    boolean interactable;
    boolean intangible;
    boolean invulnerable;

    // Physics
    HitboxCollision hitboxCollision;
    Repulsion repulsion;
    int predictionId;

    // Effects
    DynamicLight dynamicLight;
    Audio audio;
    boolean mounted;
    boolean newSpawn;
    Animation[] activeAnimations;
}

Chunk Synchronization

SetChunk Packet

Sends complete chunk data to clients:

// Packet ID: 131 (compressed, max 12MB)
public class SetChunk {
    int x, y, z;           // Chunk coordinates
    byte[] localLight;     // Local light data
    byte[] globalLight;    // Global light data
    byte[] data;           // Block data
}

UnloadChunk Packet

Removes chunk from client:

// Packet ID: 135 (8 bytes)
public class UnloadChunk {
    int chunkX;
    int chunkZ;
}

Block Updates

Single block changes:

// Packet ID: 140
public class ServerSetBlock {
    int x, y, z;      // Block coordinates
    int blockId;      // Block type ID
    byte filler;      // Filler data
    byte rotation;    // Block rotation
}

Batch block changes:

// Packet ID: 141
public class ServerSetBlocks {
    BlockChange[] changes;  // Up to 1024 per packet
}

Fluid Updates

// Packet ID: 142
public class ServerSetFluid {
    int x, y, z;
    int fluidId;
    byte level;
}

// Packet ID: 143
public class ServerSetFluids {
    FluidChange[] changes;
}

View Radius

The view radius controls how far clients can see:

// Packet ID: 32
public class ViewRadius {
    int radius;  // Chunk distance
}

Entities and chunks outside the view radius are not synchronized.

Optimization Techniques

Delta Encoding

Only changed components are sent:

1. Full update on first visibility
2. Incremental updates thereafter
3. Remove updates when component is removed

Visibility Culling

Entities outside view are not synchronized:

1. Spatial queries determine visible entities
2. Only visible entities queued for updates
3. Removed entities send removal packet

Packet Batching

Updates are batched for efficiency:

1. Changes queued during tick
2. Batch built at end of tick
3. Single packet per player per frame

Compression

Large packets use Zstd compression:

• SetChunk - Compressed (up to 12MB uncompressed)
• EntityUpdates - Compressed
• Reduces bandwidth significantly

Synchronization Events

Player Setup

When a player joins:

1. SetClientId - Assign client identifier
2. ViewRadius - Set chunk loading distance
3. SetChunk - Send nearby chunks
4. EntityUpdates - Send visible entities

During Gameplay

Continuous synchronization:

1. Entity state changes detected
2. Chunk modifications tracked
3. Updates batched per tick
4. Packets sent to affected players

Entity Spawn/Despawn

New entities:

1. Visibility system detects new entity
2. Full component update queued
3. EntityUpdates with NewSpawn flag sent

Removed entities:

1. Entity destroyed or leaves visibility
2. Network ID added to removed array
3. EntityUpdates with removal sent

Plugin Considerations

Sending Custom Updates

Use existing packet types through PacketHandler:

// Send entity update
EntityUpdates packet = new EntityUpdates();
packet.updates = new EntityUpdate[] { update };
player.getPacketHandler().write(packet);

// Send block change
ServerSetBlock blockPacket = new ServerSetBlock();
blockPacket.x = x;
blockPacket.y = y;
blockPacket.z = z;
blockPacket.blockId = blockId;
player.getPacketHandler().write(blockPacket);

Triggering Sync

Modify components to trigger automatic sync:

// Component changes automatically queue network updates
TransformComponent transform = entity.getComponent(transformType);
transform.setPosition(newPosition);
// Entity tracker will detect change and sync

Best Practices

1. Minimize state changes: Frequent changes increase bandwidth
2. Use appropriate update types: Don’t send full updates when delta suffices
3. Respect view radius: Don’t sync entities outside player view
4. Batch operations: Group related changes when possible
5. Consider compression: Large data benefits from compression

Related

• Networking Overview - Packet system architecture
• Packet Types - All packet IDs
• Entity System - Entity components
• World System - Chunk management