SamJakob / SpiGUI

A comprehensive GUI API for Spigot with pages support.
MIT License
106 stars 21 forks source link

SpiGUI

A comprehensive inventory menu API for Spigot with pages support. Supports Bukkit/Spigot 1.7 - 1.20 (see Version Notes) (Future versions ought to work just fine too!).

License No Dependencies

JitPack JavaDoc




The code for this example can be found in the library test class.



Version Notes

IMPORTANT! If you have an opinion on how backwards compatibility should be achieved with new versions, please feel free to drop a reply to this open discussion.


Installation

You can very easily install SpiGUI using JitPack. (The JitPack page contains instructions for Gradle, Maven, sbt, etc.)

Instructions for Gradle Just add the following to your `build.gradle` file: ```groovy repositories { // ... maven { url 'https://jitpack.io' } } dependencies { // ... implementation 'com.samjakob:SpiGUI:' } ```
For distribution, you can just shade the library into your plugin JAR. On Gradle, this can be done by adding the following to the end of your `build.gradle`: ```groovy jar { duplicatesStrategy(DuplicatesStrategy.EXCLUDE) from { configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) } } } ```

If you aren't using a build system, you can just download the latest JAR and add it to your project's classpath (just make sure the SpiGUI classes are included in your JAR when you build it).


Quick Start

Step 1: Create an instance of the SpiGUI library in your plugin


class MyPlugin extends JavaPlugin {

  public static SpiGUI spiGUI;

  @Override
  public void onEnable() {
    // (IMPORTANT!) Registers SpiGUI event handlers (and stores plugin-wide settings for SpiGUI.)
    spiGUI = new SpiGUI(this);
  }

}


Step 2: Use the library

public void openMyAwesomeMenu(Player player) {

  // Create a GUI with 3 rows (27 slots)
  SGMenu myAwesomeMenu = MyPlugin.spiGUI.create("&cMy Awesome Menu", 3);

  // Create a button
  SGButton myAwesomeButton = new SGButton(
    // Includes an ItemBuilder class with chainable methods to easily
    // create menu items.
    new ItemBuilder(Material.WOOD).build()
  ).withListener((InventoryClickEvent event) -> {
    // Events are cancelled automatically, unless you turn it off
    // for your plugin or for this inventory.
    event.getWhoClicked().sendMessage("Hello, world!");
  });

  // Add the button to your GUI
  myAwesomeMenu.addButton(myAwesomeButton);

  // Show the GUI
  player.openInventory(myAwesomeMenu.getInventory());

}


Step 3: Profit!


Why?

Chest Inventory Menus (commonly referred to as GUIs) are the ubiquitous way to display menus, execute actions and even manage configuration in Spigot plugins. However, the Inventory API leveraged to achieve this in Spigot is not designed for menus, making code far more verbose and far less maintainable than it needs to be.

SpiGUI is a rewrite of my outdated SpigotPaginatedGUI API including improvements and features I've added whilst using the API in my own software that aims to provide a highly readable and concise API for menus.