Migrating

This page covers two kinds of move: bringing an existing random-teleport setup (from another plugin or a pile of glue) onto LeafRTP, and upgrading LeafRTP across versions. The guiding principle is the same in both cases: do not hand-port config line by line. LeafRTP generates its own config tree, self-heals missing keys, and replaces most external glue with native features - so the fastest migration is usually to start from LeafRTP's defaults and re-express your intent, not to translate old YAML.

!!! tip "Back up first" Before any migration, stop the server and copy your existing config (and your old plugin's folder). LeafRTP never reads another plugin's files, so nothing is overwritten - but a backup means you can diff intent at your own pace.

Coming from another random-teleport setup

Most other RTP solutions are either a single monolithic config or a thin command wrapper plus glue (menus, NPC triggers, first-join scripts). LeafRTP splits behavior across small, focused files and replaces the glue with native features. Map your intent, do not copy text:

What you had	Where it lives in LeafRTP
One world's teleport area / radius / center	A region mapped to that world (center, radius, shape)
"Don't land in water/lava/cactus" rules	safety.yml and biome controls
"Skip claimed land" (WorldGuard/Towny/Lands/...)	reroll* toggles in integrations.yml (no glue)
First-join / join / respawn / world-change scatter scripts	rtp.onevent.* permissions (no glue) - see Common RTP recipes
A GUI plugin running rtp <world> per slot	The built-in Menu, or a typed custom menu
PlaceholderAPI cooldown/queue lore	LeafRTP's native %rtp_*% expansion - see PlaceholderAPI
"Buy an RTP" / per-world cost	economy.yml + per-region price overrides
A world pre-generator to warm chunks	/rtp scan (off-tick verify + spatial memory) - see Scan and spatial memory
Cooldowns / per-group limits	Permission-driven; see Permissions

Recommended bring-up sequence

1. Install LeafRTP and start the server once so it generates its config tree. Remove the old plugin (or disable it) so they do not fight over /rtp.
2. Configure each world's region fully - center, radius, shape - in its region file. Set safety/biome rules and any claim-reroll toggles now. Follow the Typical configuration order.
3. Re-express glue as native behavior: grant the rtp.onevent.* nodes you need, enable the built-in menu, set economy/permissions. Delete the old scripts/wrappers.
4. Scan each reasonably-sized region (/rtp scan start region=<name>) so the first players already get fast, reliable teleports.
5. Verify with /rtp info (cache filling, no dominant bad-cause) and a few test teleports.

!!! warning "Do not scan before the geometry is final" Changing a region's shape or radius clears its learned spatial memory by design. Finalize the region first, then scan - otherwise you scan twice.

Upgrading LeafRTP across versions

LeafRTP's config is self-healing across version bumps: when a new jar stamps a higher config version than the one on disk, LeafRTP backs up your old file (to <name>.yml.old1), re-extracts the new defaults, then overlays your existing values back on top - so new keys arrive with their defaults and your settings are preserved. You normally do not hand-edit YAML to pick up a new option.

1. Read CHANGELOG.md for the target version - it lists new keys, defaults, and any behavior changes. Entries tagged (Pro) apply only to the full edition.
2. Back up your config folder, then drop in the new jar and start the server. Because the new jar bumps the config version, the merge runs automatically: each file is backed up as <name>.yml.old1, new keys appear with their defaults, and your existing values are re-applied on top.
3. /rtp reload (or restart) to apply. Re-run /rtp info to confirm the engine is healthy.
4. If a release renamed or removed a key, the CHANGELOG calls it out. Your previous value is kept in the <name>.yml.old1 backup; a key the new version no longer defines is simply not carried forward.

!!! note "The merge is triggered by the version bump, not by every launch" Adding missing keys and re-applying your values happens when the config version on disk differs from the version the jar expects (which a real upgrade always changes). A restart on the same version does not rewrite or backfill your files. If you ever need to force a clean re-extract, delete the file and let LeafRTP regenerate it.

!!! note "Editions and platforms" Folia, multi-server/proxy, and SQL/Redis shared state are Pro features; the free jar runs on Paper / Spigot / Fabric / NeoForge as-is. Moving between editions does not change your config format - the Pro-only files simply become active. See Home.

Migrating an addon across versions

If you wrote an addon, upgrades are governed by the API stability policy: contract-tier (rtp-api) symbols are stable within a major version, so a recompile against the new tag is usually all you need. Implementation-tier (rtp-core) usage may require code changes between minors - check the CHANGELOG and the Extending RTP surface map.

See also: Typical configuration order, Common RTP recipes, What NOT to do!.