Suite

概览

BattlePass 战令系统功能概览

BattlePass 战令系统

模块简介

BattlePass 是 Suite 的战斗通行证（Battle Pass）模块，为服务器提供完整的赛季制战令系统。玩家通过完成每日、每周和赛季任务获取战令经验（XP），升级解锁各等级奖励。模块支持免费（FREE）、高级（PREMIUM）、典藏（DELUXE）三层通行证体系，赛季结束时按等级阈值自动发放结算奖励。

模块采用 ArcartX UI 客户端面板展示战令主界面、任务列表、奖励列表和赛季结算界面，所有交互通过 Packet 通讯完成，无需服务端菜单插件。

功能特性

特性说明
三层通行证FREE（免费）/ PREMIUM（高级）/ DELUXE（典藏），每层每级独立奖励配置
赛季系统赛季 ID、显示名、等级上限、经验成长曲线（ARIA 表达式自定义）、起止日期
任务系统每日 / 每周 / 赛季三类任务池，按权重加权随机抽取分配
双事件源支持 ArcartX EventBus 主题（业务语义事件）和原版 Bukkit 事件（降级），自动检测切换
任务条件事件载荷条件（EventPayloadCondition）、玩家状态条件（PlayerStateCondition）、组合条件（any_of / all_of / not）
增量策略固定增量（FixedIncrementStrategy）和载荷值增量（PayloadValueStrategy，支持 scale / max-per-event / min-per-event）
触发限制每个任务可配置冷却时间（cooldown-ms）和每日最大计入次数（max-per-day）
等级奖励每级三档奖励，支持 item / command / currency / mail 四种奖励类型
赛季结算按等级阈值（min-level）发放结算奖励，在线直接发放，离线暂存补发
档位解锁管理命令可解锁玩家 PREMIUM / DELUXE 档位
跨服同步战令等级、任务进度、已领奖励可跨服同步
数据库迁移注册 DatabaseMigratable 能力，支持存储切换时数据迁移
玩家数据清理注册 PlayerDataPurgeable 能力，支持按 UUID 或全量清理玩家数据
ArcartX UI主界面、任务列表、奖励列表、结算界面四个 UI 面板
PlaceholderAPI提供 %axsbattlepass_xxx% 系列占位符

依赖

依赖类型名称说明
外部硬依赖PlaceholderAPI占位符扩展（external-depends 硬依赖，未安装时模块不加载）
外部软依赖MythicMobs / MythicBukkitMythicMobs 怪物击杀任务（可选）
外部软依赖Vault / PlayerPoints 等货币奖励发放（可选）
ArcartX 模块（可选）loginview、fishing、entitytracker、questgps、prop、warehouse、regions、afkreward、market、chat、combateffect发布 EventBus 事件主题供任务订阅
ArcartX 模块（可选）Mail邮件类型奖励发放（不可用时降级）

模块本身不硬依赖任何 ArcartX 模块。任务通过 EventBus 主题订阅其他模块发布的事件，对应模块不存在时自动降级到 Bukkit 原版事件或跳过。

三层通行证体系

BattlePass 提供三个档位的通行证，每个档位在每个等级都有独立的奖励配置：

档位标识获取方式XP 倍率权益
免费FREE默认1.0x可领取每级 FREE 档奖励
高级PREMIUM管理员命令解锁 / 购买1.0x可领取 FREE + PREMIUM 档奖励
典藏DELUXE管理员命令解锁 / 购买1.5x可领取 FREE + PREMIUM + DELUXE 档奖励，XP 获取倍率 1.5 倍

XP 倍率机制

  • FREE 和 PREMIUM 档位 XP 获取倍率均为 1.0x
  • DELUXE 档位 XP 获取倍率为 1.5x，即完成任务获得的 XP 乘以 1.5
  • XP 倍率在任务完成计算 XP 时生效：实际XP = 任务基础XP × 难度倍率 × 档位XP倍率

档位解锁

管理员通过命令解锁玩家档位：

/axs battlepass unlock <玩家> premium
/axs battlepass unlock <玩家> deluxe

解锁后玩家即可领取对应档位的等级奖励。档位升级是单向的：FREE → PREMIUM → DELUXE，无法降级。

任务周期详解

BattlePass 任务分为三个周期，每个周期的重置规则和分配方式不同：

周期分类重置规则分配方式数量配置
每日DAILY每天 0:00 自动重置（自然日变更）从每日任务池按 weight 加权随机抽取tasks.daily-count（默认 3）
每周WEEKLY每 7 天自动重置从每周任务池按 weight 加权随机抽取tasks.weekly-count（默认 2）
赛季SEASON赛季期间不重置所有赛季任务模板全部分配给玩家全部分配

重置检测机制

  • 模块通过定时任务（每 6000 tick ≈ 5 分钟）检测所有在线玩家的重置需求
  • 每日重置：当 lastDailyResetDate 与当前自然日不一致时触发
  • 每周重置：当 lastWeeklyResetDate 距当前日期 ≥ 7 天时触发，同时 currentWeekNumber 递增
  • 重置时删除旧任务实例，从任务池重新加权随机分配新任务
  • 赛季任务不参与重置，赛季期间一直存在

加权随机分配

任务池中每个任务模板有 weight 字段（默认 1），分配时按权重加权随机选取：

  • 权重越高，被选概率越大
  • 已选任务从候选池中移除，不会重复分配同一任务
  • 分配数量取 min(count, pool.size())，任务池不足时分配全部

难度体系

每个任务模板有 difficulty 字段，对应不同的 XP 倍率：

难度标识XP 倍率适用场景
简单EASY1.0x日常行为（登录、拾取、放置方块等）
普通NORMAL1.2x中等挑战（击杀特定怪物、累计伤害、合成等）
困难HARD1.5x高难度目标（击杀 Boss、完成成就、赛季大目标等）

任务的总 XP 奖励计算公式：

任务总XP = base-xp-reward × difficulty-multiplier × 档位XP倍率

其中 difficulty-multiplier 默认取难度对应的倍率，也可通过 difficulty-multiplier 字段手动覆盖。

数据存储

模块支持两种存储模式：

模式配置说明
共享存储（推荐）storage.shared: true使用本体 config.yml 的 storage 节配置，数据库连接由本体统一管控
自建存储（不推荐）storage.shared: false模块自建独立 HikariCP 连接池，支持 SQLite / MySQL

数据库表结构详见 联动 页面。

相关文档

  • 配置 — 主配置文件、赛季配置、任务配置、奖励配置详解
  • 任务系统 — 任务模板字段、条件系统、增量策略、事件触发源
  • 奖励系统 — 等级奖励、赛季结算奖励、奖励类型详解
  • 命令与占位符 — 玩家命令、管理命令、PAPI 占位符
  • 联动 — EventBus 事件订阅、Capability 注册、跨服同步、数据库表结构

本页目录