Developer Docs

Use it in your projects

First, you have to get the GuiEngine builds into your project. When using maven, you can use the following:

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.ToberoCat</groupId>
    <artifactId>GuiEngine</artifactId>
    <version>Tag</version>
  </dependency>
</dependencies>

For gradle:

repositories {
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation 'com.github.ToberoCat:GuiEngine:Tag'
}

Create a GuiEngineAPI instance

GuiEngine requires you to use a own GuiEngineAPI when you want to display guis. Creating such a instance is as easy as writing a single line of code.

import org.bukkit.plugin.java.JavaPlugin;

import java.io.IOException;
import java.net.URISyntaxException;

public class MyGuiPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        GuiEngineApi guiEngineApi;
        try {
            guiEngineApi = new GuiEngineApi(this);
        } catch (IOException | URISyntaxException e) {
            getLogger().severe(e.getMessage());
            return;
        }
    }
}

The code above creates a new GuiEngineApi instance bound to this plugin. This binding to the plugin isn't necessary, as there are two other constructors. But this way, you don't have to worry about copying your guis from the resource folder into your data folder. Make sure you have a guis folder in your resources where you can put the guis your plugin needs. To see how to create your own guis, this beginner guide might help you.

If you decide to not use the constructor with the JavaPlugin, you have to create the api as follows:

import org.bukkit.plugin.java.JavaPlugin;

import java.io.File;


public class MyGuiPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        GuiEngineApi guiEngineApi = new GuiEngineApi("my-plugin", new File(getDataFolder(), "guis"),
                pathname -> {
                    return pathname.canRead();
                });
        //GuiEngineApi guiEngineApi = new GuiEngineApi("my-plugin", new File(getDataFolder(), "guis"));
    }
}

The not commeted example uses the GuiEngineApi constructor that takes the id of the api, the folder where the guis are located and a FileFilter. The ID is used to identify the api from other apis registered. The FileFilter determains what files in the folder are gui files that should get loaded by the GuiEngine.

If you use the commented approach, you can leave out the FileFilter. Then the default one will be used, where all files ending with .gui will get loaded.

Open a gui

Now that you have your GuiEngineApi instance, you can use it to open a gui. This is again very easy and straight forward. You can use the open Method provided by the GuiEngine.

GuIContext context = guiEngineApi.open(player, "my-gui");

That's all you need. Now the player will see the gui you desgined pop up on their screen. Notice the my-gui. This is actually a file in the guis folder, called my-gui.gui. When opening a gui, the extension is always stripped from it. The open method also returns you the GuiContext. This is a class containing the entire gui the user can see. You can use it to interact with the gui from the code side, but to this a little bit later.

The open method has a overloaded method too. You can pass it placeholders, which can be used in the gui. A placeholder is always indicated with: %%. The method where you don't pass any placeholders has a default placeholder, the viewer one. Let's try to replicate this with the overloaded method.

Map<String, String> placeholders = new HashMap<>();
placeholders.put("viewer", player.getUniqueId().toString());
GuiContext context = guiEngineApi.open(player, "my-gui");

In this primitive example, you can see that passing placeholders is almost as easy as opening the gui. Just create a map, populate it and pass it as method argument.