联动

Capability 注册

Map 模块注册以下公开能力，供其他模块与外部插件调用：

MapNavigable（公开）

地图导航能力接口，标注 @PublicCapability + @Stable——AXS 模块内部经 getCapability(MapNavigable.class) 获取，外部 Bukkit 插件经 AxsCapabilities.get(MapNavigable.class) 获取（插件需 depend: [ArcartXSuite] 或 softdepend）。

定位：地图是展示层与事件源。来源（QuestGPS / 外部插件）推送第三方插件注册路径点供玩家浏览；玩家点击"导航"时按优先级路由：全局委托 → useMapNavigation 地图代导航 → 来源 MapNavigationHandler 回调。

MapExternalTargetSpec

第三方插件注册路径点规格 record，字段：targetId / source / worldId / title / description / x / y / z / iconId / navigated / sortOrder / useMapNavigation（保留省略 useMapNavigation 的兼容构造，另有省略 iconId/navigated/sortOrder/useMapNavigation 的便捷构造）。

useMapNavigation=true 时，玩家点该目标的"导航"由地图内置导航栈执行（客户端路标 + 路径标记 + 到达判定），不回调来源 handler——来源推送后零代码获得导航能力；导航样式/到达半径/命令钩子走地图 navigation.* 配置。默认 false 走来源回调/全局委托。

MapNavigationHandler

public interface MapNavigationHandler {
    /** 玩家点击"导航"时回调；返回 true 表示已接管，false 提示"来源未提供导航支持" */
    boolean onNavigateRequest(Player player, String targetId);
 
    /** 玩家点击"取消"时回调；来源应停止自身导航，目标标记保留 */
    default void onCancelRequest(Player player, String targetId) {}
}

MapNavigationDelegate（全局委托）

setNavigationDelegate(owner, delegate) 注册的委托会先于一切导航处理拦截玩家在地图上的"导航"点击（锚点/路径点/第三方插件注册路径点；标记点 pin 不可导航不经此接口）：

public interface MapNavigationDelegate {
    // true=已接管（地图记录委托态，面板按钮切"取消"）；false=交还原处理方
    boolean onNavigateRequest(Player player, MapNavigationRequest request);
    // 委托态被终止时回调（玩家取消/互斥清除/来源接管），实现需幂等
    default void onCancelRequest(Player player, MapNavigationRequest request) {}
}

MapNavigationRequest record 携带目标完整描述：targetType（anchor/waypoint/external）、targetId、worldId、title、x/y/z、source（自有目标固定 "map"）。契约要点：

• 导航执行（信标/路径标记/追踪状态）完全由委托方负责，地图不建客户端路标
• 委托接管第三方插件注册路径点时应另调 setExternalNavigated(player, targetId, true) 驱动该目标行按钮切换
• 全服同一时间只有一个委托；重复注册由后者覆盖；owner 插件禁用时自动注销

导航互斥约定

互斥体现在跨来源层面（来源 ↔ 地图自身的锚点/路径点导航不共存；来源内部多目标并行不受此约束）：

• 来源开始自身导航 → 调 clearTrack(player) 静默清除地图导航（nav_cleared，reason=source_took_over）
• 地图开始锚点/路径点导航 → 发布 axs.map.nav_started，来源应订阅并停止自身导航

调用示例（外部插件）

MapNavigable map = AxsCapabilities.get(MapNavigable.class);
if (map == null) return; // Map 模块未启用
 
// 注册来源回调（插件 disable 时自动注销）
map.registerNavigationSource(this, "myplugin", new MapNavigationHandler() {
    @Override public boolean onNavigateRequest(Player p, String targetId) {
        startMyNavigation(p, targetId);          // 自行创建信标/路径标记
        map.setExternalNavigated(p, targetId, true); // 回推状态 → 面板按钮变"取消"
        map.clearTrack(p);                        // 互斥：清掉地图自身导航
        return true;
    }
    @Override public void onCancelRequest(Player p, String targetId) {
        stopMyNavigation(p);
        map.setExternalNavigated(p, targetId, false);
    }
});
 
// 推送目标（批量推荐 reconcile，原子替换）
map.reconcileExternalTargets(player, "myplugin", List.of(
    new MapExternalTargetSpec("target-1", "myplugin", "world",
        "击杀世界Boss", "限时目标", 128.5, 64.0, -42.0, null, false, 0)
));
 
// 打开地图并选中目标
map.openMenuFor(player, "target-1");

