HamsterAPI

Minecraft 版本： 1.13 1.13.1 1.13.2

平台： bukkit folia paper purpur spigot

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. ```yaml 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: ```java 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](https://www.spigotmc.org/wiki/using-the-event-api/). **Example: Listening for a Packet** ```java 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 ```java // 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 ```java 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. ```java 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. ```java HamsterPlayer hamsterPlayer = HamsterAPI.getInstance().getHamsterPlayerManager().get(player); hamsterPlayer.closeChannel(); ``` Send a Player to another BungeeCord Server ```java 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