CannonRTP 消息与标题
所有面向玩家的字符串都位于 plugins/CannonRTP/messages.yml，可完全覆盖。每个值都支持 MagmaCore 渐变（<gradient:#start:#end>...</gradient>）、MiniMessage 标签和传统的 & 颜色代码。任何消息中的 $prefix 占位符都会被替换为已配置的 prefix 值。
第一版仅附带英文；config.yml 中的 language 键是为未来翻译包预留的目标。
前缀与帮助标题
| 键 | 占位符 | 默认 | 描述 |
|---|---|---|---|
prefix | -- | <gradient:#ff9a3d:#ffd166>CannonRTP</gradient> &8| | 通过 $prefix 注入到每条消息中的前缀 |
helpHeader | $prefix | $prefix &fCannonRTP commands: | 在 /cannonrtp、/wc help 以及 /wc list / /wc status 顶部打印的欢迎行 |
聊天消息
| 键 | 占位符 | 描述 |
|---|---|---|
createdCannon | $prefix、$cannon、$id、$path | /wc create 成功后发送 |
placedCannon | $prefix、$cannon | /wc place 成功后发送 |
removedCannon | $prefix、$cannon | /wc remove 成功后发送 |
deletedCannon | $prefix、$cannon | /wc delete 成功后发送 |
targetWorldUpdated | $prefix、$cannon、$world | /wc target 成功后发送 |
searchCenterUpdated | $prefix、$cannon | /wc center 成功后发送 |
reload | $prefix、$count | 炮台编辑命令重建放置点后发送。/wc reload 重载整个插件，改用 MagmaCore 的共享完成消息。 |
noPermission | $prefix、$cannon | 当玩家走入其缺少 requiredPermission 的炮台时发送（每玩家每炮台限速为每 3 秒一次） |
launchCooldown | $prefix、$cannon、$seconds、$unit | 玩家在已获准发射的冷却结束前进入任意炮台时发送。$seconds 向上取整；$unit 为 second 或 seconds。每位玩家在每个炮台最多每 3 秒收到一次通知。 |
cannonDisabled | $prefix、$cannon | 保留键。已禁用的炮台会被完全排除在 tick 循环之外，因此当前版本永远不会发送这条消息 —— 该键会写入 messages.yml，但没有任何代码读取它。 |
queueCalibration | $prefix、$cannon、$queued、$target、$attempts | 当炮台仍在预加载且玩家走入时发送。在此消息中 $target 为 chargedLocationsPerCannon；$attempts 为炮台耗尽前剩余的搜索尝试预算 |
noValidLocationYet | $prefix、$cannon | 炮台在发射瞬间队列为空时的回退消息。当前版本会先检查队列，并改为发送 queueCalibration 或 noValidLocationFound，因此此消息通常不会显示。 |
noValidLocationFound | $prefix、$cannon、$reason | 当玩家走入一个已放弃搜索（用尽 searchTimeoutAttempts，或保护集成加载失败）且队列为空的炮台时发送。$reason 列出该轮搜索遇到的拒绝类别，不包含次数或频率排名。 |
invalidConfiguration | $prefix、$cannon、$reason | 当检测到配置错误时发送（例如目标世界未加载） |
statusLine | $prefix、$cannon、$status、$queued、$target、$reason | /wc list 和 /wc status 中每行使用的格式。在此消息中 $target 为 preloadedLocationsPerCannon（完整储备目标，而非已充能阈值） |
probeAllowed | $prefix | 保护集成允许该位置时由 /wc probe 发送；不检查地形或 API 监听器。 |
probeBlocked | $prefix、$plugin、$reason | /wc probe 在该位置被阻止时发送 |
unknownCommand | $prefix | 保留键。无法识别的子命令由共享的 MagmaCore 命令管理器处理，因此当前版本永远不会发送这条消息 —— 该键会写入 messages.yml，但没有任何代码读取它。 |
invalidConfiguration 同时充当通用的管理员错误行：当没有放置任何炮台时，/wc list / /wc status 也会发送它；当无法解析 id 或世界、/wc create 收到已存在的 id，或炮台文件无法保存或删除时，/wc create、/wc place、/wc remove、/wc delete、/wc target 和 /wc center 同样会发送它。
状态标签
浮动炮台标签、/wc list 以及 $status 占位符所使用的状态词都是可配置的。
| 键 | 默认 | 显示时机 |
|---|---|---|
statusLabels.ready | Ready | 队列达到 chargedLocationsPerCannon；即使低于这个显示阈值，也能使用排队目的地发射。 |
statusLabels.charging | Charging | 炮台仍在寻找它的第一个安全目的地 |
statusLabels.maintaining | Maintaining | 炮台正在补充其目的地储备 |
statusLabels.exhausted | Exhausted | 队列达到充能阈值前已用尽搜索失败额度；已排队的目的地仍可使用。 |
statusLabels.disabled | Disabled | 炮台在其配置中被禁用。仅在 /wc list 和 /wc status 中出现，因为已禁用的炮台不生成悬浮标签。 |
statusLabels.invalid | Invalid | 保留键，不显示。目标世界不可用时，将搜索重置为 SEARCHING 并移除该世界的目的地。空队列显示 Charging，$reason 报告不可用的世界。 |
这些是原始字符串，因此渐变和颜色代码在这里同样有效。你设置的内容会成为 statusLine 中的 $status 值。
标题池
发射序列中的若干标题槽位被配置为列表而非单一字符串。每次发射时，CannonRTP 会从列表中随机选取一条。这使得重复发射不会显得千篇一律。
| 键 | 占位符 | 阶段 | 描述 |
|---|---|---|---|
titles.launchQueuedTitles | $cannon | SEARCHING 开始 | 发射开始时显示的标题字符串池 |
titles.launchQueuedSubtitles | $cannon | SEARCHING 开始 | 与发射开始标题搭配的副标题池 |
titles.destinationPreviewTitles | -- | SEARCHING | 随机坐标闪烁期间显示的标题池。该阶段开始时选取一条，并在整个阶段中保持不变。 |
titles.destinationPreviewSubtitle | $x、$y、$z | SEARCHING（每 tick） | 显示闪烁随机坐标的单个副标题字符串 |
titles.destinationConfirmedTitles | $x、$y、$z、$world | FIRING 开始 | 真实目的地锁定瞬间显示的标题池 |
titles.destinationConfirmedSubtitle | $x、$y、$z、$world | FIRING 开始 | 显示真实目的地的单个副标题 |
titles.arrivalTitles | $x、$y、$z、$world | TELEPORTING | 空投传送之后立即显示的标题池 |
titles.arrivalSubtitles | $x、$y、$z、$world | TELEPORTING | 与到达标题一同显示的副标题池 |
占位符在标题及其副标题中来自同一集合并被替换，因此为一半列出的任何占位符在另一半中同样有效。例外是 destinationPreviewTitles：所选条目在该阶段开始时只格式化一次，因此 $x、$y 和 $z 在其中不会被解析。$prefix 在所有位置都能解析，尽管在标题中很少会用到它。
如果某个池被设为空列表，CannonRTP 会改用其内置默认值中的第一条。
单一字符串 vs. 池
destinationPreviewSubtitle和destinationConfirmedSubtitle是单一字符串，因为它们包含必须始终渲染的动态坐标。其他标题与副标题槽位为池，每次发射会从每个池中随机选取一条。
默认标题池
messages.yml 中默认提供的内容：
launchQueuedTitles —— Launching、Ignition、Liftoff（橙金渐变）
launchQueuedSubtitles —— $cannon（暖金色）
destinationPreviewTitles —— Calibrating、Scanning、Targeting（橙金色）
destinationConfirmedTitles —— Locked、Set、Engaged（绿色）
arrivalTitles —— Arrived、Touchdown、Airborne（冷白色）
arrivalSubtitles —— Good luck.、Stick the landing.、Eyes up. Ground soon.、Wind check complete. Good luck.、Drop zone acquired. Good luck.
占位符参考
| 占位符 | 解析为 |
|---|---|
$prefix | messages.yml -> prefix 的值 |
$cannon | 炮台的 displayName。在 deletedCannon 以及大多数通过 invalidConfiguration 发送的管理员命令错误中，它是你输入的 id。 |
$id | 炮台的配置 id（经过规范化的小写） |
$path | 新创建炮台配置文件的绝对路径（仅在 createdCannon 中出现） |
$world | 目标世界名称 |
$count | 重建后已加载的炮台放置点数量（所有炮台文件中每个 cannonLocations 条目各算一个，包括已禁用的炮台） |
$queued | 某炮台当前的队列大小 |
$target | 视上下文而定：在 queueCalibration 中为 chargedLocationsPerCannon，在 statusLine 中为 preloadedLocationsPerCannon。两个键都位于 landing.yml。 |
$attempts | 炮台耗尽前剩余的搜索尝试次数 |
$seconds | 向上取整的剩余发射冷却时间 |
$unit | second 或 seconds，与 $seconds 相匹配 |
$status | 对应的 statusLabels.* 值 —— 默认为 Ready、Charging、Maintaining、Exhausted 或 Disabled |
$reason | 关于状态或失败的可读详情 |
$plugin | 阻止该位置的保护插件名称 |
$x、$y、$z | 坐标（保留一位小数） |
本地化说明
上述每个键在展示给玩家之前都会经过 MagmaCore 的颜色/渐变处理器。针对 config.yml 中 language 的翻译包将通过同一 translatable() 钩子接入（在第一版中目前为直通实现）。