联动

依赖关系

依赖	类型	说明
ArcartX 客户端 MOD	硬依赖	提供 UI 渲染与 PacketBridge，小游戏通过 ArcartX UI 呈现
PlaceholderAPI	外部依赖	提供 PlaceholderAPI 占位符（`%axsfishing_*%`）

物品库为可选功能，鱼类/宝藏/饵料/鱼竿的 item.source 按需依赖对应插件：

Fishing 模块通过 publishedTopics() 声明并发布以下 EventBus 事件主题，其他模块（如 BattlePass、QuestGPS、OnlineRewards 等）可通过 EventBusCapability 订阅：

事件主题	触发时机	Payload 字段
`axs.fishing.success`	钓鱼成功	`fish_id`, `fish_rarity`, `fish_size`, `water_area`, `bait_id`, `is_perfect`, `player_level`
`axs.fishing.perfect`	完美捕获（成功子事件）	同 success
`axs.fishing.collection_unlock`	首次捕获某鱼种	同 success + `total_collection_count`
`axs.fishing.treasure`	钓到宝藏	`water_area`
`axs.fishing.level_up`	玩家升级	`old_level`, `new_level`, `season_id`

Fishing 同时通过 SignalDispatchable 分发信号，供 EventPacket 规则引擎匹配：

Signal	触发时机	变量
`fishing_success`	钓鱼成功	`fish_id`, `fish_name`, `fish_rarity`, `fish_size`, `water_area`, `is_perfect`
`fishing_legendary_catch`	钓到传说级鱼	同上
`fishing_first_catch`	首次捕获某鱼种	同上
`fishing_treasure`	钓到宝藏	同上

Fishing 模块注册了以下 Capability，供宿主或其他模块调用：

Capability	说明
`FishingAccess`	公开 capability（`@PublicCapability`），外部插件经 `AxsCapabilities.get(FishingAccess.class)` 获取：小游戏启停、图鉴计数、经验/疲劳读写、领奖、卖鱼
`DatabaseMigratable`	支持数据库迁移，供宿主统一管理存储迁移。`migrateDatabase(target, overwrite)` 迁移数据到目标存储描述符
`PlayerDataPurgeable`	支持清除玩家数据，供宿主的玩家数据清理功能调用。`purgePlayerData(uuid)` 删除指定玩家数据，`purgeAllPlayerData()` 删除全部

面向外部插件的钓鱼操作接口（所有方法请在 Bukkit 主线程调用）：

方法	说明
`isInMinigame(uuid)`	玩家是否正处于钓鱼小游戏中
`startMinigame(player)`	启动小游戏（鱼竿/条件不满足返回 `false`）
`collectionCount(uuid)` / `totalFishTypes()`	图鉴已解锁数 / 鱼类总数
`giveXp(uuid, amount)`	增加钓鱼经验
`fatigue(uuid)` / `setFatigue(uuid, value)`	查询/设置疲劳值
`claimReward(player, rewardId)`	领取指定赛季奖励
`sellAllFish(player)`	卖出背包全部鱼获，返回提示消息

Fishing 支持跨服同步捕获记录。启用方式：

启用后，钓鱼成功的捕获记录会同步到其他子服并持久化。

模块将以下数据存储在数据库中（SQLite 或 MySQL，表名前缀默认 axs_fishing_，共享模式下无前缀）：

数据	说明
赛季数据	等级、经验、天赋点、疲惫值、已领奖励，按赛季隔离，赛季结束重置
永久数据	累计捕获/完美捕获/宝藏次数，跨赛季保留
图鉴	各鱼种捕获次数、最大尺寸、首捕时间，跨赛季保留
饵料队列	鱼竿上挂载的饵料槽位
捕获记录	主界面最近捕获记录流与跨服同步

来源	用途
Mail 模块	赛季奖励、结算奖励、疲惫值奖励、里程碑成就通过邮件预设发放
EventPacket 模块	钓鱼信号供 EventPacket 规则引擎匹配
Title 模块	捕获成就触发称号授予（如首次传说鱼、累计 10/100/500 次捕获、50 次完美捕获）
宿主核心	钓鱼事件发布到 EventBus；管理命令的水域选区使用多边形选区工具

称号授予需 Title 模块已加载。首次捕获传说鱼同时发送邮件预设 legendary_first_catch（需 Mail 模块）。

钓鱼获得的鱼物品、宝藏、额外掉落统一经物品发放通道发放：放入背包 → 背包满转仓库 → 仓库不可用转邮件 → 邮件不可用时掉落兜底。

钓鱼产物物品通过 PDC 标签标记，可供其他模块识别：