GUI Configuration

This guide explains creating and editing GUIs

GUI Options

These options define the GUI used and what settings are applied to it

{
  "title": "<dark_gray>Example GUI",
  "size": 3,
  "items": {}
}

Title (required)

The message displayed at the top of the GUI. Uses MiniMessage formatting!

"title": "<dark_gray>Example Title"

Size (required)

The number of rows the GUI should contain. Integer value between 1 and 6.

"size": 3

Items (required)

A MAP of items to display. Each entry needs its unique string identifier. See the Items section below.

"items": {}

Alias Commands

A list of commands that can be used to access this GUI. Each entry is a new command, which should only be one word and unused by another mod. A restart is required to register commands!

"alias_commands": [
  "example"
]

Open Actions

A list of Actions that are executed when the GUI is opened. Any Open Requirements must succeed before any actions are executed. Each action can have Requirements defined that must also succeed before each actions is executed. See Actions for more information.

"open_actions": {
  "action_1": {
    "type": "COMMAND_CONSOLE",
    "click": "ANY",
    "commands": ["give %player% diamond 1"]
  },
  "action_2": {
    "type": "MESSAGE",
    "click": "ANY",
    "message": ["<blue>Thanks for opening my menu!"]
  }
}

Close Actions

A list of Actions that are executed when the GUI is closed. Each action can have Requirements defined that must also succeed before each actions is executed. See Actions for more information.

"close_actions": {
  "action_1": {
    "type": "COMMAND_CONSOLE",
    "click": "ANY",
    "commands": ["give %player% diamond_sword 1"]
  },
  "action_2": {
    "type": "MESSAGE",
    "click": "ANY",
    "message": ["<red>Sad to see you go. Take this for the road!"]
  }
}

Open Requirements

Define requirements that must be met before a GUI can be opened. Optionally, Actions can be defined to execute when the requirements have failed or succeeded. See Requirements for more information on requirements.

"view_requirements": {
  "requirements": {
    "example_requirement_1": {
      "type": "PERMISSION",
      "permission": "test.permission"
    }
  },
  "deny_actions": {
    "deny_action_1": {
      "type": "MESSAGE",
      "message": ["<red>You do not have permission!"]
    }
  },
  "success_actions": {
    "success_action_1": {
      "type": "MESSAGE",
      "message": ["<green>You do have permission!"]
    }
  }
},

Items

Items define what the GUI contains and how they behave when interacting with them.

{
  "title": "<dark_gray>Example GUI",
  "size": 3,
  "items": {
    "item_1": {
      "item": "minecraft:diamond_sword",
      "slots": [0],
      "count": 1,
      "name": "<blue><b>Example Sword",
      "lore": ["<gray><italic>Example lore!"],
      "nbt": {
        "Enchantments": [
          {
            "lvl": 3,
            "id": "minecraft:unbreaking"
          }
        ],
        "HideFlags": 1
      },
      "priority": 1,
      "view_requirements": {
        "requirements": {
            "requirement_1": {
                "type": "PERMISSION",
                "permission": "test.permission"
            }
        },
        "success_actions": {},
        "deny_actions": {}
      },
      "click_requirements": {
        "requirements": {
            "requirement_1": {
                "type": "PERMISSION",
                "permission": "test.permission.2"
            }
        },
        "success_actions": {},
        "deny_actions": {}
      },
      "actions": {
        "action_1": {
          "type": "COMMAND_CONSOLE",
          "click": "ANY",
          "commands": ["give %player% diamond_sword 1"]
        },
        "action_2": {
          "type": "MESSAGE",
          "click": "ANY",
          "message": ["<blue>You have received the Example Sword!"]
        }
      }
    }
  }
}

Item (required)

An item identifier (combination of modid:itemid). This can be any item, vanilla or modded. Unknown item stacks will default to minecraft:air.

"item": "minecraft:stone"

Slots

A list of slots that this item will be inserted into. This value should be between 0 and the (size * 9) - 1. EX: if "size: 3", then between 0 and 26. Defaults to an empty list if not provided.

