跳到主要内容

CannonRTP（WorldCannon）

CannonRTP 是一款适用于 Minecraft 服务器的多炮台随机传送插件。"WorldCannon" 是较早的 / wiki 板块名称；插件在 Bukkit 中注册为 CannonRTP，发布为 CannonRTP.jar，这也是玩家和管理员所看到的名称。

关键命名细节：

  • 插件名称：CannonRTP
  • 根命令：/cannonrtp
  • 别名：/crtp、/wc
  • 权限节点：cannonrtp.admin、cannonrtp.use
  • 配置文件夹：plugins/CannonRTP/

功能介绍​

CannonRTP 是一个多炮台随机落点系统，而非单一固定发射器。每个已配置的炮台可以在世界中放置一处或多处，每个放置点都会监测进入其触发半径的玩家。

每个炮台都可以：

  • 通过 /wc create 和 /wc place 多次放置 —— 一份炮台配置驱动其所有放置点
  • 监测玩家进入该炮台的触发半径（默认 1.75 格）
  • 预加载并维护一个由已配置目标世界中安全落点组成的队列（支持跨世界传送）
  • 拒绝不安全的地形、被阻挡的空间、受保护的领地以及世界边界外的位置
  • 可选地要求额外的单炮台权限节点
  • 通过五阶段的电影化序列发射玩家
  • 展示一个 FreeMinecraftModels 的 3D 动画炮台模型（通过每个炮台的 customModel 或全局优先级列表配置）；若未安装 FMM 则回退为变色环绕粒子
  • 在炮台上方显示一个面向玩家的悬浮状态标签（Ready / Charging / Maintaining / Exhausted）；已禁用的炮台不生成标签或模型，只在 /wc list 和 /wc status 中显示为 Disabled

快速开始​

  1. 把 CannonRTP.jar 放入 plugins/ 并启动服务器。
  2. 在游戏内运行 /wc initialize，然后运行 /wc setup 下载炮台模型包。下载需要已关联的 Nightbreak 账户，模型需要 FreeMinecraftModels。没有模型时，炮台使用粒子视觉效果。
  3. 站在炮台应该所在的位置，运行 /wc create spawn。新炮台会把玩家送入它所在的世界。
  4. 可选：运行 /wc target spawn <world> 把玩家送入另一个已加载的世界，或运行 /wc center spawn 围绕你当前位置搜索。
  5. 确保搜索区域已作为已生成的地形存在（默认距搜索中心 500 到 5000 格），然后运行 /wc status。炮台一旦持有至少一个已检查的目的地，就会发射玩家。

发射流程​

使用前，请生成或探索目标世界配置的搜索区域。CannonRTP只加载现有区块，不生成地形；未探索的搜索半径可能无法提供任何目的地。

