路径点插件技术文档

路径点插件（checkpoint）用于类似于喵窝 World Wings Rally 鞘翅拉力赛的竞赛。支持设置一系列有序的路径点，并将其存储于相应的赛道中。同时可以开设竞赛让玩家参与。

指令

本插件的指令均以 /checkpoint 开头，也可以简写为 /cpt。

玩家指令


指令	解释
`/cpt about`	查看本插件的关于信息。
`/cpt join`	不带参数，声明加入比赛。在赛道上滑翔之前，必须先加入比赛。加入比赛后，服务器会为你自动分配一个默认赛道。
`/cpt switch <campaign>`	切换到指定的竞赛（赛道）中。
`/cpt quit`	退出已经加入的所有竞赛，并清空自己的竞赛数据。
`/cpt reset <campaign>`	清除参与的一场比赛的数据，并自动重新加入这场比赛。
`/cpt rank <campaign> [pagenum]`	显示对应竞赛的排名信息。
`/cpt mycampaign`	查看已经加入竞赛的概况。
`/cpt teleport <number>`	teleport 可以简写为 tp。传送到可用的记录点。在赛道中所有的点中，有部分会是记录点。当通过了这些记录点后，你便可以在比赛过程中随时传送到那个点。到达终点后记录点将会被清空。在目前的插件版本中，退出游戏后记录点也会被清空。
`/cpt resume`	如果服务器允许保存离线数据，那么在一定的时间段（由服务器规定）内，加入服务器以后可以通过此指令来继续先前的进度。

管理员指令


指令	解释
`/cpt build <track> <number> [force?]`	从选区创建一个新的路径点。参数 track 对应的是赛道名称，如果不存在会自动创建。参数 number 对应的是路径点在该赛道的位置，从 1 开始。如果对应路径点已存在，必须将 force 设为 true 才能覆盖。
`/cpt remove <track> <number>`	删除指定的路径点。执行此项需要特别注意，见注意事项的第一条。
`/cpt copy <from-track.number> <to-track.number> [force?]`	将 from-track.number 复制到 to-track.number。如果复制到的路径不存在会自动创建。例如 `/cpt copy track1.2 track2.3` 代表将 track1 序号为 2 的点复制到 track2 序号为 3 的点处。如果 to-track.number 已经存在，那么必须把 force 指定为 true 才可执行覆盖。copy 可以简写为 cp。
`/cpt xcopy <T1.N1,T2.N2,...> <t1.n1,t2.n2,...> [force?]`	将第一个序列里的各个点分别复制到第二个序列中的各个点。例如 `/cpt xcopy track1.2,track1.3 track2.1,track2.2` 代表将 track1.2 复制到 track2.1，将 track1.3 复制到 track2.2。由于是一一对应的，两个序列的元素数量必须相同。force 参数同上。xcopy 可以简写为 xcp。
`/cpt move <from-track> <to-track> <n1,n2,n3...>`	将 from-track 中的 n1, n2, n3... 赛道迁移到新的 to-track 中。to-track 必须不含任何赛道。其中在指定序号时，可以使用连续符号：`1-7,9` 等价于 `1,2,3,4,5,6,7,9`。同理还可以使用 `1-2,4-9` 等来表示。
`/cpt list <track> [pagenum]`	列出 track 中的路径点。
`/cpt campaign new <name> [track]`	创建一场新的比赛，名为 name，对应的赛道为 track。如果 track 不填，那么自动使用与比赛同名的 track（如果存在）。默认新建的比赛是关闭的。
`/cpt campaign setstatus <name> <open\|close\|private>`	设置比赛开启状态，open、close 或者 private。open 状态的比赛，所有人都可以加入、参与；close 状态的比赛，所有人都不能加入、参与；private 的比赛，所有人都不能加入，但是已经加入的人可以参与。
`/cpt campaign delete <name>`	删除比赛。不影响赛道、玩家统计数据。
`/cpt setcheckpoint <track> <number> [flag]`	将指定路径点设置或取消设置为检查点，当玩家通过这些点以后，可以通过指令传送到这些点。flag 留空默认为 true。

如何加入一场比赛

玩家可参考

输入 /cpt join 来加入到比赛中。加入时，会自动为你分配到一个默认的比赛中，如果分配到的比赛没错，就可以马上开始滑翔了！

不过，有的时候整个比赛会分为若干个赛道组成的若干个小比赛，此时你可以通过 /cpt switch <比赛名称> 切换到相应的你想要参与的比赛中。

当成功到达最后一个路径点时，你的比赛成绩会被马上储存，并且可以由任何人通过 /cpt rank <比赛名称> 查看到。如果认为这次成绩不够好，可以输入 /cpt reset <比赛名称> 清空此次成绩后，重新开始这场比赛。

如果因特殊原因，不再参加比赛，可以输入 /cpt quit 退出参与比赛。注意此指令也会清空你的所有比赛数据，因此一般情况不要使用。

管理员：如何创建路径点

若要创建路径点，需要拥有 checkpoint.admin 权限。

手持光灵箭，右键（不用左键）依次单击顶点 1 和顶点 2，然后输入 /cpt build <赛道名称> <序号> 即可创建。对顶点的要求与 Residence、World Edit 等插件类似，须为对角顶点。

如需舍去已选选区，用左键单击任意方块即可。

如需更改，继续右键选择即可，顶点 1 和顶点 2 将轮换选择（Cropenfe 的建议）。

如需直接覆盖已经存在的路径点而创建，执行 /cpt build <赛道名称> <序号> true 即可。

注意事项

