Skip to content

GuiFunctions

Jump to bottom
Tobero edited this page Sep 17, 2023 · 10 revisions

Functions

Javadoc ToberoCat - GuiEngine Donate PayPal stars - GuiEngine forks - GuiEngine GitHub release issues - GuiEngine SpigotMain - GuiEngine

Functions

GuiEngine supports a wide variety of functions by default, enhancing the interactivity of your GUIs.

Function Types

GuiEngine encompasses two primary types of GUI functions:

  • Compute Functions: These functions are intended to be inserted into your GUI file. During parsing for a specific player's GUI, these placeholders are substituted with computed values. They often take the form: {@my.permission}.
  • Call Functions: Call functions, on the other hand, are restricted to usage within on- sections. These functions cannot be placed elsewhere. A typical call function appears like this: <on-click type="...">...</on-click>.

Compute Functions

Component Property Function

This function enables you to access values from your components. It's useful for tasks like displaying the currently selected page.

Usage: {#id.method} - The 'id' represents the component's ID you intend to target, while 'method' is the specific property you aim to access. Properties for each component are detailed in the Component documentation.

Example Usage (Non-functional components created here):

<component type="paged" id="container"/>
<component type="item" material="GRASS" name="§ePage {#container.getSelectedPage}"/> <!-- 'getSelectedPage' might be outdated; refer to the 'PageComponent' documentation -->

Permission Function

This function returns a boolean value, dependent on a permission check.

Usage: {@guinegine.reload} - The permission you wish to check for follows the '@' symbol. Returns 'true' if the user possesses the permission. Negated Usage: {!@guiengine.reload} - Determines whether the user lacks the permission. Returns 'true' if absent.

Example Usage:

<component type="item" y="3" x="1" name="§eReload" hidden="{!@guiengine.reload}">
    <head-texture>eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZWNkOGNiNGY5OWJhOTQxNDJhYmY1NWY2MzRiZTdiNjk1YzcwZmJhMGQyYjA3NjVjYTg4YmM4ZTJlZWE0NjYzNiJ9fX0=</head-texture>
    <on-click type="action">[player] guiengine reload</on-click>
</component>

<component type="item" y="3" x="1" name="§cReload" material="BARRIER" hidden="{@guiengine.reload}">
    <lore/>
    <lore>§7You are not permitted</lore>
    <lore>§7to reload guiengine</lore>
</component>

Call functions

Action Function

This function will execute a action. Many actions are available by guiengine by default, but they can also be added by external plugins using guiengine. Checkout the wiki page about actions to see the list of actions available

TypeId: action Parameters: [<action>] action-arguments

Example Usage:

<component type="item" y="1" x="6" material="RED_TERRACOTTA" name="§cDiscard Invite">
    <on-click type="action">[player] f invitediscard %invite%</on-click>
    <on-click type="action">[close]</on-click>
</component>

Delay Action

This function will make the execution of following functions pause.

TypeID: delay

Inlined Properties: unit - Set the time unit. It defaults to SECONDS. Available time units:

  • DAYS: Represents time in days.
  • HOURS: Represents time in hours.
  • MINUTES: Represents time in minutes.
  • SECONDS: Represents time in seconds.
  • MILLISECONDS: Represents time in milliseconds.
  • MICROSECONDS: Represents time in microseconds.
  • NANOSECONDS: Represents time in nanoseconds.

Paramaters: duration

Example Usage:

<component type="item" y="1" x="6" material="RED_TERRACOTTA" name="§cDiscard Invite">
    <on-click type="action">[player] f invitediscard %invite%</on-click>
    <on-click type="delay" unit="MINUTES">5</on-click> <!-- Waits for 5 minutes -->
    <on-click type="action">[close]</on-click>
</component>

Add Function

When called, this modifies the currently shown gui to add the component represented in the body.

TypeId: add Parameters: component tree

Example Usages:

Single component
<component type="item" y="1" x="6" material="RED_TERRACOTTA" name="§cDiscard Invite">
    <on-click type="add">
        <component type="item" y="1" x="6" material="GREEN_TERRACOTTA" name="§cDiscard Invite">
            <on-click type="action">[message] You clicked this component!!</on-click>
        </component>
    </on-click>
</component>
Multi component
<component type="item" y="1" x="6" material="RED_TERRACOTTA" name="§cDiscard Invite">
    <on-click type="add">
        <component type="item" y="1" x="6" material="GREEN_TERRACOTTA" name="§cDiscard Invite">
            <on-click type="action">[message] You clicked this component!!</on-click>
        </component>
        <component type="item" y="1" x="7" material="YELLOW_TERRACOTTA" name="§cDiscard Invite">
            <on-click type="action">[message] You clicked the other component!!</on-click>
        </component>
    </on-click>
</component>

Remove function

Removes a component by it's id

TypeId: remove Inlined parameters: target

Example Usage (Not functional page component):

<component type="paged" id="container"/>
<component type="item" y="1" x="6" material="RED_TERRACOTTA" name="§cDiscard Invite">
    <on-click type="remove" target="container"/>
</component>

Edit function

Edit a component

TypeId: edit Inlined parameters:

  • target - The component's id you want to edit
  • attribute - The component's attribute you want to edit
  • set-value - The new value for this attribute

Example Usage:

    <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>

Input function

This function allows you to take inputs from a user and use them in your gui. Once the input has been taken, the gui that called it will be opened again.

TypeId: input Inlined parameters:

  • input-type - Specify the input type. Currently there is: CHAT
  • variable - Set the value you can then use as placeholder to receive the input.

Input Type Specifics: CHAT: The chat input type additionally requires you to give it a message that the user will be prompted with.

Body: The function takes functions in it's body. These functions will execute as soon as the input has been received. Only these functions are allowed to use the placeholder.

Example:

Gamemode example:

<gui title="§eName" width="9" height="3" implicit-update="false">
    <component type="item" id="emerald_block"
               material="EMERALD_BLOCK"
               name="Gamemode switcher">
        <on-click type="input" input-type="CHAT" variable="my_input" message="Enter gamemode">
            <function type="action">[player] gamemode %my_input%</function>
        </on-click>
    </component>
</gui>

Multiple inputs example:

<gui title="§eName" width="9" height="3" implicit-update="false">
    <component type="item" id="emerald_block"
               material="EMERALD_BLOCK"
               name="Set time">
        <on-click type="input" input-type="CHAT" variable="time_mode" message="Enter time mode (add|set)">
            <function type="action">[message] Great choice. Now please proceed.</function>
            <function type="input" input-type="CHAT" variable="amount" message="Enter amount of ticks. Selected mode: §6%time_mode%">
                <function type="action">[player] time %time_mode% %amount%</function>
                <function type="action">[message] You've changed the time!</function>
            </function>
        </on-click>
    </component>
</gui>

Random function

Chooses a random function from it's body that will get executed

TypeId: random

Inlined Attributes:

  • seed Optional. It can be provided, when you want to create randomness in a controlled way. It acts like a special code that ensures the randomness always starts from the same point if you use the same seed, allowing you to reproduce the same random results if needed.

Body: It takes a list of functions. You can also group functions, therefore allowing you to run multiple functions instead of only one.

Examples:

Random spawn

        <on-click type="random">
            <group>
                <function type="action">[player] teleport 0 0 0</function>
                <function type="action">[message] You got teleported to the best spawn</function>
            </group>
            <function type="action">[player] teleport 10 10 10</function>
            <function type="action">[player] teleport -2000 -2000 -2000</function>
        </on-click>

Random spawn with seed. In this case, the seed will be the uuid of the player viewing:

        <on-click type="random" seed="%viewer%">
            <group>
                <function type="action">[player] teleport 0 0 0</function>
                <function type="action">[message] You got teleported to the best spawn</function>
            </group>
            <function type="action">[player] teleport 10 10 10</function>
            <function type="action">[player] teleport -2000 -2000 -2000</function>
        </on-click>

Thank you for choosing GuiEngine for your GUI development needs. Explore the Developer Docs and User Beginner Guide to unleash the full potential of this powerful framework and create stunning GUIs that leave a lasting impression on your players!

Clone this wiki locally