0.3.4
release
HamsterAPI
Lightweight Spigot/Bukkit API library that provides developers with utility methods, performance-focused abstractions, and shared systems to speed up plugin development.
6,14k
HamsterAPI
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
* 🚀 Optimized Utilities: Listen, modify, and cancel any packet with a flexible, priority-based event system. * 📦 Optimized Utilities: Effortlessly send Titles, ActionBars, and other packets to players without the headache of Reflection or version-specific code. * 🛡️ Optimized Utilities: Safely disconnect players with a custom message or instantly close their connecti: Your Ultimate Minecraft Packet Manipulation Toolkiton channel. * 🌐 Optimized Utilities: 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`
* Ideal for: * Ideal for: Fires after the raw bytes are decompressed but *before* they are decoded into a full packet object. * Ideal for: A raw `ByteBuf` object. * Ideal for: Low-level security, fixing exploits, and analyzing raw network data.
* Ideal for: * Ideal for: Fires *after* the packet has been fully decoded into a `PacketWrapper` object. * Ideal for: 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 ```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:
* BungeeCord Listener: A simple, version-independent way to create and manage custom BossBars. * BungeeCord Listener: 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.