Bukkit

Map Views

As of version 0.6, ScrollingMenuSigns allows menus to be displayed on maps, which means you can take your menus with you!

Overview

• Minecraft has the concept of map ID's - every map item has an numeric ID. Multiple map items may have the same ID.
• When maps are used as views on a menu, the map's ID is associated with that view; there is a one-to-one relationship between the SMS view and the map ID. This means that multiple maps with the same ID all show the same menu (but players are able to scroll those maps independently of each other).
• /sms list on a menu with map views will show the map ID for the view.
• When you craft a map, the next unused ID is allocated to that map. If you want multiple maps with the same ID, you need to craft several at once.
• ScrollingMenuSign also provides the /sms give map command to obtain more maps of a given ID without the need to craft them; see Getting Maps below. This is the recommended way of getting and giving map items for map views.

Permissions

To do anything with map views, you must have the scrollingmenusign.use.map permission node in addition to any other nodes needed for menu/view manipulation. E.g. to add (/sms sync) a map to an existing menu, you'll need scrollingmenusign.use.map and scrollingmenusign.commands.sync. By default, non-op players do not have scrollingmenusign.use.map - you can give this node to players directly, or give them scrollingmenusign.admin or scrollingmenusign.poweruser. See Permissions for more information.

Getting Maps

As mentioned above, SMS provides the /sms give map command to obtain new maps without the need to craft them.

The usage is:

/sms give map <menu-name> [<quantity>] [<player-name>]

or

/sms give map <view-name> [<quantity>] [<player-name>]

or

/sms give map <map-id> [<quantity>] [<player-name>]

ScrollingMenuSign will detect whether you pass an existing menu name, an existing map view name, or a numeric map ID, and Do The Right Thing:

• If you pass a menu which doesn't already have a map view, a map view will be automatically created on that menu, and the map you get will be added to it. If the menu already has a map view, the map you get will be automatically connected with that map view.
• If you pass an existing map view name, the map will be connected with that map view.
• If you pass a numeric map ID, you will get a map of that ID. In this case, the map will not be automatically connected with any map view if it wasn't already used for a map view. You can pass -1 as the ID to force creation of a new map ID.

You can also optionally specify a numeric quantity and player name to give multiple maps or give maps to another player.

E.g.

/sms give map mymenu 5 Notch

gives 5 maps for the menu "mymenu" to the player called Notch.

Creating a Map View

This is an alternative to the method described in Getting Maps above.

Get yourself a map (either craft it or use /sms give map -1 , as described above). Then do one of the following:

• Go up to an existing menu sign, and hit the sign with the map in your hand. The sign's menu will magically transfer onto the map. You will need the scrollingmenusign.maps.from.sign permission to do this, and the maps.transfer.from_sign configuration item must be true.
• While holding the map, type /sms sync <menu-name>. The map will become a view for the menu name you gave (and that menu must already exist).
• While holding the map, type /sms create <menu-name> <title>. The map will become a view for the new menu you just created.

If you hit any sign which is not currently a menu view with a map which is a menu view, the map's menu will be magically transferred onto the sign, turning the sign into a menu view. So this is equivalent to looking at the sign and typing /sms sync <menu-name>. You will need the scrollingmenusign.maps.to.sign permission to do this, and the maps.transfer.to_sign configuration item must be true.

Using a Map View

Basically, the same as for a sign view. By default, right-click scrolls down, shift + right-click scrolls up, and left-click executes the currently-selected item.

If you have Spout enabled on the server and are using the Spoutcraft client, then key bindings can also be used - by default these are Cursor-down, Cursor-up and Return. Again, these are configurable.

Removing a Map View

To detach a map from a menu, type /sms break while holding the map. The map will no longer be a view on the menu; its previous renderer (by default, a map of the region around where the map was originally crafted) should reappear.

As with all view types, you can also break a view by name /sms break <view-name>.

Background Images

