Chapter 9

Addon

The extension that adds more features to the main plugin.

Subsections of Addon

Advanced Cooldown

Code Download

Config.yml

# Format:
# <name>: <value>
#
# Example:
# simple-cooldown: 100
simple-cooldown: 100
cooldown-10000: 10000
cooldown-999: 999

Variable

<name> is the cooldown name from the config.yml

  • advanced_cooldown_<name>
  • advanced_cooldown_<name>_s or advanced_cooldown_<name>_seconds
  • advanced_cooldown_<name>_m or advanced_cooldown_<name>_minutes
  • advanced_cooldown_<name>_h or advanced_cooldown_<name>_hours
  • advanced_cooldown_<name>_format_<time-format>
    • Example Format: advanced_cooldown_<name>_format_HH:mm:ss

Requirement

Format

advanced-cooldown: <name>

Description

  • This requirement will check if the player is not in a cooldown timer named <name>.
  • After checking the requirement, the addon will start the cooldown timer for the player.

Example

advanced-cooldown:
  slot: 1
  id: clock
  name: "&cAdvanced Cooldown"
  command:
    - "tell: &aHello"
  click-requirement:
    left:
      test:
        advanced-cooldown: "simple-cooldown" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_simple-cooldown_s} seconds"
    right:
      test:
        advanced-cooldown: "cooldown-10000" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_cooldown-10000_s} seconds"
    middle:
      test:
        advanced-cooldown: "cooldown-999" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_cooldown-999_s} seconds"

Time Format

characterduration element
yyears
Mmonths
ddays
Hhours
mminutes
sseconds
Smilliseconds
  • Example:
    • HH:mm:ss: show hours, minutes and seconds
    • YY:MM:dd HH:mm:ss: show years, months, days, hours, minutes and seconds

Alternative Command Listener

Code Download

This addon adds an alternative feature for menu commands to solve the “duplicated command” issue.

Config.yml

# The list of ignored commands
ignored-commands:
- warp test

# Ignore case-sensitive when checking commands
case-insensitive: true

# Should we ignore the commands in ignored-commands
# If set to false, the plugin will do the opposite (override the commands in ignored-commands)
should-ignore: true

Anvil GUI

Code Download

Format

# Settings
menu-settings:
  menu-type: anvil

  # The title of the menu
  title: <name>

  # The text to show when the player opens the menu
  text: <text>

  # The commands executed when the player clicks the result slot (the last slot)
  complete-action:
  - action
  - action
  ...

  # The commands executed when closing the menu
  close-action:
  - action
  - action
  ...

  # Whether the addon prevents the player from closing the menu
  prevent-close: <true/false>

  # The commands to open the menu
  command:
  - command1
  - command2
  ...

  # Whether the addon will clear the user's input when completed
  clear-input-on-complete: <true/false>

# Left Button
left-button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...

# Right Button
right-button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...

# Left Button (for simplier menu)
button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...

Description

  • This is a special menu type only for getting inputs.
  • In this menu type, the addon only apply ONE icon.

Note

  • The complete-action and close-action use the Action value.
  • The left-button, right-button and button use the Button value.
  • The menu will register a Menu Variable named {anvil_input} to get the player’s input.

Example

menu-settings:
  menu-type: anvil
  command: testanvil
  title: "&cTest Anvil"
  text: "What is your name?"
  clear-input-on-complete: true
  complete-action:
  - "tell: &aHello, {anvil_input}"
  prevent-close: true
  close-action:
  - "tell: &cYou closed the menu"

button:
  id: paper

ASCII-Placeholders

Code Download

Config.yml

# This is the config for all static variables
# Format: {ascii_<name_of_variable>}
# Example: {ascii_<3}, {ascii_*}, {ascii_cross}, e.g.
#
# List of unicode symbols: http://www.fileformat.info/info/unicode/index.htm
<3: \u2764
"*": \u2605
"**": \u2739
"p": \u2022
"v": \u2714
"+": \u25C6
"++": \u2726
"x": \u2588
"/": \u258C
"cross": \u2720
"arrow_right": \u27A1
"arrow_left": \u2B05
"arrow_up": \u2B06
"arrow_down": \u2B07

Variable

  • {ascii_<name>} gets the value (symbol) from the config.yml at the key <name>

Bungee Link

Code Download

Warning

Depend: BungeeCord or its forks

Action

Send To Server

Format

  • server: <server-name>

Description

This action will send the player to the server <server-name>

Example

send-to-pvp:
  slot: 1
  id: diamond sword
  name: "&c&lPVP"
  lore:
  - "&fGo to PVP Server"
  command: "server: pvp"

