联动

Capability 注册

Lottery 模块通过 AbstractAXSModule.registerCapability 注册以下能力，供本体或其他模块调用：

LotteryAccess

面向外部插件的抽奖操作接口，经 AxsCapabilities.get(LotteryAccess.class) 获取；所有方法请在 Bukkit 主线程调用。

CaseDrawResult 为 API 侧 record（rarity/poolIndex/itemKey/itemName/amount），屏蔽内部 PoolItem 类型；无奖品时 itemKey/itemName 为 null、poolIndex 为 -1。

DatabaseMigratable

registerCapability(DatabaseMigratable.class, new DatabaseMigratable() {
    @Override public String moduleId() { return "lottery"; }
    @Override public MigrationResult migrateDatabase(StorageDescriptor target, boolean overwrite) {
        return repo.migrateData(target, overwrite);
    }
    @Override public StorageDescriptor currentDescriptor() {
        return repo.getDescriptor();
    }
});

当本体执行数据库迁移（如从 SQLite 切换到 MySQL）时，会调用各模块的 DatabaseMigratable.migrateDatabase，将模块数据从旧存储迁移到新存储。

PlayerDataPurgeable

registerCapability(PlayerDataPurgeable.class, new PlayerDataPurgeable() {
    @Override public String moduleId() { return "lottery"; }
    @Override public int purgePlayerData(UUID playerUuid) {
        return repo.deletePlayerData(playerUuid);
    }
    @Override public int purgeAllPlayerData() {
        return repo.deleteAllPlayerData();
    }
});

purgePlayerData 删除指定玩家在 Lottery 全部表中的数据（GACHA 状态、CASE 状态、日志、待领取奖励、积分、兑换记录），返回删除行数。purgeAllPlayerData 清空全部玩家数据。

跨模块 API 依赖

Lottery 模块在 LotteryService 构造时注入以下跨模块 API：

MailDispatchable 延迟获取

邮件能力通过 Supplier<MailDispatchable> 延迟获取，避免邮件模块加载顺序依赖：

Supplier<MailDispatchable> mailSupplier =
    () -> getCapability(MailDispatchable.class);

PrizeDistributor.sendMail 调用 MailPresetHelper.dispatchPresets 发送邮件预设。若邮件模块未安装或不可用，MAIL 投递方式返回失败，奖品不会入队（避免与邮件预设内容不一致）。

EventBus 事件

Lottery 模块当前未通过 EventBus 发布自定义事件。模块内部通过 Bukkit 事件监听器处理玩家上线/下线/交互：

跨服同步

Lottery 模块的数据存储支持共享模式（storage.shared: true），使用本体统一数据源。在多服环境下：

• 共享 MySQL：各服共用同一 MySQL 数据库，玩家抽奖状态、积分、兑换记录实时同步。
• 独立 SQLite：各服使用独立 SQLite 文件，数据不互通（不推荐多服使用）。

模块未实现跨服事件广播（如抽卡结果通知），如需跨服联动需通过本体 EventBus 或第三方插件实现。

数据库表结构

Lottery 模块使用 JdbcLotteryRepository 管理以下表，表名前缀默认为 axs_lottery_（共享模式）或配置的 table-prefix（自建模式）：

axs_lottery_gacha_state — GACHA 抽卡状态

主键：(player_uuid, pool_id)

axs_lottery_gacha_log — GACHA 抽卡日志

索引：(player_uuid, pool_id)

axs_lottery_case_state — CASE 开箱状态

主键：(player_uuid, pool_id)

axs_lottery_case_log — CASE 开箱日志

索引：(player_uuid, pool_id)

axs_lottery_pending_claim — 待领取奖励队列

索引：(player_uuid, claimed)

axs_lottery_points — 积分余额

主键：(player_uuid, point_id)

axs_lottery_exchange — 兑换记录

主键：(player_uuid, item_id)

与其他模块联动

与邮件模块联动

Lottery 通过 MailDispatchable Capability 联动邮件模块：

• 奖品 MAIL 投递：PoolItem.delivery = MAIL 时，通过 mail.presets 指定的邮件预设 ID 发送邮件
• 背包满溢出：DIRECT 投递时背包满，ItemRewardDispatcher 自动将溢出物品转邮件补发（overflowMailSubject / overflowMailBody）
• 待领取奖励：投递失败的物品入队 pending_claim 表，玩家上线时 claimPending 重新发放（背包满再次转邮件）

与货币模块联动

Lottery 通过 CurrencyBridgeAPI 联动货币模块：

• 消耗扣除：CURRENCY 消耗类型调用 bridge.withdraw(player, amount) 扣除货币
• 余额查询：UI 资源栏展示当前货币余额（bridge.balance(player)）
• 退还回滚：扣除失败或投递失败时调用 bridge.deposit(player, amount) 退还货币

与物品库模块联动

Lottery 通过 ItemSourceRegistry 联动物品库模块：

物品来源详情详见 物品来源。

与 UI 模块联动

Lottery 通过 PacketBridgeAPI 联动 ArcartX UI：

• UI 注册：模块启动时注册三个 UI 文件（lottery_gacha.yml、lottery_wish.yml、lottery_case.yml），绑定到配置的 UI ID
• UI 打开：packetBridge.openUi(player, uiId) 打开指定 UI
• 数据推送：packetBridge.sendPacket(player, uiId, subPacketId, payload) 推送数据包更新界面
• 客户端动作：ClientPacketHandler.handleClientPacket 接收客户端 UI 动作并分发处理

UI 配置写法详见 ArcartX UI 文档。

相关文档

• 概览 — 模块功能概览
• 配置 — 配置文件详解
• 命令与占位符 — 命令与 PAPI 占位符
• 跨服配置 — 多服共享数据库配置
• 物品来源 — 物品来源支持列表