主 API — LunaDeerMC

获取单例

DominionAPI api = DominionAPI.getInstance();

当 Dominion 尚未启用或初始化完成时，单例可能为 null。使用硬依赖时，在 onEnable() 获取；使用软依赖时，先判断插件状态。不要在 onLoad() 阶段使用它。

查询玩家

方法	返回值	说明
`getPlayer(String name)`	`PlayerDTO` 或 `null`	按玩家名称查询已知玩家
`getPlayer(UUID uuid)`	`PlayerDTO` 或 `null`	按 UUID 查询已知玩家
`getPlayerName(UUID uuid)`	`String`	根据 UUID 获取名称

PlayerDTO 保存的是 Dominion 已知的玩家数据，不等同于在线的 Bukkit Player。需要执行游戏世界操作时，仍要通过 Bukkit/Paper/Folia API 获取在线玩家对象。

查询领地

方法	返回值	说明
`getDominion(Integer id)`	`DominionDTO` 或 `null`	按 ID 查询；启用多服时可能查到其他服务器缓存的领地
`getDominion(String name)`	`DominionDTO` 或 `null`	按名称查询
`getDominion(Location location)`	`DominionDTO` 或 `null`	查询位置所在的领地；位置必须带有世界
`getAllDominions()`	`List<DominionDTO>`	获取全部领地
`getAllDominionsOfPlayer(UUID uuid)`	`List<DominionDTO>`	获取玩家拥有的领地
`getPlayerOwnDominionDTOs(UUID uuid)`	`List<DominionDTO>`	获取玩家作为所有者的领地
`getPlayerAdminDominionDTOs(UUID uuid)`	`List<DominionDTO>`	获取玩家拥有管理权限的领地
`getChildrenDominionOf(DominionDTO parent)`	`List<DominionDTO>`	获取指定父领地的直接子领地

getDominion(Location) 是最常用的空间查询。如果只需要查询，不要为了读取位置而调用 getPlayerCurrentDominion(Player)。

玩家当前领地

DominionDTO current = api.getPlayerCurrentDominion(player);

该方法根据玩家位置维护当前领地状态；当玩家从一个领地进入另一个领地时，Dominion 会触发相应的移动事件。没有领地时返回 null。

如果插件自行维护玩家位置状态，可以在玩家离开服务器、传送或数据失效时调用：

api.resetPlayerCurrentDominionId(player);

查询成员和组

MemberDTO member = api.getMember(dominion, player.getUniqueId());
GroupDTO group = member == null ? null : api.getGroup(member);

也可以用 getMember(DominionDTO, Player) 直接传入在线玩家，或用 getGroup(Integer id) 按组 ID 查询。getMember 的领地参数允许为 null，但附属应尽量先确认目标领地存在，避免把“没有领地”和“不是成员”混在一起。

权限和环境检查

按位置检查（推荐）

boolean canOpen = api.checkPrivilegeFlagSilence(
        block.getLocation(),
        Flags.CONTAINER,
        player
);

boolean creeperCanExplode = api.checkEnvironmentFlag(
        block.getLocation(),
        Flags.CREEPER_EXPLODE
);

PriFlag 表示玩家权限，例如 PLACE、BREAK_BLOCK、CONTAINER、TELEPORT；EnvFlag 表示领地环境规则，例如 CREEPER_EXPLODE、FIRE_SPREAD、MONSTER_SPAWN。

方法	是否提示玩家/触发相关反馈	适用场景
`checkPrivilegeFlag(Location, PriFlag, Player)`	可能会	直接作为玩家动作的权限判断
`checkPrivilegeFlagSilence(Location, PriFlag, Player)`	不会	内部逻辑、菜单预检查、后台任务
`checkEnvironmentFlag(Location, EnvFlag)`	不涉及玩家提示	判断位置的环境规则

主 API 也保留了以 DominionDTO 为参数的重载，但源码明确建议从 4.5.0 起优先使用按位置的重载。领地对象重载不会检查不推荐使用的 world-wide 权限规则。

Provider 和维护入口

DominionProvider dominionProvider = DominionAPI.getDominionProvider();
GroupProvider groupProvider = DominionAPI.getGroupProvider();
MemberProvider memberProvider = DominionAPI.getMemberProvider();

还可以通过 DominionAPI.getPlayerProvider()、getTeleportProvider()、getTemplateProvider() 和 getCopyProvider() 获取其他 Provider。各 Provider 的职责和异步约束见 Provider。

reloadCache()、reloadConfig() 和 getMcaWhiteListInitiative() 属于运维/高级接口。附属通常不应在自己的业务流程中重载 Dominion 全部缓存或配置；误用可能影响其他插件和在线玩家。

applyFlagChanges() 用于等待自定义 flag 和 flag 分组应用完成，详见 Flag。

统计接口

方法	说明
`dominionCount()`	领地总数
`groupCount()`	组总数
`memberCount()`	成员总数

启用多服务器时，部分查询和统计会合并其他服务器缓存；不要把返回值理解为单个后端进程的本地对象数量。