HamsterAPI: Your Ultimate Minecraft Packet Manipulation Toolkit

Effortlessly intercept, modify, and send packets without ever touching NMS or Reflection.

---

What is HamsterAPI?

HamsterAPI is a powerful, high-performance library designed to give developers complete control over Minecraft's network protocol. It provides a clean, event-driven abstraction layer, allowing you to manipulate incoming and outgoing packets with ease and stability across multiple server versions.

Forget the hassle of maintaining complex NMS code. With HamsterAPI, you get a simple, elegant, and future-proof solution for everything from creating custom cosmetics to patching exploits at the packet level.

Key Features

• 🚀 Powerful Packet Interception: Listen, modify, and cancel any packet with a flexible, priority-based event system.
• 📦 NMS-Free Packet Sending: Effortlessly send Titles, ActionBars, and other packets to players without the headache of Reflection or version-specific code.
• 🛡️ Advanced Player Control: Safely disconnect players with a custom message or instantly close their connecti: Your Ultimate Minecraft Packet Manipulation Toolkiton channel.
• 🌐 Seamless BungeeCord Integration: Easily switch players between servers, use plugin messaging channels, and manage your network.
• 🛠️ Optimized Utilities: Access our streamlined reflection and byte buffer utilities to build advanced, version-independent features.

---

Getting Started

Step 1: Add HamsterAPI as a Dependency

First, ensure HamsterAPI is included as a dependency in your plugin's plugin.yml file. This is a crucial step for your plugin to load correctly.

name: YourPlugin
version: 1.0
main: com.yourdomain.yourplugin.Main
depend: [HamsterAPI]

Step 2: Access the API Instance

The entry point to all of HamsterAPI's features is the singleton instance. You can get it anywhere in your code with a static call:

HamsterAPI api = HamsterAPI.getInstance();

From this instance, you can access all the core managers and utilities:

• getHamsterPlayerManager() - Manage player-specific actions like sending packets or disconnecting.
• getBungeeMessenger() - Communicate with your BungeeCord proxy.
• getPacketInjector() - Manually inject or remove the API from a player's network pipeline.
• getBufferIO() - A utility for decoding raw byte buffers into readable packets.

---

Core Concepts & Usage Examples

How to Listen to Packets

HamsterAPI offers a robust event system for intercepting packets at different stages of the network pipeline.

The Pipeline Flow: Client -> [Splitter & Decompress] -> PacketDecodeEvent -> [Decoder] -> PacketReceiveEvent -> Server

• PacketDecodeEvent

  • When: Fires after the raw bytes are decompressed but before they are decoded into a full packet object.
  • What you get: A raw ByteBuf object.
  • Ideal for: Low-level security, fixing exploits, and analyzing raw network data.

• PacketReceiveEvent / PacketSendEvent

  • When: Fires after the packet has been fully decoded into a PacketWrapper object.
  • What you get: A user-friendly PacketWrapper object.
  • Ideal for: Most common use-cases like creating cosmetics, canceling game events, or modifying game behavior.

To listen for events, register a listener class just as you would with Bukkit events. For more details, see the Spigot Event API Guide.

Example: Listening for a Packet

public class MyPacketListener implements Listener {

    @EventHandler
    public void onPacketSend(PacketSendEvent event) {
        // Get the packet's name
        String packetName = event.getPacket().getName();

        if (packetName.equals("PacketPlayOutChat")) {
            Player player = event.getPlayer();
            player.sendMessage("The server tried to send you a chat message!");
            
            // You can even cancel the packet
            // event.setCancelled(true);
        }
    }
}

Send a Title and Subtitle

// Get the HamsterPlayer instance for a specific player
HamsterPlayer hamsterPlayer = HamsterAPI.getInstance().getHamsterPlayerManager().get(player);

// Send a title that fades in over 1s, stays for 3s, and fades out over 1s.
// Times are in ticks (20 ticks = 1 second)
hamsterPlayer.sendTitle("§aWelcome!", "§7Enjoy your stay.", 20, 60, 20);

Send an ActionBar Message

HamsterPlayer hamsterPlayer = HamsterAPI.getInstance().getHamsterPlayerManager().get(player);

hamsterPlayer.sendActionbar("§eYou have §c5§e new messages.");

Safely Disconnect a Player (Packet Kick)

This sends a formal disconnect packet, allowing the client to gracefully handle the kick and display your custom reason.

HamsterPlayer hamsterPlayer = HamsterAPI.getInstance().getHamsterPlayerManager().get(player);

hamsterPlayer.disconnect("§cYou have been kicked for being awesome.");

Instantly Close a Player's Connection

This immediately terminates the channel without sending a formal packet. Use this for anti-cheat or emergency situations where an instant disconnect is required.

HamsterPlayer hamsterPlayer = HamsterAPI.getInstance().getHamsterPlayerManager().get(player);

hamsterPlayer.closeChannel();

Send a Player to another BungeeCord Server

HamsterPlayer hamsterPlayer = HamsterAPI.getInstance().getHamsterPlayerManager().get(player);

// The server name must match the name in your BungeeCord config.yml
hamsterPlayer.sendServer("lobby-1");

---

Roadmap: The Future of HamsterAPI

We are constantly working to expand the API's capabilities. Here’s what’s on the horizon:

• BossBar API: A simple, version-independent way to create and manage custom BossBars.
• Custom Plugin Channels: Enable direct communication between your server-side plugin and client-side mods.
• BungeeCord Listener: A dedicated listener for receiving plugin messages from the BungeeCord proxy.

Get started with HamsterAPI today and take full control of your server's network communication