开源 娱乐 [转载][支持Folia]BoatRacing|冰船竞速|F1 风格冰船竞速插件 1.1.4

[MD] # 冰船竞速 [](https://modrinth.com/plugin/boatracing) [](https://modrinth.com/plugin/boatracing) [](https://modrinth.com/plugin/boatracing/versions) [](https://adoptium.net/) [](https://modrinth.com/plugin/boatracing) [](https://github.com/RuiPereiraDev/SimpleScore) [](https://github.com/NEZNAMY/TAB) [](https://bstats.org/plugin/bukkit/BoatRacing/26881) [](https://modrinth.com/#available-languages) [](https://modrinth.com/#available-languages) [](https://modrinth.com/#available-languages) 适用于 Bukkit/Spigot（兼容 Paper/Purpur）的 F1 风格冰船竞速插件，拥有干净、原版风格的图形界面，可管理队伍、使用内置 BoatRacing 选择工具配置赛道、运行带检查点的计时赛、维修区罚时，并配备引导式设置向导。 > 状态：公开发布 (1.1.4) []() > \[!警告\] 快照名称：**snapshot-26.1-gui-fallback-01** 此快照仅适用于 Paper 26.1，若您的服务器版本非 26.1，请等待稳定版发布。该版本包含针对 AnvilGUI 的临时反射回退实现，部分图形界面/Anvil 流程在特定服务器版本或分支上可能仍存在错误。 **26.1 快照说明 (snapshot-26.1-gui-fallback-01)** * 快照目标：Paper 26.1 首个验证构建。 * 实现类型：针对 AnvilGUI 关闭事件兼容性的临时反射回退 (`handleInventoryCloseEvent`)。 * 已知风险：图形界面/Anvil 交互在部分 26.1 开发构建及非 Paper 分支上可能仍会失败。 * 计划：在官方 AnvilGUI 发布包含稳定 26.1 关闭事件修复前，保留此回退方案。 更新日志详见 [CHANGELOG.md](https://github.com/Jaie55/BoatRacing/blob/main/CHANGELOG.md)。 每次更新后我们通过以下方式测试插件以验证其行为：请查看 [CHECKLIST.md]() 中的质量保证清单。 **新功能 (1.1.4)** 1.1.4 版本整合了 `snapshot-26.1-gui-fallback-01` 的所有内容以及最终发布版的附加功能。 * **新增**：按令牌 `%boatracing_track_best_player_<track>%`、`%boatracing_track_best_time_<track>%` 和 `%boatracing_track_best_time_ms_<track>%` 提供赛道最佳记录占位符。 * **新增**：按令牌 `%boatracing_track_top_1_*_<track>%`、`%boatracing_track_top_2_*_<track>%` 和 `%boatracing_track_top_3_*_<track>%` (`player`, `time`, `time_ms`) 提供前三名占位符，用于领奖台/排行榜布局。 * **更改**：包含在快照验证周期中引入的 Paper 26.1 图形界面/Anvil 反射兼容路径。 * **更改**：比赛开始尊重全局配置 `racing.min-players-to-start`，并可通过 `tracks/<name>.yml` 中的 `racing.min-players-to-start` 进行每赛道覆盖。 * **更改**：阻止不符合最低人数要求的开始，使用语言键 `race.not-enough-players`（含 `{min}` 和 `{current}` 参数），并在 `start`、`force`、管理员图形界面开始以及注册超时自动开始中强制执行相同阈值。 * **修复**：按检查点到达顺序的计分板 tie-break（平局决胜）；在同一圈/检查点情况下，先进入的选手保持领先（无相同检查点交换）。 * **修复**：设置向导“完成”步骤在未选择命名赛道时使用 `/boatracing race open unsaved`，避免了无效的 `/boatracing race open <track>` 占位符令牌。 * **文档**：README 将赛道记录占位符行标记为 `NEW (1.1.4)`，CHECKLIST 包含明确的验证步骤。 **新功能 (1.1.3)** 赛道感知占位符与生成可靠性改进： * **按赛道范围的比赛占位符**：新增 `%boatracing_track_race_running_<track>%`、`%boatracing_track_race_registering_<track>%` 和 `%boatracing_track_race_status_<track>%` 以支持计分板/全息投影中的每赛道独立显示。 * **先前命名的兼容别名**：`%boatracing_track_racerunning_<track>%` 和 `%boatracing_track_raceregistering_<track>%` 映射到相同值。 * **按赛道的并行比赛会话**：比赛现在按赛道会话独立管理，因此不同赛道可同时运行注册/比赛。 * **地图投票命令流程**：新增 `/boatracing race voteopen`、`vote`、`voteui`、`votestatus` 和 `voteclose` 以协调聊天中的地图选择。 * **投票开始时可点击的投票界面提示**：当地图投票开启时，玩家收到可点击的聊天操作，直接运行 `/boatracing race voteui`，而非纯文本命令说明。 * **所选船 variants 可靠性**：比赛船/筏 variants 在生成后通过延迟重试重新应用，减少所选 variants 显示为默认橡木的情况。 * **预开始和比赛中禁止下车**：选手在 5 盏灯倒计时期间以及比赛进行中，现在被禁止手动离开船/筏。 * **奖励命令兼容性强化**：奖励解析现在同时支持 `commands`（列表）和旧版 `command`（单字符串），并对缺失的特定名次键（包括第一名）提供更安全的回退行为。 **新功能 (1.1.2)** 占位符、向导用户体验和国际化改进： * **PlaceholderAPI 集成**：BoatRacing 现在注册 `%boatracing_*%` 占位符用于全息投影/计分板（玩家/队伍数据、实时比赛值、记录、胜利和排名）。 * **持久化比赛统计**：新的聚合统计存储 (`stats.yml`) 用于记录玩家胜利、队伍胜利、最佳比赛和最佳圈速。 * **向导可读性优化**：设置向导提示现在更紧凑、更聚焦于步骤，以减少聊天干扰。 * **注册公告完全基于国际化**：注册广播模板现位于 `messages_<lang>.yml` (`race.registration.announce`) 中，而非 `config.yml`。 * **大厅返回流程**：新增 `/boatracing race back`；比赛结束/取消后，玩家返回等候大厅，获得可点击的返回提示，并可在 3 分钟内存窗口内返回其之前的位置。 * **扩展捆绑语言覆盖**：为 `fr`、`pt_BR`、`pt_PT`、`es_419`、`de`、`it`、`pl`、`tr`、`ja`、`ko` 添加并审核了社区捆绑包；中文现拆分为 `zh_TW`（台湾，繁体）和 `zh_CN`（大陆，简体）。 * **比赛船清理可靠性**：比赛生成的船/筏现被跟踪，并在结束/取消/重置时移除，以防止残留载具实体。 **新功能 (1.1.1)** 大厅与稳定性更新： * **可选注册大厅区域**：新增 `racing.lobby.*` 配置块。启用后，玩家加入注册时将被传送到可配置的大厅区域/位置。 * **快速大厅命令**：新增 `/boatracing setup setlobby` 命令将您当前位置保存为注册大厅并自动启用。 * **返回之前位置**：当 `racing.lobby.return-on-leave: true` 时，玩家离开注册或注册被取消时返回其原始位置。 * **活跃赛道安全**：当请求的赛道已活跃（ notably `unsaved`）时，比赛命令不再强制磁盘重载，避免陈旧内存状态问题。 * **赛道重载一致性**：`TrackConfig.load()` 现在在从磁盘读取前清除所有内存集合。 * **SimpleScore 兼容性钩子**：安装 SimpleScore 时，BoatRacing 现在与其在比赛期间隐藏/显示查看器流程集成，以防止侧边栏所有权冲突并在停止/取消后恢复外部计分板。 * **注册重启循环修复**：修复了一个状态/计时器问题，旧的 `race open` 倒计时可能在 `start/force/stop` 路径中存活并意外重新触发比赛开始。 * **设置可点击用户体验**：设置向导/管理员提示现在在需要参数时建议聊天中的命令，以便玩家在执行前进行标签补全。 * **大厅消息翻译**：大厅传送/返回反馈已添加到 EN/ES/zh_TW/zh_CN/ru 消息文件。 显式兼容性： * **SimpleScore**：BoatRacing 包含与 SimpleScore 的显式兼容性。 * GitHub: [https://github.com/RuiPereiraDev/SimpleScore](https://github.com/RuiPereiraDev/SimpleScore) * Modrinth: [https://modrinth.com/plugin/simplescore](https://modrinth.com/plugin/simplescore) * **TAB**：BoatRacing 包含与 TAB 的显式兼容性。 * GitHub: [https://github.com/NEZNAMY/TAB](https://github.com/NEZNAMY/TAB) * Modrinth: [https://modrinth.com/plugin/tab-was-taken](https://modrinth.com/plugin/tab-was-taken) **新功能 (1.1.0)** 语言与玩家控制： * **多语言支持**：消息现完全可翻译。在 config.yml (`language`) 中配置语言。捆绑选项为 `en`、`es`、`es_419`、`fr`、`pt_BR`、`pt_PT`、`de`、`it`、`pl`、`tr`、`ja`、`ko`、`zh_TW`、`zh_CN`、`ru`，并通过向插件文件夹添加 `messages_<lang>.yml` 也支持自定义捆绑包。使用 `/boatracing reload` 热重载而无需重启。 * **玩家控制的比赛管理**：新配置选项 `player-actions.allow-player-race-start`（默认：false）允许非管理员玩家开启、开始、强制开始和停止比赛。可通过各赛道配置中的 `racing.allow-player-start: true` 进行覆盖。 * **奖励系统**：完全可自定义的比赛结束奖励。在 `racing.rewards` 下配置，包含特定名次命令、消息和广播。支持占位符：{player}、{position}、{time}、{track}、{laps}。每赛道奖励覆盖全局配置。 * **性能**：PlayerMoveEvent 节流 — 检查点检测现在仅在进入新块时触发，而非每亚米级移动。 * **完整国际化基础设施**：所有插件消息（比赛、设置、队伍、管理员）已更新为使用新的外部化消息系统，支持动态占位符。 先前版本： * **1.0.9**：兼容 1.19–1.21.11；安全的船/筏材质；Paper 上的 Bukkit/Spigot 分类。 **新功能 (1.0.9)** 兼容性与修复： * 官方支持：Bukkit/Spigot/Paper/Purpur 1.19 → 26.1.1。需要 Java 17+。 * 跨版本更安全的船类型：船/筏（包括竹筏和苍白橡木 variants）的动态 Material 解析可避免旧版 API 上的 NoSuchFieldError 并移除 CraftLegacy 警告。 * 在 Paper 上归类为 Bukkit/Spigot 插件（JAR 中排除 paper-plugin.yml）。Paper 专用 API 替换为 Bukkit 安全调用。 * 文档：README、CHANGELOG 和 QA 清单已更新（EN/ES）。 更新节奏： * 后台检查仍每 5 分钟运行一次。当在运行时首次检测到新版本，控制台会立即打印 WARN（每个版本一次）。 * 每小时提醒对齐到每小时顶部（00:00、01:00、…）当版本过时时（尊重 `updates.console-warn`）。 * 管理员加入：始终在聊天中通知（若启用），从不在玩家加入时打印到控制台。 **新功能 (1.0.8)** 改进与切换： * **可自定义 HUD**：新配置标志用于显示/隐藏侧边栏和 ActionBar 的部分。 * `racing.ui.scoreboard.show-position|show-lap|show-checkpoints|show-pitstops|show-name` * `racing.ui.actionbar.show-lap|show-checkpoints|show-pitstops|show-time` * **HUD 上的维修站**：当 `racing.mandatory-pitstops > 0` 时，在侧边栏显示“PIT A/B”，在 ActionBar 显示“Pit A/B”（受上述切换控制）。 * **注册广播**现包含赛道名称和确切加入命令（语言键 `race.registration.announce` 位于 `messages_<lang>.yml`）。 * **侧边栏顺序**切换为“L/CP - Name”；移除居中/填充；名称按原样显示（保留 Bedrock 的前导 '.'）。 * **完成尝试消息**：未完成所有必需检查点即冲过终点线时，现在显示清晰的玩家消息（除了拒绝音效）。 * **设置向导**：新增可选步骤“强制维修站”，带快速按钮 \[0\] \[1\] \[2\] \[3\]。 * **设置命令**：`/boatracing setup setpitstops <n>` 设置并持久化 `racing.mandatory-pitstops`。 * **结果广播**：前三名显示奖牌 🥇/🥈/🥉 和排名颜色；存在罚时后缀时保留；名称安全渲染（保留 Bedrock 的前导 '.'）。 * **向导流程**：若步骤 4 已设置默认维修站，向导自动前进到检查点（队伍维修站仍可选）。 * **权限**：引入通配符 `boatracing.*`。管理员仍通过 `boatracing.admin` 下的显式子项获得所有插件权限，以避免循环继承。 * **标签补全**：非管理员玩家在 `/boatracing race` 下看到 `join|leave|status|vote|voteui|votestatus`；仅管理员动词（`open|start|force|stop|voteopen|voteclose`）仅对管理员建议。 更新器： * 控制台通知已恢复：启动后不久若版本过时打印单个 WARN，同时若仍过时则每小时提醒一次（尊重 `updates.console-warn`）。 * 管理员加入：当管理员加入时，运行快速检查（节流）并在新版本刚发布时数秒内通知他们。 **新功能 (1.0.7)** 错误修复与生活质量： * **控制台更新检查噪音移除**：仅当您版本过时时，在启动后不久打印单个 WARN（尊重 `updates.console-warn`）。每 5 分钟的静默周期性检查仍保留。 * **稳定性**：更新检查期间的网络错误在每次服务器运行中最多记录一次。 移除： * **内置隐藏原版计分板数字**已被移除。若您想隐藏侧边栏右侧数字，目前请使用外部插件，同时评估未来的内置方案。 UI： * **计分板重新设计**：居中行，紧凑的“Name - L X/Y CP A/B”布局，排名颜色（1=金，2=银，3=铜），您自己的名字为绿色。 **新功能 (1.0.6)** 改进与调整： * **新侧边栏排行榜**：侧边栏现在实时显示前 10 名。个人统计移至 ActionBar。 * **个人 HUD**：您的圈数、检查点和经过时间现在每 0.5 秒在 ActionBar 更新一次。 * **分段和完成差距**：紧凑消息显示您在每个检查点以及圈完成时相对于圈/完成领先者的时间差距（比赛完成时相对于获胜者）。 * **出发灯抖动**：通过 `racing.lights-out-jitter-seconds` 为出发灯延迟添加可选随机抖动。 * **实时排行榜**：侧边栏显示前 10 名；您的圈数/检查点/时间在 ActionBar 显示（比赛开始时自动创建，停止/重置时清理）。 * **隐藏原版数字**：当服务器支持时（Paper 1.20.5+），侧边栏右侧数字原生隐藏；无需 TAB 插件。 * **布局润色**：名称左对齐，整个“ - Lap X/Y \[CP\]”块居中。移除装饰分隔符和箭头前缀，基于最长可见名称的紧凑/动态填充。长名称用“...”截断，省略号后不添加额外填充。您自己的名字高亮为绿色（无粗体）。 * **FIN 标签**：标准化为“FINISHED”。 * **显示名称**：支持 EssentialsX displayName 并剥离开头的常见排名包装器如 \[Admin\]/(Rank) 以实现更整洁对齐。 **新功能 (1.0.5)** 修复与润色： * **队伍成员持久性**：队伍成员在更新/重载/启动间保留；加载恢复队伍而不重新应用容量限制。 * **设置维修站命令**：`/boatracing setup setpit [team]` 接受带空格的队伍名称（当引用时，例如 "/boatracing setup setpit "Toast Peace""）；标签补全在输入以引号开始时建议引用名称。 * **配置默认值**：在插件更新或 `/boatracing reload` 时，新默认键合并到现有 `config.yml` 而不覆盖您的更改。 * **船/筏类型**：选手以其选择的木材 variant（包括箱子 variant 和筏）而非总是橡木生成；跨 API 版本工作，带安全回退。 **新功能 (1.0.4)** * **队伍特定维修区**：新统一命令 `/boatracing setup setpit [team]` 在未提供队伍时设置默认维修站，或在提供队伍名时设置特定队伍的维修站。标签补全建议队伍名称。 * **强制维修站**：新 `racing.mandatory-pitstops` 配置（默认 0）。当 >0 时，选手必须在允许完成前完成至少该次维修站退出；维修站计数在退出维修区时进行，并持续整个比赛。 * **向导**：维修站步骤更新以提及默认维修站与各队伍维修站，并通过可点击提示引导流程。 * **配置更新**：在插件更新/重载时，新 `config.yml` 键合并到现有文件而不覆盖您的更改。 * **船类型**：选手以其选择的船/筏木材 variant（包括箱子 variant）而非总是橡木生成；跨 API 版本工作，带安全回退。 * **权限**：玩家默认可使用 `join`、`leave` 和 `status`；仅 `open|start|force|stop` 保持管理员专用。移除可能阻止具有宽松默认值的玩家的额外运行时检查。 * **船**：生成的船现在跨 API 版本稳健地尊重玩家选择的木材类型；如果枚举值不可用则回退到橡木。 * **每玩家开始槽位和网格排序**：新设置命令 `/boatracing setup setpos <player> <slot|auto>` 和 `/boatracing setup clearpos <player>`。比赛开始时，绑定到槽位的玩家首先放置；剩余选手按该赛道最佳记录时间排序（最快在前），无时间的选手置于最后。 * **设置显示**：现也显示队伍特定维修站的存在和配置的自定义开始位置数量。 * **向导（开始）**：显示自定义开始槽位管理的可选按钮 — setpos/clearpos/auto — 并显示配置的自定义槽位数量。 **新功能 (1.0.3)** * **管理员赛道图形界面**：管理多个命名赛道 — 创建和选择、删除（带确认）、重新应用所选。需要 `boatracing.setup`。 * **管理员比赛图形界面**：从图形界面管理比赛生命周期 — 打开/关闭注册、开始/强制/停止、快速设置圈数、移除注册者以及实用的设置提示。 * **术语**：“loaded” → “selected”；“pit lane” → “pit area”。 * **所有赛道配置按赛道存储在 `plugins/BoatRacing/tracks/<name>.yml` 下**。 * 启动时，旧版 `track.yml`（若存在）自动迁移至 `tracks/default.yml`（带游戏内管理员通知）。 * **设置向导用户体验**：简洁、着色、可点击。添加圈数步骤和显式完成按钮；导航按钮现在使用表情符号（⟵、ℹ、✖）且空行放置在块顶部以提高可读性。 * **选择工具**：内置魔杖（烈焰棒）。左键点击方块 = 角 A，右键点击方块 = 角 B。更丰富的 `/boatracing setup selinfo` 诊断。 * **比赛命令现需要赛道参数**：`open|join|leave|force|start|stop|status <track>`。 * **比赛生命周期**：“race stop”取消该赛道的注册和任何运行中的比赛。开始强制执行唯一网格槽位、面向前方（俯仰 0）并自动将选手载入其选择的船。“force”和“start”仅使用注册参与者。 * **标签补全**：对于需要 `<track>` 的比赛子命令（包括 `status`），它建议现有赛道名称。 * **管理员赛道图形界面**：创建赛道后，发送可点击提示以在聊天中粘贴 `/boatracing setup wizard`。 * **消息保持仅英文**：拒绝文本硬编码。 * **出发灯 + 抢跑**：精确配置 5 个红石灯，享受 F1 风格从左到右的灯光倒计时（无需红石布线）。倒计时期间移动（抢跑）应用可配置的时间罚时。 * **比赛权限**：按子命令拆分。玩家默认可 `join`、`leave` 和 `status`；管理员操作 `open|start|force|stop` 需要 `boatracing.race.admin`（或 `boatracing.setup`）。 * **维修区和检查点现在可选**。赛道就绪仅需至少一个开始槽位和终点线；向导将维修区和检查点标记为“（可选）”并允许跳过。 * 从赛道图形界面移除“另存为…”（创建/选择、删除和重新应用保留）。 * **新增**：每参与者的实时比赛计分板，显示圈数、检查点和经过时间。 * **新增**：穿过维修区在完成所有圈检查点后计为完成（若启用仍应用维修站罚时）。 ## 可用语言 * `en` English (official) * `es` Español (España) (official) * `es_419` Español (Latinoamerica) * `fr` Francais * `pt_BR` Portugues (Brasil) * `pt_PT` Portugues (Portugal) * `de` Deutsch * `it` Italiano * `pl` Polski * `tr` Turkce * `ja` Japanese * `ko` Korean * `zh_TW` Chinese (Taiwan, Traditional) * `zh_CN` Chinese (Mainland, Simplified) * `ru` Russian ## 功能 * **玩家队伍图形界面**：浏览队伍、打开队伍视图、加入/离开、管理您的选手编号和船类型，并在配置启用时从图形界面可选地重命名/更改颜色/解散。 * **管理员工具**：专门的图形界面用于队伍、玩家、比赛控制和命名赛道，以及用于脚本或控制台风格工作流的命令等效项。 * **命名赛道**：每个赛道存在于其自己的 YAML 文件中，可覆盖核心比赛设置，如圈数、强制维修站、注册时间、罚时和玩家比赛开始权限。 * **内置设置流程**：烈焰棒选择魔杖、立方体区域工具、可点击设置提示以及尽可能自动前进的紧凑引导向导。 * **网格控制**：自定义每玩家开始槽位、其余自动放置，以及按最佳记录赛道时间回退排序。 * **比赛系统**：有序检查点、可选维修区、可选强制维修站、抢跑罚时、注册大厅传送/返回、5 灯倒计时和实时结果广播。 * **多赛道比赛编排**：每赛道独立比赛会话以及聊天中管理员/玩家的地图投票命令。 * **HUD 和计分板**：比赛中侧边栏加 ActionBar，每部分配置切换，比赛后安全计分板恢复，以及外部计分板的兼容流程。 * **持久化统计**：`stats.yml` 存储胜利、最佳比赛和最佳圈速，以便 PlaceholderAPI、全息投影、计分板和 NPC 显示实时和历史数据。 * **国际化**：捆绑消息包用于 `en`、`es`、`es_419`、`fr`、`pt_BR`、`pt_PT`、`de`、`it`、`pl`、`tr`、`ja`、`ko`、`zh_TW`、`zh_CN`、`ru`；`en`/`es` 为官方，其余为社区翻译。全部可通过 `/boatracing reload` 热重载。 * **奖励、更新和指标**：每名次比赛奖励、Modrinth 更新检查以及可选的 bStats 指标。 ## 要求 * Java 17+ * 运行 Minecraft 1.19 至 1.21.11 的 Bukkit 兼容服务器 ## 支持的服务器 * CraftBukkit * Spigot * Paper * Purpur * Folia 其他 Bukkit 兼容分支可能有效，但本仓库未官方验证。 ## 平台说明 * Bukkit 系列的单个插件 jar。`plugin.yml` 针对 Bukkit API，Paper 元数据也标记插件为 Folia 支持。 * Velocity 和 BungeeCord 等代理不是 BoatRacing 游戏逻辑的执行目标。 * Mohist、Magma 或 Arclight 等 Sponge 和 Forge 混合服务器不被此 jar 支持。 ## 安装 1. 从 Modrinth 下载最新 BoatRacing jar：[https://modrinth.com/plugin/boatracing](https://modrinth.com/plugin/boatracing) 2. 将其放入您的 `plugins/` 文件夹。 3. 启动服务器一次以生成 config、messages、teams、racers、stats 和 track 文件。 4. （可选）若需 `%boatracing_*%` 占位符，请安装 PlaceholderAPI。 ## 使用 快速流程： 1. 运行 `/boatracing teams` 并创建或加入一个队伍。 2. 设置您的选手编号和船类型。 3. 从管理员赛道图形界面创建或选择赛道，或直接在活跃赛道上使用设置魔杖开始。 4. 配置开始、终点、出发灯和可选的维修站/检查点。 5. 使用 `/boatracing race open <track>` 打开注册。 6. 让玩家加入，然后开始或强制开始比赛。 根命令组： * `/boatracing teams` 打开玩家队伍图形界面。 * `/boatracing race ...` 管理注册和比赛生命周期。 * `/boatracing setup ...` 配置活跃赛道。 * `/boatracing admin` 打开管理员图形界面。 * `/boatracing reload` 重载配置、消息、队伍、选手和统计。 * `/boatracing version` 显示插件版本和更新状态。 ## 赛道设置 使用内置 BoatRacing 选择魔杖定义立方体区域。 * 用魔杖左键点击方块：设置角 A。 * 用魔杖右键点击方块：设置角 B。 * 魔杖物品：命名为 `BoatRacing Selection Tool` 的烈焰棒。 设置命令： * `/boatracing setup help` 显示设置命令列表。 * `/boatracing setup wand` 给予选择魔杖。 * `/boatracing setup addstart` 将您当前位置添加为开始槽位。 * `/boatracing setup clearstarts` 移除所有开始槽位。 * `/boatracing setup setfinish` 将当前选择保存为终点区域。 * `/boatracing setup setpit [team]` 将当前选择保存为默认维修站或特定队伍维修站。 * `/boatracing setup addcheckpoint` 按顺序追加检查点。 * `/boatracing setup clearcheckpoints` 移除所有检查点。 * `/boatracing setup addlight` 添加您正在看的红石灯作为出发灯。 * `/boatracing setup clearlights` 移除所有出发灯。 * `/boatracing setup setlaps <n>` 为活跃赛道保存圈数。 * `/boatracing setup setpitstops <n>` 为活跃赛道保存强制维修站。 * `/boatracing setup setlobby` 将您当前位置存储为注册大厅并启用。 * `/boatracing setup setpos <player> <slot|auto>` 将玩家绑定到自定义开始槽位，或用 `auto` 清除绑定。 * `/boatracing setup clearpos <player>` 移除自定义开始槽位绑定。 * `/boatracing setup show` 打印开始、出发灯、终点、维修站、队伍维修站、检查点、自定义槽位、维修站和活跃每赛道覆盖的摘要。 * `/boatracing setup selinfo` 打印选择调试信息。 设置规则： * 赛道在至少有一个开始槽位和终点区域时做好比赛准备。 * 维修区可选。 * 检查点可选。 * 出发灯对赛道有效性可选，但若使用系统期望恰好 5 个。 * 支持队伍特定维修区区域与默认维修区区域并存。 ### 引导设置向导 使用 `/boatracing setup wizard` 启动。 向导流程： * 开始 * 终点 * 出发灯 * 维修区 * 检查点 * 强制维修站 * 圈数 向导行为： * 向导由聊天驱动，对下一步操作使用可点击按钮。 * 当步骤有效时自动前进。 * 可选步骤支持跳过。 * 存在 `back`、`status`、`cancel`、`skip`、`next`、`finish` 等子操作，但为保持入口简单，故意不在标签补全中显示。 * 开始步骤也暴露自定义开始槽位管理的快速按钮。 ## 比赛与注册 比赛命令： * `/boatracing race help` * `/boatracing race open <track>` * `/boatracing race join <track>` * `/boatracing race leave <track>` * `/boatracing race back` * `/boatracing race start <track>` * `/boatracing race force <track>` * `/boatracing race stop <track>` * `/boatracing race status <track>` * `/boatracing race voteopen <track1> <track2> [seconds]` * `/boatracing race vote <track>` * `/boatracing race voteui` * `/boatracing race votestatus` * `/boatracing race voteclose` 比赛行为： * 玩家必须在加入注册前属于一个队伍。 * 注册在打开前加载赛道设置，包括任何每赛道 `racing.*` 覆盖。 * 多个比赛会话可在不同赛道上并行运行。 * 玩家一次只能在一个会话中注册/比赛。 * 标签补全为玩家包含 `vote`、`voteui` 和 `votestatus`，为管理员包含 `voteopen` 和 `voteclose`。 * 不带 `<track>` 的 `/boatracing race vote` 在活跃地图投票时打开投票图形界面（与 `/boatracing race voteui` 行为相同）。 * `/boatracing race voteopen ...` 现在在聊天中公告可点击的投票图形界面操作以运行 `/boatracing race voteui`。 * `start` 和 `force` 仅使用注册玩家。 * `start`、`force`、图形界面开始和注册超时自动开始要求至少 `racing.min-players-to-start` 在线注册玩家。 * 最低开始阈值默认为 `1`，可通过 `tracks/<name>.yml` 中的 `racing.min-players-to-start` 按赛道覆盖，不满足时显示 `race.not-enough-players`。 * 网格顺序：自定义开始槽位绑定优先，然后是最佳记录赛道时间，最后是无记录时间的玩家。 * 船使用每个玩家选择的船类型生成，带跨版本安全材质解析。 * 若存在检查点，仅当所有检查点按顺序收集后才计一圈。 * 维修区进入可应用时间罚时，维修站退出计数满足强制维修站要求。 * 抢跑可在灯光倒计时期间应用额外罚时。 * 若启用注册大厅，加入注册将玩家传送到那里。 * 离开注册或注册取消可将玩家返回其之前位置（`racing.lobby.return-on-leave`）。 * 比赛结束或比赛取消后，参与者返回大厅并在聊天中收到可点击的 `/boatracing race back` 提示。 * 保存的前大厅返回位置在内存中保留 3 分钟；之后，该比赛周期的 `/boatracing race back` 过期。 * 结果按经过时间加罚时排序并广播给在线玩家。 * 获胜者更新占位符使用的持久化玩家/队伍统计。 玩家管理的比赛： * 默认情况下，比赛控制仅限管理员。 * 当全局启用 `player-actions.allow-player-race-start: true` 时，非管理员玩家也可开启、开始、强制开始和停止比赛。 * 赛道可通过 `tracks/<name>.yml` 中的 `racing.allow-player-start: true|false` 覆盖该设置。 ## 标签补全 根建议： * 根据权限显示 `teams`、`race`、`setup`、`admin`、`reload`、`version`。 队伍建议： * `create`、`rename`、`color`、`join`、`leave`、`boat`、`number`、`confirm`、`cancel` * `join` 建议队伍名称。 * `color` 建议所有染料颜色。 * `boat` 建议支持的船和箱子船 variants，以及竹筏。 比赛建议： * 所有人都看到 `help`、`join`、`leave`、`status`。 * 拥有 `boatracing.race.back` 的玩家也看到 `back`。 * 管理员能力用户也看到 `open`、`start`、`force`、`stop`。 * 需要赛道的子命令建议现有命名赛道。 设置建议： * `help`、`addstart`、`clearstarts`、`setfinish`、`setpit`、`addcheckpoint`、`clearcheckpoints`、`addlight`、`clearlights`、`setlaps`、`setpitstops`、`setlobby`、`setpos`、`clearpos`、`show`、`selinfo`、`wand`、`wizard` * `setpit` 建议队伍名称，输入以引号开头时建议引用名称。 * `setpos` 和 `clearpos` 建议在线和已知离线玩家名称。 * `setpos` 也建议 `auto` 和可用槽位号。 管理员建议： * `help`、`team`、`player`、`tracks` * `team` 建议 `create`、`delete`、`rename`、`color`、`add`、`remove` * `player` 建议 `setteam`、`setnumber`、`setboat` ## 管理员命令和图形界面 `/boatracing admin` 打开管理员中心。 管理员图形界面部分： * 队伍：创建队伍、打开队伍视图、重命名、重新着色、添加/移除成员、删除队伍。 * 玩家：分配/移除队伍、设置选手编号、设置船类型。 * 比赛：打开/关闭注册、开始/强制/停止、快速设置圈数、自定义圈数、移除注册者。 * 赛道：创建/选择/删除命名赛道并从磁盘重新应用所选赛道。 命令等效项： * `/boatracing admin team create <name> [color] [firstMember]` * `/boatracing admin team delete <name>` * `/boatracing admin team rename <old> <new>` * `/boatracing admin team color <name> <DyeColor>` * `/boatracing admin team add <name> <player>` * `/boatracing admin team remove <name> <player>` * `/boatracing admin player setteam <player> <team|none>` * `/boatracing admin player setnumber <player> <1-99>` * `/boatracing admin player setboat <player> <BoatType>` * `/boatracing admin tracks` ## 权限 * `boatracing.*`（默认：false）：整个插件的通配符。 * `boatracing.use`（默认：true）：基础元权限。 * `boatracing.teams`（默认：true）：访问 `/boatracing teams`。 * `boatracing.version`（默认：true）：访问 `/boatracing version`。 * `boatracing.reload`（默认：op）：访问 `/boatracing reload`。 * `boatracing.update`（默认：op）：接收游戏内更新通知。 * `boatracing.setup`（默认：op）：访问赛道设置、向导、选择和设置图形界面。 * `boatracing.admin`（默认：op）：访问管理员图形界面和管理功能。 * `boatracing.race.join`（默认：true）：加入注册。 * `boatracing.race.leave`（默认：true）：离开注册。 * `boatracing.race.back`（默认：true）：返回保存的前大厅位置。 * `boatracing.race.status`（默认：true）：检查赛道比赛状态。 * `boatracing.race.admin`（默认：op）：使用 `open`、`start`、`force` 和 `stop` 管理比赛。 权限说明： * `boatracing.admin` 通过显式子项授予其他插件权限。 * 玩家始终能看到 `race` 根建议，但实际子命令仍受权限/配置限制。 * 非管理员比赛管理由配置和每赛道覆盖控制，而非单独的额外权限节点。 ## 配置 核心： * `prefix`：聊天前缀。 * `language`：捆绑值为 `en`、`es`、`zh_TW`、`zh_CN`、`ru`。 * `max-members-per-team`：队伍大小限制。 玩家操作： * `player-actions.allow-team-create` * `player-actions.allow-team-rename` * `player-actions.allow-team-color` * `player-actions.allow-team-disband` * `player-actions.allow-set-boat` * `player-actions.allow-set-number` * `player-actions.allow-player-race-start` 更新和指标： * `updates.enabled` * `updates.console-warn` * `updates.notify-admins` * `bstats.enabled` 全局比赛默认值： * `racing.laps` * `racing.mandatory-pitstops` * `racing.pit-penalty-seconds` * `racing.registration-seconds` * `racing.min-players-to-start` * `racing.false-start-penalty-seconds` * `racing.enable-pit-penalty` * `racing.enable-false-start-penalty` * `racing.lights-out-delay-seconds` * `racing.lights-out-jitter-seconds` 注册大厅： * `racing.lobby.enabled` * `racing.lobby.return-on-leave` * `racing.lobby.back-window-seconds` * `racing.lobby.world` * `racing.lobby.x` * `racing.lobby.y` * `racing.lobby.z` * `racing.lobby.yaw` * `racing.lobby.pitch` HUD 切换： * `racing.ui.scoreboard.show-position` * `racing.ui.scoreboard.show-lap` * `racing.ui.scoreboard.show-checkpoints` * `racing.ui.scoreboard.show-pitstops` * `racing.ui.scoreboard.show-name` * `racing.ui.actionbar.show-lap` * `racing.ui.actionbar.show-checkpoints` * `racing.ui.actionbar.show-pitstops` * `racing.ui.actionbar.show-time` 奖励： * `racing.rewards.enabled` * `racing.rewards.positions.<place>.commands` * `racing.rewards.positions.<place>.messages` * `racing.rewards.positions.<place>.broadcast` * 旧版兼容：`racing.rewards.positions.<place>.command`（单字符串）也接受，但推荐 `commands` 列表。 * 推荐架构卫生：为每个配置的名次块（包括 `1`）显式保留 `commands: []`。 * 支持的奖励占位符：`{player}`、`{position}`、`{time}`、`{track}`、`{laps}` 消息模板： * 注册公告文本是语言特定的，位于 `messages_<lang>.yml` 下的 `race.registration.announce`。 * 该模板支持 `{track}`、`{laps}`、`{cmd}` 和 `{label}`。 * 最低人数开始警告是语言特定的，位于 `race.not-enough-players`，支持 `{min}` 和 `{current}`。 每赛道覆盖： * `plugins/BoatRacing/tracks/<name>.yml` 下的赛道文件可覆盖 `racing.*` 值。 * 常见覆盖示例：需要更大网格的赛道的 `racing.min-players-to-start`。 * `setup show` 打印当前赛道的活跃覆盖集。 ## 更新和指标 * 更新源：Modrinth。 * 启动时若插件过时可打印 WARN。 * 静默后台检查每 5 分钟运行一次。 * 运行时首次检测到新版本会触发该版本的一次性控制台 WARN。 * 若启用 `updates.console-warn`，在版本过时期间每小时提醒警告保持活动。 * 拥有 `boatracing.update` 的管理员玩家可在加入时接收游戏内通知。 * bStats 默认启用，可通过 `bstats.enabled` 禁用。 ## 存储 * `plugins/BoatRacing/teams.yml`：队伍成员、颜色、名称和当前队伍领袖。 * `plugins/BoatRacing/racers.yml`：每玩家选手编号和船类型。 * `plugins/BoatRacing/stats.yml`：玩家胜利、队伍胜利、最佳比赛和最佳圈速。 * `plugins/BoatRacing/tracks/<name>.yml`：每个赛道一个文件，包含开始、终点、维修区、队伍维修站、检查点、出发灯、自定义槽位、最佳时间和每赛道比赛覆盖。 旧版迁移： * 若找到旧版 `plugins/BoatRacing/track.yml`，它自动迁移至 `plugins/BoatRacing/tracks/default.yml`（必要时为 `default_N.yml`）。 ## 兼容性 * Minecraft：1.19 至 1.21.11 * Java：17+ * 服务器系列：CraftBukkit、Spigot、Paper、Purpur、Folia * 可选 PlaceholderAPI 支持（软依赖） * 与 SimpleScore 兼容性钩子，用于在比赛期间隐藏/恢复外部侧边栏 * 与 TAB 环境兼容以使用计分板，无需特定 TAB 依赖 * 捆绑语言：英语、西班牙语、法语、葡萄牙语（巴西）、德语、意大利语、波兰语、土耳其语、日语、韩语、中文（台湾，繁体）、中文（大陆，简体）、俄语 * 注意：`pt_BR`、`de`、`it`、`pl`、`tr`、`ja`、`ko` 是捆绑起始文件，可能仍需要翻译审核。 * 自定义语言通过插件数据文件夹中的 `messages_<lang>.yml` 支持，并可使用 `language: "<lang>"` 选择。 ## 占位符 (PlaceholderAPI) 若安装 PlaceholderAPI，BoatRacing 注册 `%boatracing_*%` 占位符用于计分板、全息投影、NPC 和静态显示。 解析规则： * 缺失类文本数据通常解析为 `-`。 * 缺失数字数据通常解析为 `0` 或 `-1`，取决于占位符。 * `%boatracing_player_*%` 使用查看者作为上下文。 * `%boatracing_player_*_<player>%` 使用显式玩家名称或 UUID，是 NPC 和静态全息投影的理想选择。 * 队伍领袖占位符始终解析该队伍当前保存的领袖。 * 按赛道范围的比赛占位符（`%boatracing_track_race_*_<track>%`）针对请求赛道的比赛会话解析。 * 按赛道范围的最佳记录占位符（`%boatracing_track_best_*_<track>%`）针对请求的赛道令牌解析，不仅针对当前选择的赛道。 * 兼容别名可用：`%boatracing_track_racerunning_<track>%` 和 `%boatracing_track_raceregistering_<track>%`。 * 对于按赛道范围的比赛占位符，无活跃会话的赛道解析为 `false`（`running`/`registering`）或 `idle`（`status`）。 * `<track>` 令牌支持下划线代替空格（例如 `My_Track`）。 ### 类别：查看者玩家和队伍 占位符 显示内容 屏幕示例 可见性 `%boatracing_player_name%` 查看者玩家名称 `Driver: jaie55` 仅查看者看到其自身值 `%boatracing_player_team_name%` / `%boatracing_player_team_id%` / `%boatracing_player_team_color%` 查看者队伍身份 `Team: Sharks` / `Team ID: sharks` / `Color: AQUA` 查看者上下文 `%boatracing_player_team_leader_name%` / `%boatracing_player_team_leader_id%` 查看者队伍的当前领袖 `Leader: jaie55` 查看者上下文 `%boatracing_player_team_players%` / `%boatracing_player_team_player_count%` 查看者队伍名单和人数 `Members: jaie55, KiluGod` / `Members: 2` 查看者上下文 `%boatracing_player_number%` / `%boatracing_player_boat%` 查看者选手编号和选择的船 `Number: 7` / `Boat: OAK_BOAT` 查看者上下文 ### 类别：查看者实时比赛状态 占位符 显示内容 屏幕示例 可见性 `%boatracing_player_race_running%` / `%boatracing_player_race_registering%` 查看者当前是否正在比赛或当前在自身比赛会话中注册 `Running: true` / `Registering: false` 查看者上下文 `%boatracing_track_race_running_<track>%` / `%boatracing_track_race_registering_<track>%` / `%boatracing_track_race_status_<track>%` 特定赛道令牌的按赛道范围比赛状态（`running`、`registering`、`idle`） `Harbor running: true` / `Harbor status: running` / `Desert status: idle` 所有查看者相同 `%boatracing_track_racerunning_<track>%` / `%boatracing_track_raceregistering_<track>%` 按赛道运行/注册布尔值的向后兼容别名 `Harbor running(alias): true` / `Desert registering(alias): false` 所有查看者相同 `%boatracing_player_current_time%` / `%boatracing_player_current_time_ms%` 查看者实时计时器 `Time: 1:42.355` / `TimeMs: 102355` 查看者上下文 `%boatracing_player_current_lap%` / `%boatracing_player_current_checkpoint%` 查看者圈数和下一个检查点进度 `Lap: 2` / `Checkpoint: 5` 查看者上下文 `%boatracing_player_current_position%` / `%boatracing_player_current_pitstops%` / `%boatracing_player_finished%` 查看者实时位置、维修站次数和完成状态 `Pos: 1` / `Pit stops: 0` / `Finished: false` 查看者上下文 ### 类别：查看者记录和胜利 占位符 显示内容 屏幕示例 可见性 `%boatracing_player_track_best%` / `%boatracing_player_track_best_ms%` 查看者在当前赛道的最佳时间 `Track PB: 0:59.443` 查看者上下文 `%boatracing_player_best_race%` / `%boatracing_player_best_race_ms%` 查看者整体最佳比赛 `Best race: 1:40.010` 查看者上下文 `%boatracing_player_best_lap%` / `%boatracing_player_best_lap_ms%` 查看者整体最佳圈速 `Best lap: 0:28.911` 查看者上下文 `%boatracing_player_wins%` / `%boatracing_player_team_wins%` 查看者胜利数和查看者队伍胜利数 `Wins: 12` / `Team wins: 18` 查看者上下文 ### 类别：全局和顶级统计 占位符 显示内容 屏幕示例 可见性 `%boatracing_teams_count%` / `%boatracing_teams_list%` 队伍总数和队伍列表 `Teams: 4` / `Teams: Sharks, Rockets, Drift, Wave` 所有查看者相同 `%boatracing_track_name%` / `%boatracing_track_best_player%` / `%boatracing_track_best_time%` 当前赛道名称及其最佳记录 `Track: harbor` / `Track record: jaie55 - 0:58.772` 所有查看者相同 `%boatracing_track_best_player_<track>%` / `%boatracing_track_best_time_<track>%` / `%boatracing_track_best_time_ms_<track>%` 特定赛道令牌的最佳记录 **NEW (1.1.4)** `%boatracing_track_best_time_harbor%` -> `0:58.772` / `%boatracing_track_best_player_harbor%` -> `jaie55` 所有查看者相同 `%boatracing_track_top_1_player_<track>%` / `%boatracing_track_top_1_time_<track>%` / `%boatracing_track_top_1_time_ms_<track>%` 特定赛道令牌的第一名持有者和时间 **NEW (1.1.4)** `%boatracing_track_top_1_player_harbor%` -> `jaie55` / `%boatracing_track_top_1_time_harbor%` -> `0:58.772` 所有查看者相同 `%boatracing_track_top_2_player_<track>%` / `%boatracing_track_top_2_time_<track>%` / `%boatracing_track_top_2_time_ms_<track>%` 特定赛道令牌的第二名持有者和时间 **NEW (1.1.4)** `%boatracing_track_top_2_player_harbor%` -> `KiluGod` / `%boatracing_track_top_2_time_harbor%` -> `1:00.120` 所有查看者相同 `%boatracing_track_top_3_player_<track>%` / `%boatracing_track_top_3_time_<track>%` / `%boatracing_track_top_3_time_ms_<track>%` 特定赛道令牌的第三名持有者和时间 **NEW (1.1.4)** `%boatracing_track_top_3_player_harbor%` -> `RacerX` / `%boatracing_track_top_3_time_harbor%` -> `1:01.004` 所有查看者相同 `%boatracing_top_player_wins_name%` / `%boatracing_top_player_wins%` 胜利最多的玩家 `Top wins: jaie55 (29)` 所有查看者相同 `%boatracing_top_team_wins_name%` / `%boatracing_top_team_wins%` 胜利最多的队伍 `Top team: Sharks (77)` 所有查看者相同 `%boatracing_top_player_best_race_name%` / `%boatracing_top_player_best_race%` 最佳比赛持有者和时间 `Best race: KiluGod - 1:38.404` 所有查看者相同 `%boatracing_top_player_best_lap_name%` / `%boatracing_top_player_best_lap%` 最佳圈速持有者和时间 `Best lap: jaie55 - 0:27.950` 所有查看者相同 ### 类别：按名称查找队伍 使用 `<team>` 与队伍令牌。名称带空格的队伍可在文档/示例中使用下划线地址。 占位符 显示内容 屏幕示例 可见性 `%boatracing_team_leader_name_<team>%` / `%boatracing_team_leader_id_<team>%` 特定队伍的当前领袖 `%boatracing_team_leader_name_sharks%` -> `Leader: jaie55` 所有查看者相同 `%boatracing_team_players_<team>%` 特定队伍的玩家列表 `%boatracing_team_players_sharks%` -> `Members: jaie55, KiluGod` 所有查看者相同 `%boatracing_team_player_count_<team>%` 特定队伍的成员数 `%boatracing_team_player_count_sharks%` -> `Members: 2` 所有查看者相同 `%boatracing_team_wins_<team>%` 特定队伍的胜利数 `%boatracing_team_wins_sharks%` -> `Wins: 77` 所有查看者相同 ### 类别：按名称或 UUID 查找玩家 使用 `<player>` 与精确玩家名称或 UUID。这些是 NPC、雕像标签、固定全息投影和排行榜墙的占位符。 占位符 显示内容 屏幕示例 可见性 `%boatracing_player_name_<player>%` 目标玩家名称 `%boatracing_player_name_jaie55%` -> `Driver: jaie55` 所有人都看到目标玩家数据 `%boatracing_player_wins_<player>%` 目标玩家胜利数 `%boatracing_player_wins_jaie55%` -> `Wins: 12` `jaie55` 和 `KiluGod` 都看到 Jaie55 的胜利 `%boatracing_player_best_race_<player>%` / `%boatracing_player_best_race_ms_<player>%` 目标玩家最佳比赛 `%boatracing_player_best_race_jaie55%` -> `Best race: 1:40.010` 所有人都看到目标玩家数据 `%boatracing_player_best_lap_<player>%` / `%boatracing_player_best_lap_ms_<player>%` 目标玩家最佳圈速 `%boatracing_player_best_lap_jaie55%` -> `Best lap: 0:28.911` 所有人都看到目标玩家数据 `%boatracing_player_track_best_<player>%` / `%boatracing_player_track_best_ms_<player>%` 目标玩家在当前赛道的最佳时间 `%boatracing_player_track_best_jaie55%` -> `Track PB: 0:59.443` 所有人都看到目标玩家数据 `%boatracing_player_team_name_<player>%` / `%boatracing_player_team_id_<player>%` / `%boatracing_player_team_color_<player>%` 目标玩家的队伍信息 `Team: Sharks` / `Team ID: sharks` / `Color: AQUA` 所有人都看到目标玩家数据 `%boatracing_player_team_leader_name_<player>%` / `%boatracing_player_team_leader_id_<player>%` 目标玩家队伍的当前领袖 `%boatracing_player_team_leader_name_jaie55%` -> `Leader: jaie55` 所有人都看到目标玩家数据 `%boatracing_player_team_wins_<player>%` 目标玩家队伍的胜利数 `%boatracing_player_team_wins_jaie55%` -> `Team wins: 18` 所有人都看到目标玩家数据 `%boatracing_player_number_<player>%` / `%boatracing_player_boat_<player>%` 目标玩家的选手编号和选择的船 `Number: 7` / `Boat: OAK_BOAT` 所有人都看到目标玩家数据 ## 备注 * 队伍可有多个成员和当前保存的领袖。领袖占位符始终反映当前领袖，而非历史创建者值。 * 若当前领袖离开队伍，领导权自动回退到下一个存储的成员。 * 作为最后成员离开队伍会自动删除该队伍。 * 面向用户的文本基于消息捆绑包，可在 `messages_<lang>.yml` 中自定义，然后使用 `/boatracing reload` 重载。 ## 构建（开发者） * Maven 项目；生成 `BoatRacing.jar` 运行包。运行 `mvn -DskipTests clean package`。 ## 许可证 根据 MIT 许可证分发。详见 `LICENSE`。 [/MD]