PortableHole's configuration is stored in bukkit/plugins/PortableHole/config.yml. It can be edited directly. Once editing is complete, the updated configuration can be reloaded by typing /ph reload (or by restarting/reloading the server).

Configuration Reference

author_validation.playersList of StringList of player names whose books may be used to create holes - see Author Validation belowempty
author_validation.groupsList of StringList of permission group names whose players' books may be used to create holes - see Author Validation belowempty
book_titleStringBooks must have this title to be used as tunnelling books. Note: if you change this after players have received or created tunneling books, those books will no longer function! It is recommended to set this once, before players start using the plugin.Portable Hole
default_book_textList of StringThe text that appears inside the book, if read. Unlike book_title, this can be changed at any time without breaking existing books.[ "Left-click to use!" ]
costsList of (cost,blocks)Defines the cost players pay to create holesSee Costs
crafting.enabledBooleanWhether or not to add a recipe for the tunnelling book. See Crafting a Book
crafting.recipeList of StringThe recipe for crafting a tunnelling book. See Crafting a Book
crafting.ingredientsMap of character to material nameThe materials to use for shaped recipes. See Crafting a Book
crafting.authorStringThe player name to use as the author for all crafted tunnelling books. See Crafting a Book
crafting.shapedBooleanIs the tunnelling book recipe shaped or shapeless? See Crafting a Book
effects.hole_openEffectEffect to play when a hole opens - see Effects belowsound,name=enderman_teleport
effects.hole_closeEffectEffect to play when a hole closes - see Effects belowsound,name=enderman_teleport
effects.hole_failedEffectEffect to play when hole creation fails for any reason - see Effects belowsound,name=note_bass
lifetime.initialintegerInitial lifetime in ticks for created holes15
lifetime.per_lengthintegerLifetime in ticks per block-length of created holes. A hole of length n has a lifetime of lifetime.initial + lifetime.per_length * n ticks - e.g. a one-block hole will last for 35 ticks, or 1.75 seconds.20
log_levelStringPlugin's logging level - one of FINEST, FINER, FINE, INFO, WARNING, SEVERE. Leave at INFO normallyINFO
max_tunnel_length.horizontalintegerThe maximum length that a horizontal tunnel can be31
max_tunnel_length.verticalintegerThe maximum length that a vertical tunnel can be31
particle_effectStringParticle effect to play inside an open hole. May be any visual effect from - ender_signal, potion_break, smoke, mobspawner_flames (or leave blank to disable particle effects)ender_signal
tunnellable.blacklistList of integerA list of block id's that will cause tunnel creation to fail, if encountered - by default, any block with an associated tile entity - chests, furnaces, dispensers....23,54,58,61,62,95,116,117,118
tunnellable.whitelistList of integerA list of block id's which may be tunnelled through. By default any "passable" block - i.e. a block that can be walked through - will be considered as the end of a tunnel, but you can override this by adding block id's to the whitelist.empty
verbose_chargesbooleanWhen true, players are messaged about all charges made for creating holestrue
void_tunnellingbooleanWhen true, it's possible to open tunnels into the void (Y<=0). Be careful with this setting - falling into the void isn't fun.false

Message Text

All messages displayed to players can be modified, e.g. if your players' primary language is not English. The defaults are:

messages.cant_createCan't create a hole here.
messages.too_deepCan't create a hole that deep.
messages.stoppedSomething prevents you from tunnelling here...
messages.cant_affordCan't afford to dig!
messages.creditsYou have %d tunnelling credits.
messages.gave_book"Gave a %s book to &e%s."
messages.got_book"You have been given a %s book."
messages.not_valid_authorThe author of this book isn't allowed to create holes.
messages.charge_made"Tunnelling charge taken: &e%s"

Author Validation

The author_validation.players and author_validation.groups settings are used as follows:

  1. If author_validation.players and author_validation.groups are both blank, then anybody's books can be used to create a hole.
  2. Otherwise, if the book's author is in the players list, the book can be used.
  3. Otherwise, if the book's author is in a permission group in the groups list, the book can be used. (For this to work, you must have Vault installed, along with a configured permissions plugin).
  4. Otherwise, the book cannot be used to create a hole.

This allows you to restrict whose books may be used. E.g. you might only want players in the admins permission group to be allowed to create usable tunnelling books. Note that these books can be given/traded/sold to other players - it is the book's author that is checked, not the player who is using the book.


Several settings allow you to define special effects, either sounds or visual, which are played when a particular event occurs. See the entries in Settings under effects for a list of those settings and their defaults. The format for specifying an effect is:


All effects start with effect type, followed by one or more key/value pairs. The valid effect types are:

  • sound: Play a sound that the client knows about.
  • effect: Play an effect which may be visual, audible, or both. E.g. puff of smoke, portal particles...
  • explosion: Play an explosion effect (or even a real explosion!)
  • lightning: Play a lightning effect (or even a real lightning strike!)

The valid parameters are:

Parameter nameTypeUse withDescription
volumefloatsoundSpecifies the volume of the sound, default 1.0
pitchfloatsoundSpecifies the pitch of the sound, default 1.0 (valid range appears to be 0..3)
namestringsound, effectSpecifies the Bukkit sound or effect name to play. See for a list of valid sounds, and for a list of valid effects (you may use upper or lower case).
datainteffectEffect-specific data. Not all effects need this. For SMOKE, it gives the smoke direction (4 is straight up)
radiusinteffectThe radius of the effect. Players must be within this radius to see/hear the effect. Default: 64
powerfloatexplosion, lightningThe power of an explosion or lightning strike. Any value above 0 means a real explosion or strike (for lightning, all non-zero values are equivalent). Default: 0
firebooleanexplosionIf true, explosions will also cause fires. Default: false

Leaving a setting as blank disables playing an effect for that event.


If you wanted to use piston effects instead of ender-style effects for holes, you could do:

  hole_open: sound,name=piston_extend
  hole_close: sound,name=piston_retract

Or if you want no sounds played at all:



Posts Quoted:
Clear All Quotes