RiftRaid｜裂境讨伐

面向 Luminol 26.2 的区域线程安全 Boss 讨伐插件

功能亮点 · 下载 · 快速开始 · 命令与权限 · 配置说明 · Folia · 构建

RiftRaid 将定时 Boss、全服公告、BossBar、奖池 GUI、Vault 金币、PlayerIntensify 强化碳与 YAML / MySQL 状态存储整合为一套可配置的讨伐流程。当前提供僵尸王与铁傀儡王，模型和碰撞箱统一使用原生 Attribute.SCALE 缩放。

核心能力

能力	说明
双首领讨伐	僵尸王与铁傀儡王，拥有独立属性、刷新权重和奖励
Folia 原生调度	Region、Entity、Global 与 Async 上下文分离
战斗结算	60 格 BossBar 与刷新 Title、伤害统计、最高伤害奖励与全服聊天公告
自定义奖池	Vault 金币与 PlayerIntensify 强化碳
热切换存储	YAML、MySQL 与 MariaDB，无需重启服务器
可配置效果	聊天、Title、声音、粒子与死亡结算效果

讨伐流程

设置刷新点 → 冷却计时 → 30 / 3 / 2 / 1 秒公告 → Boss 刷新 → 全服讨伐 → 奖励结算 → 下一轮冷却

执行 /rr setspawn 会设置共用刷新点并重新开始完整冷却。默认 cooldown-seconds: 1800，因此设置后不会立即刷新 Boss。

• 倒计时只在 30 秒、3 秒、2 秒和 1 秒进行全服公告；低 TPS 跨秒时使用有限容差，状态跨重启保存且不会重复播报。
• Boss 生成时会向全服发送包含 Boss 名称和整数坐标的聊天公告；Title 与 Subtitle 只向 Boss 同世界 60 格内玩家显示。
• BossBar 默认只对 Boss 同世界 60 格内玩家可见；正好 60 格仍可见，超过范围或位于其他世界时不可见。
• 声音继续使用 effects.<stage>.sound.radius 的独立范围，不受 BossBar 或 Title 范围影响。
• /rr status 会向普通玩家说明 Boss、冷却和刷新失败原因，管理员还能查看存储、revision 与内部等待状态。

当前 Boss

Boss	实体	默认血量	缩放	定位	金币范围
僵尸王	Zombie	5,000	2.5×	均衡近战首领	100–200
铁傀儡王	Iron Golem	7,500	2.0×	高伤害重型首领	200–350

两种 Boss 共用刷新点，每轮按照独立权重随机选择。原生缩放会同时改变模型、碰撞箱和眼睛高度；逻辑高血量兼容核心属性上限，BossBar 展示实际逻辑血量，并受配置的可见范围约束。

快速开始

环境要求

• Java 25
• Luminol 26.2
• Vault 及一个兼容目标服务端的 Economy Provider
• PlayerIntensify 4.2.8

安装

1. 从 Releases 下载 RiftRaid-1.2.3.jar。
2. 将 Vault、经济插件、PlayerIntensify 4.2.8 和 RiftRaid 放入服务端 plugins 目录。
3. 启动服务器，确认依赖均已成功启用。
4. 在清理好的竞技场执行 /rr setspawn。
5. 使用 /rr status 查看完整冷却；需要立即测试时可执行 /rr spawn zombie_king。

刷新点需要至少 7 × 7 × 6 的无阻挡空间，脚下中心方块必须为实体方块。僵尸王默认碰撞箱约为 1.5 × 4.875，可在客户端使用 F3 + B 查看实际碰撞箱。

PlayerIntensify 是运行时必需依赖，但其 Jar 不会被打入 RiftRaid，也不会在本仓库重新分发。RiftRaid 只通过运行时公开 API 创建与识别强化碳。

命令与权限

命令	权限	说明
/rr、/rr help	riftraid.use	显示按权限区分的美化帮助页
/rr loot [boss]	riftraid.use	打开 Boss 奖池预览
/rr status	riftraid.use	查看 Boss、冷却、诊断与存储健康状态
/rr setspawn	riftraid.admin	设置共用刷新点并重新开始完整冷却
/rr spawn [boss]	riftraid.admin	立即提交随机或指定 Boss 刷新
/rr despawn	riftraid.admin	移除当前 Boss 并开始下一轮冷却
/rr reload	riftraid.admin	异步验证配置并热切换 YAML / MySQL

