Quickstart Guide

Installation

Copy ScrollingMenuSign.jar into your server's bukkit/plugins folder
If you want economy functionality and/or non-trivial permissions support, you will also need to install the Vault plugin, if you don't already have it.
Restart or reload your server

Before You Start

Make sure you have permissions to run all ScrollingMenuSign commands - if you're using a permissions plugin, give yourself the scrollingmenusign.admin node (or perhaps scrollingmenusign.* if your permissions plugin isn't superperms-compatible), and if you're not using any permissions plugin, you will need to be an op. See Permissions for full details.

Creating a Menu

Place a sign somewhere. The sign text doesn't matter - it can be blank.
Look at the sign and type /sms create mymenu &4My Menu
You should now see a sign with a red centred title of My Menu on line 1, and a ">" on line 3.
(For a full list of colour codes known to the plugin, see http://www.minecraftwiki.net/wiki/Formatting_codes)

Adding Entries

Type /sms add mymenu Day "/time day" -feedback "It's daytime!"
Type /sms add mymenu Night "/time night" -feedback "It's night time!"
(the options supported by the /time command depend on what plugins you have installed - Essentials, General etc. modify the command - play around with it)
Type /sms add mymenu &2Hello "\Hello everyone!"
Type /sms add mymenu &4Bye "\\Goodbye <NAME>!"
(The leading backslash '\' makes the player speak the rest of the line of text. A double leading backslash '\\' privately messages the player with the text. The string "<NAME>" will be replaced with the player's actual name)

Further reading: Usage / Adding Menu Items and Command Parser

Scrolling and Executing Entries

You should now have a sign with a title and 3 lines showing the first three items you added. Right-click the sign, and the 3 lines should scroll, showing the 2nd-4th lines you added. Keep right-clicking and the entries will wrap around.
Shift (sneak) and right-click the sign, and the entries will scroll backwards.
Shift (sneak) and scroll your mouse wheel while looking at the sign.
Left-click the sign with various items selected (pointed to by the ">" on line 3) and see what happens.

Tab Completion

SMS has comprehensive support for tab completion (console tab completion needs CraftBukkit 1.6.2+), both for subcommands and command arguments. Examples:

Type /sms l<Tab> - the command is auto-completed to /sms list
Type /sms list m<Tab> - the command is auto-completed to /sms list mymenu
This works for pretty much any command - SMS will always try to find a good completion, or display the possible completions if there is more than one, or display some sensible usage information if there are no completions.

Adding a new Sign View

Place a second sign somewhere (again, the sign text doesn't matter).
Look at the sign and type /sms sync mymenu
This sign now displays the same menu as the first sign, although it can be scrolled independently.
/sms sync is used for adding new views to a menu you created previously

Further reading: View Types / Sign Views and Usage / Adding Views

Map Views

Get yourself a map: use /sms give map mymenu - the server will give you a map showing the same menu! You can scroll and execute it just like a sign view.
Alternatively, type /sms sync mymenu while holding an ordinary map in front of you. That will have the same effect - your map will now be a view on mymenu.
Get yourself an item frame and put the map in it. You can now interact with the map just like a sign view! To get the map out, look at it and type /sms break -frame.

Multisign Views

Get four signs, and put them on a wall in a 2x2 array.
Look at any of the four signs you placed, and type /sms sync mymenu -multi
You now have a multisign view, which can show up to seven lines at a time (2 x 4 - 1 for the title), and 30 characters for each label (2 x 15)
Add a menu item with a long label: /sms add mymenu "This is a very long label" "\Long labels work!"
You'll see that the entire label text is visible (if you look at your basic sign view created originally, you'll see that long label was truncated)

Further reading: View Types / Multisign Views

Inventory Views

Add an inventory view to this menu. Type /sms sync mymenu -inv and make a note of the view name that has been created. We'll assume for this example that it's mymenu-4.
Now, there are a couple of ways to pop this menu up:
Type /sms view mymenu-4 -popup. An inventory window will appear with several stone blocks. Mouse over those blocks and you will see tooltips corresponding to the menu labels in mymenu. Click one, and see what happens...
Now for a more friendly way of getting to this view: type /sms give popup mymenu-4 blazerod. You'll get a blaze rod item in your inventory - hold that item and left or right-click it. The inventory view will appear, as before. (You can also get multiple items and/or give these items to other players with /sms give popup mymenu-4 <item-name> <amount> <player-name> - any known Bukkit material name can be used for the item).
Let's give the menu some more interesting icons: type /sms edit mymenu Day -icon wool:yellow and /sms edit Night -icon wool:black. Now pop the view up again, and see the difference...
Finally, for another way to get one of those "popup books", get yourself (craft or otherwise give) a book and quill item. Hit one of the sign views you created before with it, and see what happens...

Further reading: View Types/Inventory Views

Public Hologram Views

You will need SMS v3.0.0+ and HoloAPI installed to use public hologram views

Let's create a hologram view for our menu. Type /sms sync mymenu -holopub. You will be prompted to click a block to set as the view anchor. Choose a suitable block, and click it.
Two things will happen: the menu will appear as a hologram above your clicked block, and you will be given a view name. For this example, we'll assume the name is mymenu-5.
You can interact with the hologram in the same way you interact with sign views: (shift-)right-click to scroll, and left-click to execute.
Type /sms view mymenu-5 offset 2.0 - the hologram will move up by one block. You can give any floating-point distance here, so the hologram can appear a long way from the anchor block.
Type /sms view mymenu-5 direction EAST - the hologram will now appear 2 blocks east of the anchor block instead of 2 blocks above. Any compass direction plus UP, DOWN, and SELF can be used here.
Now put a lever on the anchor block and flip it a couple of times. Nothing happening? Type /sms view mymenu-5 redstone HIGH, and now see what happens when you flip the lever! You can show/hide public holograms with the presence or absence of a redstone signal to the anchor block.

Further reading: View Types/Public Hologram Views

Private Hologram Views

You will need SMS v3.0.0+ and HoloAPI installed to use private hologram views

Now for another type of hologram view: the private hologram view. It looks very much like the public hologram view, and is interacted with in the same way, but it doesn't appear at a static location for all players to see. Instead, players can use a specially created item to pop the view up for themselves alone. In this respect, the private hologram view as a little more like the inventory view.
Type /sms sync mymenu -holopri. A view will be created, and you will need to note the view name - for this example, we'll assume mymenu-6.
How to actually display this view? One option is to do /sms view mymenu-6 -popup, but there's a nicer way: popup items
Type /sms give popup mymenu-6 blazerod, and you will receive a blaze rod, named "My Menu" (and glowing if you have ProtocolLib installed). Left- or right-click that blaze rod...
... and your view appears in front of you! Other players cannot see or interact with this view; it's private to you alone. Interact with it just like a public hologram view.
To dismiss this view, simply click with the blaze rod away from the view, and it will pop down again.

Further reading: View Types/Private Hologram Views

Spout Views

Ignore this section if you don't have Spout installed and/or aren't using the Spoutcraft client. Also note that there is no Spout plugin for CB 1.7.x or Spoutcraft for Minecraft 1.7 at this time.

Add a spout view to this menu. Type /sms sync mymenu -spout, and make a note of the view name that has been created. We'll assume for this example that it's mymenu-7.
Type /sms view mymenu-7 spoutkeys p. Now press 'p' and see what happens...

Further reading: View Types / Spout Views

Redstone Views

Place a lever somewhere.
Type /sms sync mymenu -redstone and left-click the lever when prompted.
Now, while looking directly at the lever, type /sms view . poweron Day
The dot . you used there is a useful shortcut meaning "the currently targeted view" - it'll also work if you're looking at a sign view, looking at a public hologram anchor block, holding a map view, or holding a popup book/item for an inventory or private hologram view.
Type /sms view . poweroff Night
Flip the lever a few times and see what happens...

Further reading: View Types / Redstone Views

Submenus

Type /sms create central &1Central
Type /sms add central "My Menu" "SUBMENU mymenu"
Type /sms give map central to get a map on this new menu.
Now try executing the "My Menu" item on your map view.
The map has now changed to displaying your original mymenu menu! You'll also notice that the title has an extra "->" tag prepended to it to indicate that you're in a submenu, and there's a special "<-BACK" menu item added at the end - click this item to go back to your central menu.
You can do this with any view type, not just maps. Try creating a sign view on the central menu, for example.

Item Tooltips

Type /sms edit central "My Menu" -lore "Go to my menu"
Now look at the map view you added to the central menu. You'll see a tooltip is shown when the "My Menu" item is selected.
This also works for any view type, not just maps.
For sign views, place a sign next to (left, right, above, below) an existing sign or multisign view, with the text [smstooltip] on the first line. You'll get a confirmation message that a tooltip sign has been added; that sign will now display any tooltip information for the selected menu item.

Advanced Commands

Type /sms add mymenu Hurt "$H,1 \\ouch!"
Type /sms add mymenu Heal "$H,-1 \\that's better!"
Try executing those entries. $H,count charges the player count health points - a positive count takes health away, a negative count restores it. Other cost types can be used too - see Command Parser
Type /sms uses mymenu 3. Execute a few entries and see what happens after the third time.
Type /sms uses mymenu clear to remove the usage limit. See Limited Use Menus.
Here's a quick & easy item repair station: /sms add mymenu "Repair Item" "$E,1;<I>,-10,D && \\Repaired <INAME> - you have <MONEY> left." - this charges one economy credit to repair 10 durability points of damage on the item you're currently holding.

Permission Elevation

Some prerequisites for this example: the Essentials plugin and any permissions plugin which is supported by Vault. We'll be demonstrating how a normal player can use the Essentials /warp command from signs without having general access to the command. If you're not using Essentials, that's fine - just pick a command and its associated permission node from any other plugin you want to test with.

Do this is as an op user:

Set up a warp somewhere: /setwarp warp1
Add a warp entry to our example menu: /sms add mymenu "Warp 1" "/@warp warp1"
Type: /sms set elevation.nodes essentials.warp

Now, get on the console and de-op yourself: deop <yourname>. You should see a message in your game window that you're no longer an op. Also make sure that your player does not have the essentials.warp permission node; typing /warp warp1 should fail with a no-permission error.

Click the Warp 1 menu entry, and you should warp to your warp point, even though you don't have direct permission! What happened here is that ScrollingMenuSign temporarily added the essentials.warp permission node, ran the warp command, and then immediately removed the permission node again. That's what the '@' in /@warp means.

Using permission elevation, you can allow players to run certain commands in a controlled manner - you can put other restrictions on execution such as adding a cost to the command, if you wish.

You will probably want to re-op yourself at the console when done testing: op <yourname>

Viewing and Changing the Plugin Config

Type /sms getcfg to view the current plugin configuration. It will span more than one page - you can scroll back with the mouse wheel while the chat window is open.
Change the config: type /sms setcfg actions.wheeldown.normal scrolldown and /sms setcfg actions.wheelup.normal scrollup. Now you no longer need to hold Shift to use the mouse wheel!
Don't want people accidentally left-clicking signs and running commands? Type /sms setcfg actions.leftclick.normal none and /sms setcfg actions.leftclick.sneak execute. Now you need to Shift+Left-click the sign to execute a command.
Prefer your view titles left-justified by default? Try /sms setcfg title_justify left and see how your signs/maps/etc. change.
Changing the config back to the previous setting is left as an exercise :-)
See Configuration for a full list and description of all config items.

Other Stuff

Type /sms remove mymenu Bye to remove the Bye item. Notice that it's gone from both signs (and the map/spout views if you still have them) - each sign is just a view on the menu items in mymenu.
Type /sms edit mymenu Hello -label Hello! to change the label of the "Hello" menu item without needing to remove and re-add it.
Type /sms list
Type /sms list mymenu
Type /sms menu mymenu
While holding the map, type /sms break. The menu will disappear and the map will revert to its previous contents.
Type /sms delete mymenu to destroy the menu - both signs will go blank (all views that have been created on the menu get deleted)
Type /sms undelete mymenu to restore the deleted menu. The menu will be back, but any views will need to be manually re-created.

Where to go from here?

Read the Usage Overview for a general operational guide
Read the pages under View Types for information on the various view types you can use (sign, map, inventory, spout, redstone)
Learn about the command parser for some more powerful menu actions
Place limitations on the number of times a menu can be used: Limited Use Menus
Want to manage menus from your own plugin? Read up on the API!

Comments

To post a comment, please login or register a new account.

ScrollingMenuSign

Bukkit Plugins

Pages