Topaz's Minecraft SMP Toolkit (or tztk) enhances the vanilla Minecraft server by providing some useful scripts and in-game commands. Talk to me about it at topaz.minecraft.toolkittopazstorm.com.
Scripts
tztk-update.sh downloads the latest minecraft_server.jar from minecraft.net and overwrites the local copy. Shut down the Minecraft server before running this.
tztk-server.pl is like another person sitting at the Minecraft console. When you run it, it runs the Minecraft server and acts as a proxy between the server console and your terminal. However, when it sees a chat message on the console that it recognizes as a command, it takes action! See the commands list below for details. It will only respond to commands which have corresponding files present in the tztk/allowed-commands directory; for example, the -wp-set command will only be recognized if the file tztk/allowed-commands/wp-set exists. It will also maintain a tztk/players.txt file with a list of currently connected players, much like the creative server did.
In-game commands
Entries in <angle brackets> are placeholders and should be replaced with an actual value. Entries in [square brackets] are optional. Entries in {curly|braces} are choices. For example, -create {<id>[x<count>]|<kit>} implies you could actually type things like -create 278, -create 73x64, or -create armor instead.
Commands may also be run secretly by prefixing them with /tell, as in /tell -create 278 to create items secretly. Note that with /tell, a command argument is still required (so Minecraft considers it a valid /tell command); for example, to run -list secretly, one would need to type /tell -list x instead.
To limit what can be created, change the allow file to a directory (like tztk/allowed-commands/create/), and then put files with the same names as decimal IDs in a subdirectory named either whitelist (to only allow certain types) or blacklist (to only disallow certain types). If the whitelist directory is present at all, whitelists will be enforced. For example, create a file named tztk/allowed-commands/create/whitelist/287 to only allow the creation of string, or a file named tztk/allowed-commands/create/blacklist/46 (with no whitelist present) to disallow only the creation of TNT.
You can adjust the maximum amount (from the default of 64) by putting the desired value in the tztk/allowed-commands/create/max file.
You can also define kits, lists of items which may be created by just naming the kit instead of giving an ID. For example, you could create a kit named armor which spawns the player a full set of diamond armor when they type -create armor. To define a kit, create a file in tztk/allowed-commands/create/kits/ and give it the name of the kit. Within that file, put IDs, optionally followed by counts (just like -create would take), one on each line. These definitions are limited by the same rules as the standard -create command. For example, to create a thorough starter kit, create the file tztk/allowed-commands/create/kits/starter and fill it with something like this.
Determining whether such a kit takes all the fun out of the game is left as an exercise for the server admin.
-tp <player> teleports the user to the specified player.
-wp <name> teleports the user to the specified waypoint.
-wp-set <name> creates (or moves) the specified waypoint at (or to) the user's location.
-wp-list lists all available waypoints.
-list lists all connected users.
-buy <command> [<amount>] lets users pay for commands with items in their inventories. The specified amount is the number of uses of the command they want to buy, defaulting to 1 use. After running this command, the player must log out and back in to give tztk a chance to update their inventory.
-buy-list lists the available for-pay commands and their prices in the format id(quantity).
-bank-list displays the number of uses of each for-pay command the user currently has left.
Console commands
-snapshot may be invoked from the console to force a snapshot of the world. This uses the same logic as the periodic snapshots, including forcing a flush of all chunks and updating the latest symlink.
Waypoints
The waypoint system combines player-to-player teleportation with user data persistence. A waypoint is really just a fake user which acts as a teleport destination for other players. When one is created, a fake user is logged in, teleported to the user, and logged back out. When one is used, a fake user with the same name is logged in (where it logged out upon creation, since user data is persisted), the user is teleported to it, and it is logged back out. Waypoints are stored by the server (that is, their user data is perissted) in the world directory under players/wp-<name>.dat, which also happens to be the pattern the -wp-list command searches for. Because users with arbitrary names need to be able to log in, you'll need to set online-mode=false in your server.properties file, which sadly also allows anyone to join without authentication (but see the section on user whitelists below).
If you would prefer to keep online-mode set to true and you have a spare Minecraft account you're not using, you can put its authentication information in username and password files in the tztk/waypoint-auth directory. If present, tztk-server.pl will use this account to authenticate against minecraft.net and use that session ID to log in to your server, swapping around waypoint data behind the scenes to keep the locations distinct.
User whitelists
To restrict your server to only specific usernames or IPs, you can create user whitelists. To do this, create a directory named either tztk/whitelisted-ips or tztk/whitelisted-players. Once one of these directories exists, the corresponding whitelist will be enforced, even if it is empty. (Players on the same computer as the server can always log in.) Then, place files named the same as the IPs or usernames to be whitelisted in the appropriate directory; for example, create tztk/whitelisted-players/Topaz2078 to let me play on your server, or create tztk/whitelisted-ips/1.2.3.4 to allow anyone at 1.2.3.4 connect.
Snapshots
To create periodic snapshots, put the desired snapshot period (in seconds) into a file named tztk/snapshot-period in the server's root directory. (For example, to take a snapshot no more than once per day, you could run echo 86400 > tztk/snapshot-period to create such a file.) As tztk-server.pl runs, it will occasionally check this file and verify that the most recent snapshot is within this period. Otherwise, it will halt auto-saving, force a full save, tar/gzip the world directory, and restart saving. The resulting .tgz files will appear in tztk/snapshots/, wich the most recent snapshot pointed at by the tztk/snapshots/latest symlink. To delete all but the latest few snapshots, put the desired number of snapshots into a file named tztk/snapshot-max (this number must be at least 1, of course).
Minecraft<->IRC Chat bridge
You can bridge your Minecraft server's chat with an IRC channel! To do this, create a directory named tztk/irc/ and fill it with files named host, port, nick, and channel filled with the parameters you'd like the IRC client to use. If a file is not present, the defaults are localhost:6667 as minecraft on #minecraft. In IRC, users can type -list to see a list of currently connected Minecraft players.
Message of the Day
To provide users with an MOTD, create a file named tztk/motd in the server's root directory. Each line of this file will be individually whispered to players as they join the server.
Command payment
Commands which are already allowed via the allowed-commands mechanism may be given a price per use. To do this, create a tztk/payment/ directory. This directory should contain subdirectories named the same as the command for which you would like to set a price. Within each such subdirectory, create a cost directory, which should contain files named by item ID and containing the number of that item required for purchase. The final cost for each use of the command is the combination of all of these item-amount files. For example, to cause -wp to cost two books per use, create a file named tztk/payment/wp/cost/340 and have it contain 2. Then, if a player types -buy wp 6 and logs out and back in, they will have six uses of -wp, but 12 fewer books in their inventory.
Requirements
tztk expects a Unix-like environment (tested on Ubuntu, CentOS, and Cygwin) and Perl. It expects java to be in your path. It expects to be placed in the same directory as the vanilla server files (that is, minecraft_server.jar and tztk-server.pl should be in the same directory). It reads your server.properties file, which should also be in the same directory, and assumes those values are correct and in use (which they should be, since it loads them and starts the actual server at the same time).
For waypoints to work, you'll also need to either set online-mode=false in your server.properties file, which sadly also allows anyone to join without authentication, or set an unused Minecraft account up for waypoint authentication. For snapshots to work, you'll also need a tar binary installed and in your path which understands GNU Tar options. You might also need the Perl module LWP::UserAgent, which you can install with the sudo perl -MCPAN -e 'install LWP::UserAgent' command.
For inventory modifications to work (like for command payment with -buy), you will need the Perl modules IO::Compress::Gzip and IO::Uncompress::Gunzip. If you don't seem to have them (you'll know if you get an error about them when you launch tztk-server.pl), you can use something like sudo perl -MCPAN -e 'install IO::Compress::Gzip, IO::Uncompress::Gunzip' to install them.
Download
You can download a tar/gzip of tztk; it was last built on 2013-10-31 at 12:18 EDT and is 8980 bytes. Its MD5 hash is 9fa6668d, and its SHA256 hash is abcdf20c. If you like, you can also clone the Git repository with git clone http://minecraft.topazstorm.com/topaz-minecraft-smp-toolkit.git to fork or work on a patch.
Donate
Todo
- - Have -wp detect when it fails to teleport the player and not deduct the command price in that case.
- - Configurable crafting recipes based on banked blocks.
- - Limit waypoints-per-user.
- - Show the last online time of the last N offline players or a specific player based on players/*.dat modtime.
- - Ability to jump directly to a coordinate by writing out a temporary waypoint file.
- - Merge various patches from others.
- - Allow for mods to give people an option instead of forking.
- - Catch slash commands instead of -x chats or whispers.