Got a question that the wiki doesn't answer? Ask on the forum (preferred), or join us on IRC.
WorldGuard
Regions
API
Contents
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.
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.
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)
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)
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 LocalPlayer
s and locations to Vector
s. That is illustrated in the example below.
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
StateFlag
s, useboolean allows(StateFlag flag, LocalPlayer player)
- For
StateFlag
s where you can't pass a player, useboolean allows(StateFlag flag)
- For other flags, use (this will return the correct type -- for example, the "greeting" flag automatically returns a string)
mixed getFlag(Flag flag)
return set.allows(DefaultFlag.PVP);
// ... 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.
RegionManager
first. At that point, you can call ProtectedRegion getRegion(String id)
To get a region by area, get an ApplicableRegionSet
as explained above and iterate over it:
ApplicableRegionSet
for (ProtectedRegion region : set) { // region here }
- To set a flag, use where flag is a copy of the flag from
region.setFlag(flag, flag.parseInput(plugin, sender, value))
com.sk89q.worldguard.protection.flags.DefaultFlag
(explained previously). The signature of the parseInput method iswhere ? is the relevant data type for that flag (an integer, a string, etc.). (This method used Java generics.)? parseInput(WorldGuardPlugin plugin, CommandSender sender, String input)