GUIs

effectwith title <text>

Window title; & colour codes work

open gui with title "&8Warps" with 3 rows for player:
    set {_slot} to 0
    for each {_name} in keys of {warp}:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%" lore "&7Click to go":
            teleport player to {warp.%{_name}%}
            close gui
    if player has permission "warps.admin":
        slot 27 is "anvil" named "&eManage warps"

Try it

effectwith <n> rows

Optional, 1 to 6; the default is 3

open gui with title "&8Warps" with 3 rows for player:
    set {_slot} to 0
    for each {_name} in keys of {warp}:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%" lore "&7Click to go":
            teleport player to {warp.%{_name}%}
            close gui
    if player has permission "warps.admin":
        slot 27 is "anvil" named "&eManage warps"

Try it

structurefor player

Who sees it. Use a name instead to show it to someone else: for %arg.1%

open gui with title "&8Warps" with 3 rows for player:
    set {_slot} to 0
    for each {_name} in keys of {warp}:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%" lore "&7Click to go":
            teleport player to {warp.%{_name}%}
            close gui
    if player has permission "warps.admin":
        slot 27 is "anvil" named "&eManage warps"

Try it

conditionslot <n> is "<item>"

Slots are numbered from 1, left to right, top to bottom (row 2 starts at 10)

open gui with title "&8Warps" with 3 rows for player:
    set {_slot} to 0
    for each {_name} in keys of {warp}:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%" lore "&7Click to go":
            teleport player to {warp.%{_name}%}
            close gui
    if player has permission "warps.admin":
        slot 27 is "anvil" named "&eManage warps"

Try it

expressionowned by <name>since 1.7.3

In a menu, for a "player_head": whose face it shows. Comes before named

open gui with title "&8Online" with 1 rows for player:
    slot 1 is "player_head" owned by player.name named "&f%player.name%"

Try it

expressionnamed <text>

Optional item name

open gui with title "&8Warps" with 3 rows for player:
    set {_slot} to 0
    for each {_name} in keys of {warp}:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%" lore "&7Click to go":
            teleport player to {warp.%{_name}%}
            close gui
    if player has permission "warps.admin":
        slot 27 is "anvil" named "&eManage warps"

Try it

expressionlore <text>

Optional description lines, separated by |

open gui with title "&8Warps" with 3 rows for player:
    set {_slot} to 0
    for each {_name} in keys of {warp}:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%" lore "&7Click to go":
            teleport player to {warp.%{_name}%}
            close gui
    if player has permission "warps.admin":
        slot 27 is "anvil" named "&eManage warps"

Try it

effectclose gui

Closes the window for the player

close gui

Try it

expressionslots <a> to <b> are <item>since 1.7.64

The same button in several slots at once: slots 1 to 9 are "black_stained_glass_pane", slots 11, 13, 15 are "barrier" named "&cLocked". With a block under it, clicking any of them runs it

command /frame:
    trigger:
        open gui with title "&8Kits" with 3 rows for player:
            slots 1 to 9 are "black_stained_glass_pane" named " "
            slots 11, 13, 15 are "iron_sword" named "&fStarter":
                send "&aYou picked a kit."

Try it

structureslot <n> takes items:since 1.7.63

A slot a player can put an item into, from their cursor or by shift-clicking it in their own inventory. The block under it runs then, with the item as {_item}; the item is taken, so give it back if they should keep it. shown as <item>, named <text> and lore <text> say what the empty slot looks like

command /sell:
    trigger:
        open gui with title "&8Sell diamonds" with 3 rows for player:
            fill empty slots with "gray_stained_glass_pane"
            slot 14 takes items shown as "hopper" named "&ePut diamonds here":
                if type of {_item} is "diamond":
                    add amount of {_item} * 10 to {%player%.coins}
                    send "&aSold for %amount of {_item} * 10% coins."
                else:
                    give {_item} to player
                    send "&cOnly diamonds are bought here."

Try it

effectfill empty slots with <item>since 1.7.61

In the block: every slot no slot line took shows that item, with no name and nothing to click. It may stand anywhere in the block

command /menu:
    trigger:
        open gui with title "&8Menu" with 3 rows for player:
            fill empty slots with "gray_stained_glass_pane"
            slot 14 is "diamond" named "&bShop":
                send "&7The shop is not open yet."

Try it

expressionborder with <item>since 1.7.61

The same for the slots along the edge only

command /framed:
    trigger:
        open gui with title "&8Kits" with 3 rows for player:
            border with "black_stained_glass_pane"
            slot 14 is "iron_sword" named "&fStarter"

Try it

eventon close:since 1.7.61

In the block: the lines under it run when the window closes, as the player it was open for, with the local variables as they were. Opening another window closes this one too

command /bank:
    trigger:
        open gui with title "&6Bank" for player:
            slot 5 is "gold_ingot" named "&eYour coins: %{%player%.coins}%"
            on close:
                send "&7Come again."

Try it

effectrefresh every <duration>since 1.7.61

In the block: while the window is open it draws itself again that often, on the page it is on, so that a time or a balance in it stays right

command /clock:
    trigger:
        open gui with title "&8Clock" for player:
            refresh every 1 second
            slot 5 is "clock" named "&f%server.time%"

Try it

expressiongui pagesince 1.5.8

The page being shown

open gui with title "&8Menu" with 1 rows for player:
    slot 5 is "paper" named "&fPage %gui page%"

Try it

expressionpage <n> of <list> with <k> per pagesince 1.5.8

The part of a list that page n shows

