API

Developer API

The latest development release of Residence includes a Developer API in the form of the ability to add and act upon your own flags, as well as support for some custom Bukkit events. I will try to provide additional help in the forum thread to anyone making a Residence addon. Also, if you need a API function for your plugin that Residence doesn't currently provide, post it in the main Residence forum thread and I will try to add it. You can locate the download files on the Download page.

Adding your own flags

I am going to assume you are familiar with Bukkit, and are familier with how to add .jar files as libraries in your programming projects. I am also going to assume you know how to use Bukkit's Listener classes.

For this step by step instructions, I am going to pretend I am adding the "build" flag to Residence.

Step 1: First, add the Residence.jar as a library to your plugin.

Step 2: Now we need to tell residences that "build" is a valid flag. We can do this through the FlagPermissions class like this:

FlagPermissions.addFlag("build");

Step 3: Now we need to actually act upon this flag. Since we are adding a "build" flag, we need to add code to the onBlockPlace() Bukkit listener event. First we need to find out if the block being placed is within a Residence. We can do that by trying to get a valid ClaimedResidence object at the location of the block placement. We can do that like this:

Location loc = event.getBlock().getLocation();
ClaimedResidence res = Residence.getResidenceManager().getByLoc(loc);

Now we need to check if we actually got a residence back, by doing a null check:

if(res!=null)

If res is null, then there is no residence at that location, otherwise we got a residence and now we need to check and see if the "build" flag is allowed or not. First we need to get the Residences permissions like this:

ResidencePermissions perms = res.getPermisssions();

Now, we can do a check to see if build is allowed, and if not cancel the event:

String playerName = event.getPlayer().getName();

boolean defaultValue = true;

boolean hasPermission = perms.playerHas(playerName, "build", defaultValue);

if(!hasPermission)
 event.setCancelled(true);

Step 4 (optional): If you want to make your flag a valid world permission too (can be set for a whole world, for when not within a residence), we can then do a different check for when res == null. First we need to get the World permissions list:

String worldName = event.getBlock().getWorld().getName();
FlagPermissions perms = Residence.getWorldPermisssions(worldName);

Then, simply use the same playerHas() function we used in step 3 to check the flag:

boolean hasPermission = perms.playerHas(playerName, "build", defaultValue);

if(!hasPermission)
  event.setCancelled(true);

Step 5 (combines Step 3 and 4 into one): If you dont care about determining if there is a Residence at a location or not, and simply want to check if a player is allowed to do something at a specific location, you can also use a simplified function to get a FlagPermissions object that you can do checks on:

Location loc = event.getBlock().getLocation();
FlagPermissions = Residence.getPermsByLoc(loc);

If there is no residence at this spot, it will instead automatically pull the World permissions thereby combining both checks into one.

Custom Bukkit Events

There are a number of custom Bukkit events you can hook into. To use them, you need to create a class that extends Bukkit's CustomEventListener class. Then, Override the onCustomEvent() method like this:

public class MyListener extends CustomEventListener {
  @Override
  public void onCustomEvent(Event event) {
    //do stuff
  }
}

Create a instance of this class, and then register it with bukkit in your plugin's main class:

getServer().getPluginManager().registerEvent(Event.Type.CUSTOM_EVENT, myListener, Priority.Normal, this);

Now you can catch Residence events, which are listed in the next section.

Residence Bukkit Events

This is a list of current Residence events you can catch.

• ResidenceCommandEvent - called whenever a player uses a command registered with Residence.
• ResidenceFlagChangeEvent - called whenever a flag on a residence is changed. (Cancellable)
• ResidenceFlagCheckEvent - called whenever a check is done on a residence flag. (Return value can be overridden)
• ResidenceEnterEvent - called whenever a player enters a Residence
• ResidenceLeaveEvent - called whenever a player leaves a Residence
• ResidenceOwnerChangeEvent - called whenever the owner of a residence changes.
• ResidenceCreationEvent - called upon creating a new residence (Cancellable)
• ResidenceDeleteEvent - called upon the deletion of a residence with a query-able cause. (Cancellable)
• ResidenceRentEvent - called upon all rent related events, with a query-able cause. (Cancellable) More to come over time.

To determine which of these events has been called in your CustomEventListener class, you need to use Java's "instanceof" operator and cast each event to its proper class like this:

if(event instanceof ResidenceCommandEvent)
{
  ResidenceCommandEvent e = (ResidenceCommandEvent) event;
  //do stuff
}
else if(event instanceof ResidenceFlagChangeEvent)
{
  ResidenceFlagChangeEvent e = (ResidenceFlagChangeEvent) event;
  //do stuff
}

etc... All residence events allow access to the corresponding ClaimedResidence object using tge getResidence() method.

Other Useful API Calls

There are many other things you can do with the Residence API. There is a sort of "manager" for each Residence subsystem. Each manager can be accessed through static methods from the main Residence class: //ResidenceManager - places and controls all residences.

ResidenceManager rmanager = Residence.getResidenceManager();

//SelectionManager - controls selection points for creating residences

SelectionManager smanager = Residence.getSelectionManager();

//EconomyManager - returns a interface to the economy plugin residence has hooked into.

EconomyInterface econ = Residence.getEconomyManager();

//ConfigManager - holds the configuration settings from the config file.

ConfigManager cmanager = Residence.getConfigManager();

//PermissionManager - holds the permission groups from the config as well as links into any Permissions plugin that you may be using.

PermissionManager pmanager = Residence.getPermissionManager();

//WorldFlagManager - holds flags that apply to the whole world

WorldFlagManager wmanager = Residence.getWorldFlags();

There are more then that, but those are the more important ones.

Manually Enabling Residence

If your plugin name starts with a letter before "R", it may be that your plugin enables before Residence. This could be bad if you need immediate access to Residence functions, since Residence won't be fully initialized yet. To be safe, you may want to include code to check if Residence exists and is enabled. You can do that with this code snippet:

PluginManager pm = getServer().getPluginManager();
Plugin p = pm.getPlugin("Residence");
if(p!=null)
{
  if(!p.isEnabled())
  {
    System.out.println("<your plugin name> - Manually Enabling Residence!");
    pm.enablePlugin(p);
  }
}
else
{
  System.out.println("<your plugin name> - Residence NOT Installed, DISABLED!");
  this.setEnabled(false);
}