InventoryGui

A library that simplifies the creation of chest GUIs for Bukkit/Spigot plugins and allows assigning of the GUI to a specific InventoryHolder. If you are in need of a GUI for text inputs then take a look at WesJD's AnvilGUI library.

Requires Java 8.

GitHub repository

Take a look at the examples below to learn how to create a GUI with this library or use the InventoryGui Javadocs.

Every line in the array define the line in the inventory chest interface.

The characters are getting assigned to certain elements laters, similar to how recipes are defined. Any empty slot will be filled with a filler character that you can also define yourself.

snippet.java

String[] guiSetup = {
    "  s i z  ",
    "  ggggg  ",
    "  fpdnl  "
};

The GUI supports 3*3, 5*1 and 9*x inventory sizes. Sizes that do not match these are getting expanded to the next bigger one.

You create GUIs assigned to an InventoryHolder like a Container or a LivingEntity.

If the holder is null then you are not able to retrieve the GUI by the holder via InventoryGui.get(holder).

snippet.java

InventoryGui gui = new InventoryGui(yourPlugin, theInventoryHolder, guiTitle, guiSetup);
gui.setFiller(new ItemStack(Material.GRAY_STAINED_GLASS, 1)); // fill the empty slots with this

You can add certain GUI elements to the GUI which will be assigned to a certain character from the setup. With these elements you define the actions that should happen when the player interacts with the element. E.g. you can run some code when the player clicks it. Some elements (like the state one) have predefined actions that happen when they are clicked. (e.g. toggling between the possible states)

A simple, static element that runs some action when it is clicked.

snippet.java

gui.addElement(new StaticGuiElement('s',
        new ItemStack(Material.REDSTONE),
        42, // Display a number as the item count
        click -> {
            if (click.getEvent().getWhoClicked().getName().equals("Redstone") {
                click.getEvent().getWhoClicked().sendMessage(ChatColor.RED + "I am Redstone!");
                return true; // returning true will cancel the click event and stop taking the item
            }
            return false; // returning false will not cancel the initial click event to the gui
        },
        "You can add lines describing this element here!",
        "The first line is displayed as the displayname,",
        "any additional ones as the lore!",
        "Any text the ItemStack had will be overwritten."
)); 

All of these arguments (besides the ItemStack) are optional. See the docs for more details on the available convenience constructors.

An Element that directly accesses the holder inventory. This can be used to handle placing and retrieving items from parts of a GUI as if that part was a normal inventory. You can even back the element by a virtual Bukkit inventory instead of a real one!

If the element is displayed only in one slot it will show the first item in the inventory. In two slots the first two and so on.

snippet.java

// With an existing holder (e.g. block or entity)
gui.addElement(new GuiStorageElement('i', theInventoryHolder.getInventory()));
 
// With a virtual inventory to access items later on
Inventory inv = Bukkit.createInventory(null, InventoryType.CHEST);
gui.addElement(new GuiStorageElement('i', inv));
gui.setCloseAction(close -> {
    saveInv(inv); // Save inventory content or process it in some other way
    return false; // Don't go back to the previous GUI (true would automatically go back to the previously opened one)
});

An element that can have certain states that trigger some code when changed to. and automatically changes the ItemStack icon.

snippet.java

gui.addElement(new GuiStateElement('z', 
        new GuiStateElement.State(
                change -> {
                    change.getEvent().getWhoClicked().setFlying(true);
                    change.getEvent().getWhoClicked().sendMessage("You are now flying!");
                },
                new ItemStack(Material.WOOL, 1, 5)), // the item to display as an icon
                "flyingEnabled", // a key to identify this state by
                ChatColor.GREEN + "Enable flying!", // explanation text what this element does
                "By clicking here you will start flying"
        ),
        new GuiStateElement.State(
                change -> {
                    change.getEvent().getWhoClicked().setFlying(false);
                    change.getEvent().getWhoClicked().sendMessage("You are no longer flying!");
                },
                new ItemStack(Material.WOOL, 1, 14)),
                "flyingDisabled",
                ChatColor.RED + "Disable flying!",
                "By clicking here you will stop flying"
        )
));

… you can define as many states as you want, they will cycle through on each click you can also set the state directly via GuiStateElement#setState(String key)

You can also dynamically load elements each time the GUI is re-drawn. E.g. when you want to cache GUIs but not the text of some buttons or dynamically change them while they are open without closing and reopening them.

Dynamic elements just return one of the other elements that should be displayed each time InventoryGui#draw is called. The slot character for the returned element doesn't really play a role, it is recommended to set it to the DynamicGuiElement's slot character though.

snippet.java

gui.addElement(new DynamicGuiElement('d', () -> {
    return new StaticGuiElement('d', new ItemStack (Material.CLOCK), 
        click -> {
            click.getGui().draw(); // Update the GUI
            return true;
        }, 
        "Update time: " + new SimpleDateFormat("HH:mm:ss").format(new Date()));
}));

As you can see you can change the content of a DynamicGuiElement after a player click on it by calling InventoryGui#draw in the action of the supplied element.

A group can contain multiple different elements and if there are more elements in the group than display slot you can use the GuiPageElement to switch between pages.

snippet.java

GuiElementGroup group = new GuiElementGroup('g');
for (String text : texts) {
    // Add an element to the group
    // Elements are in the order they got added to the group and don't need to have the same type.
    group.addElement((new StaticGuiElement('e', new ItemStack(Material.DIRT), text);
}
gui.addElement(group);

It will automatically detect GuiElementGroup elements with more elements in them than available slots with that character in the GUI and go to the according page on click. (depending on type) There are also some pagination specific placeholders available for the element descriptions.

snippet.java

// First page
gui.addElement(new GuiPageElement('f', new ItemStack(Material.ARROW), PageAction.FIRST, "Go to first page (current: %page%)"));
 
// Previous page
gui.addElement(new GuiPageElement('p', new ItemStack(Material.SIGN), PageAction.PREVIOUS, "Go to previous page (%prevpage%)"));
 
// Next page
gui.addElement(new GuiPageElement('n', new ItemStack(Material.SIGN), PageAction.NEXT, "Go to next page (%nextpage%)"));
 
// Last page
gui.addElement(new GuiPageElement('l', new ItemStack(Material.ARROW), PageAction.LAST, "Go to last page (%pages%)"));

After you have created the GUI you can retrieve it with the original holder and show it to a player.

snippet.java

InventoryGui gui = InventoryGui.get(InventoryHolder holder);
gui.show(player);

Obviously you can also show the GUI directly after creating it.

You can easily depend on the library with maven.

snippet.xml

<repositories>
    <repository>
        <id>minebench-repo</id>
        <url>https://repo.minebench.de/</url>
    </repository>
</repositories>

snippet.xml

<dependencies>
    <dependency>
        <groupId>de.themoep</groupId>
        <artifactId>inventorygui</artifactId>
        <!--The following version may not be the latest. Check it before using.-->
        <version>1.4.2-SNAPSHOT</version>
        <scope>compile</scope>
    </dependency>
</dependencies>

As this is not a stadalone plugin you have to shade it into your plugin! E.g. with the maven-shade-plugin like this.

You can also get development builds directly from the Minebench Jenkins ci server if you want to manually add it to your project but I strongly advise using a dependency management tool like maven or gradle!

InventoryGui is licensed under the following, MIT license:

Copyright 2017 Max Lee (https://github.com/Phoenix616)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.