"slots": [0, 1, 7, 8]

Amount

The amount of this item that should be displayed in each slot. Defaults to 1 if not provided.

"amount": 10

Name

The name to override the item with. Defaults to the item's normal name if not provided. Uses MiniMessage formatting!

"name": "<red>Example Stone"

Lore

A list of lore to override the item with. Defaults to an empty list if not provided. Uses MiniMessage formatting!

"lore": [
  "<gray>Example Line 1",
  "<gray>Example Line 2"
]

NBT

An NBT Compound that is set onto the item. This follows the same formatting as applying NBT to an item via /give. No additional NBT is applied if not provided.

"nbt": {
  "Enchantments": [
    {
      "lvl": 3,
      "id": "minecraft:unbreaking"
    }
  ],
  "HideFlags": 1
}

Priority

The priority of this item to the defined slots compared to other items. The closer to 0, the higher the priority. Useful in combination with View Requirements to display different items using conditionals. Defaults to 0 if not provided.

"priority": 10

View Requirements

Define when an item is allowed to be displayed using conditionals. All listed requirements must be met in order for the item to be displayed. Useful in combination with Priority to display different items using conditionals. Optionally, Actions can be defined to execute when the requirements have failed or succeeded. See Requirements for more information on requirements.

"view_requirements": {
  "requirements": {
    "example_requirement_1": {
      "type": "PERMISSION",
      "permission": "test.permission"
    }
  },
  "deny_actions": {
    "deny_action_1": {
      "type": "MESSAGE",
      "message": ["<red>You do not have permission!"]
    }
  },
  "success_actions": {
    "success_action_1": {
      "type": "MESSAGE",
      "message": ["<green>You do have permission!"]
    }
  }
},

Click Actions

A list of Actions that are executed when the item is clicked on. The Click Type must be correct and any Click Requirements defined must succeed before the actions are executed. See Actions for more information.

"click_actions": {
  "action_1": {
    "type": "COMMAND_CONSOLE",
    "click": "ANY",
    "commands": ["give %player% diamond_sword 1"]
  },
  "action_2": {
    "type": "MESSAGE",
    "click": "ANY",
    "message": ["<blue>You have received the Example Sword!"]
  }
}

Click Requirements

Define when an item's actions are allowed to be executed when clicked on using conditionals. All listed requirements must be met in order for any actions to be ran or checked. Optionally, Actions can be defined to execute when the requirements have failed or succeeded. See Requirements for more information on requirements.

"click_requirements": {
  "requirements": {
    "example_requirement_1": {
      "type": "PERMISSION",
      "permission": "test.permission"
    }
  },
  "deny_actions": {
    "deny_action_1": {
      "type": "MESSAGE",
      "message": ["<red>You do not have permission!"]
    }
  },
  "success_actions": {
    "success_action_1": {
      "type": "MESSAGE",
      "message": ["<green>You do have permission!"]
    }
  }
},

Actions

Actions are a list of well, actions, that are executed either when an item is clicked on (and the Click Type is correct), a GUI is opened/closed, or a Requirement has failed/succeeded, depending on where they are defined. A list of requirements can be defined that will be checked before the action can be ran. Additionally, chance and delay values can be defined to add odds of successful execution or delaying the execution, respectively. Each entry in each actions section must have a unique string identifier. See Action Types for the types and additonal options.

"actions": {
  "action_1": {
    "type": "COMMAND_CONSOLE",
    "click": "ANY",
    "commands": ["give %player% diamond_sword 1"]
  },
  "action_2": {
    "type": "MESSAGE",
    "click": "ANY",
    "message": ["<blue>You have received the Example Sword!"]
  },
  "action_3": {
    "type": "COMMAND_CONSOLE",
    "click": "ANY",
    "commands": ["give %player% diamond 1"],
    "requirements": {
      "requirements": {
        "type": "PERMISSION",
        "permission": "test.permission"
      }
    }
  },
  "chance_action_1": {
    "type": "MESSAGE",
    "click": "ANY",
    "chance": 0.5,
    "message": ["<gold>This is a RARE message!"]
  },
  "delayed_action_1": {
    "type": "MESSAGE",
    "click": "ANY",
    "delay": 100,
    "message": ["<blue>You received the Example Sword 5 seconds ago!"]
  }
}

