Blacklist

The blacklist allows an action (or several) to be performed whenever a player does something (place a block, use an item, etc.). Some example applications include:

• Blocking players from mining gold ore

• Notifying all administrators when a diamond block is found

• Sending the player a message when they place an enchantment table

An example of a blacklist file is:

# Deny lava buckets
[lava_bucket]
ignore-groups=admins,mods
on-use=deny,tell
message=Sorry, you can't use lava buckets!

# Deny some ore
[gold_ore,iron_ore]
ignore-groups=admins
on-break=deny,tell,notify

# No TNT!
[tnt]
ignore-groups=admins
on-place=deny,notify,kick

Blacklist Files

For every world, you will find per-world configuration files:

• worlds/world/blacklist.txt

• worlds/world_nether/blacklist.txt

• worlds/mining_world/blacklist.txt

Hint

Unfortunately, you cannot share one blacklist file for several worlds from within WorldGuard. However, you may be able to create a “symlink” on your operaitng system to have two files refer to the same one.

The Format

A blacklist file consists of several sections in the format of:

[a list of items/blocks to match]
event to watch=what to do
event to watch=what to do
event to watch=what to do
option=value

Lines starting with # are ignored by WorldGuard. You can use this to place notes for yourself.

Matching Syntax

Items and blocks can be matched by specifying one of the entries on Bukkit’s material list. Multiple items and blocks can be matched by separating each entry by a comma:

[oak_wood,brick,glass]

Events

Now that you have specified the items or blocks to watch out for, you must specify the situations in which you would like to catch, as well as the action to perform.

The available events are listed below.

Event	Explanation
on-break	When the matched block is being mined
on-destroy-with	When the matched item or block is being held by the player during mining
on-place	When the matched block is being placed
on-use	When an item in the player’s inventory is used
on-interact	When a player interacts (i.e. right click) with the matched block (door, lever, etc.)
on-drop	When the player drops the matched item
on-acquire	When the player acquires the matched item
on-dispense	When a dispenser dispenses the matched item
on-equip	When the player equips the matched item

When specifying an event, a list of “actions” must be specified afterwards, as illustrated below:

[enchantment_table]
on-place=deny,tell
on-drop=notify

Available Actions

Multiple actions can be specified for each event.

Action	Explanation
deny	Denies the action (only if the blacklist not in “whitelist mode” (explained later))
allow	Permits the action (only if the blacklist is in “whitelist mode”)
notify	Notify admins with the worldguard.notify permission
log	Log to console, file, or database
tell	Tell the player that the action was not allowed
kick	Kick the player
ban	Ban the player

Options

Options are specified in the same place as events, as illustrated below:

[enchantment_table]
on-place=deny,tell
message=Sorry, you can't use enchantment tables!

In this case, message is an option that overrides the message used by the “tell” action.

Option	Explanation
ignore-groups	Comma-separated list of permission groups to not affect
ignore-perms	Comma-separated list of permissions to not affect – make up your very own permissions!
comment	Message for yourself that is printed with log and notify actions (to override the default message)
message	Message to show the user (to override the default message). Put %s in the message to have it be replaced with the item name (in English)

Whitelist Mode

Switching the blacklist to whitelist mode (via the Configuration) will invert the behavior. Only entries with the allow action will be permitted.

Tip

Whitelist mode may seem very restrictive. To place a block, you would need to allow using the block (the item in the player’s hand), interacting with the existing block (in the world, that’s being clicked to place “on”), and placing the block. You may find Build Permissions easier to use since it supports wildcards (in permission nodes) depending on your use case.

Examples

Example: Blocking some bucket use

[lava_bucket,water_bucket,bucket]
on-use=deny,tell

Example: Kicking players using TNT and notify administrators

[tnt]
ignore-groups=admins
on-place=deny,notify,kick

Example: Allowing only the people in the “obsidian” group and administrators to use obsidian

[obsidian]
ignore-groups=admins,obsidian
on-place=deny,tell
on-break=deny,tell

Logging

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

• Console

• File

• Database

These log targets can be enabled or disabled in the Configuration. Multiple log targets can be enabled at one time. By default, only the console log target is enabled.

Console Logging

Console logging merely prints the log entries to the server console.

File Logging

File logging writes the log entries to a file. In the Configuration, the path for the log file can be specified with special variables in it (like today’s date), so you can have logs automatically rotated every day.

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 “%”

Database Logging

WorldGuard can write the log entries to a MySQL database. However, you will have to create the database and table yourself first. The SQL needed to create the table is provided below:

CREATE TABLE IF NOT EXISTS `blacklist_events` (
 `id` int(11) NOT NULL AUTO_INCREMENT,
 `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,
 PRIMARY KEY (`id`)
);