10 Upgrade Notes

10 升级说明

中文版本 | English version

这一页用于从旧版本升级到当前版本时快速核对。普通首次安装不需要阅读这一页，直接看 1 快速开始 即可。

升级到 2.4

• /wild 现在是独立的长距离随机传送模块，不再是 /rtp 的别名。检查新增的 wild.enabled、wild.minRadius 和 wild.maxRadius。
• Home 模块新增共享发布与订阅。发布和订阅是运行时状态，不会迁移或写入存储；重启后需要重新建立。
• home 配置新增 sharedHomeMaximum 和 sharedHomeBroadcastCooldownSeconds，旧配置缺少这些字段时会使用默认值。
• /homes 与 /warps 增加管理页面和删除确认，原有命令仍然保留。

2.4 不提升配置或存储版本，原有 home、warp、back 和 TPA 数据格式不变。

升级前

升级前建议先做两件事：

• 备份服务器目录中的配置文件和存储数据。
• 确认服务器可以正常停止，不要在运行中直接替换模组文件。

当前配置文件位于：

config/teleport_commands.json

旧版存储如果仍然存在，会在首次启动时自动迁移到当前存储结构。迁移成功后，旧文件会被归档，避免重复迁移。

升级后优先检查

启动后建议按顺序检查：

/tpc status
/tpc help
/tpc config teleporting preload
/tpc config teleporting defaultSafetyCheck
/tpc debug

重点确认：

• 各模块是否处于预期启用状态。
• teleporting.preloadEnabled 是否符合服务器需求。
• teleporting.defaultSafetyCheck 是否符合服务器需求。
• teleporting.restoreRotation 是否开启（默认开启，传送至已保存位置时恢复朝向）。
• 额外调试日志是否仍然关闭。

v2.0 后的重要默认行为

当前默认行为更偏向轻量和可预测：

• debugEnabled=false，额外调试日志默认关闭。
• teleporting.preloadEnabled=false，目标区块预加载默认关闭。
• teleporting.defaultSafetyCheck=false，已知目标传送默认不做安全落点搜索。
• RTP 使用独立随机落点安全检查，不受 defaultSafetyCheck 和目标预加载开关影响。

如果希望 /home、/sharedhome、/warp、/back、/worldspawn 在目标点附近寻找安全落点，需要同时开启：

/tpc config teleporting preload true
/tpc config teleporting defaultSafetyCheck true

新增功能

传送朝向恢复

在创建或更新 home、warp、tmphome 时，模组会自动记录当前玩家朝向（yaw/pitch）。传送时，如果 teleporting.restoreRotation 开启（默认开启），玩家会被还原到保存时的朝向。

/tpc config teleporting restoreRotation  # 查看当前状态
/tpc config teleporting restoreRotation true
/tpc config teleporting restoreRotation false

旧数据（未记录朝向的位置）不受影响，传送时会保持玩家当前朝向。

TPA 信任规则

新增 /trust 命令，允许玩家设置自动接受或拒绝 TPA/TPAHere 请求的规则。可以为所有玩家设置全局默认规则，也可以为特定玩家设置覆盖规则。详见 5.3 TPA 模块。

配置迁移

配置文件会自动迁移到当前结构。旧版中的部分字段会被规范化，例如旧的 RTP 半径字段会迁移为当前的最小/最大半径结构。

如果你手动维护配置文件，升级后建议重新对照 4 配置文件，确认字段名和默认值。

存储迁移

旧版 JSON 存储会在启动时迁移到当前存储格式。迁移逻辑会尽量保留：

• 玩家 homes。
• 全局 warps。
• 默认 home。
• 地图显示/隐藏偏好。

迁移失败通常说明旧文件损坏或数据结构异常。不要直接删除旧数据；应先备份，再查看服务端日志。

回滚注意事项

升级到新版本并完成存储迁移后，不建议直接回退到旧版模组。旧版可能无法识别新存储结构。

如果必须回滚，应使用升级前备份的数据。