发射序列由五阶段状态机驱动（SEARCHING -> FIRING -> TELEPORTING -> DROPPING -> LANDING）。当玩家进入符合条件的炮台触发半径时：

  1. CannonRTP 检查 cannonrtp.use。
  2. 检查炮台可选的 requiredPermission。
  3. 检查每位玩家的发射冷却（runtime.launchCooldownSeconds，默认 30 秒）。该限制在所有炮台之间共享，并且不会消耗已排队的目的地。
  4. 验证该炮台至少有一个已预加载的落点排队。（已禁用的炮台、位于未加载世界中的炮台以及位于未加载区块中的炮台永远走不到这一步 —— 它们被完全排除在 tick 循环之外，因此根本无法被触发。）
  5. 从该炮台队列中消耗一个预加载的安全落点。
  6. 触发 CannonRTPLaunchEvent（可取消）。如果监听器取消该事件，目的地会被退还到队列中，并且不会开始冷却。
  7. Searching 阶段（默认 42 tick，可通过 launchWarmupTicks 配置）：玩家获得漂浮效果，如果启用了自定义模型则炮台播放 fire 动画，同时随机坐标预览会通过标题/副标题闪烁显示。当模型激活时，玩家还会获得隐身效果，使动画呈现更清晰。
  8. Firing 阶段（默认 45 tick，由 verticalBoostTicks 控制）：移除漂浮/隐身效果，播放发射音效，生成火焰+烟雾+爆炸效果，并每 tick 施加一次 verticalBoostVelocity。真实目的地坐标此时显示。
  9. Teleporting 阶段（单 tick）：已排队的目的地会被重新校验（地形柱、保护插件集成、API 监听器）。若仍然通过校验，玩家会被传送到其正上方恰好 50 格处，并施加缓降效果。空投高度永远不会被钳制 —— 落点校验器已经保证到达方块位于世界最大高度之下，而不再通过校验的目的地会取消发射并转为回收玩家。
  10. Dropping 阶段：玩家拖着烟雾尾迹下落（LARGE_SMOKE + CAMPFIRE_SIGNAL_SMOKE）。
  11. Landing 阶段：玩家站在地面上且垂直速度低于每 tick 0.08 格时进入。CannonRTP 解除自身施加的缓降，播放落地特效（云冲击波、火焰环、尘埃过渡），并触发 CannonRTPLandingEvent。如果下落超过最大时长（slowFallingSeconds x 20 tick），CannonRTP 会将玩家送回安全位置，不触发落地事件。

落点安全规则​

在某个位置被加入预加载队列之前，当前代码会按以下顺序进行检查：

  • 目标世界已加载（在未加载期间，炮台会停止预加载并报告 Target world <name> is not loaded.）
  • 搜索中心可解析 —— 优先使用配置的 searchCenter，其次是炮台自身位置（当它位于目标世界中时），最后是目标世界的出生点
  • 候选点位于世界边界之内
  • 候选点所在的区块已加载（按需加载，不会生成新地形）
  • 候选点所在列存在最高的非空气方块
  • 落点正下方的表面方块为固体且非液体
  • 该表面方块不在已配置的不安全地面材料列表中，也不是下界的基岩顶盖
  • 落点位于世界最小高度或以上，且其上方 51 格处的到达方块仍低于世界最大高度
  • 52 格空投柱（从落点一直到到达时的头部方块）中的每一个方块都是空气或可穿过
  • 该柱中没有任何方块在已配置的不安全身体材料列表中
  • 所有启用的保护插件集成均允许该位置
  • 没有任何 CannonRTPLocationValidationEvent 监听器否决该候选点

在下界，CannonRTP 会拒绝基岩顶盖，并向下扫描寻找一个整条空投柱都安全的裸露洞穴地面。这使得下界目标成为可能，而不会把玩家投放到顶盖之上或穿过实心地形。

搜索尝试在全局范围内被限速为每 tick 一次（20 次/秒），通过轮询方式在所有活跃炮台之间公平分配。每个炮台拥有自己的超时计数器（searchTimeoutAttempts，默认 100，最小 10）。

炮台状态​

每个炮台都有一个内部状态，可通过 /wc status 或 /wc list 查看：

显示内部状态含义
Disabled--该炮台在配置中被显式禁用
ChargingSEARCHING（队列为空）仍在预加载首批安全落点
MaintainingSEARCHING（队列非空）已有部分落点，仍在补充已消耗的槽位
ReadyREADY拥有足够的预加载落点（>= chargedLocationsPerCannon）以发射玩家
ExhaustedEXHAUSTED已用尽 searchTimeoutAttempts 仍未填满储备

内部搜索状态恰好只有三个取值（READY、SEARCHING、EXHAUSTED）；Disabled 在查询该状态之前就已判定，而 Charging / Maintaining 是 SEARCHING 的两种呈现方式。Ready 优先于 Exhausted —— 仍持有已充能储备的炮台即使上一个搜索窗口超时，也会显示为 Ready。