Boss 参数支持 zombie_king 与 iron_golem_king。聊天默认使用暗红色 [副本系统] 前缀，可通过 chat-prefix 修改。

奖励系统

• Vault 金币只发给最高有效伤害玩家，Boss 死亡后会公布获胜者和实际发放结果。
• 强化碳在 Boss 所属 Region 的死亡位置物理掉落，不会跨线程直接修改实体或物品状态。
• 奖池 GUI 支持僵尸王与铁傀儡王标签切换，物品名称和 Lore 均强制取消斜体。
• 每个 Boss 拥有独立金币范围、抽取次数、概率和数量。
• 概率单位为百分比，同一奖池条目的总和不能超过 100%，剩余概率区间为空奖。

强化碳奖池

以下示例对应僵尸王的默认普通强化碳条目：

bosses:
  zombie_king:
    rewards:
      coins:
        min-amount: 100
        max-amount: 200
      intensify-cokes:
        rolls: 1
        entries:
          normal:
            type: RYAN_COKES
            chance-percent: 65.0
            min-amount: 1
            max-amount: 3
            menu-slot: 11

可用强化碳类型：

• RYAN_COKES
• ENCHANTED_COKES
• SPECIAL_GRADE_COKES
• DIVINE_GRADE_COKES
• ANCIENT_FURNACE_CARBON_COKES

配置说明

常用配置

服主通常只需要调整刷新冷却、倒计时、Boss 权重、缩放、属性、奖励和存储类型：

spawn:
  cooldown-seconds: 1800
  countdown-seconds: [30, 3, 2, 1]
  selection:
    zombie_king: 50.0
    iron_golem_king: 50.0

bosses:
  zombie_king:
    scale: 2.5
    attributes:
      max-health: 5000.0
      attack-damage: 20.0

storage:
  type: YAML
  server-id: server-1

bossbar:
  radius: 60.0

announcements:
  spawn:
    title-radius: 60.0

完整运行时默认配置见 config.yml，逐项中文说明见 config.example.yml。BossBar 与刷新 Title / Subtitle 使用独立范围，默认都只对 Boss 同世界 60 格内玩家可见；刷新聊天公告继续全服发送，声音继续使用自身的独立 radius。

config-version: 4 会把 v3 未修改的旧 BossBar 默认值从 64 格迁移为 60 格，并保留服主自定义范围；同时补充独立的 announcements.spawn.title-radius: 60.0。从 v2 升级时仍会迁移 30、3、2、1 倒计时和新版展示配置，但不会覆盖已经自定义的倒计时、声音或公告。Boss 属性、奖励、刷新点、冷却和存储数据保持不变，任何无效配置都不会替换当前运行时快照。

进阶说明

Boss 没有刷新？查看状态诊断

/rr setspawn 会启动完整刷新冷却，默认 cooldown-seconds: 1800，因此设置后不会马上出现 Boss。执行 /rr status 会显示下列诊断之一：

诊断	含义
COOLDOWN	正在等待完整冷却结束
MISSING_SPAWN	尚未执行 /rr setspawn
WORLD_MISSING	保存的世界不存在或未加载，60 秒后重试
CHUNK_UNLOADED	刷新区块未加载，等待玩家进入
REGION_UNAVAILABLE	安全范围进入未加载或不归当前线程所有的区块，60 秒后重试
UNSAFE	刷新点没有配置要求的无阻挡空间，60 秒后重试
STORAGE_UNAVAILABLE	MySQL / YAML 不可写或正在切换，新刷新已暂停
DISABLED	spawn.enabled 已关闭
ACTIVE	Boss 已生成或正在活动

玩家无法挖掘方块？查看保护边界

RiftRaid 不包含领地保护功能，也不监听 BlockBreakEvent、BlockDamageEvent、BlockPlaceEvent 或 PlayerInteractEvent，不会取消玩家挖掘、放置或普通方块交互。自动化测试会持续检查这个边界。

如果出现全服无法挖掘方块，请优先检查：

• server.properties 中的 spawn-protection
• 玩家是否处于冒险模式
• WorldGuard、Residence、Lands、GriefPrevention、HuskClaims 等保护插件
• 权限组是否缺少目标世界的建造权限
• 是否只有非 OP 玩家或出生点附近受到影响

Boss 刷新前的 7 × 7 × 6 安全检查只读取刷新点周围方块是否可通过，不会修改方块，也不会取消任何玩家事件。

