Skip to content

Migration Tools

Alexisleder edited this page Jul 11, 2026 · 1 revision

Migration Tools

This page explains the migration and export/import tools added in LederProtections v1.1.0.

Migration tools are designed to help server owners move protection data safely, especially from ProtectionStones to LederProtections.


Safety First

Migration modifies important protection data.

Before using any migration command:

  1. Stop the server.
  2. Back up your worlds.
  3. Back up plugins/WorldGuard/.
  4. Back up plugins/LederProtections/.
  5. Test on a staging server first.
  6. Run a scan.
  7. Run a dry-run.
  8. Review the generated report.
  9. Only then run the real import.

Main Features

Feature Description
ProtectionStones scan Detects importable ProtectionStones regions.
ProtectionStones dry-run Shows what would happen without changing anything.
ProtectionStones import Imports compatible regions into LederProtections.
Exact radius matching Default mode; avoids resizing protections.
Suggested missing tiers Generates suggested stones.yml entries for missing radii.
Single-region migration Allows scanning/importing one region at a time.
ProtectionStones name import Imports ps-name as the protection display name when available.
Old message cleanup Removes old ProtectionStones greeting/farewell flags by default.
Native export/import Exports and imports LederProtections protection data.

ProtectionStones Migration

LederProtections can import compatible ProtectionStones regions from WorldGuard.

ProtectionStones regions are detected from WorldGuard region data.

Common ProtectionStones region ID format:

ps{x}x{y}y{z}z

Example:

ps428x71y-39z

This ID points to the original protection block location:

x = 428
y = 71
z = -39

Default Migration Behavior

By default, migration is strict.

LederProtections only imports ProtectionStones regions when the source radius exactly matches a configured stone tier in stones.yml.

Example:

ProtectionStones radius LederProtections tier exists Default result
64 Yes Imported
20 No Skipped as missing tier
50 No Skipped as missing tier
6 No Skipped as missing tier

This avoids silently resizing protections.


Exact Mode

Exact mode is the default.

These commands are equivalent:

/lep migrate protectionstones import
/lep migrate protectionstones import --mode exact

Exact mode means:

ProtectionStones radius must match a LederProtections stone radius exactly.

If no matching tier exists, the region is skipped with a missing-tier status.


Nearest Mode

Nearest mode is available for advanced migrations.

/lep migrate protectionstones import --mode nearest

Nearest mode may resize protections.

Example:

ProtectionStones radius Possible mapped LederProtections radius
20 16 or 32, depending on mapping
50 64
10 8

Use nearest mode only when you understand and accept that imported protection sizes may change.


Scan

Scan detects possible ProtectionStones regions.

/lep migrate protectionstones scan

Verbose scan:

/lep migrate protectionstones scan --verbose

Scan does not modify anything.

It only reports what the migrator detects.


Dry Run

Dry-run shows what would happen during import without modifying anything.

/lep migrate protectionstones import --dry-run

Recommended verbose dry-run:

/lep migrate protectionstones import --dry-run --verbose

Dry-run generates a report under:

plugins/LederProtections/migrations/

Real Import

After reviewing the dry-run report, run:

/lep migrate protectionstones import

This performs a real import using strict exact mode.


Single-Region Scan and Import

You can scan or import one region at a time.

Scan one region:

/lep migrate protectionstones scan --region ps428x71y-39z

Dry-run one region:

/lep migrate protectionstones import --dry-run --region ps428x71y-39z

Import one region:

/lep migrate protectionstones import --region ps428x71y-39z

Short positional syntax may also be supported:

/lep migrate protectionstones scan ps428x71y-39z

If the same region ID exists in multiple worlds, use:

/lep migrate protectionstones scan --region ps428x71y-39z --world world

Missing Tiers

If a ProtectionStones radius does not exist in LederProtections stones.yml, it is skipped by default.

Example:

ProtectionStones radius: 20
LederProtections stones.yml: 4, 8, 16, 32, 64
Result: MISSING_TIER

This is intentional.

LederProtections will not silently convert radius 20 into radius 16 or 32.


Suggested Missing Tiers

To generate suggested stones.yml entries for missing radii, run:

/lep migrate protectionstones suggest-stones

Or during dry-run:

/lep migrate protectionstones import --dry-run --suggest-missing-tiers

Suggested tiers are written to:

plugins/LederProtections/migrations/suggested-stones-YYYY-MM-DD-HH-mm-ss.yml

The generated file is only a suggestion.

It does not modify stones.yml automatically.

Review the file, copy the tiers you want into stones.yml, adjust materials/prices/permissions, then restart or reload the server and run dry-run again.


Suggested Tier Materials

Suggested tiers use decorative glazed terracotta materials by default.

Example materials:

Suggested material
LIGHT_BLUE_GLAZED_TERRACOTTA
BLUE_GLAZED_TERRACOTTA
CYAN_GLAZED_TERRACOTTA
LIME_GLAZED_TERRACOTTA
PURPLE_GLAZED_TERRACOTTA
MAGENTA_GLAZED_TERRACOTTA