Type (required)

The type of action that this entry is. Must be in full capitalization. A list of types can be found in Action Types.

"type": "MESSAGE"

Click

The type of click that is required for this action to execute. Must be in full capitalization. A list of types can be found in Click Types. Defaults to ANY if not provided.

"click": "ANY"

Delay

The time in ticks (20 ticks a second) until the action should be executed. Defaults to 0 (no delay) if not provided.

"delay": 100

Chance

The chance that this action should be executed. Allowed values are between 0.0 and 1.0. An example of a 50% chance would be 0.5. Defaults to no chance check if not provided.

"chance": 0.5

Requirements

Define when an action is allowed to execute using conditionals. All listed requirements must be met in order for the action to be ran. The Click Type must be correct before the requirement will be checked. Optionally, Actions can be defined to execute when the requirements have failed or succeeded. See Requirements for more information on requirements.

"requirements": {
  "requirements": {
    "example_requirement_1": {
      "type": "PERMISSION",
      "permission": "test.permission"
    },
  },
  "deny_actions": {
    "deny_action_1": {
      "type": "MESSAGE",
      "message": ["<red>You do not have permission!"]
    }
  },
  "success_actions": {
    "success_action_1": {
      "type": "MESSAGE",
      "message": ["<green>You do have permission!"]
    }
  }
},

Additional Options

Additional options are available depending on the type of action used. See Action Types for each type's additional options.

Action Types

Identifier	Description	Options
MESSAGE	Send a message to the player	"message": [ "<message here>" ]
COMMAND_CONSOLE	Run a command as the console	"commands": [ "<command>" ]
COMMAND_PLAYER	Run a command as the player	"commands": [ "<command>" ]
BROADCAST	Broadcast a message to all players	"message": [ "<message here>" ]
PLAYSOUND	Play a sound to the player	"sound": "<sound identifier>", "volume": "<float 0.0-1.0>", "pitch": "<float 0.0-1.0>"
OPEN_GUI	Open a GUI for the player	"id": "<gui id>"
CLOSE_GUI	Close this GUI for the player	None
REFRESH_GUI	Refresh the player's current GUI	None
GIVE_XP	Give XP to the player	"amount": "<int>", "level": "<true/false>"
CURRENCY_DEPOSIT	Deposit currency from a player's account	"amount": "<amount>", "currency": "<currency_id>"
CURRENCY_WITHDRAW	Withdraw currency from a player's account	"amount": "<amount>", "currency": "<currency_id>"
CURRENCY_SET	Set the balance of a player's account	"amount": "<amount>", "currency": "<currency_id>"
GIVE_ITEM	Give the player an item	"item": "<item identifier>", "amount": "<amount>", "nbt": {}
TAKE_ITEM	Take an item from the player if possible. Strict will define if NBT needs to be exact	"item": "<item identifier>", "amount": "<amount>", "nbt": {}, "strict": false

Click Types

Identifier	Left Click	Shift Left Click	Right Click	Shift Right Click	Middle Click	Throw (Q)
ANY	☑	☑	☑	☑	☑	☑
LEFT_CLICK	☑	☐	☐	☐	☐	☐
SHIFT_LEFT_CLICK	☐	☑	☐	☐	☐	☐
ANY_LEFT_CLICK	☑	☑	☐	☐	☐	☐
RIGHT_CLICK	☐	☐	☑	☐	☐	☐
SHIFT_RIGHT_CLICK	☐	☐	☐	☑	☐	☐
ANY_RIGHT_CLICK	☐	☐	☑	☑	☐	☐
ANY_CLICK	☑	☑	☑	☑	☐	☐
ANY_MAIN_CLICK	☑	☐	☑	☐	☐	☐
ANY_SHIFT_CLICK	☐	☑	☐	☑	☐	☐
MIDDLE_CLICK	☐	☐	☐	☐	☑	☐
THROW	☐	☐	☐	☐	☐	☑