As of v1.0.0, map views support a background image, which is drawn behind the menu text. For each map view you want to add a background image to, set the imagefile view attribute to the name of the image file you want to use. You can pass a full URL (e.g. http://server.example.com/path/to/image.png) or a relative name (e.g. path/to/image.png) - if a relative name is used, then you will first need to set up the resource_base_url configuration setting to the base URL from where you want to load your images. Example:

/sms set resource_base_url http://www.some-web-server.com/images/
/sms view mymenu-1 imagefile bg1.png
/sms view othermenu-1 imagefile http://somewhere-else.com/images/nicetexture.png

In this case the image at http://www.some-web-server.com/images/bg1.png will be used for the mymenu-1 view, and http://somewhere-else.com/images/nicetexture.png for othermenu-1.

You only need to set resource_base_url once - that setting is then used for all subsequent image files.

Notes:

• Supported file formats are JPG, PNG, BMP, WBMP and GIF (i.e. the same formats that the Java ImageIO class supports by default)
• The image will be automatically scaled to 128x128 (the Minecraft map resolution). Therefore images with a square aspect ratio are likely to look best.
• As of ScrollingMenuSign 1.0.0, all images are drawn on the entire 128x128 background - there isn't any support for drawing in a smaller area of the map, but this functionality is planned for a future release.
• Minecraft maps have a limited palette, so care needs to be used in choosing images that look good as backgrounds.

Image Caching

Images will be downloaded when the /sms view view-name imagefile ... command is run, so take care not to choose a non-responding or slow website - this could cause server lag since a separate thread is not currently used to download the image file.

However, once the image is downloaded, it is automatically cached as a 128x128 .png file, so it will be loaded much more quickly the next time it's needed. If you need to clear the image cache, look in the plugins/ScrollingMenuSign/imagecache folder - the cached files in there are stored with names based on the MD5 hash of the full URL.

Background Fill

As of v2.3.2, ScrollingMenuSign allows a solid background fill colour to be specified for the view. See http://minecraft.gamepedia.com/Map_Item_Format#Map_colors for a full list of valid colours. The default fill colour is 9 (a mid-beige colour). This is controlled by the background view attribute. E.g. if you would prefer no fill for the view, then do:

/sms view <view-name> background 0

Note that views with no background fill will appear quite transparent when placed in item frames (see below) and show up the item frame behind them.

You can also use the maps.background config setting to define the default fill colour to be used for all new map views.

Fonts

Prior to v2.0.0, all maps were drawn in the default Minecraft font; no customisation was possible.

As of v2.0.0, SMS can use any font known to Java to draw the map text. By default, it uses the SansSerif font, size 9. This can be changed in the Configuration with the maps.font and maps.fontsize settings. Fonts can also be changed on a per-view basis with the font and fontsize view attributes.

To see a list of all known fonts, type /sms font (note: expect a lot of output).

You can easily add custom fonts to SMS. Simply upload the TTF or Type1 font files you want to your CraftBukkit server and place them in plugins/ScrollingMenuSign/fonts, then do /sms reload fonts to pull in any new fonts you've uploaded.

If you really like the old Minecraft-style look, you can always download the Minecraftia font here: http://www.dafont.com/minecraftia.font - use a fontsize of 8 for best results. (http://www.dafont.com/ is a good source of fonts in general)

Framed Maps

As of v2.2.0, map view maps which are placed in item frames will behave properly; the usual controls scroll and execute items in the map view. This means that map views can be framed, acting like prettier sign views! (Previous to v2.2.0, maps could be placed in item frames, but just behaved as normal items do).

A separate permission node is used for framed map views: scrollingmenusign.use.map.framed. All players have this permission node by default.

Since left-clicking a frame map view has a special meaning, it's not possible to break the frame or remove the map by clicking. Instead, target the framed map, and type /sms break -frame. The map will pop out of the frame and drop as an item in the world, leaving an empty frame which can be broken or filled as normal.

Caution: while framed map views behave very much like sign views, the resource requirement (CPU & network) is significantly higher. Be careful about overusing this feature!

Attributes

See Usage/Managing Views for information on viewing and changing view attributes.

Map views support the following attributes: