EN 10 Upgrade Notes

10 Upgrade Notes

中文版本 | English version

This page is for upgrading from older versions. For a fresh install, start with 1 Quick Start.

Upgrading to 2.4

• /wild is now an independent long-range random teleport module instead of an /rtp alias. Review the new wild.enabled, wild.minRadius, and wild.maxRadius settings.
• The Home module adds shared publication and subscription. Publications and subscriptions are runtime-only; they are neither migrated nor persisted and must be recreated after restart.
• Home config adds sharedHomeMaximum and sharedHomeBroadcastCooldownSeconds; older configs use defaults when these fields are absent.
• /homes and /warps add management pages and delete confirmation while keeping the existing commands.
• Version 2.4 retains protocol v1 compatibility with 2.3 peers for existing home and warp map synchronization. Shared-home map synchronization requires both the client and server to use 2.4 or another protocol v2-compatible build.

Version 2.4 does not increment config or storage schema versions. Existing home, warp, back, and TPA data formats remain unchanged.

Before Upgrading

Before replacing the mod file:

• Back up server config and storage data.
• Stop the server cleanly before replacing the mod.

Current config file:

config/teleport_commands.json

If legacy storage still exists, it is migrated automatically on first startup. After successful migration, the old file is archived to avoid repeated migration.

First Checks After Upgrade

After startup, check:

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

Confirm:

• Modules are enabled or disabled as expected.
• teleporting.preloadEnabled matches your server policy.
• teleporting.defaultSafetyCheck matches your server policy.
• teleporting.restoreRotation is enabled (enabled by default; restores saved yaw/pitch when teleporting to stored locations).
• Extra debug logging is still disabled unless you intentionally enabled it.

Important Defaults Since v2.0

Current defaults favor lightweight and predictable behavior:

• debugEnabled=false: extra debug logs are disabled by default.
• teleporting.preloadEnabled=false: target chunk preloading is disabled by default.
• teleporting.defaultSafetyCheck=false: known-target teleports do not search for nearby safe landing points by default.
• RTP and Wild use their own random-destination safety logic and are not affected by defaultSafetyCheck or target preloading.

If you want /home, /sharedhome, /warp, /back, and /worldspawn to search for safer nearby landing points, enable both:

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

New Features

Teleport Rotation Restoration

When creating or updating a home, warp, or temporary home, the mod now records the player's current orientation (yaw/pitch). If teleporting.restoreRotation is enabled (default on), the player is restored to the saved orientation on teleport.

/tpc config teleporting restoreRotation  # check current state
/tpc config teleporting restoreRotation true
/tpc config teleporting restoreRotation false

Old data (locations saved without rotation) is unaffected — the player's current orientation is preserved on those teleports.

TPA Trust Rules

New /trust commands let players set rules to auto-accept or auto-deny TPA/TPAHere requests. Global default rules can be set for all players, and per-player override rules for specific players. See 5.3 TPA Module for details.

Config Migration

Config files are migrated automatically to the current structure. Some old fields are normalized, such as older RTP radius settings being migrated into the current min/max radius structure.

If you maintain config manually, compare your file with 4 Configuration File after upgrading.

Storage Migration

Legacy JSON storage is migrated into the current storage format on startup. Migration is designed to preserve:

• Player homes.
• Global warps.
• Default home.
• Map visibility preferences.

Migration failure usually indicates damaged legacy data or an unexpected historical structure. Do not delete old data directly; back it up first and check server logs.

Rollback Notes

After upgrading and completing storage migration, direct rollback to an older mod version is not recommended. Older versions may not understand the new storage structure.

If rollback is required, restore the backup taken before upgrade.