CannonRTP 配置
CannonRTP 将其全局设置分散到 plugins/CannonRTP/ 下的多个文件中，并在 plugins/CannonRTP/cannons/ 下为每个炮台提供一份独立的配置文件。
文件布局
| 文件 | 用途 |
|---|---|
plugins/CannonRTP/config.yml | 顶层运行时标志（设置状态、语言、粒子刷新间隔、炮台模型优先级、Spigot 资源 id） |
plugins/CannonRTP/landing.yml | 落点搜索调优（队列大小、超时尝试次数、缓降时长、不安全材料列表、失败开放行为） |
plugins/CannonRTP/sounds.yml | 发射序列中播放的音效 |
plugins/CannonRTP/messages.yml | 所有面向玩家的消息、前缀和标题池 |
plugins/CannonRTP/protection.yml | 各保护插件集成的开关 |
plugins/CannonRTP/cannons/<id>.yml | 每个炮台一份文件（每份可驱动多个放置点） |
plugins/CannonRTP/cannons_disabled/ | 用于存放随内容包发布但当前已禁用的炮台配置的暂存文件夹。当你在 /wc setup 菜单中启用或禁用某个内容包时，对应文件会在 cannons/ 和 cannons_disabled/ 之间移动。 |
plugins/CannonRTP/content_packages/<package>.yml | 每个 Nightbreak 内容包的生成元数据（版本、下载链接、用于查找其文件的前缀）。通常不需手动编辑。 |
插件开箱即附带三份示例炮台配置：
example_cannonrtp.yml—— 空白参考模板，默认禁用。可在手写炮台文件时作为 YAML 参考使用。cannonrtp_free_cannon.yml—— 已启用，无放置点，指向免费的cannonrtpFMM 模型。cannonrtp_premium_cannon.yml—— 已启用，无放置点，指向高级的cannonrtp_premiumFMM 模型。
这些配置默认都没有填入 cannonLocations，因此在管理员运行 /wc create 或 /wc place 之前，世界中不会生成任何东西。
config.yml
| 键 | 默认 | 行为 |
|---|---|---|
setupDone | false | 追踪 Nightbreak 首次设置是否已完成 |
language | english | 要加载的翻译文件。第一版仅附带英文；该键为未来翻译包预留 |
runtime.particleIntervalTicks | 15 | 闲置炮台粒子的渲染频率（最小 5） |
runtime.cannonModelPriority | [cannonrtp_premium, cannonrtp] | FreeMinecraftModels 模型名称的优先级列表，自上而下检查。对于任何未设置自身 customModel 的炮台，将使用在服务器上找到的第一个模型。如果都未找到，则使用环绕粒子作为回退方案。 |
runtime.spigotResourceId | "" | 版本检查器使用的 Spigot 资源 id。留空以禁用。 |
landing.yml
| 键 | 默认 | 行为 |
|---|---|---|
preloadedLocationsPerCannon | 10 | 插件尝试为每个炮台维持排队的安全目的地总数（最小 1） |
chargedLocationsPerCannon | 1 | 炮台状态标签翻转为 Ready 所需的最小排队落点数（最小 1，最大不超过 preloadedLocationsPerCannon）。只要队列中至少有一个落点，炮台就会立即发射玩家 —— 该阈值仅影响视觉标签。 |
searchTimeoutAttempts | 100 | 炮台被标记为 Exhausted 前允许的失败搜索尝试次数（最小 10）。搜索尝试在全局范围内被限速为每 tick 一次（每秒 20 次），并在所有活跃炮台之间公平分配。 |
slowFallingSeconds | 60 | 空投后缓降效果的最大时长（最小 1）。玩家着陆时该效果会被提前移除。 |
failOpenOnProtectionErrors | false | 如果保护插件 API 报错，默认会阻止落点。设为 true 可在无法安全查询保护插件时仍允许落地继续。 |
unsafeGroundMaterials | [LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW] | 会使落点表面失格的材料 |
unsafeBodyMaterials | [LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB] | 会使落点脚部或头部空间失格的材料 |
材料为 Bukkit Material 枚举名称。无效条目会作为警告记录并被跳过。
sounds.yml
| 键 | 默认 | 行为 |
|---|---|---|
levitationStart.sound | BLOCK_BEACON_ACTIVATE | searching 阶段开始时播放的音效 |
levitationStart.volume | 1.0 | |
levitationStart.pitch | 1.15 | |
blastOff.sound | ENTITY_GENERIC_EXPLODE | firing 阶段开始时播放的音效 |
blastOff.volume | 1.0 | |
blastOff.pitch | 0.9 |
音效值可以是 Bukkit Sound 枚举名称（例如 BLOCK_BEACON_ACTIVATE）或命名空间键（例如 minecraft:block.beacon.activate）。无效的音效名称会作为警告记录，并在该步骤中被静默跳过。
messages.yml
所有消息均支持 MagmaCore 渐变、MiniMessage 标签和传统的 & 颜色代码。$prefix 占位符会被替换为已配置的前缀。
完整的消息键、占位符列表以及发射序列中使用的标题池，请参阅消息与标题页面。
单炮台配置字段
每个炮台文件（plugins/CannonRTP/cannons/<id>.yml）存储如下字段：
| 字段 | 默认 | 备注 |
|---|---|---|
isEnabled | true（新创建的炮台） | 已禁用的炮台不会触发并显示为 Disabled |
displayName | CannonRTP（或创建时传入的名称） | 用于消息、状态输出和悬浮标签 |
cannonLocations | 空列表 | 序列化的 world,x,y,z,pitch,yaw 字符串列表。一份炮台配置可以生成多个世界中的放置点。由 /wc create、/wc place、/wc remove 管理。 |
targetWorld | 创建时的当前世界 | 支持跨世界传送 —— 将此项设为不同的世界即可让玩家落入与炮台不同的世界。运行时必须已加载，否则炮台显示为 Invalid。 |
searchCenter | null | 如果未设置，插件会从炮台自身位置开始扩散（当炮台位于目标世界时）或从目标世界的出生点扩散 |
triggerRadius | 1.75 | 用于检测附近玩家的炮台半径（最小 0.5 格） |
minSearchRadius | 500 | 从搜索中心起的最小落点搜索距离（最小 0） |
maxSearchRadius | 5000 | 最大落点搜索距离（始终至少限定为 minSearchRadius + 1） |
launchWarmupTicks | 42 | Searching 阶段的 tick 时长（最小 1） |
verticalBoostTicks | 45 | Firing 阶段的 tick 时长（最小 0） |
verticalBoostVelocity | 1.35 | firing 阶段每 tick 施加的向上速度（最小 0） |
enableParticles | true | 控制闲置环绕粒子动画。仅在未启用自定义模型且玩家位于 36 格范围内时渲染。 |
requiredPermission | "" | 该炮台可选的额外权限门控。拥有 cannonrtp.use 但缺少该节点的玩家会看到已配置的无权限消息。 |
customModel | "" | 该炮台可选的 FreeMinecraftModels 模型名称。若留空，则插件回退到 runtime.cannonModelPriority。 |
炮台创建默认值
当你运行 /wc create <id> 时：
- 炮台 id 会被转为小写，
a-z、0-9、_、-以外的字符会被替换为_ displayName默认为CannonRTP，除非使用了/wc create <id> <display_name>（<display_name>中的下划线会被转换为空格）- 玩家当前位置会被追加到
cannonLocations targetWorld设为玩家当前世界searchCenter不设置（若炮台位于目标世界则回退到炮台自身位置，否则回退到目标世界的出生点）
创建完成后，插件会回复配置文件的绝对路径，以便你手动编辑 displayName、customModel、requiredPermission、搜索半径以及发射调优参数。
FreeMinecraftModels 集成
当某个炮台解析到有效的 FreeMinecraftModels 模型 —— 无论是通过它自身的 customModel 字段还是全局 runtime.cannonModelPriority 列表 —— 且 FreeMinecraftModels 已安装时：
- 在炮台位置生成一个静态模型实体
- 悬浮文字标签的高度提升至炮台上方 2.0 格（无模型时为 1.2 格）以避免遮挡模型
- 模型激活时关闭闲置环绕粒子动画
- 在发射期间，炮台在 searching 阶段开始时播放其
fire动画（如果存在）；同时玩家在 searching 阶段被隐身，使动画呈现更清晰
如果在服务器运行期间启用或禁用 FreeMinecraftModels，炮台模型缓存会失效，视觉效果会在下一 tick 刷新。
闲置粒子回退
当没有模型激活时，炮台会在炮台中心周围渲染一对环绕的 DUST_COLOR_TRANSITION + FIREWORK 粒子。颜色会根据炮台的实际状态变化：
| 状态 | 主色 | 强调色 |
|---|---|---|
| Ready | 橙色 | 金色 |
| Searching（charging / maintaining） | 暖橙色 | 金色 |
| Exhausted | 红色 | 暖红色 |
| Invalid configuration | 深红色 | 红色 |
仅在玩家位于炮台 36 格范围内时渲染闲置粒子。
悬浮状态标签
每个炮台都会在其基座上方生成一个面向玩家的 TextDisplay，显示显示名称和当前状态（Ready、Charging、Maintaining、Exhausted、Disabled 或 Invalid）。该标签为非持久化（永远不会保存到区块数据中），区块重新加载时会自动重建。
运行时验证行为
当以下任一检查失败时，CannonRTP 会拒绝候选落点：
- 目标世界未加载
- 搜索中心无效
- 随机采样点落在世界边界之外
- 候选区块加载失败
- 找不到安全的固体非液体表面
- 脚部或头部空间被阻挡
- 地形或身体方块匹配已配置的不安全材料列表
- 保护插件集成阻止该落点
- 有
CannonRTPLocationValidationEvent监听器否决了该候选点
如果某炮台耗尽了 searchTimeoutAttempts（默认 100）仍未填满储备，它会变为 Exhausted 状态，并开始返回已配置的失败消息而非发射玩家。失败消息中包含最常见拒绝原因的摘要。每当队列槽位空出时（例如发射之后），该炮台会重置其超时计数器。
交互防护
CannonRTP 会防止玩家在已经处于活跃发射序列中时触发炮台。当前发射结束（着陆或断线）后，玩家可以再次使用炮台。没有额外的冷却计时器。