MinecraftGUI

A lightweight Java library for creating GUI menus in Minecraft Paper plugins with a fluent builder pattern. This is a personal project by Touchie771, but it's open for anyone to use and contribute to.

Features

• Fluent Builder Pattern: Create menus with an intuitive, chainable API
• Type Safety: Full compile-time validation and null safety with JetBrains annotations
• Adventure API Integration: Modern text component support for rich formatting
• Immutable Design: Menus are immutable once created, preventing accidental modifications
• Comprehensive Validation: Built-in validation for inventory sizes, slots, and item quantities

Quick Start

Adding to Your Project

Add this library as a dependency in your Paper plugin's build.gradle:

repositories {
maven {
name ="GitHubPackages"
url = uri("https://maven.pkg.github.com/Touchie771/MinecraftGUI")
credentials {
username =<your-username>
password =<your-PAT>
}
}
}
dependencies {
compileOnly("me.touchie771:minecraftgui:1.1.5")
}

Basic Usage

importme.touchie771.minecraftGUI.api.Menu;
importme.touchie771.minecraftGUI.api.SlotItem;
importnet.kyori.adventure.text.Component;
importorg.bukkit.Material;
publicclassExamplePluginextendsJavaPlugin {
@OverridepublicvoidonEnable() {
// Create a simple menuMenumenu = Menu.newBuilder()
.size(27)
.title(Component.text("Example Menu"))
.items(
newSlotItem(
Component.text("Diamond Sword"),
13, // Center slotMaterial.DIAMOND_SWORD,
1
)
)
.build();
// Open the menu for a playerplayer.openInventory(menu.getInventory());
}
}

Advanced Usage

// Create a menu with multiple itemsMenucomplexMenu = Menu.newBuilder()
.size(54)
.title(Component.text("Complex Menu"))
.items(
newSlotItem(Component.text("Shop"), 10, Material.CHEST, 1),
newSlotItem(Component.text("Settings"), 13, Material.REDSTONE, 1),
newSlotItem(Component.text("Info"), 16, Material.BOOK, 1)
)
.build();
// Modify menu after creationcomplexMenu.addItems(
newSlotItem(Component.text("New Item"), 22, Material.EMERALD, 1)
);
// Get item at specific slot (useful for click events)SlotItemclickedItem = complexMenu.getItemAt(slot);
if (clickedItem != null) {
// Handle click logic
}
// Remove itemscomplexMenu.removeItems(clickedItem);
// Clear entire menucomplexMenu.clear();

API Reference

Menu Class

The main class for creating and managing GUI menus.

Builder Methods

• size(int size) - Set inventory size (must be multiple of 9, max 54)
• title(Component title) - Set the menu title
• items(SlotItem... items) - Add initial items
• build() - Create the menu instance

Instance Methods

• addItems(SlotItem... items) - Add items to existing menu
• removeItems(SlotItem... items) - Remove items from menu
• clear() - Remove all items
• getInventory() - Get the Bukkit Inventory instance
• getItems() - Get unmodifiable set of all items
• getItemAt(int slot) - Get item at specific slot

SlotItem Record

Represents an item in a menu slot.

Parameters:

• Component itemName - Display name of the item
• int itemSlot - Slot position (0-53 for chest inventories)
• Material material - Minecraft material type
• int quantity - Stack size (1-64)

Requirements

• Java: 21 or higher
• Minecraft: 1.21+ (Paper server)
• Gradle: 7.0+ for building

Building

./gradlew build

The built JAR will be located in build/libs/.

Testing

./gradlew test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub Issues page.