Alert

Format

  • alert: <message>

Description

This action will send <message> to all servers in the network

Example

ping-everyone:
  slot: 1
  id: paper
  name: "&ePing @everyone"
  command: "alert: &b&l@everyone"

Converter

Code Download

Note

This is a work-in-progress. More features will be added soon.

Warning

This addon does not guarantee to convert 100% of your menus, because the structure is usually different between menu plugins.

BetterGUI does not have conflict with other menus. Therefore, it’s recommended to do a fresh start by making your next menu entirely in BetterGUI, then rework your old menus one-by-one in BetterGUI.

Supported plugins

How to use

  1. Don’t delete your old plugin
  2. Download & Install the addon
  3. Start & Join your server
  4. Type /convertmenu <plugin> [menu]
  • If you don’t set the [menu], the addon will convert all menus from your old menu plugin.
  1. The converted files will be in plugins/BetterGUI/addon/Converter/<plugin>

Dynamic Title

Code Download

Description

This is an addon for your existing menus. This enables updating inventory titles.

How to use

Set the creator option of the menu-settings to be dynamic-title

menu-settings:
  name: '&u&lExample Menu'

  creator: "dynamic-title"
  # ...

More settings

menu-settings:
  name: '&u&lExample Menu'

  # The creator to enable Dynamic Title
  creator: "dynamic-title"

  # How often the title should update in ticks (20 ticks = 1 second)
  title-period: 5

  # The title template
  # The list of title "frames" that will be displayed in order (when the title refreshes)
  title-template:
  - "&u-"
  - "&u--"
  - "&u---"
  - "&u----"
  - "&u-----"
  - "%original%"
  - "&u-----"
  - "&u----"
  - "&u---"
  - "&u--"
  - "&u-"
  - ""
Warning

Sometimes when you close the menu, the menu will not be closed. It’s a known (and wont-fix) bug because of how the packet is sent. You may have to set the title-period higher to reduce the chance the bug occurs.

Enchant Keyring

Code Download

This addon adds an Item Modifier similar to Enchantment but it uses Minecraft’s keys instead of Bukkit’s ones. It is useful for those who use custom enchantment plugins and want to add these enchantments to the menu.

Format

enchant-key:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]

Note

  • The <enchantment> use Minecraft’s key in the format of <name>:<key> (Similar to the enchantment key you use in the /enchant command in Vanilla).
  • You can set the [level] of the <enchantment>. It’s optional.

Example

enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  enchant-key:
    - "minecraft:unbreaking, 1"
  POSITION-X: 1
  POSITION-Y: 1

Eval Extra

Code Download

Description

  • This is an addon to apply math expressions in some settings of the menu
  • With this, you can write advanced math in menu. Especially, this addon is useful to write advanced conditions in Condition Requirement

Example

stone:
  id: stone
  amount: "25 + 3"
stone:
  id: stone
  amount: "FLOOR(SQRT(18))" # The amount will be the floor value of the square root of 18, which is 4
test-view-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is higher than 5"
  view-requirement:
    level:
      condition: "{level} > 5" # This will check if the player's level is higher than 5

Operator

  • The basic is the use of math operators in the expressions (+, -, *, /, etc)
  • Examples:
amount: "5 + 7" # The amount will be 11
amount: "{level} % 64 + 1" # The amount will be from 1 to 64, based on the level
  • Along with math operators, you can also use Boolean operators (>, <, =, >=, <=, etc) to compare values.
  • Example:
condition: "{level} > 5" # This will check if the player's level is higher than 5

Function

  • Functions are the process of “input to output”, take the input and returns the corresponding output.
  • Functions
  • Example:
amount: "FLOOR(SQRT(18))" # The amount will be the floor value of the square root of 18, which is 4

String Functions

  • This addon also accepts comparing strings with String Functions
  • It includes:
    • STRCT("this", "is") check if is is in this (this contains is)
    • STREDW("String", "ing") check if String ends with ing
    • STREQ("str1", "str1") check if str1 equals str1
    • STREQIC("str1", "str1") check if str1 equals str1 (case-insensitive)
    • STRLEN("Hello World") get the length of Hello World
    • STRMP("String", "String-?") check if String matches the RegExr pattern String-?
    • STRSTW("String", "Str") check if String starts with Str

Skip the Evaluation

  • If you want to skip your string from evaluation for some reason, put [skip-eval] before your string
    • Example: If you want to skip 1 + 1, put [skip-eval] like this [skip-eval] 1 + 1

ExterHeads

Code Download

