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]

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.

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);
        }
    }
}

// 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);

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

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

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.");

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();

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

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