Tutorial/Controls
Controls
All controls have these common keys
- row
- the row of the screen to place the control in
- if row_span is more than 1 this will be the starting row
- col
- the column of the screen to place the control in
- if col_span is more than 1 this will be the starting column
- row_span
- how many rows the control should cover
- default is 1
- col_span
- how many columns the control should cover
- default is 1
- x
- the exact starting x position of the control
- y
- the exact starting y position of the control
- width
- the exact width of the control
- height
- the exact height of the control
- type
- the type of the control to place
- possible values are link_button, text_box, gradient, text_label, combo_box, spacer, texture, check_box, radio_button, slider, button
- priority
- the order to place the controls in
- possible values are from 1 (drawn first) to 5 (drawn last)
- show_permission
- this is the permission the player must have to be able to see this control
- if the player lacks the permission the control won't be visible at all
- using this on a button won't hide any controls the button relies on (text_boxes, etc.)
- hide_permission
- players with this permission won't see the control at all
- using this on a button won't hide any controls the button relies on (text_boxes, etc.)
- show_funds
- set this to hide the control from any player who doesn't have sufficient funds in his account
- needs Vault and an economy plugin installed
- must be an integer
- using this on a button won't hide any controls the button relies on (text_boxes, etc.)
Automatic layout
By specifying row and col (and optionally row_span and col_span) the control will have its x, y, width, and height calculated automatically based on the num_columns key in the screen.
Manual layout
By specifying x, y, width, and height, the control will be placed in that exact position.
Note that each screen can have a mixture of both automatically and manually laid out controls.
As well as the above keys, each control has a few keys of its own.
link_button
Used to jump to another screen (next page, page 7, accept page, etc.) If the screen linked to requires a permission to be seen, the link_button won't do anything if clicked by players without that permission.
- text_color
- the colour this button's text will be
- value must be in the format r,g,b, or r,g,b,a
- default is 255,255,255,255 (white)
- hover_color
- the colour this button's text will be when the mouse is over the button
- value must be in the format r,g,b, or r,g,b,a
- default is 150,120,50 (yellowish)
- text
- the text that will appear on the button
- info
- the tooltip that will appear when the mouse is hovered over the button
- use && to make a line break in the tooltip
- link_to
- the id of the screen to jump to
text_box
The text_box is a control for typing in values.
- text
- the text that will appear in the text_box when it's empty
- will not be used in commands
- inner_color
- the colour of the text-entry area
- value must be in the format r,g,b, or r,g,b,a
- default is 0,0,0,255 (black)
- outer_color
- the colour of the text_box's border
- value must be in the format r,g,b, or r,g,b,a
- default is 159,159,159,255 (grey)
- info
- the tooltip that will appear when the mouse is hovered over the text_box
- use && to make a line break in the tooltip
- name
- the name to reference the text_box's value from a button
- see Using the command key below
- password_box
- set to yes to replace all text input with asterisks (*)
- skin_texture
- set this to the name key of a texture to automatically show the skin of any player typed in the box
gradient
The gradient draws a coloured rectangle, and can have a colour at the top, transforming into a different colour at the bottom.
- top_color
- the colour at the top of the gradient
- value must be in the format r,g,b, or r,g,b,a
- default is 255,255,255,255 (white)
- bottom_color
- the colour at the bottom of the gradient
- value must be in the format r,g,b, or r,g,b,a
- default is 255,255,255,255 (white)
text_label
The text_label is a simple line of text.
- text_color
- the colour of the text
- value must be in the format r,g,b, or r,g,b,a
- default is 255,255,255,255 (white)
- text
- the text to appear on the label
- align
- the horizontal alignment of the label
- possible values are left, center, and right
- default is center
combo_box
- text
- the default text that appears when nothing is selected
- info
- the tooltip that will appear when the mouse is hovered over the combo_box
- use && to make a line break in the tooltip
- name
- the name to reference the combo_box's value from a button
- see Using the command key below
- items
- the items that will appear in the drop down list when the combo_box is clicked
- each item has two child nodes - text and selected_value
- text is what should appear in the list
- selected_value is what should be sent to the command. If it's missing, the value from text will be sent instead
- mode
- this allows the combo_box to set itself up as a list of online or offline players
- possible values are normal, online_players, offline_players, banned_players, and all_items
- default is normal
- if set to online_players or offline_players or banned_players, the last item will select no player, and return an empty string
- skin_texture
- set this to the name key of a texture to automatically show the skin of any player selected
spacer
The spacer creates a thin line which can be used to visually separate rows
- color
- the colour of the spacer
- value must be in the format r,g,b, or r,g,b,a
- default is 255,255,255,255 (white)
texture
The texture control is used to put an image onto a screen.
- url
- the address of the image
- must be a public link
- must be surrounded with quotes
- must have a .png or .jpg extension
- it's possible to place a gradient over the texture to add a level of transparency
- mode
- set this to skin to have the texture be a 2D representation of the current player
- when using this do not use the url key
- example - mode: skin
- name
- the name is used to use this texture to display the selected player's skin from a combo_box, slider, or text_box
check_box
- text
- the text to appear to the right of the check_box
- info
- the tooltip that will appear when the mouse is hovered over the check_box
- use && to make a line break in the tooltip
- checked
- whether the check_box starts off checked
- default is no
- checked_value
- the value that will be returned if the check_box is checked
- must be a string, so surround it with quotes if it's a number
- default is true
- unchecked_value
- the value that will be returned if the check_box is unchecked
- must be a string, so surround it with quotes if it's a number
- default is false
- name
- the name to reference the check_box's value from a button
- see Using the command key below
radio_button
Radio_buttons can be placed anywhere on the screen. Set the group key to the same value to ensure only one radio_button from every group can be selected at any one time.
- text
- the text to appear to the right of the radio_button
- info
- the tooltip that will appear when the mouse is hovered over the radio_button
- use && to make a line break in the tooltip
- selected
- whether the radio_button starts off selected
- default is no
- selected_value
- the value that will be returned if the radio_button is selected
- must be a string, so surround it with quotes if it's a number
- group
- the name to reference the radio_button's value from a button
- default is 0
- see Using the command key below
slider
The slider is used to allow quick selecting of a value.
- text
- the description that will appear on the slider
- info
- the tooltip that will appear when the mouse is hovered over the slider
- use && to make a line break in the tooltip
- max
- the value represented by the right end of the slider
- default is 100
- default
- the starting position of the slider
- default is 50
- if the default value is higher than the max value, default will be set to max
- align
- the horizontal alignment of the text on the slider
- possible values are left, center, and right
- default is center
- text_color
- the colour of the text on the slider
- value must be in the format r,g,b, or r,g,b,a
- default is 255,255,255,255 (white)
- name
- the name to reference the slider's value from a button
- see Using the command key below
- mode
- this allows the slider to set itself up as a list of online or offline players
- possible values are normal, online_players, offline_players, banned_players, and all_items
- default is normal
- if set to online_players or offline_players or banned_players, moving the slider to the far right will select no player, and return an empty string
- skin_texture
- set this to the name key of a texture to automatically show the skin of any player selected
button
The button is the only control that can activate a command.
- text_color
- the colour this button's text will be
- value must be in the format r,g,b, or r,g,b,a
- default is 255,255,255,255 (white)
- hover_color
- the colour this button's text will be when the mouse is over the button
- value must be in the format r,g,b, or r,g,b,a
- default is 150,120,50 (yellowish)
- text
- the text that will appear on the button
- info
- the tooltip that will appear when the mouse is hovered over the button
- use && to make a line break in the tooltip
- stay_open
- usually, the GUI will close after a command has executed. Set this to yes to keep the GUI open
- command
- the command that will be run when the button is clicked
- for a command, add / to the beginning
- for a chat message, don't add /
- separate each command with a semi-colon (;)
- temp_permissions
- a list of permissions that will be temporarily give to the player in order to use the command
- the permissions will be removed one second after the button is clicked
- cost
- set this to deduct the amount from the account of anyone using the button
- needs Vault and an economy plugin installed
- Must be an integer
- can be a negative number which will give money to the player instead of deducting it
- the cost will be deducted once even if the button contains more than one command
- the cost will be deducted even if the command fails (due to permissions, misuse, etc.)
- confirm_command
- if set to yes, an additional button must be clicked before the command or chat message is sent
- hide_command
- if set to yes, the tooltip with the command connected to the button will not show
Using the command key
In the command value, use ^name^ to insert the value of any other control on the screen. For most controls, ^name^ must match their name key, but for radio_buttons, it must match their group key,
There are a few global constants you can use as well
- gc_player_name
- the current player's name
- gc_server_name
- the name of the server
- gc_world_name
- the name of the current player's world
- gc_online_player_count
- the number of currently online players in all the worlds on the server
- gc_offline_player_count
- the total number of players who have joined this server
- gc_world_player_count
- the number of players in the current player's world
- gc_player_money
- the player's balance (requires Vault and an economy plugin)
For example
command: /give ^givep^ ^item_id^ ^item_data^ ^amount^
where givep is the name of a control that returns the player (either slider or text_box), item_id is the name of a control that returns the item's id, etc.