Listening to Packets

In this guide, you'll learn how to listen to packets that are being sent or received from the Client.

Packets are defined in com.hypixel.hytale.protocol and organized by category in com.hypixel.hytale.protocol.packets. Base class is Packet and the sub-packages contain actual packet classes. The low-level Netty handler is com.hypixel.hytale.server.core.io.netty.PlayerChannelHandler, it delegates packet processing logic to com.hypixel.hytale.server.core.io.adapter.PacketAdapters.

The server has a built-in adapter system that makes injection very straightforward. You don't need to hook into Netty manually. You can use the PacketAdapters class to register inbound (Client -> Server) and outbound (Server -> Client) watchers. The process for registering inbound packets is the same as for outbound.

The PacketAdapters class provides several registerInbound method overloads. Possible argument types are PacketWatcher, PacketFilter, PlayerPacketWatcher and PlayerPacketFilter.

The difference between PacketWatcher and PacketFilter is that the PacketFilter can prevent packet processing and block the packet from reaching the server (for inbound) or reaching the player (for outbound).

Player Packet Tracker (Utility)

To get a better understanding of how packets are sent to/from players, you can add this snippet below to track packets sent to/from players:

public class PlayerPacketTracker {
    private static final HytaleLogger LOGGER = HytaleLogger.forEnclosingClass();

    private static class PlayerStats {
        final Map<String, AtomicInteger> sent = new ConcurrentHashMap<>();
        final Map<String, AtomicInteger> received = new ConcurrentHashMap<>();
    }
    private static final Map<String, PlayerStats> stats = new ConcurrentHashMap<>();

    private static String getPlayerName(PacketHandler handler) {
        if (handler instanceof GamePacketHandler gpHandler) {
            return gpHandler.getPlayerRef().getUsername();
        }
        return null;
    }

    public static void registerPacketCounters() {
        PacketAdapters.registerInbound((PacketHandler handler, Packet packet) -> {
            String playerName = getPlayerName(handler);
            if (playerName != null) {
                stats.computeIfAbsent(playerName, k -> new PlayerStats())
                        .received.computeIfAbsent(packet.getClass().getSimpleName(), k -> new AtomicInteger(0))
                        .incrementAndGet();
            }
        });

        // Listener for sent packets (Outbound)
        PacketAdapters.registerOutbound((PacketHandler handler, Packet packet) -> {
            String playerName = getPlayerName(handler);
            if (playerName != null) {
                stats.computeIfAbsent(playerName, k -> new PlayerStats())
                        .sent.computeIfAbsent(packet.getClass().getSimpleName(), k -> new AtomicInteger(0))
                        .incrementAndGet();
            }
        });

        // Schedule logging every 3 seconds
        HytaleServer.SCHEDULED_EXECUTOR.scheduleAtFixedRate(() -> {
            if (stats.isEmpty()) return;

            for (Map.Entry<String, PlayerStats> entry : stats.entrySet()) {
                String player = entry.getKey();
                PlayerStats pStats = entry.getValue();

                StringBuilder sb = new StringBuilder();

                // Build Sent string
                List<String> sentLogs = new ArrayList<>();
                pStats.sent.forEach((type, atomic) -> {
                    int count = atomic.getAndSet(0);
                    if (count > 0) {
                        sentLogs.add(type + " x" + count);
                    }
                });

                if (!sentLogs.isEmpty()) {
                    sb.append("Sent ").append(String.join(", ", sentLogs));
                }

                // Build Received string
                List<String> recvLogs = new ArrayList<>();
                pStats.received.forEach((type, atomic) -> {
                    int count = atomic.getAndSet(0);
                    if (count > 0) {
                        recvLogs.add(type + " x" + count);
                    }
                });

                if (!recvLogs.isEmpty()) {
                    if (!sb.isEmpty()) sb.append("\n");
                    sb.append("Received ").append(String.join(", ", recvLogs));
                }

                if (!sb.isEmpty()) {
                    LOGGER.atInfo().log("To " + player + ":\n" + sb);
                }
            }
        }, 3, 3, TimeUnit.SECONDS);
    }
}

Then call PlayerPacketTracker.registerPacketCounters(); in your setup() function.

Injecting our own function to the PacketAdapter.

We can inject our own function to the PacketAdapter by using one of the methods mentioned above, here is an example that prints all packets sent from the server to the client.

PacketAdapters.registerOutbound((PacketHandler handler, Packet packet) -> {
    var handlerName = handler.getClass().getSimpleName();
    var packetName = packet.getClass().getSimpleName();

    // some common packets excluded to reduce spam
    if (!"EntityUpdates".equals(packetName) && !"CachedPacket".equals(packetName)) {
        logger.at(Level.INFO)
              .log("[" + handlerName + "] Sent packet id=" + packet.getId() + ": " + packetName);
    }
});

Modfying an incoming packet

In the following example, we modify a incoming packet containing skin data to remove that data from the packet. With this, every player will have default skin.

PacketAdapters.registerInbound((PacketHandler handler, Packet packet) -> {
    if (packet instanceof PlayerOptions skinPacket) {
        skinPacket.skin = null;
    }
});

Player packet handling

We can use another method in PacketAdapter to specifically target packets send by a player. In this method, returning true cancels the packet while returning false allows the packet to pass through. This allows you to add your own logic to packets.

Warning

While you can cancel packets entirely, client-side prediction still occurs and the targeted client will still see their movement inputs work as normal. This requires extra work (guide pending) to prevent the player from taking certain actions; cancelling packets is likely not the right approach.

PacketAdapters.registerInbound((PlayerPacketFilter) (player,  packet) -> {
    if (packet instanceof ClientMovement movementPacket) {
        // Do some logic here, then return true to cancel the packet
        return true;
    }
    return false;
});

Packet handlers

Packet Handlers and the incoming packet types and corresponding packet ids of the packets they handle. Packets can be present in multiple handlers. If any other type of packet comes in during wrong phase, the handler will disconnect the sender. These are serverbound (inbound) packets. Some packets are used in both directions, such as SyncInteractionChains. Packets not mentioned here are likely clientbound (outbound), but will be added soon.