开发者帮助 API - bluesadi/ResidenceChineseTutorial GitHub Wiki

开发者API

Residence最新的开发版本包括一个开发者API，其功能是能够添加和处理你自己的标志(flags)，以及支持一些自定义Bukkit事件。该教程会给Residence附属插件的开发者提供更多帮助。此外，如果你需要Residence的API目前还不提供的函数，请将你的需求发布至Residence在SpigotMC上的帖子。你可以在下载界面找到你所需要的文件。

添加你自己的标志

在阅读以下教程之前，该教程默认你对Bukkit的开发、如何添加依赖jar文件以及如何使用Bukkit提供的Listener类已经相当熟悉。
为了开始这个教程，假设你现在正在为Residence添加一个“build”标志。
第一步: 首先，将Residence.jar作为你插件的依赖文件。
第二步: 现在你需要告诉Residence:"build"是一个有效的标志,我们可以通过FlagPermissions类来达成这个目的:

FlagPermissions.addFlag("build");

第三步: 现在我们需要真正执行这个标志了。为了添加“build”标志，我们需要将代码添加到一个名为onBlockPlace()的Bukkit监听器方法中。首先，我们需要确定所放置的方块是否在领地内。我们可以通过尝试在方块放置位置获取有效的ClaimedResidence对象来实现：

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

现在我们需要进行一个空指针检查：

if(res!=null)

如果res字段为null，那么该位置不存在领地，如果res字段不为null，那么我们需要检查并查看该领地是否允许“build”标志。首先，我们需要获得Residences权限:

ResidencePermissions perms = res.getPermisssions();

现在我们需要检查该领地是否允许放置方块，如果不允许，那么我们就取消这个事件

String playerName = event.getPlayer().getName();
boolean defaultValue = true;

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

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

第四步(可选) 如果你想让你的标志在整个世界有效（当不在领地内时），我们可以在res == null时进行不同的检查。首先，我们需要获取世界的权限列表（World permissions list）：

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

然后使用与第三步中相同的方法playerHas()来检查这个标志：

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

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

第五步(合并了第三步和第四步): 如果你不关心确定某个位置是否有领地，并且只是想检查某个玩家是否被允许在特定位置做某事，你还可以使用更简单的方法来获取一个FlagPermissions：

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

如果该位置不存在领地，那么这个方法将自动返回该世界的权限列表，从而将两次检查合并为一次。

自定义Bukkit事件

你可以使用许多自定义的Bukkit事件。要使用它们，你需要创建一个类继承Bukkit的CustomEventListener。然后覆写onCustomEvent()方法：

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

在主类中注册:

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

现在你可以开始监听Residence的事件了!

Residence事件一览:

  • ResidenceCommandEvent - 当玩家使用Residence插件的指令时触发该事件。
  • ResidenceFlagChangeEvent - 当一个领地的标志(flag)被改变的时候触发该事件。 (Cancellable)
  • ResidenceFlagCheckEvent - 用指令检查一个领地的标志时触发该事件。 (返回值可以被覆写)
  • ResidenceEnterEvent - 当玩家进入一个领地时触发该事件。
  • ResidenceLeaveEvent - 当玩家离开一个领地时触发该事件。
  • ResidenceOwnerChangeEvent - 当一个领地的所有者改变时触发该事件。
  • ResidenceCreationEvent - 当一个新的领地被创建时触发该事件。 (Cancellable)
  • ResidenceDeleteEvent - 当一个领地被删除时触发该事件。 (Cancellable)
  • ResidenceRentEvent - 当一个领地被租借时触发该事件。 (Cancellable)
    后续也可能会添加更多事件。

为了判断你在CustomEventListener类中所监听到的Event对象，你需要使用java中的instance关键字对对象的类型进行检查:

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

等等...所有的Residence事件都可以通过getResidence()方法获取对应的ClaimedResidence对象。

其他API方法

Residence API还有许多其他功能。每个Residence的子系统都有一种“管理器(Manager)”。每个管理器都可以通过Residence的主类的静态方法获得：

ResidenceManager rmanager = Residence.getResidenceManager();
//SelectionManager - 管理领地的选择点(即确定领地区域的位于对角线上的两个点)
SelectionManager smanager = Residence.getSelectionManager();
//EconomyManager - 返回Residence所绑定的一个经济插件的实例的接口。

EconomyInterface econ = Residence.getEconomyManager();
//ConfigManager - 管理插件从配置文件中导入的设置

ConfigManager cmanager = Residence.getConfigManager();
//PermissionManager - 管理从配置文件中导入的权限组并链接Residence所绑定的权限插件

PermissionManager pmanager = Residence.getPermissionManager();
//WorldFlagManager - 管理适用于整个世界的标志

WorldFlagManager wmanager = Residence.getWorldFlags();

除此之外还有更多的Manager，以上仅仅列出了比较重要的部分。

保证Residence首先启动(译者添加)

在plugins.yml中添加以下代码:

depend: [Residence]

即可

手动启动Residence(译者注:请使用上面的方法保证Residence在你的插件之前启动)

如果你的插件名称以“R”之前的字母开头，那么你的插件很可能会在Residence之前启动。如果你需要立即使用Residence的方法，这可能导致很糟糕的结果，因为Residence尚未完全初始化。为了安全起见，你需要检查Residence是否存在并已启动:

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);
}
⚠️ **GitHub.com Fallback** ⚠️