查看“路径点插件技术文档”的源代码

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

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

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

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

== 如何加入一场比赛 ==
<pic src="https://wiki.oases.red/uploads/7/79/cpt-wiki-1.png" caption="玩家可参考"></pic>

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

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

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

{{helper-alert|text=默认情况下，清空一场比赛的数据以后会自动重新加入这场比赛。如需加入其它比赛，请自行使用 /cpt switch 切换。}}

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

== 管理员：如何创建路径点 ==
若要创建路径点，需要拥有 <code>checkpoint.admin</code> 权限。

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

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

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

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

== 注意事项 ==

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

== 配置文件 ==

* config.yml 用于配置插件功能。
* tracks.yml 用于存储赛道和路径点。
* campaigns.yml 用于存储竞赛设置。
* analytics.yml 用于存储玩家竞赛数据。
* checkpoints.yml 用于存储玩家可用的记录点数据。
* progress.yml 用于存储玩家的进度跟踪数据（暂未推出）。
<syntaxhighlight lang="yaml">
# 在玩家执行 /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
</syntaxhighlight>

== 常见问题 ==

=== 问题 1：提示「找不到可自动分配比赛，请联系管理员」？ ===
这句话的意思是，由于服务器的设置，会在你加入服务器的时候尝试帮你自动分配一个比赛。然而，可能所有的比赛都处于 close（关闭）或者 private（私密）状态，所以自动分配失败了。

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

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

=== 问题 2：如果在比赛中途掉线呢？ ===
如果已经开始滑翔而掉线，具体情况'''根据服务器设置而定'''，但建议确保网络连接稳定再比赛！

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

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

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

=== 问题 3：穿过一个路径点但是没有任何提示/反应？ ===
可能是你没有执行 <code>/cpt join</code>。或者是你执行了 <code>/cpt quit</code>。

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

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

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

=== 问题 4：我可以参加多少个比赛？ ===
当前还没有设置最高上限的功能，因此理论上可以参加一个或者无数个，具体取决于服务器的配置。

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

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

=== 问题 5：如何查看成绩？ ===
<code>/cpt rank <比赛名称> [页码]</code> 查看你的排名，排名中会有成绩。

=== 问题 6：我可以一直保持在比赛中途状态吗？ ===
在 2023.08.26 18:00 以后的版本中，玩家在比赛的每一段（即点与点之间）所停留的时间有一定的限制，超过此限制将会自动删除当前比赛数据。默认情况下此限制为 120 秒。

=== 问题 7：中途下线，还会计时吗？ ===
依照服务器设定而定，详见问题 2。

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

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