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.

Desiging Guis without a interpreter

There is another way to open a gui for a player that doesn't involve any files, only pure code. This method can be set equal to using a regualr gui framework. I personally don't recommend it, as you should always try to use this tool to make everything configurable, but something there isn't a way around.

You will still need a gui context, aswell as a interpreter, but you can skip the file.

GuiInterpreter interpreter = guiEngineApi
        .getInterpreterManager()
        .getInterpreter("default"); // Or just use new DefaultInterpreter();
if (interpreter == null)
    return;

GuiContext context = new GuiContext(interpreter, "§eMy gui", 9, 5);
context.add(guiEngineApi, new SimpleItemComponentBuilder<>()
        .setName("§aMy Item")
        .setMaterial(Material.SLIME_BALL)
        .createComponent());

Map<String, String> placeholders = new HashMap<>();
interpreter.getRenderEngine().showGui(context, player, placeholders);

As you can see, this isn't as simple as it was before. So, let's go over this step by step. The first thing we need is a interpreter. Even though we don't have to interprete a gui from a file, we still need it to to create a gui context. For getting a gui interpreter, there are two ways. The first one is probably the easies. Just create a new instance of the interpreter you need, like I do in the commented part. This might work well for some interpreters, but especially ones that aren't included in the default guiengine plugin, you mgith prefer the second approach. You can get a instance of the interpreter manager by using getInterpreterManager() on the guiEngineApi. This then allows you to search for a interpreter, using the getInterpreter method. This is then the same id as you would use in a gui file. Because I want to use the default one, I put in "default". The interpreter returned is marked as nullable. This means there is possible the chance that this might be null. Because I know that the default interpreter is always there, I could probably skip this null check.

Now after we got the interpreter, we can create the GuiContext. This context now has the settings for the gui, like the title, width, height. Once we have the context, we can use it to add components to it. By using the add method, we can add a component. To add a component we must also pass the guiEngine api reference again. This is needed so the component can get bound to this api. Then we can start creating out component. GuiEngine aims on creating Components that are easy to make with the gui files while also being easy to create without one. That's why we a builder for each gui component. We just have to create a builder of the desired component, use the methods provided and once where're finished call the createComponent() method.

In this case I'm using the SimpleItemComponentBuilder. It's basically the builder that hides behind the type "item" in the gui files. I can then set the properties like in the gui file.

Once I've designed my gui context, I can show it to a player. This can only be done using a gui render engine. This is the thing responsible for handling events and rendering your content onto a inventory. You pass the player, the context and the placeholders. Even though the placeholders won't get parsed from any components when calling the showGui method, it's still required, so components that render their own guis inside can parse the gui with the same placeholders.

Note: You could theoretically use a different render engine then the gui interpreter provides, which might work well in some cases, but as soon as the context gets requested to be redrawn, it chooses the interpreters one, which might cause issues.