This addon adds Item Modifiers to get heads from popular head plugins.

Head Database

Format

head-database: <head-id>
head-db: <head-id>
hdb: <head-id>

Example

head-item:
  hdb: 1
  name: "&cHead Database"
  lore:
  - ""
  - "&7This is a head item from Head Database"

TheSilentPro’s HeadDB

Format

tsp-head: <head-id>
tsp-head-name: <head-name>

Example

head-item:
  tsp-head: 1
  name: "&cHeadDB"
  lore:
  - ""
  - "&7This is a head item from HeadDB"

Item Gotcha

Code Download

Config.yml

stone:
  id: STONE
  amount: 32

advanced_stone:
  id: STONE
  amount: "32"
  name: "&c{player}'s Stone"
  lore:
    - "A dummy Stone"
    - ''
    - "&kYes, it's very dummy and stupid"

Create an item

  • The config should be easy if you are familiar with Button and, particularly, Dummy Button
  • Yes, you can think of the config.yml as a Menu setup, but with dummy buttons
  • Therefore, if you want to make an item, you can set it up in the config.yml as how you did in your menu (Name, Material, Lore, etc)

Command

CommandPermissionDescription
giveitem <item_name>bettergui.itemsGive <item_name> to the player

Action

Format

  • give: <item>
  • give: <item>, <amount>
  • give: <material>, <amount>

Description

This action will give the player the <item> (specified in the config.yml) or the <material> with the <amount>

Example

give-stone:
  slot: 1
  id: stone
  name: "&cGive me stone"
  command: "give: stone"

give-advanced-stone:
  slot: 2
  id: stone
  name: "&cGive me advanced stone"
  command: "give: advanced_stone"

give-kits:
  slot: 3
  id: diamond sword
  name: "&cGive kits"
  command:
  - "give: DIAMOND_SWORD"
  - "give: STONE, 10"

Requirement

Format

item: <item>
item:
  value: <item>
  take: <true/false>
item: <item>, [amount]
item:
  value: <item>, [amount]
  take: <true/false>

Description

  • This requirement will check if the player has the <item> (specified in the config.yml) in his inventory
  • You can set the amount value to specify the amount of <item> the requirement should check
  • You can set the take value (true or false) to allow/disallow the plugin to take the items of the player alter checking successfully

Example

take-stone:
  slot: 1
  type: predicate
  button:
    id: stone
    name: "&cTake Stone"
  click-requirement:
    left:
      take-one: # Take one stone
        item: "stone"
    right:
      take-ten: # Take ten stone
        item: "stone, 10"
    middle:
      take-multi: # Take 10 stone and 1 cobblestone
        item:
          value:
            - "stone, 10"
            - "cobblestone"
          take: true
    default:
      check-stone: # Check (not take) if the player has 20 stone
        item:
          value:
            - "stone, 20"
          take: false

ItemBridge Hook

Code Download

Warning

Depend: ItemBridge

Format

itembridge: <id>
item-bridge: <id>

Description

This item modifier allows you to use the item with the <id> from ItemBridge in your menus.

Note

This item modifier is order-sensitive. You have to set it before other modifiers.

Example

test-itembridge:
  slot: 0
  itembridge: "minecraft:stone"
  name: "&bItemBridge"

Meta Play

Code Download

Description

This addon adds a new variable to get and set metadata of players. This can be used to store data for the player.

Variable

  • {meta_<key>} gets the value from the metadata of the player at the key <key>
  • {meta_number_<key>} gets the value from the metadata of the player at the key <key> and converts it to a number

Action

  • mete(<key>): <value> sets the value of the metadata of the player at the key <key> to <value>
  • meta(<key>, number): <value> sets the value of the metadata of the player at the key <key> to <value> as a number
  • meta(<key>) removes the value of the metadata of the player at the key <key>

Note: In <value> you can use the variable {value} to get the previous value of the metadata.

Example

T:
  id: diamond
  name: "&b&lMeta: &f{meta_number_diamond_count}"
  command:
    left: "meta(diamond_count, number): {value} + 1" # Requires EvalExtra to use expressions
    right: "meta(diamond_count): 0"

PaperSpec

Code Download

Description

This addon add functions that only work on PaperMC and its forks.

Warning

Requirement: Paper 1.19.4 or newer is required for this addon to work.

Set the creator option of the menu-settings to be mini-title.

Then you can use MiniMessage formatting for the inventory title.

menu-settings:
  name: '<red><b>A inventory title generated by MiniMessage'

  creator: "mini-title"
  # ...

Item Modifiers

Skull Modifier

Format