Server owners can change these before applying them.


Physical Stone Conversion

When importing a ProtectionStones region with an exact matching LederProtections tier, LederProtections converts the source block to the configured LederProtections stone material by default.

Example:

ProtectionStones block LederProtections mapped material Result
DIAMOND_ORE EMERALD_ORE Block is replaced with EMERALD_ORE.
EMERALD_ORE EMERALD_ORE Block is adopted without replacement.

This keeps /lep check clean because the physical block matches the configured LederProtections stone tier.


Keeping Source Stones

Advanced admins can preserve source blocks with:

/lep migrate protectionstones import --keep-source-stones

If the source block does not match the mapped LederProtections material, the import may be skipped to keep validation safe.

Use this only if you understand the impact.


Missing Stones

If the original ProtectionStones block is missing and the location is air, the region is skipped by default.

To place the mapped LederProtections stone automatically:

/lep migrate protectionstones import --place-stones

This should only be used after reviewing a dry-run report.


Old ProtectionStones Messages

ProtectionStones may leave WorldGuard flags such as:

greeting
farewell
greeting-action
farewell-action
greeting-title
farewell-title

LederProtections cleans these old message flags by default during import.

This prevents old messages such as:

Entering <player>'s protected area
Leaving <player>'s protected area

from appearing after migration.

To keep source flags:

/lep migrate protectionstones import --keep-source-flags

ProtectionStones Names

ProtectionStones may store custom names in ps-name.

LederProtections attempts to import this as the protection display name.

Example:

ProtectionStones ps-name LederProtections name
Casa64 Casa64
Base Principal Base Principal

If the name is missing or invalid, LederProtections uses a fallback migrated name.


Y-Bounds Normalization

ProtectionStones regions may use very large vertical bounds when y_radius = -1.

Example:

-32768 to 32767

LederProtections normalizes imported protection bounds to the actual world height.

Example:

-64 to 319

This prevents /lep check from reporting invalid Y bounds after migration.


Migration Reports

Migration reports are saved under:

plugins/LederProtections/migrations/

Reports include information such as:

Field Description
Source region ID Original ProtectionStones region ID.
Source radius Radius detected from the source region.
Mapped tier LederProtections stone tier used for import.
Source name Imported ps-name if available.
Imported name Final LederProtections display name.
Source block Original block at the stone location.
Final block Final LederProtections stone block.
Y normalization Source and normalized vertical bounds.
Cleaned flags Old source flags removed during import.
Status Import, skip or conflict status.

Common Statuses

Status Meaning
IMPORTABLE The region can be imported.
MISSING_TIER No exact LederProtections stone tier exists for the source radius.
STONE_MISSING The source stone block is missing.
STONE_CONFLICT The source stone location contains an unsafe block.
ALREADY_IMPORTED The region appears to have already been imported.
CONFLICT_EXISTING_LEDER The candidate conflicts with an existing LederProtections protection.
UNSUPPORTED_SHAPE The WorldGuard region shape is not supported.
WORLD_NOT_FOUND The world could not be found.
SUSPICIOUS_ID The region ID looks suspicious or ambiguous.

Native LederProtections Export

Export all LederProtections protections:

/lep export protections

Exports are saved under:

plugins/LederProtections/exports/

Use this for:

  • backups;
  • server migration;
  • support reports;
  • moving protections to another server.

Native LederProtections Import

Dry-run native import:

/lep import protections <file> --dry-run

Real native import:

/lep import protections <file>

Native import validates the file, checks conflicts and avoids overwriting existing protections by default.


Permissions

Permission Description
lederprotections.admin.migrate Allows using migration commands.
lederprotections.admin.export Allows exporting LederProtections protections.
lederprotections.admin.import Allows importing LederProtections protection exports.

These permissions are included under admin access if configured that way.


Recommended Migration Workflow

Recommended ProtectionStones migration workflow:

/lep migrate protectionstones scan
/lep migrate protectionstones import --dry-run --verbose
/lep migrate protectionstones suggest-stones

Then:

  1. Review the reports.
  2. Add any missing tiers to stones.yml if needed.
  3. Restart or reload the server.
  4. Run dry-run again.
  5. Import one region first.
  6. Run /lep check.
  7. Import the rest.

Example:

/lep migrate protectionstones import --region ps428x71y-39z
/lep check
/lep admin

If the first import works correctly, continue with:

/lep migrate protectionstones import

Best Practices

Recommended practices:

  • Always back up first.
  • Always run dry-run first.
  • Review generated reports.
  • Prefer exact mode.
  • Add missing tiers instead of using nearest mode when preserving sizes matters.
  • Use single-region import for testing.
  • Use --place-stones only after dry-run.
  • Use --keep-source-flags only if you intentionally want old WorldGuard flags.
  • Do not keep ProtectionStones active while both plugins manage the same regions.

Recommended Next Pages

Clone this wiki locally