User Beginner Guide

Introduction

Welcome to the beginner's guide for server owners and developers! This guide aims to introduce you to the basic concepts of the plugin. However, it's important to note that the plugin and its accompanying wiki may not be perfect. We are continuously working to improve them. If you come across any suggestions, bugs, issues, or feedback of any size, feel free to create an issue here and share your thoughts. Additionally, you can even fix it locally and submit a pull request to contribute to the project's development. Your input is highly valued as we strive to make this plugin better together. Let's dive in and get started with the guide!

Getting started

At first, you'll have to download the GuiEngine (Download). All download sites:

• GuiEngine - Spigot
• GuiEngine Release

Once the plugins are installed on your server, start it. Once the server started, you'll be able to navigate to plugins/GuiEngine/guis. This folder contains all guis you created without a plugin requiring them. I'll now refer to it as gui folder.

Commands

Now, before we'll dive into creating our first gui, you should make yourself familiar with the commands the plugin provided. The most important one will be /guiengine reload. This will reload all guis, no matter which plugin is requiring them. The second command you'll need is /guiengine open <plugin> <gui>. This command allows you to open any gui, no matter which plugin or nesting (We'll come later to that). When using this command, I highly recommend using the tablist (The black box above the chatbar when typing). It suggests all possible options. When no plugins are installed using GuiEngine, the command list should show as first argument default. So a example usage for this command would be /guiengine open default my-gui /guiengine give <item> <plugin> <gui> <player> This command gives a player a item they can click, opening a gui. The item can be created in the config.yml.

Picking the right gui folder

Now that you know the commands, let's start creating a gui. First thing you'll have to know what gui you want to create. Is it from a specific plugin? If yes, you should navigate to the gui folder of the plugin and edit a file !IMPORTANT: Don't create new files in a non default gui folder except the plugin needs it!. If you want to create a gui from scratch, you should use the gui folder fo GuiEngine.

Gui folder structure

Once you found yourself in the right folder, depending on your case, the folder might not be empty.

The gui folder is able to contain folders and gui files. You can create folders in folders and so on to group your guis, while the gui files represent the actual gui. Note that when you have a gui placed in a subfolder of the gui folder, it will no longer just have the name of the file, it will now be subfoldername/filename. If you have even one more layer of folders, there will be another subfolder in the name.

Create a gui

In the GuiEngine gui folder create a file named my-gui.gui. Make sure when creating the file that the extension is correct. When on windows, the extensions might be hidden. You should show them, to make sure they're correct.

Once the file has been created, open it in a text file editor of your choice. I recommend using a editor that detects and supports xml files, as this will make your live easier writing them. A free editor you can use is Visual Studio Code from Microsoft. I'll be using Intellij from Jetbrains for my XMl file editing.

Once you've opened the file, you'll have to create the base layout of the gui, starting with the root tag. The root tag in this is will be <gui></gui>. Now that the root tag exists, you can define some generic gui values, like the title, height and width. Note: Height is counted in minecraft gui rows, meaning the maximum is 6 and minimum is 1. The width in minecraft is limited to 9 slots per row. This property gets more meaning when creating more complex guis.

Now you can choose a different interpreter (The thing that translates this file into an actual minecraft gui). You can leave it for now, but that you know when you need it, the attribute goes like interpreter="default" for the default interpreter.

Now the gui file should look like this (Color can be different depending on your text editor): Note that I've used a color code in the title to make it more colorful (§b is the color code). Minecraft color codes can be used with § instead of &.

Adding components to the gui

Now to make the gui functional, you have to add components. Components are just a way to decribe certain things in a gui. For simplicity, we'll add a simple item, which when clicked prints a text to the player.

To add a component, create a component tag, with the attribute type set to item. Now depending on the component type choosen, you now have to add addional attributes. The item needs at least a material property, saying which item you wanted. Additionally, you can provide a name, x and y. Note: If you need help with the materials, you can press F3 + H to show advanced item stats. When you now hover over a item, you can see the item id.

You can now use this item id, by stripping the minecraft: and make the rest upper case. You can then use this in as the material. This approach works fine for most items, but some don't work like this. If you have such a case, navigate to this website, https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html.

Here is how my gui looks now:

Testing your gui is as important as creating it. To do so, type /guiengine reload to reload the guis. Once it reloaded, type /guiengine open default my-gui. This should now open a gui looking like this:

Now, lets add a second item. Just copy the previous component and paste it below. You can now change values to your likings, save and test inbetween until you're happy with the layout of your items.

My gui file now looks like this (Ignore the light bulb):

Running the commands from above again and the gui looks like this:

Adding item descriptions

Now, usually items in guis have special descriptions below when hovering above them. This can also be done using guiengine. Inbetween the component tag you can write <lore>Text</lore> with your text to add into the item description.

Now having added some lores, my gui now looks like this:

And in game:

Adding click events

Now that you've created static items, we now want something to happen when you click them. This can be done using the same approach as we used for lores. Add a on-click tag. This time, the tag also has some attributes. The attribute is type. Types define what should happen when clicked. We'll use the type action and edit. Actions are a way interact with things outside of the gui. Edit is a type of interactin within the gui, specifically edit something.

My first item having the action on-clicks:

You can have multiple on clicks happening. In this case. The actions will do following:

• The first will send a message to the player
• The second one executes any command, in this case /summon zombie
• The last one closes the gui

Now to the edit item:

There's lot of stuff to cover here. First, I've given the componet a id, so the gui can find it again. The id can be any name, as long as it does only container alphabet, numbers, dashes and underscores.

Now the on-click. The type edit requires three attirbutes, target, attribute and set-value. The target should reference a component by id. The attribute should be which attribute you want to edit of this target component and the set-value tells the edit function which value the attribute will have.

Opening the gui in minecraft and clicking both items should be working as intented

The final code for the gui we just created:

<gui width="9" height="4" title="§bMy first gui">
    <component type="item" x="5" y="2" material="REDSTONE_BLOCK" name="§cSuspicious red button">
        <lore>§7A button</lore>
        <lore>§7You shouldn't click me</lore>
        <on-click type="action">[message] §cYou shouldn't have clicked me...</on-click>
        <on-click type="action">[player] summon zombie</on-click>
        <on-click type="action">[close]</on-click>
    </component>
    <component type="item" id="green-button" x="3" y="2" material="GREEN_TERRACOTTA" name="§aGreen button">
        <lore>§7Click me</lore>
        <lore>§7I promise §ait's worth§7 it</lore>
        <on-click type="edit" target="green-button" attribute="name" set-value="§eYou clicked me :)"/>
        <on-click type="edit" target="green-button" attribute="material" set-value="YELLOW_TERRACOTTA"/>
    </component>
</gui>

Creating a clickable item

Now the last topic I want to cover in this guide is the creation of a clickable item. This feature allows you to design a item users can click, allowing them to open your gui without having to type the command.

First, you have to find the config file, where you can design your item. It is located in plugins/GuiEngine/config.yml. Now open it. Once you opened it, you should search for a section called items.

Once you found it, you can see the example item that has already been created. When you want to create a new item, just copy the example item and rename the root element. Then you can start customizing it to your liking. Change the name of it, the material, the lore, etc. You can use the same trick to get the material as above.

I now desgined a new item. It's a golden apple. Now let's bring it into the game.

You can now use the following command to receive your clickable item, that opens my-gui (That's the gui we just created). /guiengine give my_gui_item default my-gui. When you run this command as a player, you will receive the item bound to the gui 'my-gui' provided by the default api. When you create your own items and guis, the commands tab complete will help you, so you don't have to remember everything.

You can also run this command in the console or from a command block. For this, you can add a player name at the end, like this: /guiengine give my_gui_item default my-gui Notch0815

Conclusion

You've successfully created your first GUI using GuiEngine! You've learned how to add components, item descriptions, and click events to make your GUI interactive. Explore further possibilities with GuiEngine by referring to the documentation, which covers pre-made components, functions, and more.

Enjoy creating custom GUIs for your Minecraft server! If you encounter any issues or need further assistance, don't hesitate to seek help from the community or the plugin's support channels. Happy crafting!