Advanced User Guide

Work in Progress

Advanced User Guide

In this user guide we'll be building a server hub gui with an admin page. The hub menu should teleport players to different minigames and let them view stats, while the admin page is supposed to make managing players easier.

Setup

The first thing I'll be doing is creating a folder where I'm storing my hub related guis. In this folder, I'll create my main gui, called main.gui

Writing the main gui

In my case, I want to have a gui with a header and a page for each minigame category.

Creating the layout

I've created a new file in the hub folder, called navigation-bar.gui. I've written the following content in it:

<gui title="Navigation Bar" width="9" height="1" implicit-update="false">
</gui>

This should look kinda familiar to you, except the implicit-update. The implicit update value determines if the gui should automatically refresh all component's attributes (Like name, material, type, etc) and check if there have been any external changes (They might have been caused due to compute functions, functions that compute values when rendering). Because this is a very costly process, I've disabled it for this gui, as I know for sure that I'm not going to have a content that updates while being viewed, I'll come back to it later.

Now that cleared, let's continue and add some items. I want my player's head to be in the center, showing some information about myself.

<gui title="Navigation Bar" width="9" height="1" implicit-update="false">
    <component type="item" x="0" material="BLACK_STAINED_GLASS_PANE"/>
    <component type="item" x="1" material="BLACK_STAINED_GLASS_PANE"/>
    <component type="item" x="2" material="BLACK_STAINED_GLASS_PANE"/>
    <component type="item" x="3" material="BLACK_STAINED_GLASS_PANE"/>
    <component type="item" x="4" name="§e{%player_name%}'s Profile">
        <head-owner>%viewer%</head-owner>
        <lore/>
        <lore>§7Language: §e{%player_locale_display_name%}</lore>
        <lore>§7Ping: §a{%player_ping%}</lore>
        <lore>§7IP: §e{%player_ip%}</lore>
    </component>
    <component type="item" x="5" material="BLACK_STAINED_GLASS_PANE"/>
    <component type="item" x="6" material="BLACK_STAINED_GLASS_PANE"/>
    <component type="item" x="7" material="BLACK_STAINED_GLASS_PANE"/>
    <component type="item" x="8" material="BLACK_STAINED_GLASS_PANE"/>
</gui>

Okay, so that's content of the navigation-bar.gui. Let's go over it.

As you can see, there are 9 item component's I've added, 8 of them should already be understandable (I suppose you've already read the beginner guide), therefore I'll only take a look at the item positioned at the center.

Compute functions

As you can see, this item is utilizing papi with the Player extension (Run /papi ecloud download Player to use it). This allows us to get some information about the player, as this information isn't provided by gui engine (After all, it's only responsible for rendering guis). You can use any placeholders provided by placeholderapi by using {%your_placeholder%}.

So, you have probably spotted the small outliner: %viewer%. This is a placeholder provided by gui engine itself. It's a reference to the viewer's uuid. It's usually only needed for setting the head owner. But when're already here - What's the difference between %viewer% and {%player_ping%} for example. Basically, the one in {} isn't actually a placeholder. It's a computable function. Computable functions are a powerful way to make your guis more interactive. You can use them to check for permissions, receive values from components or just use them to get papi placeholders (Read more about them here). And because we're already taking about compute functions, let's also talk about the implicit-update property defined above.

Implicit update

So, the implicit update is responsible for updating all compute functions when the gui gets rerendered. This process doesn't take much time itself for a single component, but the issue is, just the navigation bar already uses 4 compute functions. All these for functions will have to be reparsed and rerendered everytime the gui schedules a new render. This is useless in this case, because the values from papi won't change anyways (except the ping), therefore I've set it to false. But be aware. When you notice your guis slow down the server, implicit update is enabled by default.