paper-skull: <skull>
paper-head: <skull>
skull$: <skull>
head$: <skull>

Description

  • This modifier will set the <skull> of the item
  • <skull> accepts a player name or an UUID (unique id)

Example

skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  paper-skull: "HSGamer"
  # paper-skull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  paper-skull: "{player}"

DisplayName & Lore Modifiers

Format

mini-name: <minimessage formatting text>
mini-lore:
- <minimessage formatting text>
- <minimessage formatting text>
- ...

Description

You can use MiniMessage formatting for the name and lore of your menu items. Just make sure you use the new format above instead of the original name and lore modifiers.

There are aliases for the modifiers. You can also use:

  1. name$ for the mini-name modifier
  2. lore$ for the mini-lore modifier

Note that the legacy color codes (&c, &3) does not work in the new format.

Example

minimessage:
  position-x: 1
  position-y: 1
  mini-name: "<rainbow>Rainbow Name"
  mini-lore:
    - "<b>Bold text"
    - "<aqua>Simple color!"
    - "<#00ff00>R G B color!"
    - "<gradient:green:blue>Gradient color!"
    - "<transition:#00ff00:#ff0000:0>Transition color!"
    - "<font:myfont:custom_font>Uses a custom font from a resource pack"
    - "<lang:block.minecraft.diamond_block> <- this is a translatable text"

Action

<type>: The type of the component (json, minimessage, legacy)

  • paper-tell(<type>): <text>: send the component text to the player
  • paper-broadcast(<type>): <text>: send the component text to all players
  • paper-tell(<type>, bar): <text>: send the component text as an action bar to the player
  • paper-broadcast(<type>, bar): <text>: send the component text as an action bar to all players

MiniPlaceholders support

MiniPlaceholders is supported in all settings that involve MiniMessage formatting

Example

mini-tps:
  position-x: 1
  position-y: 1
  mini-name: "<rainbow>TPS"
  mini-lore:
    - "<white><b>1m: <green><server_tps_1>" # <server_tps_1> is a MiniPlaceholders placeholder
    - "<white><b>5m: <green><server_tps_5>" # <server_tps_5> is a MiniPlaceholders placeholder

PlayerPoints Bridge

Code Download

Warning

Depend: PlayerPoints

Variable

  • {points} gets the points the player having

Action

Format

  • give-point: <point>

Description

This action gives <point> to the player

Example

give-point:
  slot: 1
  id: emerald
  name: "&cGive points"
  command: "give-point: 10"

Requirement

Format

point: <value>
point:
  value: <value>
  take: <true/false>

Description

  • This requirement checks if the player has at least <value> points
  • You can set the take value (true or false) to allow/disallow the plugin to take the points of the player alter checking successfully

Example

check-points:
  slot: 1
  id: emerald
  name: "&cTake Points"
  click-requirement:
    left:
      take-point: # Take 10 points
        point: 10
    right:
      check-point: # Check if the players has 10 points
        point:
          value: 10
          take: false
        success-action: "tell: &a You have enough points"
        fail-action: "tell: &a You don't have enough points"

Switch Icon

Code Download

Format

button-name:
  type: switch
  child:
    button1:
      <button-settings>
    button2:
      <button-settings>
    button3:
      <button-settings>
    ...

Description

This is a button that changes everytime the user clicks

Example

switch-icon:
  type: switch
  child:
    frame_icon1:
      name: "&cFrame 1"
      id: red_wool
    frame_icon2:
      name: "&aFrame 2"
      id: green_wool
    frame_icon3:
      name: "&bFrame 3"
      id: light_blue_wool

TokenManager Bridge

Code Download

Warning

Depend: TokenManager

Variable

  • {tokens} gets the tokens the player having

Action

Format

  • give-token: <token>

Description

This action gives <token> to the player

Example

give-token:
  slot: 1
  id: emerald
  name: "&cGive tokens"
  command: "give-token: 10"

Requirement

Format

token: <value>
token:
  value: <value>
  take: <true/false>

Description

  • This requirement checks if the player has at least <value> tokens
  • You can set the take value (true or false) to allow/disallow the plugin to take the tokens of the player alter checking successfully

Example

check-tokens:
  slot: 1
  id: emerald
  name: "&cTake tokens"
  click-requirement:
    left:
      take-token: # Take 10 tokens
        token: 10
    right:
      check-token: # Check if the players has 10 tokens
        token:
          value: 10
          take: false
        success-action: "tell: &a You have enough tokens"
        fail-action: "tell: &a You don't have enough tokens"

Vault Bridge

Code Download

Warning

