Got a question that the wiki doesn't answer? Ask on the forum (preferred), or join us on IRC.



From Wiki
Jump to: navigation, search

The blacklist allows you to control how blocks and items are interacted with by users. You can control what happens in the following events:

  • When a player is about to destroy a block
  • When a player is using an item to destroy a block
  • When a player is placing a block
  • When a player is using an item (lighter, bucket, etc.)
  • When a player is interacting with an item (chests, pressure plates, etc.)
  • When a player is dropping an item
  • When a player is acquiring (or has acquired) an item
  • When a player is eating something edible(Cookie, Apple, etc.)
Check out the new WorldGuard documentation for WG 6+:


The blacklist file is blacklist.txt and it can be found in plugins/WorldGuard/worlds/YourWorldName/blacklist.txt (this file is created when you first start up WorldGuard). Rules are organized by the blocks or items that they are affected. Some example rules follow. Note that the entire blacklist can be reversed in functionality by setting blacklist.use-as-whitelist to true in your world's config file.

Example: Sample rules

# Deny lava buckets

# Deny some ore

# No TNT!


Each section has:

Type Example
A list of blocks or items to affect (you can use names or IDs)
Some options (groups to ignore, etc.)
message=You can't mine %s!
comment=ore is banned here
Some events to catch (when a block is placed, etc.) and what to do

To put "comments" on a line (text that is only for yourself), put a pound symbol (#) at the very beginning of a line.


  • ignore-groups - a comma-separated list of groups to not affect
  • ignore-perms a comma-separated list of permissions to not affect (made.up.permission)
  • comment - a message for administrators that is printed with 'log' and 'notify' actions
  • message - an optional message to show the user instead for the 'tell' action; %s can be used in the message to substitute item name


  • on-break - when a block of this type is about to be broken
  • on-destroy-with - the item/block held by the user while destroying
  • on-place - when a block is being placed
  • on-use - when an item is being used (lighters, buckets)
  • on-interact - when a block is being interacted with (chests, pressure plates, etc.)
  • on-drop - the item is being dropped from the player's inventory
  • on-acquire - the item enters a player's inventory via some method


  • deny - deny completely
  • notify - notify admins (who have the /worldguardnotify permission)
  • log - log to console/file/database
  • tell - tell a player that that's not allowed
  • kick - kick player
  • ban - ban player
Warning: The ban action currently doesn't work in Bukkit.


Example: Block all bucket use
Example: Kick and notify administrators for using TNT
Example: Allow only the people in the "obsidian" group and administrators to use obsidian

Logging configuration

With the log action, messages can be logged to several places:

  • Console
  • File
  • Database

Console logging

Parameter Value Default Since Description
blacklist.logging.console.enable true/false true 1.0 Log to console.

File logging

File logging was revamped in 1.2. For file logging names, you can specify substitution variables such as the current date or the player name. If you use variables that cause many files to be created (such as a file per user or second), WorldGuard will keep a limited number of file handles open (configurable), closing older ones as necessary. If you specify directories that don't exist in the log file path, the directories will be created automatically.

The following variables can be used:

  •  %Y the year (YYYY)
  •  %m the month (MM)
  •  %d the day (DD)
  •  %W the week of the year (00-52)
  •  %H 24-hour time (HH)
  •  %h 12-hour time (HH)
  •  %i the minute (mm)
  •  %s the second (ss)
  •  %u the user's name
  •  %% translates to a single percent sign "%"
Parameter Value Default Since Description
blacklist.logging.file.enable true/false false 1.2 Log to file. integer 10 1.2 Number of files to keep open at any given moment.
blacklist.logging.file.path string worldguard/logs/%Y-%m-%d.log 1.2 Path to log to. On Windows, be sure to use two backslashes (\\) for every one (\).

Database logging

Parameter Value Default Since Description
blacklist.logging.database.enable true/false false 1.0 Log to database.
blacklist.logging.database.dsn string jdbc:mysql://localhost:3306/minecraft 1.0 Database connection string. In the default as shown, the host, port, and database are all included. Put backslashes (\) before colons (:) when specifying this.
blacklist.logging.database.user string root 1.0 Database username.
blacklist.logging.database.pass string 1.0 Database password.
blacklist.logging.database.table string blacklist_events 1.0 Table to store log.

Table SQL : WorldGuard 4

The following SQL can be run in MySQL:

CREATE TABLE `blacklist_events` (
  `event` varchar(25) NOT NULL,
  `player` varchar(16) NOT NULL,
  `x` int(11) NOT NULL,
  `y` int(11) NOT NULL,
  `z` int(11) NOT NULL,
  `item` int(11) NOT NULL,
  `time` int(11) NOT NULL,
  `comment` varchar(255) NULL,
  PRIMARY KEY (`id`)

Table SQL : WorldGuard 5

In WorldGuard 5, a field 'world' has been added:

- Use this to create a new MySQL Table :

CREATE TABLE IF NOT EXISTS `blacklist_events` (
 `world` varchar(10) NOT NULL,
 `event` varchar(25) NOT NULL,
 `player` varchar(16) NOT NULL,
 `x` int(11) NOT NULL,
 `y` int(11) NOT NULL,
 `z` int(11) NOT NULL,
 `item` int(11) NOT NULL,
 `time` int(11) NOT NULL,
 `comment` varchar(255) DEFAULT NULL,

- Use this to update the Table for WorldGuard 5 :

ALTER TABLE  `blacklist_events` ADD  `world` VARCHAR( 6 ) NOT NULL AFTER  `id`

Navigation menu