事件

监听方式

Dominion 事件是 Bukkit 事件。附属实现 Listener，在 onEnable() 中注册即可：

public final class DominionListener implements Listener {
    @EventHandler
    public void onEnter(PlayerMoveInDominionEvent event) {
        DominionDTO dominion = event.getDominion();
        event.getPlayer().sendMessage("进入领地：" + dominion.getName());
    }
}

getServer().getPluginManager().registerEvents(new DominionListener(), this);

事件中的 Player、Location、世界和实体操作仍然遵守 Bukkit/Paper/Folia 的线程要求。不要在高频移动事件中执行数据库扫描或阻塞 IO。

玩家移动事件

事件	关键数据	说明
PlayerMoveInDominionEvent	getPlayer()、getDominion()	玩家进入一个领地
PlayerMoveOutDominionEvent	getPlayer()、getDominion()	玩家离开一个领地；因领地删除触发时 getDominion() 可能为 null
PlayerCrossDominionBorderEvent	getPlayer()、getFrom()、getTo()	统一表示进入、离开或从一个领地移动到另一个领地

在边界事件中：

• from == null 表示从无领地区域进入领地；
• to == null 表示从领地离开到无领地区域；
• from 和 to 都不为 null 时表示两个领地之间的切换。

如果只关心进入或离开，优先监听专门的 PlayerMoveInDominionEvent 或 PlayerMoveOutDominionEvent。

数据操作事件

领地

cn.lunadeer.dominion.events.dominion 和其 modify 子包提供：

DominionCreateEvent、DominionDeleteEvent、DominionReSizeEvent、DominionRenameEvent、DominionTransferEvent、DominionSetTpLocationEvent、DominionSetMessageEvent、DominionSetMapColorEvent、DominionSetEnvFlagEvent、DominionSetGuestFlagEvent。

这些事件通常包含操作人、目标领地、旧值和新值。可修改的新值包括名称、边界、所有者、传送点、消息、地图颜色和 flag 值；能否修改以具体事件的公开 setter 为准。

组和成员

数据	事件
组	GroupCreateEvent、GroupDeleteEvent、GroupRenamedEvent、GroupSetFlagEvent、GroupAddMemberEvent、GroupRemoveMemberEvent
成员	MemberAddedEvent、MemberRemovedEvent、MemberSetFlagEvent

取消和修改

继承 ResultEvent 的数据操作事件实现了 Cancellable。在数据处理前，附属可以取消或修改事件：

@EventHandler
public void onDominionCreate(DominionCreateEvent event) {
    if (event.getName().startsWith("reserved-")) {
        event.setCancelled(true);
        return;
    }

    // 修改将在后续 Dominion 数据处理中使用
    event.setName(event.getName().toLowerCase(Locale.ROOT));
}

event.call() 会按照 Bukkit 事件机制分发事件；Dominion 的实际数据处理在事件监听结束后继续进行。因此不要假设事件处理方法返回时，数据库写入已经完成。

获取异步操作结果

创建、添加成员、创建组等事件有对应的 Future 和 after... 回调。常见模式如下：

@EventHandler
public void onMemberAdded(MemberAddedEvent event) {
    if (event.isCancelled()) return;

    event.afterAdded(member -> {
        if (member == null) {
            // Dominion 的后续校验或写入失败
            return;
        }

        DominionDTO dominion = event.getDominion();
        getLogger().info("Added " + member.getPlayerUUID()
                + " to " + dominion.getName());
    });
}

不同事件的回调名称包括 afterCreated、afterModified、afterAdded、afterRemoved 和 afterSet。回调收到的 DTO 可能为 null，应当先判断。

不要在事件监听器中调用 getFutureToComplete().get()。Future 是由 Dominion 在后续异步流程中完成的，阻塞等待会卡住服务器线程。

自定义 Flag 注册事件

FlagRegisterEvent 提供 getPlugin()、getFlag()、setFlag(...) 和取消状态。它允许其他插件拒绝或替换待注册的 flag。附属注册 flag 时应检查 Flags.registerEnvFlag(...)/registerPriFlag(...) 的布尔返回值。

MCA 导出事件

ExportMcaListEvent 携带 List<McaRecord>，可以在 Dominion 导出领地涉及的 MCA 区域列表时读取或调整列表。它属于高级集成接口；普通附属不需要监听它。