Bukkit

Getting started

Installation

Grab the latest version of ReMap and ProtocolLib, and put the jar-files into your server's "plugins"-folder. Start the server to make ReMap create a data folder and a config.yml file. These will be located inside the "plugins"-folder.

Remap files

ReMap doesn't do anything by itself. It needs "remap files", which contains translations. A remap file is a plain-text file. You can create them using any plain-text editor, like Notepad. The file name and file type can be anything you like, except for "config.yml", as this name is reserved for ReMap's configuration. Save the files in the "ReMap"-folder inside your server's "plugins"-folder. Remap files can contain four different types of patterns, called "remaps", "swaps", "bleeps" and "replies".

• Remaps translate commands that players execute. They can be used to add aliases and redirect commands.
• Swaps translate chat messages. They can be used to translate messages sent by the server as well as other players.
• Bleeps replace sub-strings within chat messages. Unlike swaps, these patterns do not need to match the message body entirely. Best suited for replacing certain words from the chat.
• Replies are like remaps, but instead of executing a command, they just send the player a message. Suitable for blocking or faking hard-to-reach commands, like "/plugins" or "/help". You can also add custom commands with this, like the famous "/reg"-command.

Below is the basic format of remap files:

pattern type:
'translate this': 'into this'
'translate this': 'into this'

pattern type:
'translate this': 'into this'
'translate this': 'into this'

Below is a working remap file, containing all four types of patterns. Files do not need to contain all four types, and they do not need to be listed in any particular order.

remap:
help: plugins

swap:
Set time to 0: The time is now 0.

bleep:
kiwhen: nehwik

reply:
fish: Fishing is nice.
salmon: Salmon is a fish.

• If used, this remap file will prevent players from using the "/help"-command. When they do, they will just see the list of plugins currently loaded on the server, as if they used the "/plugins"-command. Note that remaps do not accept partial matches, so players can still use the "/help 1"-command, because the index number does not exist in the remap pattern ("help").
• When the time is changed using "/time set 0", the message from Bukkit saying "Set time to 0" will come out as "The time is now 0.".
• Any time the word "kiwhen" is sent to the chat, it will come out as "nehwik". If a player called "kiwhen" says something in the chat, it will look like "<nehwik> I said something.".
• The commands "/fish" and "/salmon" are added, and when used, they will simply display the given messages to the player who used them.

Note: You don't need to type forward slashes to indicate commands. You can put them in if you want, but ReMap doesn't care much about it. This also applies to double-slashed commands, like the ones used by WorldEdit. Also, all patterns (left side of the colon) are case-insensetive.

Removing chat messages

To make swaps and bleeps remove words or phrases completely instead of just replacing them, simply leave the output (right side of the colon) empty. No quotes or spaces, just plain empty.

bleep:
kiwhen:

This bleep pattern will remove the word "kiwhen" from the chat. The same format applies to swap patterns.

Wildcards

ReMap can interpret wildcards. A wildcard is used to match non-specific words. There are two kinds of wildcards. A percent sign followed by a number (%1, %2 and so on) will match any single word, and an asterisk (*) will match any single word and all words that follow it.

Here is another remap file example, using wildcards:

remap:
sun %1: time set %1

swap:
Unknown *: Command doesn't exist, sorry.

This will add the "/sun"-command. ReMap will simply shift whatever the player typed after "/sun" into the "/time set"-command. If one were to type "/sun 6000", the server would recognize this as "/time set 6000".

The swap pattern uses an asterisk to match any chat message starting with "unknown", that has two words or more in it. More specifically, it will cause Bukkit's good old "Unknown command. Type "help" for help." to come out as "Command doesn't exist, sorry.".

Note: You can use the asterisk in the output too (right side of the colon). This will print every word that the left-side asterisk matched against. In the example above, it would come out as "command. Type "help" for help.".

Wildcard limitations

Wildcards cannot be used everywhere.

The first word in a remap pattern cannot be a wildcard. This is because using a wildcard up front would match all commands, which would cause some interesting side effects. If your intention is to block all commands, just type in ReMap's own "/remap block"-command. This will disable all commands that are not defined in the remap files. For safety reasons, "/remap block" can still be used when command blocking is enabled. However, it will act as if it's blocked if the client does not have permission to turn it off.

Swaps, unlike remaps, can use wildcards as the first word in patterns. If a swap pattern is only a single asterisk, it will match all chat messages. There's a good way to make the chat completely useless...

Bleeps takes everything literally, and do not interpret wildcards.

Wrapping

If your pattern or output contains colons, you must wrap them in quotes. Both single and double quotes can be used. This is just to make sure ReMap understands which of the colons separate the pattern from the output. Wrapping is only required when a colon is present.

swap:
Unknown *: Command doesn't exist, sorry.
Unknown *: 'Error: Unknown command.'
Unknown *: '"Error: Unknown command."'

When a player types an unknown command, the output will be like this:

Command doesn't exist, sorry.
Error: Unknown command.
"Error: Unknown command."

Notice that the double quotes are still present in the third swap, ReMap only strips away one set of quotes.

Line breaks

Swaps, bleeps and replies will interpret a backslash followed by the lower case letter n as a line break. (\n)

Colors

Swaps, bleeps and replies will interpret an ampersand followed by a hexadecimal number as colors. (&0 through &F)

Additions (multi-commands)

All four types of patterns will interpret the caret-symbol as an addition to the last pattern. (^) For remaps, you can use this to execute multiple commands when a player types the command defined as the pattern. In swaps, bleeps and replies, this will simply add another line of text to the output, just like a line break would. Example:

remap:
sun %1: time set %1
^: say Why would you do this?

The command "/sun 0" will first trigger "/time set 0" followed by "/say Why would you do this?".

If your remap files contain the exact same pattern more than once, ReMap will also interpret this as an addition.

Note: If a remap triggers the "/reload"- or "/stop"-command (or any similar function) any commands that follow will not trigger, as ReMap will disable the whole server in the process.

Order of elements

The order of elements is significant. ReMap reads files top-down in alphabetical order. This means that you should put specific remaps near the top, and more general remaps further down in the files. Here is an example:

swap:
Set time to 0: Good morning!
Set time to %1: The time is now %1.

In this case, the two swaps apply to the same message, but we want to print a different message if the time is set to 0. Since ReMap reads from the top down, it will match against the first statement if the time is 0, and therefore print "Good morning!". If the time is anything else, it will not match the first statement, and it will say "The time is now X.". If these statements are reversed, ReMap will always match against the first statement and it will never say "Good morning!", even if the time is set to 0.

ReMap's own commands and permissions

ReMap does have a few commands. That, together with details surrounding permission handling is covered on the front page.