set {_shown} to page 2 of {names} with 9 per page

Try it

expressionpages of <list> with <k> per pagesince 1.5.8

How many pages the list needs; at least 1

set {_count} to pages of {names} with 9 per page

Try it

effectnext page / previous pagesince 1.5.8

In a click block: show the page after or before

open gui with title "&8Menu" with 1 rows for player:
    slot 1 is "arrow" named "&ePrevious":
        previous page
    slot 9 is "arrow" named "&eNext":
        next page

Try it

effectset gui page to <n>since 1.5.8

In a click block: jump to a page

open gui with title "&8Menu" with 1 rows for player:
    slot 5 is "compass" named "&eBack to the first page":
        set gui page to 1

Try it

effectrefresh guisince 1.5.8

In a click block: draw the gui again on the same page, after the click changed what it shows

open gui with title "&8Clicker" with 1 rows for player:
    slot 5 is "gold_ingot" named "&6Clicks: %{%player%.clicks}%":
        add 1 to {%player%.clicks}
        refresh gui

Try it

Guide and examples

open gui builds a chest menu and shows it to a player. Each slot line places an item; a slot line that ends with : gets a block that runs when the slot is clicked.

open gui with title "&8Coin Shop" with 3 rows for player:
    slot 12 is "diamond" named "&bDiamond" lore "&7Price: &e50 coins|&7Click to buy":
        if {%player%.coins} < 50:
            send "&cYou need 50 coins for that."
        else:
            subtract 50 from {%player%.coins}
            execute console command "give %player.name% diamond 1"
        close gui
    slot 14 is "gold_ingot" named "&6Balance: &e%{%player%.coins}% coins"
    slot 16 is "barrier" named "&cClose":
        close gui

Part	Meaning
`with title <text>`	Window title; `&` colour codes work
`with <n> rows`	Optional, 1 to 6; the default is 3
`for player`	Who sees it. Use a name instead to show it to someone else: `for %arg.1%`
`slot <n> is "<item>"`	Slots are numbered from 1, left to right, top to bottom (row 2 starts at 10)
`owned by <name>`	In a menu, for a `"player_head"`: whose face it shows. Comes before `named`
`named <text>`	Optional item name
`lore <text>`	Optional description lines, separated by `\|`
`close gui`	Closes the window for the player
`slots <a> to <b> are <item>`	The same button in several slots at once: `slots 1 to 9 are "black_stained_glass_pane"`, `slots 11, 13, 15 are "barrier" named "&cLocked"`. With a block under it, clicking any of them runs it
`slot <n> takes items:`	A slot a player can put an item into, from their cursor or by shift-clicking it in their own inventory. The block under it runs then, with the item as `{_item}`; the item is taken, so give it back if they should keep it. `shown as <item>`, `named <text>` and `lore <text>` say what the empty slot looks like
`fill empty slots with <item>`	In the block: every slot no `slot` line took shows that item, with no name and nothing to click. It may stand anywhere in the block
`border with <item>`	The same for the slots along the edge only
`on close:`	In the block: the lines under it run when the window closes, as the player it was open for, with the local variables as they were. Opening another window closes this one too
`refresh every <duration>`	In the block: while the window is open it draws itself again that often, on the page it is on, so that a time or a balance in it stays right

Item names are Minecraft material names in quotes, such as "diamond" or "oak_planks". An unknown name shows a barrier and logs a warning.
Items in a GUI are buttons. They cannot be taken, moved or shift-clicked out.
Titles, names and lore are filled in when the GUI opens. To refresh what a GUI shows, open it again.
The block under open gui is ordinary code in which every slot line adds a slot, so slots can come out of a loop or sit behind an if:

open gui with title "&8Warps" with 3 rows for player:
    set {_slot} to 0
    for each {_name} in keys of {warp}:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%" lore "&7Click to go":
            teleport player to {warp.%{_name}%}
            close gui
    if player has permission "warps.admin":
        slot 27 is "anvil" named "&eManage warps"

Pages. A gui knows which page it is showing. gui page is that number, starting at 1, and a click can turn it. The gui is drawn again in the same window, without closing:

open gui with title "&8Warps" with 5 rows for player:
    set {_names} to keys of {warp}
    set {_slot} to 0
    for each {_name} in page (gui page) of {_names} with 36 per page:
        add 1 to {_slot}
        slot {_slot} is "ender_pearl" named "&b%{_name}%":
            teleport player to {warp.%{_name}%}
            close gui
    if gui page > 1:
        slot 37 is "arrow" named "&ePrevious":
            previous page
    if gui page < pages of {_names} with 36 per page:
        slot 45 is "arrow" named "&eNext":
            next page

Syntax	Meaning
`gui page`	The page being shown
`page <n> of <list> with <k> per page`	The part of a list that page `n` shows
`pages of <list> with <k> per page`	How many pages the list needs; at least 1
`next page` / `previous page`	In a click block: show the page after or before
`set gui page to <n>`	In a click block: jump to a page
`refresh gui`	In a click block: draw the gui again on the same page, after the click changed what it shows

Turning a page or refreshing runs the whole open gui block again, with the local variables as they were when the gui was first opened, so the list is looked up afresh each time.
A slot may be given a whole item instead of a name in quotes, which is how a button gets a glow: slot 5 is 1 nether star glowing named "&dRewards".
A click block runs as the player who clicked. It sees the local variables as they were when its slot line ran, so each slot made in a loop remembers its own round; saved variables such as {%player%.coins} are always current.