WorldGuardRegionsAPI

Access WorldGuard

Your plugin needs to get access to WorldGuard. You do this by accessing the plugin manager on the server, which you can access within your plugin.

Example: Getting a reference to WorldGuard

import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
import org.bukkit.plugin.Plugin;
 
private WorldGuardPlugin getWorldGuard() {
    Plugin plugin = getServer().getPluginManager().getPlugin("WorldGuard");
 
    // WorldGuard may not be loaded
    if (plugin == null || !(plugin instanceof WorldGuardPlugin)) {
        return null; // Maybe you want throw an exception instead
    }
 
    return (WorldGuardPlugin) plugin;
}

As of newer versions of WorldGuard, you can also use a static method that caches the instance of the plugin and stores it for you.

Example: Getting a reference to WorldGuard via WGBukkit

import com.sk89q.worldguard.bukkit.WGBukkit;
 
// now any time you need to access the Worldguard plugin
// for example, to get all the regions at a point
    ApplicableRegionSet set = WGBukkit.getRegionManager(world).getApplicableRegions(location);

Check out the javadocs at the javadoc site.

Simple permission queries

Once you've gotten access to WorldGuard, you can do simple "can build?" checks given a player using either of these methods that are available on WorldGuardPlugin:

• boolean canBuild(org.bukkit.entity.Player player, org.bukkit.Location location)

• boolean canBuild(org.bukkit.entity.Player player, org.bukkit.block.Block block)

Example: Checking if a player can change the block underneath

return getWorldGuard().canBuild(player,
        player.getLocation().getBlock().getRelative(0, -1, 0));

Region managers

WorldGuard has a global region manager followed by individual region managers for each world. However, to simplify developer access to the API, there's a simple method on WorldGuardPlugin to let you access the individual region managers.

• com.sk89q.worldguard.protection.manager.RegionManager getRegionManager(org.bukkit.World world)

Warning: The method can return null, indicating that region support is disabled for the given world.

Example: Getting the region manager for a world

return getWorldGuard().getRegionManager(world);

To get the flags or build information for a point, you need a ApplicableRegionSet, which stores information about the applicable regions at a given point. With it you can query information flags and other features at that specific point. Once you've gotten a set, it is a simple matter of querying the methods on it. However, be aware that because WorldGuard abstracts classes this deep, you will have to convert players to LocalPlayers and locations to Vectors. That is illustrated in the example below.

Example: Checking for build access using an ApplicableRegionSet

import com.sk89q.worldguard.protection.managers.RegionManager;
import com.sk89q.worldguard.protection.ApplicableRegionSet;
import static com.sk89q.worldguard.bukkit.BukkitUtil.*;
 
WorldGuardPlugin worldGuard = getWorldGuard();
Vector pt = toVector(block); // This also takes a location
 
RegionManager regionManager = worldGuard.getRegionManager(world);
ApplicableRegionSet set = regionManager.getApplicableRegions(pt);
return set.canBuild(localPlayer);

Checking flags

Flags are stored in com.sk89q.worldguard.protection.flags.DefaultFlag, which is a class with a number of static fields for each class. (It is not possible to add your own flags yet.) You'll need access to a ApplicableRegionSet (shown above). To query a flag's state, you need to call the correct method. This depends on the type of flag:

• For StateFlags, use

  boolean allows(StateFlag flag, LocalPlayer player)

• For StateFlags where you can't pass a player, use

  boolean allows(StateFlag flag)

• For other flags, use

  mixed getFlag(Flag flag)

  (this will return the correct type -- for example, the "greeting" flag automatically returns a string)

Example: Checking the PvP flag

return set.allows(DefaultFlag.PVP);

Tip: A sample of DefaultFlag's contents:

// ...
public static final StateFlag PVP = new StateFlag("pvp", 'p', true);
public static final StateFlag TNT = new StateFlag("tnt", 't', true);
// ...

Accessing a region

Region objects are all subclasses of com.sk89q.worldguard.protection.regions.ProtectedRegion. There are different subclasses for different shapes, such as ProtectedCuboidRegion or ProtectedPolygonalRegion. To get at one of these region objects, you can either fetch it by name or fetch it by location. If you are fetching it by location, you may end up with a list of regions.

To get a region by name, you'll have to get the appropriate RegionManager first. At that point, you can call

ProtectedRegion getRegion(String id)

to get the region (or null if it doesn't exist).

To get a region by area, get an ApplicableRegionSet as explained above and iterate over it:

Example: Iterating over an ApplicableRegionSet

for (ProtectedRegion region : set) {
    // region here
}

• To set a flag, use

  region.setFlag(flag, flag.parseInput(plugin, sender, value))

  where flag is a copy of the flag from com.sk89q.worldguard.protection.flags.DefaultFlag (explained previously). The signature of the parseInput method is

  ? parseInput(WorldGuardPlugin plugin, CommandSender sender, String input)

  where ? is the relevant data type for that flag (an integer, a string, etc.). (This method used Java generics.)

Javadocs

• Javadocs