Bukkit

Quickstart Guide

Installation

• If you want economy-based tunnelling costs or permission group checking, you will need to have Vault installed, along with a properly-configured economy and/or permissions plugin.
• Copy PortableHole.jar into bukkit/plugins and restart/reload your server.
• Edit bukkit/plugins/PortableHole/config.yml to your liking (see Configuration) and type ph reload to reload the edited configuration.

Before You Start

Server admins: make sure you have permission to run all PortableHole commands - if you're using a permissions plugin, give yourself the portablehole.admin permission node, or if you're not using a permissions plugin, ensure that you have op status.

Players: the default set of permissions granted should be fine.

Configuring

All configuration for the plugin is stored in bukkit/plugins/PortableHole/config.yml. This file should be edited directly - any changes will be pulled in when the /ph reload command is run (or the server is restarted). See Configuration for a full list of what can be changed.

If your players' primary language is not English, you might wish to update the book_title, default_book_text and messages configuration settings to localise all plugin text and messages. book_title in particular should be changed before any players get portable hole books, since the title is what is checked. If book_title is changed after players get their books, those books will cease to function, and players will need to get new books with the updated title.

Setting up Costs

You will probably wish to define what costs players must pay to create holes (or at least review and modify the default costs in config.yml). See Costs for a full description of defining tunnelling costs.

Getting a Book

PortableHole uses written book items as the "wand" item for creating holes. The book must have a title of Portable Hole (or whatever the definition of the book_title config setting is). There are three ways to get a book:

• You can craft a book & quill item and sign it with the right title.
• You can craft a tunnelling book directly: see Crafting a Book.
• You can use the /ph give command to give yourself a pre-written book. (You can also use /ph give <player> to give a pre-written book to someone else). This needs the portablehole.commands.give permission, only available to ops by default.

Digging a Hole

The easiest part! Just left-click a block while holding the tunnelling book, and the plugin will try to create a tunnel for you.

• If the tunnel would be too long (more than 31 blocks by default but see max_tunnel_length.horizontal and max_tunnel_length.vertical config settings) or certain blacklisted blocks are encountered (by default any block with a tile entity associated, such as chests, furnaces, crafting benches...), then tunnel creation will fail.
• If you don't have the portablehole.cost.exempt permission and you can't afford the creation cost, tunnel creation will fail.
• If some other plugin (i.e. a terrain protection plugin such as WorldGuard) cancels a BlockBreakEvent for any block in the tunnel, tunnel creation will fail.

Otherwise a tunnel will open up with an associated sound and particle effect!

You can create both horizontal and vertical tunnels, depending on whether you click the side or the top/bottom of the block. Horizontal tunnels are two blocks high (with the clicked block being the upper layer), but note that each 2x1 "gap" counts as a single block-length for costing and tunnel lifetime purposes. (E.g. a horizontal tunnel 5 blocks long actually contains 10 blocks - 5x2x1 - but is costed for 5 blocks, not 10).

Danger!

You have a limited time to get through the tunnel, so don't hang around. By default tunnel lifetime is 15 ticks plus 20 ticks for block of tunnel length, e.g. a tunnel through a one-block thick wall will last for 1.75 seconds, while a tunnel through 10 blocks of ground will last 10.75 seconds. This is configurable; see the lifetime.initial and lifetime.per_length settings in Configuration.

Be very careful about downward tunnels, especially those created below Y=32. Apart from falling damage (unless you have a way of cancelling it), a vertical tunnel will descend to bedrock if possible, and you may find yourself unable to dig horizontally to get out of the hole before it closes up. You could also end up falling into a cavern with lava at the bottom. Jumping into a hole without looking first is just a bad an idea as digging straight down - don't do it!

If the tunnel closes on you while you're in it, you will take suffocation damage, so take care! But you can use your tunnelling book to create a new hole even while entombed.