Bukkit

User Variables

Overview

• User variables can be used to substitute text into menu titles, menu item labels, menu item tooltips, and into commands that are run from menus.
• User variables can also be used to control the execution of commands with the special @v restrictor.
• As their name suggests, they are specific to each player. i.e. if playerA sets a variable, playerB does not see it.
• User variables persist when the player logs out.
• To set, read or delete a variable with the /sms var command, you need the scrollingmenusign.commands.var permission. To manage a variable for a different user, you also need scrollingmenusign.vars.other. Both of these are included in scrollingmenusign.admin.

Managing Variables

• /sms var <varname> <value> - set a user variable for the calling player
• /sms var <player-uuid>.<varname> <value> - set another player's user variable
• /sms var *.<varname> <value> - set a default value for the variable, used when a player doesn't have the variable defined

You can leave out the <value> to just display the current value. If you are setting the variable for another player, or setting the default value, you can also run the command from the console.

• /sms var -i <variable> - increment (add 1 to) the variable, if it's numeric (an error will be thrown if it's not)
• /sms var -i <variable> <amount> - add <amount> (can be negative) to the variable, if it's numeric

These might be useful if you want to maintain a counter of some kind.

You can also pass '-q' as the first argument to /sms var to make it set variables silently, which could be important if you're running the command from a menu (you don't want variable values being reported to players). E.g.:

• /sms var -q <variable> <value>

Defaults

As mentioned above, if a variable substitution is encountered where the player does not have that variable defined, the special *.<varname> default is used instead. If even that is undefined, a fallback default is used; this is the user_variables.fallback_sub config setting, by default "???".

Basic Example

/sms add mymenu "Set Time to <$when>" "/time <$when>"

Executing that menu entry requires the player to have set the when variable beforehand (the player will get an error if he hasn't set the variable). However, it's also possible to specify a default for non-existent variables:

/sms add mymenu "Set Time" "/time <$when=day>"

Now, if the executing player doesn't have a definition for when, the default of "day" will be taken, and no error will be thrown.

This feature is probably most useful in large macros, e.g. where you might want to run a set of commands on a player, but not know the actual player name when you created the macro & menu entry.

Restricting Execution

See also Command Parser for a description of restrictions.

It's possible to restrict execution of a command based on the value of user variables. E.g. this command will say "Yes!" if the user's count variable is 5 or greater, otherwise it will show the current value:

/sms add mymenu "Check count" "@v:count>=5 \\Yes! $$ \\No! count is only <$count=0>

(Note also the default value of 0 there to avoid errors if the executing user doesn't have a count set at all)

The following conditions are supported by @v:

• @v:varname=value - true if the variable is exactly equal to the value
• @vi:varname=value - true if the variable is equal to the value (case-insensitive)
• @vr:varname=value - true if the variable matches the regexp value (and @vir for case-insenstive regexp match)
• @v:varname>number - true if numeric variable is greater than the given number (and also <, <=, >=)
• @v:varname - true if the variable is set to anything
• @v:varname= - true if the variable is set to any empty string

@!v negates the tests, e.g. @!v:varname will be true if the variable is unset for the player.

Regex example - this tests if the status variable is either "ok" or "good" and reports accordingly:

/sms add mymenu "Status" "@vr:status=(ok|good) \\Everything's fine! $$ \\Problem! Status = <$status>

Prompted Variables

These are special anonymous variables, which are prompted for when the menu item is executed. They are specified as <$:prompt>. The prompt is the text that is displayed to the player to ask for a value to be inserted into the command.

Example:

/sms add mymenu "Give Item" "/i <$:Enter an item name or ID...>"

When the entry is executed, the player will see a message: Enter an item name or ID.... The next string typed in chat will be used as the variable substitution for the command, so if the player types "1", the command /i 1 will be run, and the player will receive a block of stone.

You can have multiple prompted variables in a command - they will be prompted for in order.