upsertExternalTarget/reconcile/clearExternalTargets/openMenuFor 为同步主线程操作；registerNavigationSource/unregisterNavigationSource 线程安全。

数据清理与迁移

• /axs purge 可按 UUID 或全量清理玩家地图数据（解锁记录、路径点、标记点、地图设置）
• /axs migrate map 支持 SQLite ↔ MySQL 跨源迁移

第三方插件对接方案

获取接口：AxsCapabilities.get(MapNavigable.class)（需 depend/softdepend: [ArcartXSuite] + compileOnly axs-api）。

第三方插件注册路径点"导航"点击按优先级路由：全局委托 → useMapNavigation 地图代导航 → 来源 handler → 提示「来源未提供导航支持」。按接入用途选择：

同一 source 可按目标混用：部分目标 useMapNavigation=true 交由 Map 导航，其余经来源 handler 自行执行。

第三方插件注册路径点由 Map 执行导航（useMapNavigation）

spec 设 useMapNavigation=true 后，点击"导航"由 Map 导航栈全程执行——客户端路标、路径标记、到达判定、finish-commands、按钮态翻转、取消、互斥、跨世界 cross_world_navigate：

// 推送第三方插件注册路径点：useMapNavigation=true 表示该目标的导航由 Map 执行
map.reconcileExternalTargets(player, "myplugin", List.of(
    new MapExternalTargetSpec(
        "target-1", "myplugin", "world",
        "击杀世界Boss", "限时目标",
        128.5, 64.0, -42.0,
        null, false, 0, true)
));
 
// 等价命令式入口：不经面板点击，直接由 Map 开始导航该目标（不经全局委托）
map.navigateExternalTarget(player, "target-1");

• 取消路径同样由 Map 处理：来源插件不接收 onCancelRequest，亦无需调用 setExternalNavigated（navigated 标志由 Map 维护）
• upsert/reconcile 推送新坐标时自动刷新路标；目标被 reconcile/clear 移除时其导航态一并回收
• 导航样式与行为参数（navigation.waypoint.*/finish-* 等）统一采用 Map 配置，来源插件不可按目标定制
• navigateExternalTarget 亦可在来源 handler 内按需转交：同一 source 可混用"Map 执行"与"来源自执行"的目标

第三方插件代理自身注册路径点导航（来源回调）

来源插件注册 MapNavigationHandler：玩家点击"导航"/"取消"回调至来源插件，导航执行由来源插件完成：

MapNavigable map = AxsCapabilities.get(MapNavigable.class);
if (map == null) return; // Map 模块未安装或未启用
 
// 1. 注册来源回调：source 须与 spec.source 一致；owner 插件禁用时自动注销
map.registerNavigationSource(this, "myplugin", new MapNavigationHandler() {
 
    // 玩家点击"导航"时回调
    // 返回 true 表示已接管；返回 false 则提示「来源未提供导航支持」
    @Override
    public boolean onNavigateRequest(Player player, String targetId) {
        navService.start(player, targetId);
        // 回推导航状态：面板按钮由"导航"切换为"取消"
        map.setExternalNavigated(player, targetId, true);
        return true;
    }
 
    // 玩家点击"取消"时回调：停止导航并回推按钮状态（目标标记保留在地图上）
    @Override
    public void onCancelRequest(Player player, String targetId) {
        navService.stop(player, targetId);
        map.setExternalNavigated(player, targetId, false);
    }
});
 
// 2. 推送目标（原子替换该 source 的全部目标，建议批量 reconcile）
map.reconcileExternalTargets(player, "myplugin", specs);

互斥义务：来源插件开始导航前调用 map.clearTrack(player) 清除地图导航；订阅 axs.map.nav_started，在 Map 开始导航时停止自身导航。QuestGPS 模块即采用此模式。

第三方插件代理全部地图标记点导航（全局委托）

setNavigationDelegate(this, delegate) 后，锚点/路径点/第三方插件注册路径点的"导航"点击统一回调 onNavigateRequest（标记点 pin 不可导航，不经委托）：