MySQL、MariaDB 与热切换说明

默认使用 YAML：

storage:
  type: YAML
  server-id: server-1

切换 MySQL / MariaDB：

storage:
  type: MYSQL
  server-id: survival-1
  mysql:
    host: 127.0.0.1
    port: 3306
    database: minecraft
    username: root
    password: "change-me"
    table-prefix: riftraid_
    maximum-pool-size: 4
    connection-timeout-ms: 5000
    retry-seconds: 30

修改后执行 /rr reload 即可，无需重启服务器。热切换过程会暂停新 Boss 刷新，将唯一内存 RaidState 快照写入目标后端；如果切换期间 revision 发生变化，会继续追写到一致后再原子替换仓库。目标初始化或写入失败时，旧配置和旧仓库继续使用。

这不是历史数据迁移工具：插件不会扫描或导入旧 state.yml、其他表或历史讨伐记录，只交接当前刷新点、活动 Boss 的 UUID、session、类型、区块、下次刷新时间、诊断和倒计时状态。Vault 金币、伤害贡献和历史战斗不由 RiftRaid 存储。

多个服务器共用同一数据库时，每台服务器必须配置唯一的 server-id，否则会写入同一行并相互覆盖。表前缀只接受字母、数字和下划线。MySQL 初始化、查询、写入和重连均在异步生命周期 I/O worker 执行；MySQL 失败时不降级到 YAML，新刷新会暂停并按 retry-seconds 重试，当前状态保留在内存。

声音、粒子与公告效果

倒计时、生成和死亡效果均可单独配置 enabled、type、category、volume、pitch 和 radius。声音范围独立于 BossBar 和刷新 Title；radius: 0 代表发送给所有在线玩家。倒计时与生成声音默认关闭，死亡时的低音量末影龙声音保持启用。粒子包含类型、数量、三个方向偏移和速度参数，并始终在 Boss 所属 Region 执行。

effects:
  death:
    sound:
      enabled: true
      type: ENTITY_ENDER_DRAGON_DEATH
      category: HOSTILE
      volume: 0.35
      pitch: 1.0
      radius: 64.0

Folia 调度与线程安全边界

• 插件在 onEnable 早期只检测一次 Folia 并缓存结果，之后所有业务调度只经过统一调度包装器。
• Boss 生成、属性、PDC、AI、伤害、掉落与粒子在 Region 或 Entity 所属上下文执行。
• 全服玩家枚举在 Global 上下文执行，每位玩家的聊天、Title、声音和 BossBar 操作回到其 EntityScheduler。
• YAML / MySQL 保存通过生命周期 I/O worker 串行执行，Vault 结算和配置文件处理在 AsyncScheduler 执行；Region 线程不会同步等待数据库、网络或其他 Region。
• 共享状态使用不可变快照、原子变量或并发集合；重复任务、重连任务、Boss 引用和伤害表均有显式清理路径。
• 目标 Luminol 26.2 build 726 的 API 实际公开 PlayerRespawnEvent、PlayerTeleportEvent、PlayerChangedWorldEvent、WorldLoadEvent 和 WorldUnloadEvent；RiftRaid 当前没有注册这些监听器。
• Boss 会阻止传送门、实体传送、变形与乘坐载具。当前版本没有注册实体活塞推动监听器，因此不声明能够取消活塞推动。

folia-supported: true 只允许插件在 Luminol 的 Regionized 模型上加载，不代表第三方 Vault Economy Provider 或 PlayerIntensify 已在目标组合中证明线程安全。升级 Luminol、Vault 或 PlayerIntensify 后，应重新验证实际运行环境。

第三方组件与许可证

RiftRaid 由 cloudfl4re 维护，使用 GNU General Public License v3.0 发布。

发行 Jar 内包含并重定位 HikariCP 7.1.0（Apache License 2.0），并包含 MariaDB Connector/J 3.5.10（LGPL-2.1-or-later）及其运行依赖。详细声明见 NOTICE。Luminol API、Vault API 与 PlayerIntensify 不会打入发行 Jar。

构建

mvn --batch-mode clean verify

构建需要 Java 25，并使用 me.earthme.luminol:luminol-api:26.2.build.726-stable，不需要本地 PlayerIntensify Jar。成品位于 target/RiftRaid-1.2.3.jar。GitHub Actions 会同时启动 MySQL 8，验证建表、完整状态往返和 server-id 隔离。