UltimateUI guide
How to use Functions
Functions#
A function is a named list of actions that you write once on a page and call from any number of elements. Calling a function pastes its actions into the place where you called it, so everything after the call runs once the function has finished.
Functions are defined in the functions: section of a page file located in plugins/UltimateUI/contents/pages. This section sits at the top level of the file, next to blocks:, variables: and keybinds:.
name: shop
command: shop
functions:
buy:
params:
item: DIAMOND
price: 100
actions:
- type: console
value: 'give %player% {item} 1'
- type: variable
variable: coins
operation: subtract
value: '{price}'
- type: message
value: '<green>Bought {item} for {price}'
blocks:
- type: block
id: buy_button
actions:
- type: function
function: buyCalling a function#
To execute function, You can use the function action type.
actions:
- type: function
function: buyThe name is read from function:, then name:, and finally from the action value. If no function with that name exists, the console prints a warning listing the functions the page actually defines, and the remaining actions keep running.
Parameters#
params: holds the default values of a function. arguments: (or the shorter args:) overrides them when you call it:
functions:
buy:
params:
item: DIAMOND
price: 100
actions:
- type: message
value: 'Bought {item} for {price}'
blocks:
- type: block
id: buy_netherite
actions:
- type: function
function: buy
arguments:
item: NETHERITE_INGOT
price: 500params: can also be written as a plain list when you only want to name the parameters. Every one of them then defaults to an empty value:
params:
- item
- priceA parameter is written as {name} and is replaced everywhere in the function body, every value, and inside nested sections such as the then: and else: branches of a condition. Defaults and arguments both support placeholders, so price: '%vault_eco_balance%' works.
What you can put inside#
A function accepts every action type, including a call to another function:
| Type | What it does |
|---|---|
command | Runs a command as the player |
console | Runs a command from the console |
message | Sends a message to the player |
sound | Plays a sound, for example BLOCK_NOTE_BLOCK_PLING 1 1 |
teleport | Teleports the player, for example world: nether x: 10 y: 64 z: 20 |
delay | Waits before the next action, for example 20t or 1s |
give | Gives an item |
redirect | Opens another page and ends the chain |
close | Closes the UI |
toggle | Hides and shows elements through hide: and show: |
visibility | Sets the visibility of the elements you list |
variable | Changes a variable |
condition | Runs then: or else: depending on an expression |
permission | Runs then: or else: depending on a permission |
function | Calls another function |
Variables#
Variables store values that your UI can read and change while it is open a coin balance, a selected page, a counter. They are declared in the variables: section of a page file, at the same level as blocks: and functions:.
name: shop
command: shop
variables:
page: 1
*coins: 100
blocks:
- type: text
id: balance
text: 'Coins: {coins}'A variable declared without a value starts at 0. You read one by writing {name} or ${name} in the text of an element or in the value of an action.
Local variables#
A name written normally, such as page, is local to the open UI. It lives as long as the UI is open, and it disappears the moment it is closed. This is the right choice for anything tied to a single screen. The page of a list, the currently selected tab, a counter of clicks.
variables:
page: 1
blocks:
- type: block
id: next_page
actions:
- type: variable
variable: page
operation: add
value: 1Global variables#
A name prefixed with * or $ is global. It is shared by every page the player opens, so a value set on one page can be read on another after a redirect. It is stored per player and is cleared when the player closes the UI.
variables:
*coins: 100The value written in variables: is only a starting value. If the player already has that global variable, the declared value is ignored and the current one is kept, so moving between pages that declare the same global variable will not reset it.
Changing a variable#
The variable action writes a new value. variable: is the name, operation: is what to do, and value: is the number or text to use:
actions:
- type: variable
variable: coins
operation: subtract
value: 50| Operation | What it does |
|---|---|
set | Writes the value, this is the default |
add | Adds to the current value |
subtract | Subtracts from the current value |
multiply | Multiplies the current value |
divide | Divides the current value |
Which variable gets written depends on the name you use:
variable: coins- updates the global variable if the player already has one with that name, otherwise the local onevariable: *coins- always writes to the global variable, creating it if needed
Every change redraws the UI, so any text using that variable updates immediately. Writing the same value again changes nothing and does not redraw.
Conditions#
Conditions let a function decide what to do, most often by comparing a variable:
variables:
*coins: 100
functions:
try_buy:
params:
price: 50
actions:
- type: condition
value: '{coins} >= {price}'
then:
actions:
- type: variable
variable: coins
operation: subtract
value: '{price}'
- type: message
value: '<green>Purchased!'
else:
actions:
- type: message
value: '<red>Not enough coins.'Comparison operators available in a condition:
=and==- equal, for numbers and for text!=- not equal>=- greater than or equal to<=- less than or equal to>- greater than<- less than
Repeating a function#
A function can call itself, which lets you repeat an action. Always guard such a call with a condition, otherwise it will run forever:
variables:
left: 3
functions:
countdown:
actions:
- type: message
value: '{left}'
- type: variable
variable: left
operation: subtract
value: 1
- type: condition
value: '{left} > 0'
then:
actions:
- type: delay
value: 1s
- type: function
function: countdown