• 返回 true 表示接管：Map 记录委托导航态并发布 nav_started，不创建路标——路标/路径/到达判定均由委托方实现；返回 false 表示放行，移交下一级处理（可按 targetType/source 选择性接管）
• onCancelRequest 在取消/互斥/玩家退出时触发，须保证幂等；取消逻辑应以 targetType + targetId 建立稳定映射——request 坐标为尽力重解（目标已删除时为 0），不可依赖坐标
• 委托接管第三方插件注册路径点时需另调 setExternalNavigated 更新该行按钮；全局唯一委托，重复注册覆盖，owner 插件禁用时自动注销
• 边界：cross_world_navigate 的传送段（含扣费）由 Map 先行执行，成功后移交委托方；传送/解锁/路径点管理不经委托；除 onCancelRequest 外无其他生命周期回调（无到达事件）

map.setNavigationDelegate(this, new MapNavigationDelegate() {
 
    // 点击任意"导航"先回调此方法：
    // 返回 true 接管（Map 记委托态、发 nav_started，但不建路标）；
    // 返回 false 放行（第三方插件注册路径点 → useMapNavigation/来源 handler；自有目标 → Map 内置导航）
    @Override
    public boolean onNavigateRequest(Player player, MapNavigationRequest req) {
        // 示例策略：仅接管地图自有目标，第三方插件注册路径点放行给来源处理
        if (MapNavigationRequest.TYPE_EXTERNAL.equals(req.targetType())) {
            return false;
        }
        World world = Bukkit.getWorld(req.worldId());
        if (world == null) {
            return false;
        }
        // navId 必须建立稳定映射：取消回调时 request 坐标不可靠（目标已删除时为 0）
        String navId = "map-" + req.targetType() + "-" + req.targetId();
        navService.start(player, navId,
            new Location(world, req.x(), req.y(), req.z()), req.title());
        return true;
    }
 
    // 委托导航态被取消/互斥清除/玩家退出时回调；必须幂等
    @Override
    public void onCancelRequest(Player player, MapNavigationRequest req) {
        navService.stop(player, "map-" + req.targetType() + "-" + req.targetId());
    }
});
// 插件禁用时 Map 自动注销委托；也可显式调用 map.clearNavigationDelegate(this)

其他入口

• 仅展示：仅推送目标、不注册 handler，点击"导航"提示「来源未提供导航支持」（适合位置公示，可在 description 注明）
• 事件订阅：经 EventBusCapability 订阅下表主题——external_navigate 在回调/委托之前发布，各接管路径均可观测
• 打开地图：openMenuFor(player, targetId) 依次匹配第三方插件注册路径点 → 路径点 → 标记点，未命中按世界兜底打开

AXS 模块额外选项：复用导航栈

axs-api 提供可复用的导航目标/路径标记组件（Map 与 QuestGPS 的导航均构建其上）。AXS 模块实例化后可获得多目标并行登记 + 单路标单路线、到达滞回 + 命令钩子、NPC 动态跟随、跨世界提示、标题模板等能力。

此路线需要模块上下文注入的路标/NPC 桥接，仅适用于 AXS 模块，外部 Bukkit 插件不可用。

EventBus 主题

Map 模块向 EventBus 发布以下主题，其他模块/外部插件可经 EventBusCapability 订阅：

跨服同步

ArcartXMap.yml 中 worlds、anchors、waypoints 段支持跨服配置同步，其他配置段各服独立加载。

实际生效的世界/锚点定义位于 worlds/ 目录的独立文件中，多服部署需自行保持各服 worlds/ 文件一致。

数据存储

Map 模块将玩家的锚点解锁记录、路径点、标记点与地图设置存储在数据库中（SQLite 或 MySQL，支持共享存储与自建存储模式）。客户端小地图设置改动会自动同步到服务端持久化。

与其他模块联动

QuestGPS

Map 模块不存在时 QuestGPS 导航功能正常运行，仅跳过地图标记同步。

Chat（点位分享）

ArcartX Waypoint

ArcartX Waypoint 不存在时锚点/路径点导航不可用，但地图菜单、HUD 与第三方路径点转发正常使用。

Adyeshach

Adyeshach 不存在时模型导航提示自动关闭（navigation.model-marker.enabled 仍可设为 true，但运行时检测不可用后跳过），路标导航与贴图导航提示（navigation.texture-marker）不受影响。

Multiverse-Core

Vault / 货币系统

Vault 不存在时锚点解锁/传送的货币消耗不可用。配置了货币消耗但桥接不可用时，操作失败并提示「货币桥接不可用」。

物品消耗

物品匹配器配置参考 /docs/guide/item-sources 中的物品匹配器语法。

配置版本迁移

Map 模块自动将旧版本配置升级到当前版本：

模块启动时自动检测 config-version 并按序执行迁移，无需人工干预。