跳到主要内容

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 / Disabled / Invalid）

发射流程​

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

  1. CannonRTP 检查 cannonrtp.use。
  2. 检查炮台可选的 requiredPermission。
  3. 验证该炮台是否启用、配置是否有效、是否至少有一个已预加载的落点排队。
  4. 从该炮台队列中消耗一个预加载的安全落点。
  5. 触发 CannonRTPLaunchEvent（可取消）。如果监听器取消该事件，目的地会被退还到队列中，炮台恢复正常状态。
  6. Searching 阶段（默认 42 tick，可通过 launchWarmupTicks 配置）：玩家获得漂浮效果，如果启用了自定义模型则炮台播放 fire 动画，同时随机坐标预览会通过标题/副标题闪烁显示。当模型激活时，玩家还会获得隐身效果，使动画呈现更清晰。
  7. Firing 阶段（默认 45 tick，由 verticalBoostTicks 控制）：移除漂浮/隐身效果，播放发射音效，生成火焰+烟雾+爆炸效果，并每 tick 施加一次 verticalBoostVelocity。真实目的地坐标此时显示。
  8. Teleporting 阶段（单 tick）：玩家被传送到目的地上方 50 格处（受世界最大高度限制），并施加缓降效果。
  9. Dropping 阶段：玩家拖着烟雾尾迹下落（LARGE_SMOKE + CAMPFIRE_SIGNAL_SMOKE）。
  10. Landing 阶段：玩家着陆后（或达到最大下落时长）立即移除缓降效果，并播放落地爆发特效（云冲击波、火焰环、尘埃过渡）。CannonRTPLandingEvent 触发。

落点安全规则​

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

  • 目标世界已加载
  • 搜索中心有效
  • 候选点位于世界边界之内
  • 候选点所在的区块已加载（按需加载，不会生成新地形）
  • 候选点所在列存在最高的非空气方块
  • 该方块之上的脚部和头部空间可穿过
  • 表面方块为固体且非液体
  • 表面方块不在已配置的不安全地面材料列表中
  • 脚部和头部方块不在已配置的不安全身体材料列表中
  • 所有启用的保护插件集成均允许该位置
  • 没有任何 CannonRTPLocationValidationEvent 监听器否决该候选点

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

炮台状态​

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

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

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

运行环境要求​

  • Minecraft API：1.21.4（已测试至 1.21.11）
  • Java：21
  • 推荐服务器软件：Paper 或当前兼容的分支
  • MagmaCore：2.2.0 或更新版本（共享库，已遮蔽打包进插件）
  • 可选依赖：FreeMinecraftModels（用于 3D 动画炮台模型）

可靠性​

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

  • 当炮台所在区块卸载时，其标签和模型会被移除；区块重新加载时会重新生成
  • 当炮台所在世界卸载时，该炮台会被挂起；世界再次加载时会唤醒
  • 当 FreeMinecraftModels 在运行期间被启用或禁用时，模型缓存会失效，视觉效果会在下一 tick 刷新

从这里开始​