Requirements

Requirements are a list of checks that must succeed for a GUI to open, Item to display, or Action to activate, depending on where it's used. A MAP of requirements must be listed that are checked when activated. A list of deny and success actions can then be defined that will activate when any requirement has failed or all have succeeded, respectively. Each entry in the requirements section must have a unique string identifier. See Requirement Types for the types and additonal options.

"<type>_requirements": {
  "requirements": {
    "example_requirement_1": {
      "type": "PERMISSION",
      "permission": "test.permission"
    },
  },
  "deny_actions": {
    "deny_action_1": {
      "type": "MESSAGE",
      "message": ["<red>You do not have permission!"]
    }
  },
  "success_actions": {
    "success_action_1": {
      "type": "MESSAGE",
      "message": ["<green>You do have permission!"]
    }
  }
},

Requirements

Type (required)

The type of action that this entry is. Must be in full capitalization. A list of types can be found in Action Types.

"type": "MESSAGE"

Comparison

The type of comparison that this requirement should do. The usage changes depending on the requirement used. See Comparison Types for more information. Defaults to == (equals) if not provided.

"comparison": "=="

Additional Options

Additional options are available depending on the type of action used. See Action Types for each type's additional options.

Deny Actions

A MAP of actions that are performed when any requirement has failed. Each entry needs its unique string identifier. See Actions for more information.

"deny_actions": {
  "deny_action_1": {
    "type": "MESSAGE",
    "message": ["<red>You do not have permission!"]
  }
},

Success Actions

A MAP of actions that are performed when all requirements has succeeded. Each entry needs its unique string identifier. See Actions for more information.

"success_actions": {
  "success_action_1": {
    "type": "MESSAGE",
    "message": ["<green>You do have permission!"]
  }
},

Requirement Types

Identifier	Description	Options
PERMISSION	Check if the player has a permission	"permission": "<permission.node>"
ITEM	Check if the player has an item. Strict will define if NBT needs to be exact	"item": "<item identifier>", "amount": "<amount>", "nbt": {}, "strict": false
CURRENCY	Check if the player has an amount of currency	"amount": "<amount>", "currency": "<currency_id>"
PLACEHOLDER	An input string will be parsed and checked against an output string. Strict will define if capitalization needs to be exact	"input": "<string>", "output": "<string>", "strict": false
JAVASCRIPT	An expression string will be parsed and then evaluated by the GraalVM JavaScript engine. The expression should return a boolean value	"expression": "<string>"
DIMENSION	Check if the player is in a dimension	"id": "<mod:id>"
PLAN_PLAYTIME	Check the player's playtime. Requires the Plan mod.	"time": "<seconds>"

Comparison Types

Identifier	PERMISSION/DIMENSION	ITEM/CURRENCY	PLACEHOLDER	JAVASCRIPT
==	Returns equality check	Has exactly `"amount"`	Input matches Output	Expression returns true
!=	Returns opposite of equality check	Does not have exactly `"amount"`	Input does not match Output	Expression returns false
>		Has greater than `"amount"`
<		Has less than `"amount"`
>=		Has greater than or equal to `"amount"`
<=		Has less than or equal to `"amount"`

GUI Configuration

GUI Options

Title (required)

Size (required)

Items (required)

Alias Commands

Open Actions

Close Actions

Open Requirements

Items

Item (required)

Slots

Amount

Name

Lore

NBT

Priority

View Requirements

Click Actions

Click Requirements

Actions

Type (required)

Click

Delay

Chance

Requirements

Additional Options

Action Types

Click Types

Requirements

Requirements

Type (required)

Comparison

Additional Options

Deny Actions

Success Actions

Requirement Types

Comparison Types

Clone this wiki locally