Legacy Documentation (1.3.2 and older)
Creating a new GUI with skript-gui is simple.
The pattern to create a new GUI:
create [a] [new] gui [[with id] %-string%] with %inventory% [(and|with) ([re]move[e]able|stealable) items] [(and|with) shape %-strings%]When creating a GUI, you need to provide an inventory. This is where using the Virtual Inventory expression is useful.
Virtual Inventory Patterns:
virtual %inventorytype% [with size %number%] [(named|with (name|title)) %string%]
virtual %inventorytype% [with %number% row[s]] [(named|with (name|title)) %string%]
virtual %inventorytype% [(named|with (name|title)) %string%] with size %number%
virtual %inventorytype% [(named|with (name|title)) %string%] with %number% row[s]TIP! Not sure what an inventory type looks like? View it here: https://skriptlang.github.io/Skript/classes.html#inventorytype
Now we can put together a basic GUI.
command /opengui:
trigger:
create a gui with virtual chest inventoryHowever, there are many more customization options for the GUI and Virtual Inventory Expression.
Name - The title displayed in the top-left of the inventory
Example - virtual chest inventory named "My EPIC GUI!"
Size - The number of rows in a GUI
Example - virtual chest inventory with 3 rowsThe two above options can be combined in several ways. One way is:
virtual chest with 3 rows named "My EPIC GUI!"All the ways to write it are shown in the patterns listed above.
Stealable Items - With this, you can specific whether items from this GUI can be taken by players.
Example - create a gui with virtual chest inventory and stealable items
Note: By default, items can't be taken from a GUI.
Shape - Shape allows you to customize the layout of a GUI
Example - create a gui with virtual chest inventory and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx"
This would create a GUI that has an 'x' border.
When setting the slots of a GUI, you could set the slot 'x' of the GUI, and all of those slots would be set,
creating a border around the GUI.Now, we can create more advanced GUIs. Look at the following, for example:
create a gui with virtual chest inventory with 3 rows named "My EPIC GUI!" and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx"Here's how that would look in-game (with the 'x' part of the shape set):
A GUI can be opened like any other inventory through Skript.
Script Example: create a gui with virtual chest open the last gui to player
### Accessing a Created GUI
To use the GUI you just created, you can use the Last GUI Expression. Pattern:
```yaml
[the] (last[ly] [(created|edited)]|(created|edited)) gui
That sums up creating and opening a GUI! Be sure to check out the next pages on how to edit and add items to your GUI.
There are two ways you can add items to a GUI. They are commonly referred to as "GUI Make Sections".
(make|format) [the] next gui [slot] (with|to) [[re]mov[e]able|stealable] %itemtype%
(make|format) gui [slot[s]] %strings/numbers% (with|to) [[re]mov[e]able|stealable] %itemtype%Just as you can make all of the items in a GUI stealable by the player, you can make specific slots stealable too. Include the removable or stealable word from the pattern above and the player will be able to take it.
TIP! Not sure what an ItemType looks like? Find out here: https://docs.skriptlang.org/classes.html#itemtype
All code modifying a GUI has to go within the GUI creation section or a GUI editing section. You can learn about how to edit a GUI that has been already created here: https://github.com/APickledWalrus/skript-gui/wiki/5.-Using-Global-GUIs
We'll continue from our GUI shown in the last page:
command /opengui:
trigger:
create a gui with virtual chest inventory with 3 rows named "My EPIC GUI!" and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx"
open the last gui for the playerNow, to add items, all you have to do is put one of the patterns from above within the GUI creation section.
command /opengui:
trigger:
create a gui with virtual chest inventory with 3 rows named "My EPIC GUI!" and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx":
make gui slot "x" with dirt named "! BORDER !"
open the last gui for the playerThe above code would fill the "x" slot (from the GUI's shape) in the GUI with dirt that's named named "! BORDER !"
The GUI's contents can also be buttons so that code will run when you click on the item. Turning slots into buttons is easy. All you have to do is put the code that you want to run within the slot creation section. Here's an example:
command /opengui:
trigger:
create a gui with virtual chest inventory with 3 rows named "My EPIC GUI!" and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx":
make gui slot "x" with dirt named "! BORDER !":
send "Hey %player%! You just clicked a border slot!" to player
open the last gui for the playerHere's what the GUI looks like now and what happens when you click on one of the dirt border blocks:
TIP! GUIs have a bunch of values that you can use when a slot is clicked! Check out https://github.com/APickledWalrus/skript-gui/wiki/4.-GUI-Values for more information.
You can also unformat/remove a GUI slot. The patterns to do that are:
(un(make|format)|remove) [the] next gui [slot]
(un(make|format)|remove) gui [slot[s]] %strings/numbers%
(un(make|format)|remove) all [[of] the] gui [slots]NOTE: If you ever want to change a GUI slot, you don't have to remove it first! The previous slot will be automatically removed.
Let's say we wanted to remove the border if it was clicked on. This is where we could use the unformat effect.
command /opengui:
trigger:
create a gui with virtual chest inventory with 3 rows named "My EPIC GUI!" and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx":
make gui slot "x" with dirt named "! BORDER !":
send "Say goodbye to your GUI border %player%!" to player
remove gui slot "x"
open the last gui for the playerNow, if you click the one of the border dirt blocks, it will remove all of them and send a message.
Here's what it looks:
There are two other options to remove a GUI slot too.
(un(make|format)|remove) [the] next gui [slot]
This effect removes the slot before the next available slot.
For example, if you had a GUI with 27 slots total and 26 of them were set,
this effect would remove the 26th slot, and the last two slots would now be empty.
(un(make|format)|remove) all [[of] the] gui [slots]
This effect removes every slot that is set.TIP! Did you know you can check if a player has a GUI open? See https://github.com/APickledWalrus/skript-gui/wiki/6.-Other-Syntax-and-Information#gui-condition for more information.
That is all there currently is to modifying the contents of a GUI. Check out the other pages to learn about using Global GUIs, GUI Values, and a tutorial on how to edit a GUI that has already been created.
There is also a GUI event that is fired when the GUI is opened or closed. You can listen to it within the GUI creation section. Patterns:
run (when|while) (open[ing]|clos(e|ing)) [[the] gui]
run (when|while) [the] gui (opens|closes)
run on gui (open[ing]|clos(e|ing))If you wanted to send the player a message when they opened and closed the GUI, you could do:
command /opengui:
trigger:
create a gui with virtual chest inventory with 3 rows named "My EPIC GUI!" and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx":
run on gui open:
send "Welcome to this GUI %player%!" to player
run on gui close:
send "Thanks for visiting this GUI %player%!" to player
open the last gui for the playerA GUI Close Event may also be cancelled. Pattern:
(cancel|uncancel) [the] gui clos(e|ing)Using this in your GUIs is as simple as putting the effect within the section.
command /opengui:
trigger:
create a gui with virtual chest inventory with 3 rows named "Your New Home":
run on gui close:
cancel gui close
send "You will never escape this GUI %player%!" to player
open the last gui for the playerThere are many values available to use when a player clicks on a slot in a GUI. Below, I'll go through each one and what it does.
Values that are usable in the "run on gui close" section are marked.
[the] gui slot
This returns the number of the slot that was clicked.
There may be two slots with the same slot number, since the player can also see their inventory.
[the] gui raw slot
This is the "raw" number of the slot that was clicked.
Unlike the gui-slot expression, this number is unique to the slot.
[the] gui hotbar slot
If the player uses a number key (1-9) to try and move the clicked item to their hotbar,
this value will return the hotbar slot, where 0 is the first slot.
If the player didn't use a number key to click the item, then this expression will return -1.
[the] gui inventory
This expression returns the inventory of the clicked item (the GUI's inventory).
This expression is usable in the "run on gui close" section.
[the] gui inventory action
This expression returns what the player tried to do when they clicked.
See https://docs.skriptlang.org/classes.html#inventoryaction for a list of actions.
[the] gui click (type|action)
This expression returns the type of click.
See https://skriptlang.github.io/Skript/classes.html#clicktype for a list of click types.
[the] gui cursor [item]
The item in the player's cursor.
[the] gui [clicked|current] item
The item that was clicked.
[the] gui slot type
The type of slot that was clicked.
See https://github.com/APickledWalrus/skript-gui/wiki/6.-Other-Information#slot-types for a list of slot types.
[the] gui player
The player that clicked the slot.
This expression is usable in the "run on gui close" section.
[the] gui (viewer|player)s
A list of the players that are currently viewing the GUI.
This expression is usable in the "run on gui close" section.
[the] gui slot id
The part of the GUI's shape that this slot is under.
In our "Border GUI" example, this would return "x" if the slot in question was a border slot.
If this slot doesn't have a shape, " " will be returned
[the] gui
The GUI of the slot.
This expression is usable in the "run on gui close" section.
If you wanted to edit a Global GUI, or even the last created GUI, you should use the GUI Editing section. The pattern for the GUI Editing section is:
(change|edit) [gui] %guiinventory%TIP! Not sure what a guiinventory is? See https://github.com/APickledWalrus/skript-gui/wiki/6.-Other-Information#guiinventory to learn about what it means and why it's called that.
To use this section in a command, you could write:
command /editgui:
trigger:
edit gui with id "myGlobalGUI": # NOTE: You can edit the "last gui" tooYou can modify the contents of the GUI or its "on close" section.
command /editgui:
trigger:
edit gui with id "myGlobalGUI":
make gui slot "-" with barrier named "THE GUI HAS BEEN EDITED!"
run on gui close:
send "THIS IS THE NEW ON CLOSE MESSAGE!" to playerAlong with modifying the contents in an editing section, you can modify the GUI's properties too. You can modify the name, size, shape, and whether items are stealable. Patterns and details:
[the] [skript-gui] name[s] of %guis%
%guis%'[s] [skript-gui] name[s]
Set, reset, or get the name of the GUI.
[the] (size[s]|rows) of %guis%
%guis%'[s] (size[s]|rows)
Set, reset (if possible), or get the total number of rows the GUI has.
[the] shape[s] of %guis%
%guis%'[s] shape[s]
Set, reset, or get the GUI's shape.
The returned shape will be a singular string.
[the] lock status[es] of %guis%
%guis%'[s] lock status[es]
Set, reset, or get the GUI's lock status.
This is whether the GUI's contents can be taken by players.Here's how you could use these in a script:
command /editgui:
trigger:
edit gui with id "myGlobalGUI":
set the skript-gui name of the edited gui to "My RENAMED GUI!"
set the size of the edited gui to 1
reset the edited gui's shape # Sets the shape to the default value. Specifying "items" or "actions" has no effect here.
set the edited gui's lock status to false # Items can now be taken from the GUI!That sums up most of the features of skript-gui. If you have any suggestions, questions, or run into any issues, please let me know!
Global GUIs are GUIs that can be used anywhere. They have a String ID and are usually created in the Script Load event.
To create a Global GUI, you have to specify an ID in the GUI creation section.
create a gui with id "myGlobalGUI" with virtual chest inventoryAll GUI customization remains the same.
To open a Global GUI, you can use the following expression:
[the] gui [with id] %string%
# The GUI from above would be: the gui with id "myGlobalGUI"To open the GUI using the Open GUI Effect you could write:
open gui with id "myGlobalGUI" to playerTIP! The Open GUI Effect's pattern is: (open|show) [[skript[-]]gui] %guiinventory% (to|for) %players%
Here's a complete example on how to create and open a Global GUI:
on script load:
create a gui with id "myGlobalGUI" with virtual chest inventory with 3 rows named "My EPIC GUI!" and shape "xxxxxxxxx", "x-------x", and "xxxxxxxxx":
make gui slot "x" with dirt named "! BORDER !":
send "Hey %player%! You just clicked a border slot!" to player
command /opengui:
trigger:
open gui with id "myGlobalGUI" to playerTo remove a global without restarting the server, you can use the deletion changer on the Global GUI expression. Here's what that looks like:
command /deleteglobalgui:
trigger:
delete gui with id "myGlobalGUI"This expression returns a list of the identifiers of all registered global GUIs. Syntax:
[all [[of] the]|the] (global|registered) gui id(s|entifiers)Here's what this expression looks like in use:
command /guis:
trigger:
loop registered gui identifiers:
send loop-stringThis expression returns the ID of a GUI if it has one. Syntax:
[the] id[entifier] of %guiinventorys%
%guiinventorys%'[s] id[entifier]Here's what this expression looks like in use:
make gui slot 0 with barrier named "Get GUI ID":
send "ID of GUI: %id of the gui%" to playerThis condition is whether the specified players have or don't have a GUI open. Syntax:
%players% (has|have) a gui [open]
%players% (doesn't|does not|do not|don't) have a gui [open]This expression returns the character representing a GUI's next open slot. Syntax:
%guiinventorys%'[s] next gui slot[s]
[the] next gui slot[s] of %guiinventorys%
[the] next gui slotPlease note that the third pattern is only usable in GUI scopes (create, edit, make, open, close, etc.)
If you see this in patterns, it simply means the syntax wants a GUI.
Technical Note: The only reason it's called a "guiinventory" is because Skript does not like the name "gui"
armor - An armor slot in the player's inventory
container - A regular slot in the player's inventory (anything not covered by the other types)
crafting - A slot in the crafting input area
fuel - The fuel slot in a furnace inventory, or the ingredient slot in a brewing stand inventory
outside - A pseudo-slot representing the area outside the inventory window
quickbar - A slot in the hotbar
result - A result (or output) slot in a furnace or crafting inventory