Depend: Vault

Variable

  • {money} gets the money the player having
  • {money_formatted} gets the money the player having (formatted)
  • {group} gets the group the player is currently in

Action

Format

  • give-money: <money>

Description

This action gives <money> to the player

Example

give-money:
  slot: 1
  id: emerald
  name: "&cGive money"
  command: "give-money: 10"

Requirement

Money

Format

money: <value>
money:
  value: <value>
  take: <true/false>

Description

  • This requirement checks if the money the player having is at least <value>
  • You can set the take value (true or false) to allow/disallow the plugin to take the money of the player alter checking successfully

Example

check-money:
  slot: 1
  id: emerald
  name: "&cTake money"
  click-requirement:
    left:
      take-money: # Take 10 money
        money: 10
    right:
      check-money: # Check if the players has 10 money
        money:
          value: 10
          take: false
        success-action: "tell: &a You have enough money"
        fail-action: "tell: &a You don't have enough money"

Group

Format

group: <name>

Decription

This requirement checks if the player is in the group <name>

Example

check-group:
  slot: 1
  id: stone
  name: "&cStone Group"
  click-requirement:
    default:
      stone-group: # Check if the player is in the "stone" group
        group: stone
        success-action: "tell: &aYou are welcome"
        fail-action: "tell: &cGet out of here"

World and Region

Code Download

Warning

Depend: WorldGuard (for Region & Flag)

Variable

  • {region} gets the name of the region the user standing on
  • {flag_<flag_name>} gets the status of the flag <flag_name> at the region the user standing on

Requirement

World

Format

world: <world_name>
world:
- <world_name>
- <world_name>

Description

This requirement checks if the player is at the world <world_name>

Region

Format

region: <region_name>
region:
- <region_name>
- <region_name>

Description

This requirement checks if the player is at the region <region_name>

Region Owner

Format

region-owner: <region_name>
region-owner:
- <region_name>
- <region_name>

Description

This requirement checks if the player is the owner of the region <region_name>

Region User

Format

region-user: <region_name>
region-user:
- <region_name>
- <region_name>

Description

This requirement checks if the player is the user of the region <region_name>

Flag

Format

flag:
  flag1: <value1>
  flag2: <value2>
  flag3: <value3>
  ...

Description

This requirement checks if the status of the flag at the region the player standing on matches the value

XCross

Code Download

Description

This addon integrates XSeries so that you can use version-independent values in some item modifiers & actions.

Item Modifier

Material Modifier

Format

xmaterial: <material>
xid: <material>
xmat: <material>

Description

  • This modifier will set the <material> of the item

Example

stone-button:
  slot: 1
  xid: stone
player-head:
  slot: 2
  xid: player_head

Enchantment Modifier

Format

xenchantment:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
xenchant:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
xenc:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...

Description

  • This modifier will add the <enchantment>s to the item
  • You can set the [level] of the <enchantment>. It’s optional.

Example

enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  XENCHANTMENT:
    - "durability, 1"
  POSITION-X: 1
  POSITION-Y: 1

Potion Effect Modifier

Format

xpotion:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
xeffect:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...

Description

  • This modifier will add the <potion> effect to the item.
  • You can set the [duration] and [amplifier] of the <potion> effect. These are optional.

Example

potion:
  position-x: 1
  position-y: 1
  name: "&bPotion"
  id: potion
  xpotion:
    - "SPEED"
    - "WEAKNESS, 30, 1"

Skull Modifier

Format

xskull: <skull>
xhead: <skull>

Description

  • This modifier will set the <skull> of the item
  • <skull> accepts a player name, an UUID (unique id), an Base64 value, or a texture.minecraft.net URL

Example

skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  xskull: "HSGamer"
  #xskull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"
  #xskull: "http://textures.minecraft.net/texture/ffcdae586b52403b92b1857ee4331bac636af08bab92ba5750a54a83331a6353"
  #xskull: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZmZjZGFlNTg2YjUyNDAzYjkyYjE4NTdlZTQzMzFiYWM2MzZhZjA4YmFiOTJiYTU3NTBhNTRhODMzMzFhNjM1MyJ9fX0="

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  xskull: "{player}"

Action

Play Sound

Format

  • xsound: <sound>, [volume], [pitch]
  • xsound: <sound> [volume] [pitch]

Description

  • This action will send the <sound> to the player
  • You can specify the [volume] and the [pitch] of the <sound>. Those are optional

Example

  • xsound: BLOCK_NOTE_BLOCK_PLING
  • xsound: BLOCK_NOTE_BLOCK_PLING 1 2