Macros allow multiple commands to be run from a single menu item.
To define a macro
/sms macro add mymacro1 \Hello! /sms macro add mymacro1 \And now goodbye!
This creates a macro mymacro1 with two entries - one to make the player say "Hello!" and one to make the player say "And now goodbye!". If the macro doesn't already exist, it will be automatically created.
Note the leading backslash (\) - this means that the following text will be spoken by the player, as if they'd typed it in directly.
To call a macro
To call a macro from a menu entry, prefix the macro name with a '%' sign:
/sms add mymenu "Macro test" %mymacro1
Macros can even call each other:
/sms macro add mymacro2 /time day /sms macro add mymacro1 %mymacro2
ScrollingMenuSign will detect recursive loops and stop their execution, posting a warning.
Macros can take arguments, specified as a numeric value inside angle brackets (<>). E.g.:
/sms macro add buyitem "$E,<3> /@give <NAME> <1> <2>" /sms add mymenu "32 Stone ($50)" "%buyitem stone 32 50"
When the "32 stone" menu item is executed by a player called desht, the %buyitem macro is run with the arguments stone, 32, 50. The macro expands the commands to
$E,50 /@give desht stone 32 which means "charge 50 economy credits and if successful run the /give command with privilege elevation and give desht 32 stone". With a macro like this, it becomes possible to add other buy/sell entries very quickly and easily.
You can also use the special argument <*>, which is replaced with all arguments passed to the macro, joined by a space.
To list existing macros
/sms macro list -------|1 line (page 1/1)|-------------- 1) mymacro1 ----------------------------------------
To show a macro
/sms macro list mymacro1 -------|2 lines (page 1/1)|------------- 1) \Hello! 2) \And now goodbye! ----------------------------------------
To remove a line from a macro
You need to specify the line number of the line to remove. Use
/sms macro list <macro-name> to get this.
/sms macro remove mymacro1 2 Removed command from macro 'mymacro1'.
To remove an entire macro
/sms macro remove mymacro1 Removed macro 'mymacro1'.
Editing Macro Files Directly
Macros are stored under
plugins/ScrollingMenuSigns/data/macros/, one file per macro in YAML files (prior to v0.8, all macros were stored in
plugins/ScrollingMenuSign/commands.yml). These files can be edited directly if you choose - however, be sure to do a
/sms reload (or
/sms reload macros) immediately after any changes to ensure they don't get overwritten when the plugin next does a save.
A useful example
Maybe you want to allow some players to switch the game time to day or night via a sign. But you also want everyone on the server to know who's doing the switching.
/sms macro add daytime \I'm making it daytime now! /sms macro add daytime /@time day /sms add mymenu Daytime %daytime
Now, when a player executes that menu item, they'll tell the entire server that they've done it.
Macro Flow Control
The special command sequence '$$$' in a command will halt that command and also the macro containing that command, if any, assuming that the command actually ran. See Command Parser (Chaining Commands section) for more information.
Here is an example which allows you to "buy" a permission node, or perk (credit for the original concept goes to Seinna on the Bukkit forums):
/sms macro add buynode @n:<1> \\You already own that perk. $$$ /sms macro add buynode $<2>,<3> /@perm player <N> setperm <1> true /sms create bridgeperk "Bridge Perk" /sms add bridgeperk "10 sponges" %buynode falsebook.blocks.bridge sponge 10 /sms add bridgeperk "2 diamonds" %buynode falsebook.blocks.bridge diamond 2
This allows players to spend either 10 sponges or 2 diamonds (and other possible costs could be added) to purchase a permission node. The macro first checks to see if the player already has the node in question (parameter <1>, in this case falsebook.blocks.bridge) and if so, tells them so and exits the macro. If the player doesn't have the permission node, then macro execution continues to the second line, the charge is applied (via parameters <2> and <3>) and, assuming the charge was affordable, the permission node is given to the player (in this case using PermissionsBukkit, but other permissions plugins have commands to do the same thing).
The use of arguments here (<1>, <2>, <3>) means that this same macro can be used to buy any permission node for whatever cost (or costs) you want to charge.