6 min

Packets

Send data to clients using packets. Control UI, spawn effects, and sync game state.

Sending Packets

Packets are sent through the player's connection:

1// Send to single player
2player.getPlayerConnection().write(packet);
3
4// Send to all players in world
5for (Player p : world.getPlayers()) {
6    p.getPlayerConnection().write(packet);
7}
thread safe
Packet sending is thread-safe. You don't need world.execute() for packets.

Common Packets

packetpurpose
ShowEventTitleDisplay title/subtitle text
UpdateMovementSettingsChange player physics
SpawnParticleSystemSpawn particle effects
UpdateModelChange entity appearance
PlaySoundPlay sound effects
TeleportEntityMove entities instantly

Packet Examples

ShowEventTitle

1// Create formatted title text
2FormattedMessage title = new FormattedMessage(
3    "WELCOME",           // rawText
4    null,                // messageId
5    null,                // children
6    null,                // params
7    null,                // messageParams
8    "#00FF88",           // color (hex)
9    MaybeBool.True,      // bold
10    MaybeBool.False,     // italic
11    MaybeBool.False,     // monospace
12    MaybeBool.False,     // underlined
13    null,                // link
14    false                // markupEnabled
15);
16
17FormattedMessage subtitle = new FormattedMessage(
18    "Enjoy your stay",
19    null, null, null, null,
20    "#AAAAAA",
21    MaybeBool.False,     // bold
22    MaybeBool.True,      // italic
23    MaybeBool.False,     // monospace
24    MaybeBool.False,     // underlined
25    null, false
26);
27
28// Create and send packet
29ShowEventTitle packet = new ShowEventTitle(
30    0.5f,    // fadeIn (seconds)
31    0.5f,    // fadeOut (seconds)
32    3.0f,    // duration (seconds)
33    null,    // icon
34    true,    // isMajor
35    title,   // primaryTitle
36    subtitle // secondaryTitle
37);
38
39player.getPlayerConnection().write(packet);
no strikethrough!
FormattedMessage does NOT have strikethrough. Params 9-10 are monospace and underlined.

SpawnParticleSystem

1// Get player position (returns Vector3d, not Position)
2TransformComponent transform = player.getTransformComponent();
3Vector3d pos = transform.getPosition();
4
5// Create particle packet
6SpawnParticleSystem packet = new SpawnParticleSystem(
7    "Poof_Large",                              // particle name
8    new Position(pos.x, pos.y + 1, pos.z),    // spawn position
9    new Direction(0f, 0f, 0f),                 // direction
10    1.5f,                                      // scale
11    null                                       // color (null = default)
12);
13
14// Send to all nearby players
15for (Player p : world.getPlayers()) {
16    p.getPlayerConnection().write(packet);
17}

UpdateMovementSettings

1// Get default movement settings
2MovementSettings settings = MovementConfig.DEFAULT_MOVEMENT.toPacket();
3
4// Modify speed
5settings.baseSpeed *= 2.0f;  // Double speed
6settings.forwardWalkSpeedMultiplier *= 2.0f;
7settings.backwardWalkSpeedMultiplier *= 2.0f;
8settings.strafeWalkSpeedMultiplier *= 2.0f;
9
10// Modify jump
11settings.jumpForce *= 1.5f;  // 50% higher jumps
12
13// Apply to player
14UpdateMovementSettings packet = new UpdateMovementSettings(settings);
15player.getPlayerConnection().write(packet);

Discovering Packets

Find available packets in the server JAR:

1# List all packet classes
2jar tf HytaleServer.jar | grep "protocol/packets"
3
4# Inspect packet constructor
5javap -public -cp HytaleServer.jar \
6  com.hypixel.hytale.server.protocol.packets.ShowEventTitle

MaybeBool Enum

common gotcha
The MaybeBool enum uses PascalCase: MaybeBool.True,MaybeBool.False, MaybeBool.Null. NOT TRUE/FALSE.
1// CORRECT
2MaybeBool.True
3MaybeBool.False
4MaybeBool.Null   // for "unset" / default
5
6// WRONG - will not compile
7MaybeBool.TRUE
8MaybeBool.FALSE

Broadcast Helper

Create utilities for common packet operations:

PacketUtils.javajava
1public class PacketUtils {
2    
3    public static void broadcast(World world, Object packet) {
4        for (Player player : world.getPlayers()) {
5            player.getPlayerConnection().write(packet);
6        }
7    }
8    
9    public static void broadcastExcept(World world, Player except, Object packet) {
10        for (Player player : world.getPlayers()) {
11            if (!player.equals(except)) {
12                player.getPlayerConnection().write(packet);
13            }
14        }
15    }
16    
17    public static void broadcastNear(Position center, double radius, Object packet) {
18        // Send to players within radius of position
19        for (Player player : getPlayersNear(center, radius)) {
20            player.getPlayerConnection().write(packet);
21        }
22    }
23}