任何一个赛道内的路径点的序号必须是连续的（必须是从 1 开始，然后依次递增），否则会发生不可预测的错误。这在通过指令删除路径点时需要注意。使用指令 /cpt forcecontinuous <赛道名称> 可以整理此赛道下不连续的序号（顺序不变）。
在比赛期间，玩家或者服务器掉线会导致未到达终点玩家的进度数据丢失，因此请确保网络顺畅再开始比赛。这一点会在后续更新中逐渐修复。
现阶段插件为初版，bug 在所难免，因此请积极汇报你遇到的 Bug。汇报方式见文末。

配置文件

config.yml 用于配置插件功能。
tracks.yml 用于存储赛道和路径点。
campaigns.yml 用于存储竞赛设置。
analytics.yml 用于存储玩家竞赛数据。
checkpoints.yml 用于存储玩家可用的记录点数据。
progress.yml 用于存储玩家的进度跟踪数据（暂未推出）。

# 在玩家执行 /cpt join 后为玩家分配的默认竞赛的名称
# 留空则随机选择
default-campaign-name: ~
# 如果为 true，玩家只能在一个比赛中留下数据
# 当切换到另外的比赛时，先前比赛的数据会被删除
# 建议当此项为 true 时给玩家适当的提醒。
single-choice: false
# 如果为 true，自动在玩家登录的时候执行 /cpt join
# 如果执行不成功（例如所有的比赛都处于关闭状态），会为玩家发送一条提示
# 如果不需要这条提示，请启用 disable-auto-join-failure-warning。
auto-join-on-login: false
# 见上
disable-auto-join-failure-warning: false
# 当玩家在比赛中途退出服务器后，要将其进度保存多久
# 单位：秒，整数
# 如果设置为 0，则不为中途退出服务器的玩家保存任何数据
# 如果为正数，当中途退出服务器的玩家迟于该期限上线，不能继续进度
# 如果为负数，表示不设期限（不建议）
halfway-progress-deadline: 0
# 允许在一段之间停留的最长时间
# 单位：秒，整数
# 在单段停留超出此时间，整场比赛的数据会被重置，并提示玩家
timer-max-timeout: 120
# 是否在玩家下线后仍然计时
allow-timer-working-offline: false
# 是否允许玩家手动使用 /cpt resume 继续比赛
allow-resume: true
# 如果为 true，会在玩家上线的时候自动尝试继续其比赛
# 如果执行不成功（例如期限已过），会为玩家发送一条提示
# 如果不需要这条提示，请启用 disable-auto-resume-failure-warning。
auto-resume-on-login: false
disable-auto-resume-failure-warning: false
# 将所有选取的检测范围扩大指定的格数（x y z 三个方向）
point-detection-offset: 0

常见问题

问题 1：提示「找不到可自动分配比赛，请联系管理员」？

这句话的意思是，由于服务器的设置，会在你加入服务器的时候尝试帮你自动分配一个比赛。然而，可能所有的比赛都处于 close（关闭）或者 private（私密）状态，所以自动分配失败了。

请在比赛被设置为 open 后再使用 /cpt join 参加，/cpt switch 切换。

当然，也有可能是管理员疏忽忘记设置为 open 了，请提醒管理员。

问题 2：如果在比赛中途掉线呢？

如果已经开始滑翔而掉线，具体情况根据服务器设置而定，但建议确保网络连接稳定再比赛！

当然，如果你不经常掉线，就不要自己吓自己了。

当 halfway-progress-deadline 设置为 0 时，掉线以后数据会被删除。
当 halfway-progress-deadline 设置为正数时，掉线以后数据会在此指定的秒数内存在，再次上线以后可使用 /cpt resume 继续比赛。

还需要注意服务器设置的 timer-max-timeout，当在同一段内超过此秒数，数据也会被删除。当 allow-timer-working-offline 设定为 true 时，下线以后仍然会计时。

问题 3：穿过一个路径点但是没有任何提示/反应？

可能是你没有执行 /cpt join。或者是你执行了 /cpt quit。

如果已经执行了 /cpt join 而没有反应，请检查执行以后的提示信息是否显示「参赛失败，暂无比赛可选择」的信息（这条信息的含义见问题 1）。

也可能是你已经完成了这场比赛。如果需要重新开始，请输入 /cpt reset <比赛名称> 来重置，这会删掉上次的参赛数据。

如果确定已经执行而且已经切换到了某场具体的比赛，仍然没有反应，这很有可能是一个 bug，请参阅文末的「问题反馈或参与维护」章节提出反馈，帮助我们改善插件！

问题 4：我可以参加多少个比赛？

当前还没有设置最高上限的功能，因此理论上可以参加一个或者无数个，具体取决于服务器的配置。

如果插件配置中的 single-choice 被设置为 true，那么每个玩家都只能参加一个比赛。此时如果使用 /cpt switch 切换到另一场比赛，前一场比赛的数据会被删除。

如果插件配置中的 single-choice 被设置为 false（默认），那么每个玩家可以无限制地参加比赛并保存比赛数据。

问题 5：如何查看成绩？

/cpt rank <比赛名称> [页码] 查看你的排名，排名中会有成绩。

问题 6：我可以一直保持在比赛中途状态吗？

在 2023.08.26 18:00 以后的版本中，玩家在比赛的每一段（即点与点之间）所停留的时间有一定的限制，超过此限制将会自动删除当前比赛数据。默认情况下此限制为 120 秒。

问题 7：中途下线，还会计时吗？

依照服务器设定而定，详见问题 2。

问题反馈或参与维护

服务器内外用户均可反馈和维护。前往 GitHub 提交 Issue 或者 Pull Request 即可。

https://github.com/oasis-mc/checkpoint