┌──────────┐  registerCapability   ┌──────────────┐  getCapability   ┌──────────┐
│ Title    │ ─────────────────────→│  Capability  │←──────────────── │ EventPkt │
│ Module   │  TitleGrantable.class │  Registry    │  TitleGrantable  │ Module   │
└──────────┘                       └──────────────┘                  └──────────┘

// 提供方：注册
context.registerCapability(TitleGrantable.class, titleService);
 
// 使用方：查找（务必判空）
TitleGrantable title = context.getCapability(TitleGrantable.class);
if (title != null) {
    title.giveTitle(player.getUniqueId(), "hero", "7d", "MyModule");
}

MapNavigable map = AxsCapabilities.get(MapNavigable.class);
if (map != null) {
    map.openMenuFor(player, targetId);
}

public interface TitleGrantable {
    boolean giveTitle(UUID playerId, String titleId, String duration, String source);
}

public interface TitleConfigQueryable {
    TitleInfo queryTitle(String titleId);
    record TitleInfo(String displayName, String qualityName, String description) {}
}

public interface MailDispatchable {
    MailSendResult sendMail(MailSendRequest request);
    MailSendResult dispatchPreset(MailPresetRequest request);
}

// 获取（外部插件唯一入口；AXS 模块内部用 getCapability(AxsMailService.class) 取同一实例）
AxsMailService service = AxsCapabilities.get(AxsMailService.class);
if (service == null) return; // mail 模块未启用

public interface ChatCardSendable {
    boolean sendChatCard(Player player, String cardId, Map<String, String> data);
}

public interface ChatMutable {
    String mutePlayer(String playerName, Instant expiresAt, String reason, String mutedBy);
    String unmutePlayer(String playerName);
    boolean isMuted(UUID playerUuid);
    List<MuteInfo> listMutes();
    record MuteInfo(UUID playerUuid, String playerName, String mutedBy,
                     String reason, Instant createdAt, Instant expiresAt) {}
}

public interface SubtitlePlayable {
    boolean playGroup(Player player, String groupId);
}

public interface SignalDispatchable {
    void dispatchSignal(String signal, Player subject, Map<String, String> variables);
}

public interface CombatEffectTriggerable {
    boolean triggerPacket(String packetId, Player recipient, Map<String, String> variables);
    boolean triggerDirect(String uiId, String packetHandler, Player recipient, Object payload);
}

public interface MapNavigable {
    void upsertExternalTarget(Player player, MapExternalTargetSpec spec, boolean select);
    void upsertExternalTargets(Player player, List<MapExternalTargetSpec> specs);
    void reconcileExternalTargets(Player player, String source, List<MapExternalTargetSpec> specs);
    void clearExternalTargets(Player player, String source, boolean syncView);
    void setExternalNavigated(Player player, String targetId, boolean navigated);
    boolean navigateExternalTarget(Player player, String targetId);
    void registerNavigationSource(Plugin owner, String source, MapNavigationHandler handler);
    void unregisterNavigationSource(String source);
    void setNavigationDelegate(Plugin owner, MapNavigationDelegate delegate);
    void clearNavigationDelegate(Plugin owner);
    boolean hasNavigationDelegate();
    void clearTrack(Player player);
    void openMenuFor(Player player, String targetId);
}

public interface MapNavigationHandler {
    boolean onNavigateRequest(Player player, String targetId); // true=已接管；false=提示导航失败
    default void onCancelRequest(Player player, String targetId) {} // 停止自身导航，标记保留
}

public interface MapNavigationDelegate {
    // 玩家请求开始导航；true=已接管（地图记录委托态），false=交还原处理方
    boolean onNavigateRequest(Player player, MapNavigationRequest request);
    // 委托态被终止（玩家取消/互斥清除/来源接管/退出关闭），实现需幂等
    default void onCancelRequest(Player player, MapNavigationRequest request) {}
}

public interface QuestGpsNavigable {
    void offerQuest(Player player, String questId, boolean openMenu);
    void acceptQuest(Player player, String questId);
    void openMenu(Player player);
    void trackQuest(Player player, String questId);
    void trackTask(Player player, String questId, String taskId);
    boolean eventRuleLocked(Player player, String ruleId);
    boolean moduleEntryLocked(Player player, String moduleEntryId);
}

public interface TabRefreshable {
    void requestViewerRefresh(Player viewer, String reason);
    void requestGlobalRefresh(String reason);
}

public interface MenuOpenable {
    boolean openMenu(Player player, String menuId);
    void refreshMenu(Player player);
}

public interface AfkRewardDispatchable {
    boolean isAfk(UUID playerUuid);
    String getAreaName(UUID playerUuid);
    int getAfkSeconds(UUID playerUuid);
    String getAfkMode(UUID playerUuid);  // "REGION" / "MANUAL" / null
    boolean startManualAfk(Player player, String areaName);
}

public interface WarehouseAutoDepositable {
    DepositResult depositToPersonalWarehouse(Player player, ItemStack itemStack);
    record DepositResult(boolean success, long storedAmount, int remainingAmount, String message) {}
}

public interface PickupNotifiable {
    boolean isNotificationActive(UUID playerId);
    boolean notifyPickup(Player player, ItemStack itemStack, int amount);
}

public interface PickupInterceptor {
    boolean isAutoPickupIntercepted(UUID playerId);
}

public interface ExtraBackpackAccess {
    boolean isAvailable(Player player);
    Snapshot snapshot(Player player);
    DepositResult deposit(Player player, ItemStack itemStack);
    WithdrawResult withdraw(Player player, String categoryId, int slot, int amount);
    // record Snapshot, CategorySnapshot, SlotSnapshot, DepositResult, WithdrawResult
}