当某个已启用保护插件的集成加载失败且 failOpenOnProtectionErrors 为 false 时，炮台也会在不采样任何地形的情况下显示 Exhausted。参见保护插件集成。

不存在单独的“配置无效”状态。目标世界变得不可用时，会丢弃该世界的排队目的地，并将搜索状态重置为 SEARCHING。空队列显示 Charging，/wc status 的 $reason 列报告 Target world <name> is not loaded.。目标世界加载后恢复搜索。messages.yml 中的 statusLabels.invalid 键存在，但不会显示。

只要队列中至少有一个目的地，炮台就会立即发射玩家。chargedLocationsPerCannon 阈值仅影响视觉上的 READY 标签。

运行环境要求​

  • Minecraft：plugin.yml 声明 api-version: 1.21.4；当前源码树基于 Spigot 26.3-R0.1-SNAPSHOT API 构建
  • Java：21
  • 推荐服务器软件：Paper 或当前兼容的分支
  • MagmaCore：2.2.0 或更新版本（共享库，已遮蔽打包进插件）
  • 可选依赖：FreeMinecraftModels（用于 3D 动画炮台模型）
  • 统计：CannonRTP 会向 bStats 报告匿名使用统计数据（插件 id 为 34460）。如需退出，请在 plugins/bStats/config.yml 中设置 enabled: false，这会作用于服务器上所有使用 bStats 的插件。

可靠性​

CannonRTP 在世界和区块生命周期事件中保持其视觉效果与队列的一致性：

  • 当炮台所在区块卸载时，其标签和模型会被移除；区块重新加载时会重新生成
  • 当炮台所在世界卸载时，该炮台会被挂起；世界再次加载时会唤醒
  • FreeMinecraftModels 启用、禁用，或在支持重载完成事件的版本上完成内容重载时，会丢弃旧炮台模型并从当前模型注册表重新创建；没有该事件的旧版 FMM 中，已移除的模型实例也能被直接检测到
  • 在空投传送之前，已排队的目的地会针对地形、保护插件集成和 API 监听器重新检查；如果它已变得不安全，发射流程会转为回收玩家，而不是照旧使用过期坐标
  • 发射清理只会移除 CannonRTP 仍然拥有的漂浮、隐身和缓降效果，并恢复它临时替换掉的更早的效果，而不会删除其他插件更新的状态
  • 如果发射因目的地世界卸载而无法继续，CannonRTP 会将玩家回收到炮台座位或另一个已加载世界的出生点；当没有安全的回收世界可用时，会保留缓降效果
  • /wc reload、免重启插件更新，以及每个编辑炮台的命令（create、place、remove、delete、target、center）都会重建所有炮台：正在进行的发射会被取消，玩家被回收到炮台座位；排队的目的地会被丢弃并重新搜索；发射冷却也会重置
  • 如果玩家在发射途中断开连接，发射会结束，CannonRTP 会移除其施加的效果；玩家不会被传送

故障排查​

  • 炮台一直处于 Charging 或变为 Exhausted。 运行 /wc status 并阅读其原因。常见原因包括目标世界未加载、搜索区域从未生成、地表不符合落点安全规则（水默认是不安全材料，因此开阔海洋永远不合格），以及覆盖该区域的领地或区域保护。/wc probe 会在你所站的位置测试保护检查。已启用但加载失败的保护集成会让所有炮台停止搜索；参见保护集成。
  • 玩家走进炮台却没有任何反应。 检查 cannonrtp.use、该炮台的 requiredPermission、该炮台是否已启用，以及发射冷却（runtime.launchCooldownSeconds，默认 30 秒）。
  • 删除炮台或移动正在使用的目的地之前， 请备份 plugins/CannonRTP/cannons/ 中它的文件。

寻求帮助时，请附上 /wc status 的输出、CannonRTP 和服务端的版本、受影响炮台的配置文件以及完整的服务器日志。/logify 会上传日志并返回一个链接。

从这里开始​