public interface AxsMarketService {
    enum MarketView { AUCTION, AUCTION_SELL, SHOP_LIST, SHOP, RECYCLE,
                      HISTORY, SELL, PLAYER_SHOP, MY_LISTINGS }
    void openUi(Player player, MarketView view);
    CompletableFuture<Boolean> createAuctionListing(Player player, ItemStack item,
                              double startingBid, String currency, long durationSeconds);
    CompletableFuture<Boolean> cancelListing(Player player, long listingId);
    CompletableFuture<Boolean> searchAuction(Player player, String keyword);
    int auctionCount();
    int shopCount();
    int myListingCount(Player player);
    boolean playerShopEnabled();
}

public interface BattlePassAccess {
    boolean isSeasonActive();
    int addXp(Player player, int xp);           // 返回增加后的总经验
    void setXp(Player player, int xp);
    void removeXp(Player player, int xp);
    void setLevel(Player player, int level);
    boolean unlockTier(Player player, String tier);  // "PREMIUM" / "DELUXE"，大小写不敏感
    int claimAllRewards(Player player);          // 返回领取的奖励份数
    void updateTaskProgress(Player player, String taskId, int increment);
    void resetProgress(UUID playerUuid);         // 重置本赛季进度
}

public interface FishingAccess {
    boolean isInMinigame(UUID playerUuid);
    boolean startMinigame(Player player);        // 鱼竿/条件不满足返回 false
    int collectionCount(UUID playerUuid);
    int totalFishTypes();
    void giveXp(UUID playerUuid, int amount);
    int fatigue(UUID playerUuid);
    void setFatigue(UUID playerUuid, int value);
    boolean claimReward(Player player, String rewardId);
    String sellAllFish(Player player);           // 返回结果提示消息
}

public interface RegionQueryable {
    List<RegionInfo> regionsAt(String world, int x, int y, int z); // 按优先级排序
    List<RegionInfo> regionsInWorld(String world);
    List<RegionInfo> allRegions();
    int countRegionsByOwner(UUID owner);
 
    record RegionInfo(String id, String world,
                      int minX, int minY, int minZ,
                      int maxX, int maxY, int maxZ,
                      int priority, String parentId,
                      Set<UUID> owners, Set<UUID> members) {
        boolean contains(String world, int x, int y, int z);
        boolean hasAccess(UUID playerUuid); // owner 或 member，不含权限组判定
    }
}

public interface BossTrackerQueryable {
    boolean isTrackedBoss(UUID entityUuid);
    int activeSessionCount();
    int activeViewerCount();
    List<BossSessionInfo> activeSessions(String mobIdFilter); // null = 不过滤
 
    record BossSessionInfo(UUID entityUuid, String mythicMobId, String displayName,
                           double health, double maxHealth,
                           int participantCount, int trackedPlayerCount,
                           double totalDamage) {}
}

public interface LotteryAccess {
    long getPoint(UUID playerUuid, String pointId);
    Map<String, Long> getPoints(UUID playerUuid);
    boolean givePoints(UUID playerUuid, String pointId, long amount);
    boolean exchange(Player player, String itemId);
    List<CaseDrawResult> openCase(Player player, String poolId, int count); // 开箱动画照常播放
 
    record CaseDrawResult(String rarity, int poolIndex,
                          String itemKey, String itemName, int amount) {}
}

public interface LoginViewQueryable {
    boolean isAuthenticated(Player player);
    boolean isRegistered(Player player);
    void openFor(Player player);
    void openFor(Player player, boolean force); // force=true 已认证也强制打开
}

public interface PropAccessible {
    List<String> propIds();
    PropApplyResult applyPropToMainHand(Player player, String propId);
 
    record PropApplyResult(boolean success, String message) {}
}

public interface AnnouncerBroadcastable {
    void broadcastNow(String text);               // 立即播报，打断当前展示
    void broadcastNow(String text, boolean forward);
    void enqueue(String text, boolean forward);   // 加入队列，当前展示结束后播报
}

public interface RgbRenderable {
    String render(String entryId, OfflinePlayer player); // player 可为 null；条目不存在返回空串
    List<String> entryIds();
}

public interface OnlineRewardsQueryable {
    boolean hasSignedToday(UUID playerUuid);
    int todayOnlineMinutes(UUID playerUuid);
    int weeklyOnlineMinutes(UUID playerUuid);
    int monthlyOnlineMinutes(UUID playerUuid);
    boolean signIn(Player player);
    boolean makeupSignIn(Player player, String date);   // yyyy-MM-dd
    boolean addMakeupCards(Player player, int amount);
    void grantDailyRewards(Player player);
    boolean addOnlineMinutes(Player player, int minutes);
}

public interface EventBusCapability {
    void publish(String topic, Player player, Object payload);
    void publish(String topic, Player player, Map<String, String> payload); // 向后兼容
    void registerPublisher(String topic);
    boolean hasPublisher(String topic);
    String subscribe(String topic, EventHandler handler);  // 支持通配符 "axs.market.*"
    void unsubscribe(String subscriptionId);
    record BusEvent(String topic, Player player, Object typedPayload, long timestamp) {}
    @FunctionalInterface interface EventHandler { void handle(BusEvent event); }
}

EventBusCapability bus = context.getCapability(EventBusCapability.class);
if (bus != null) {
    // 发布（AXS 内置主题统一 axs.<模块id>.<事件名> 前缀）
    bus.publish("axs.market.listing_created", player, Map.of("price", "1000"));
    // 订阅
    String subId = bus.subscribe("axs.market.*", event -> {
        logger.info(event.player().getName() + " 触发了 " + event.topic());
    });
    // 取消订阅
    bus.unsubscribe(subId);
}