minecraft-server/docs/migrations/lands-to-landclaim.md

Migration Plan: Lands v7.21.3 → LandClaimPlugin

Target: LandClaimPlugin (Modrinth, MIT, by AyoSynk) Date Planned: [TBD - Player Agreement] Server: Purpur 1.21.10 on nullstone (Debian 13) World: Preserved intact. Only plugin data wiped. Grace Period: 48 hours after migration Rollback Window: 7 days (Lands DB archived)

---

0. Current State

Lands v7.21.3 on Nullstone

• JAR: Lands-7.21.3.jar (2.9MB, paid plugin from IncrediblePlugins)

• Database: SQLite database_v2.db (168KB)

• Cached players: 43

• Active lands (from event log):

  • K'land / JellyLand — block placements, deleted 2025-05-30 for INACTIVITY
  • Portal — bank deposits (500 → 1000 → 2000), deleted 2025-09-11 for INACTIVITY
  • HighCaillou — deposit 10
  • HIVE — deposit 10,000
  • Headquarters — recurring deposits (20 → 40 per cycle)
  • batcave / batcave1 — recurring deposits (10 per cycle)
  • MyLawn — deposits
  • Jessie — deleted 2025-12-09
  • TheArchitect — deposits

• Economy: Lands Bank is active — players deposit money into land banks. Economy integration via Vault/EssentialsX.

• Nations: Config present but enabled: false — never used.

• Features in use: Basic land claiming, bank deposits, roles, events logging. No nations, no wars.

• Dependencies: Vault (economy bridge), EssentialsX (economy backend)

• Data to lose: All claim boundaries, land bank balances, member lists, role assignments for each land.

Target: LandClaimPlugin

• License: MIT (free, open-source)
• Compatibility: 1.21.x — Paper, Purpur, Spigot confirmed
• Claim Model: Chunk-based (16x16), single claim profile per player
• Permissions: Tiered flag system (Owner → Member → Public)
• Features: In-game map, warps, alliances, auto-claim while walking, PvP blocking
• No: Nations, wars, web portal, land bank — these are Lands-specific features we don't use anyway.

---

1. Pre-Migration (Phase 0 — 48h before)

1.1 Backup Everything

ssh user@192.168.0.100

# Create backup directory
mkdir -p /opt/backups/lands-migration-$(date +%Y%m%d)

# Full server backup (running state — consistent snapshot via docker exec for world)
tar czf /opt/backups/lands-migration-$(date +%Y%m%d)/minecraft-plugins.tar.gz \
  -C /opt/docker/minecraft plugins/

# Lands-specific backup (the important part for rollback)
tar czf /opt/backups/lands-migration-$(date +%Y%m%d)/lands-complete.tar.gz \
  -C /opt/docker/minecraft/plugins \
  Lands Lands-7.21.3.jar

# Also grab the SQLite DB separately (small, critical)
cp /opt/docker/minecraft/plugins/Lands/Data/database_v2.db \
   /opt/backups/lands-migration-$(date +%Y%m%d)/

# Verify
ls -lh /opt/backups/lands-migration-$(date +%Y%m%d)/

1.2 Player Communication

Discord announcement:

📢 LAND SYSTEM CHANGE — Vote Required

We're replacing Lands (paid, complex, heavy) with LandClaimPlugin (free, simple, chunk-based).

What changes:
✅ New claiming system (/claim instead of /lands GUI)
✅ Chunk-based (16x16 blocks) — easier to see your borders
✅ Free claims, no economy cost during grace period
✅ Same world, same builds — only plugin data wiped
⚠️ ALL EXISTING CLAIMS WILL BE RESET
⚠️ Land bank balances will NOT carry over
🎁 48-hour grace period — free unlimited re-claiming

Timeline:
- Vote opens now (48h to respond)
- If approved, migration happens on [DATE]
- ~5 min downtime during swap
- 48h grace period to rebuild your claims

Land bank balances note: Current Lands bank deposits will NOT transfer.
The new system doesn't use land banks. This economy cost is going away.

Reply with 👍 to approve or 👎 to reject. Questions below.

In-game MOTD (during announcement):

§6⚠ Land system upgrade vote in Discord! §fReply in #announcements.
§7Migration may reset all claims. 48h grace period to re-claim.

1.3 Download New Plugin

# Get the compatible version for 1.21.10 / Purpur
# Check: https://modrinth.com/plugin/landclaimplugin/versions
# Need a build that supports 1.21.10 (currently latest covers 1.21.x)

# Download (replace with actual URL when ready)
wget -O /tmp/LandClaimPlugin.jar "https://cdn.modrinth.com/data/[...]/LandClaimPlugin-[version].jar"

# Quick validation
file /tmp/LandClaimPlugin.jar
# Should report: Java archive data (JAR)

---

2. Migration Execution (Phase 1 — Server Downtime)

2.1 Stop Server

ssh user@192.168.0.100
cd /opt/docker/minecraft

# Stop the container
docker compose down
# Wait for clean shutdown (saves world, closes DBs)
# Verify: docker ps | grep minecraft-mc (should be empty)

2.2 Remove Lands Completely

cd /opt/docker/minecraft/plugins

# Remove JAR
rm -f Lands-7.21.3.jar

# Remove entire data directory (claims, bank, roles, language, configs, logs)
rm -rf Lands/

# Verify it's gone
ls -la Lands* Lands/
# Should return: No such file or directory

2.3 Install LandClaimPlugin

# Move downloaded JAR to plugins
mv /tmp/LandClaimPlugin.jar /opt/docker/minecraft/plugins/LandClaimPlugin.jar
chown user:user /opt/docker/minecraft/plugins/LandClaimPlugin.jar
chmod 644 /opt/docker/minecraft/plugins/LandClaimPlugin.jar

# Verify
ls -la /opt/docker/minecraft/plugins/LandClaimPlugin.jar

2.4 Start Server (Config Generation Boot)

cd /opt/docker/minecraft
docker compose up -d

# Watch for plugin load
docker logs -f minecraft-mc

# Look for LandClaimPlugin startup messages
# Let it run for 2-3 minutes to generate default config
# It will create /opt/docker/minecraft/plugins/LandClaimPlugin/ with config.yml + data/
# Wait until you see: "Server running. /help for help. /stop to quit." or similar

# Stop again for config editing
docker compose down

2.5 Configure LandClaimPlugin

# Edit the generated config
nano /opt/docker/minecraft/plugins/LandClaimPlugin/config.yml

Critical config changes recommended:

# --- CLAIM SETTINGS ---
# Start generous to reduce player friction
claims:
  max-per-player: 50          # High limit — reduce later (default might be 5-10)
  max-size-chunks: 125        # Per-claim size cap (reasonable = ~2000x2000 area)
  auto-claim-enabled: true    # Claim chunks as you walk through them
  require-adjacent: false     # Allow scattered claims (like Lands did)
  diagonal-enabled: true

# --- ECONOMY ---
# DISABLE during grace period
economy:
  enabled: false              # Free claims for now
  cost-per-chunk: 0           # 0 = no charge

# --- PROTECTION FLAGS ---
protection:
  block-break: OWNER          # Only claim owner can break
  block-place: OWNER
  entity-damage: OWNER
  animal-kill: MEMBER         # Allow members to hunt/kill
  item-pickup: OWNER
  item-drop: OWNER
  door-toggle: PUBLIC         # Friendly to visitors
  container-access: MEMBER    # Chests restricted to members
  redstone-use: PUBLIC        # Allow public redstone (doors, farms)
  vehicle-use: MEMBER
  pvp-inside-claim: false     # No PvP inside claimed land (safe zones)
  tnt: false                  # Block TNT
  creeper-explosion: true     # Keep creeper grief (it's survival, part of the game)
  piston-cross-boundary: false # Prevent pistons pushing across claim edges

# --- VISUAL HELPERS ---
visuals:
  claim-borders: true         # Particle borders on join/claim
  border-particle: flame      # Or barrier, end_rod
  in-game-map: true           # Show claim overlay

# --- WARPS ---
warps:
  enabled: true
  per-claim-max: 5           # Reasonable limit per claim

2.6 Clean Up Plugin Dependencies

# LuckPerms — remove old Lands permissions
# Open LuckPerms web editor or use RCON
# Remove all perms matching: lands.*
docker exec minecraft-mc luckperms editor
# In the web editor, search "lands" and delete matching nodes
# Then add new perms if needed:
#   /lp group default permission set "landclaim.claim.max.<number>" 50

# TAB plugin — check for Lands placeholders
grep -r "lands" /opt/docker/minecraft/plugins/TAB/ 2>/dev/null
# If found, remove/replace with LandClaim equivalents

# DiscordSRV — no direct LandClaim integration exists
# Console channel will still log /claim commands via the console
# Later: set up n8n webhook for automated claim notifications

---

3. Go Live (Phase 2 — Grace Period Begins)

3.1 Start Server

ssh user@192.168.0.100
cd /opt/docker/minecraft
docker compose up -d

# Verify
docker logs minecraft-mc | tail -30
# Confirm:
# - World loads (all 3 dimensions)
# - LandClaimPlugin enabled without errors
# - EssentialsX, DiscordSRV, all plugins load cleanly
# - RCON on port 25575
# - Port 25565 accepting connections

3.2 Update MOTD

# In docker-compose.yml, update the MOTD line:
# MOTD: "§a✓ New land system live! §e/claim§f to protect. 48h grace period."
docker compose restart

3.3 Discord & In-Game Announcement

DISCORD:
🟢 Land system is LIVE! Use /claim to protect your builds.
📍 Your old Lands claims are gone — time to rebuild!
⏰ 48-hour grace period: free, unlimited claiming.
📖 How to claim:
   1. Stand in the chunk you want to claim
   2. Run /claim add
   3. Walk and auto-claim is enabled
   4. View your claims: /claim map
Questions? Ask in #support.

# In-game broadcast
ssh user@192.168.0.100 "docker exec minecraft-mc rcon-cli say '§a✓ New land system live! Use /claim to protect. 48h free claiming!'"

---

4. Post-Migration Monitoring (Phase 3)

Time	Action
T+1h	Check logs for LandClaimPlugin errors. Verify claim borders work. Test /claim add in-game.
T+6h	Monitor Discord for player issues. Check if any players report missing builds (grief while unclaimed).
T+12h	Verify claim data directory is growing (new claims being made). Run /claim list to see top claimers.
T+24h	Backup new LandClaimPlugin data directory. Check for any claim conflicts between players.
T+48h	Grace period ends. Optionally enable economy (economy.enabled: true, cost-per-chunk: 10). Announce enforcement start.
T+7d	If no issues, consider deleting the Lands backup or moving to cold storage.

---

5. Risk Matrix

Risk	Likelihood	Impact	Mitigation
LandClaimPlugin incompatible with Purpur 1.21.10	Low	High	Test on dev clone first. Modrinth shows Purpur 1.21.x supported.
Players lose critical builds during grace period	Medium	High	Admins patrol during first 6h. /claim add for abandoned bases. Consider temporary WorldGuard protection on major builds.
Land bank money loss causes player anger	Medium	Medium	Document clearly that bank balances don't carry over. This is a one-time wipe. Future economy-free system means no more deposits.
Auto-claim causes accidental claims	Low	Low	Players can /claim remove instantly. Admin can fix abuse.
Claim boundary disputes	Medium	Low	Admin tool /claim admin unclaim <player>, /claim admin transfer for dispute resolution.
TAB/LuckPerms broken by old Lands hooks	Low	Low	These just display empty placeholders. Not server-breaking. Fix in TAB config + LuckPerms web editor.

---

6. Rollback Plan

If LandClaimPlugin causes critical issues or players revolt:

# 1. Stop server
docker compose -f /opt/docker/minecraft/docker-compose.yml down

# 2. Remove new plugin
rm -f /opt/docker/minecraft/plugins/LandClaimPlugin.jar
rm -rf /opt/docker/minecraft/plugins/LandClaimPlugin/

# 3. Restore Lands from backup
cd /opt/docker/minecraft/plugins
tar xzf /opt/backups/lands-migration-*/lands-complete.tar.gz

# 4. Verify Lands files restored
ls -la Lands-7.21.3.jar Lands/

# 5. Start server
docker compose -f /opt/docker/minecraft/docker-compose.yml up -d

# 6. Verify
rcon-cli say "§cLand system reverted to Lands. Claims restored."

---

7. Suggestions / Future Improvements

1. Claim decay for inactive players: If someone hasn't logged on in 60+ days, auto-unclaim their land. Prevents dead claims on buildable land. Can be automated with a cron + RCON script.

2. Claim dashboard: Bash script that RCONs /claim list, formats it, and posts to admin Discord channel weekly.

3. Bluemap/Dynmap integration: If LandClaimPlugin supports layer overlays on a web map, players can see claims from a browser, not just in-game.

4. Economy-free by design: LandClaimPlugin keeps claiming free and simple. Consider keeping it that way. The economy cost was a friction point for new players who wanted to build but had no money yet.

5. Admin mediation tools: The plugin has admin commands (/claim admin). Make sure moderators know:

   • /claim list — view all claims
   • /claim admin unclaim <player> — remove a player's claims
   • /claim admin transfer <from> <to> — move a claim between players

6. Backup script update: Edit /opt/docker/backup.sh to include LandClaimPlugin in the daily backup (currently only backs up Minecraft world + configs, not plugin-specific data).

---

8. Files in This Repo

Path	Description
config/	All server config files (pulled live from nullstone)
config/plugins/Lands-config.yml	Current Lands config — reference before removal
config/plugins/Lands-*.yml	All Lands sub-configs — roles, nations, wars, events, levels
docker-compose.yml	Live container definition from nullstone
README.md	Server documentation, plugin inventory, ops
docs/migrations/lands-to-landclaim.md	This migration plan
scripts/	Migration + operational scripts (below)

---

9. Migration Helper Script

Place in scripts/migrate-lands-to-landclaim.sh:

#!/usr/bin/env bash
# migrate-lands-to-landclaim.sh
# Run on nullstone as root. Performs the full Lands → LandClaimPlugin migration.
set -euo pipefail

BACKUP_DIR="/opt/backups/lands-migration-$(date +%Y%m%d_%H%M%S)"
MC_DIR="/opt/docker/minecraft"
PLUGIN_DIR="$MC_DIR/plugins"

log() { echo "[$(date '+%H:%M:%S')] $*"; }

# --- Pre-checks ---
log "Checking prerequisites..."

# Is server running?
if docker ps --format '{{.Names}}' | grep -q '^minecraft-mc$'; then
    log "Server is running. Stop it first: cd $MC_DIR && docker compose down"
    exit 1
fi

# Backup directory
mkdir -p "$BACKUP_DIR"
log "Backup directory: $BACKUP_DIR"

# --- Step 1: Backup Lands ---
log "Backing up Lands plugin..."
if [ -f "$PLUGIN_DIR/Lands-7.21.3.jar" ]; then
    cp "$PLUGIN_DIR/Lands-7.21.3.jar" "$BACKUP_DIR/"
    cp -r "$PLUGIN_DIR/Lands" "$BACKUP_DIR/"
    log "Lands JAR + data backed up"
else
    log "WARNING: Lands-7.21.3.jar not found at $PLUGIN_DIR"
    log "Plugin may already be removed or installed at different version"
    exit 1
fi

# --- Step 2: Remove Lands ---
log "Removing Lands plugin..."
rm -f "$PLUGIN_DIR/Lands-7.21.3.jar"
rm -rf "$PLUGIN_DIR/Lands/"
log "Lands removed"

# --- Step 3: Install LandClaimPlugin ---
log "Installing LandClaimPlugin..."
LCP_JAR="$PLUGIN_DIR/LandClaimPlugin.jar"

# Check if JAR already exists
if [ -f "$LCP_JAR" ]; then
    log "LandClaimPlugin.jar already exists at $LCP_JAR"
else
    log "ERROR: LandClaimPlugin.jar not found at $LCP_JAR"
    log "Download it first: wget -O $LCP_JAR <modrinth-url>"
    log "Rolling back..."
    cp "$BACKUP_DIR/Lands-7.21.3.jar" "$PLUGIN_DIR/"
    cp -r "$BACKUP_DIR/Lands" "$PLUGIN_DIR/"
    exit 1
fi

chown user:user "$LCP_JAR"
log "LandClaimPlugin installed"

# --- Step 4: Start server for config generation ---
log "Starting server to generate config..."
cd "$MC_DIR"
docker compose up -d

log "Waiting 90 seconds for config generation..."
sleep 90

# Check if the plugin loaded
if docker logs minecraft-mc 2>&1 | grep -qi "landclaim"; then
    log "LandClaimPlugin loaded successfully"
else
    log "WARNING: No LandClaimPlugin messages in logs"
    docker logs minecraft-mc | tail -20
fi

# --- Step 5: Stop for config edit ---
log "Stopping server..."
docker compose down
log "Server stopped. Now edit:"
log "  $PLUGIN_DIR/LandClaimPlugin/config.yml"
log ""
log "Recommended changes:"
log "  - claims.max-per-player: 50"
log "  - claims.auto-claim-enabled: true"
log "  - economy.enabled: false  (for grace period)"
log "  - visuals.claim-borders: true"
log ""
log "When done, start: cd $MC_DIR && docker compose up -d"
log "Grace period begins. Announce to players."
log ""
log "=== Migration complete ==="

---

Version: 1.0 Author: veilor.uk Infrastructure Created: 2026-04-24

---

10. Execution Log — Completed 2026-04-24 01:21 BST

What Actually Happened

Step	Result	Details
Backup	✅ PASSED	Full plugins backup: 446MB. Lands-specific: 2.6MB. SQLite DB: 168KB
Server stop	✅ PASSED	Clean shutdown via docker compose down. World saved.
Remove Lands	✅ PASSED	Lands-7.21.3.jar deleted. plugins/Lands/ directory removed entirely. SQLite DB backed up before removal.
Download LandClaimPlugin	✅ PASSED	v2.0.4 from Modrinth (supports Paper/Purpur 1.21.4–1.21.11). SHA256: 48562c17ec59c35eb7c3529b84763d026679d0782ffd2dc7dc53169af41be688
Install plugin	✅ PASSED	JAR placed at plugins/LandClaimPlugin.jar (4.2MB). Ownership: user:user.
First boot (config gen)	✅ PASSED	Plugin loaded cleanly. Remapper took 1,459ms. SQLite DB created at plugins/LandClaimPlugin/PlayerData/database.db (77KB). Config + locales + menus generated.
Custom config applied	✅ PASSED	Config replaced via docker cp. Key changes verified: chunkClaimLimit: 50, autoClaimDefault: true, blockWorld: [], autoUnclaimDefault: true. All map integrations disabled.
Restart	✅ PASSED	Server restarted. LandClaimPlugin 2.0.4 loaded. 0 claims (expected). Status: healthy.
Lands verification	✅ PASSED	Zero Lands* files remain in /data/plugins/. No stale data anywhere.
Lands event log captured	✅	From backup: 43 cached players. Active land names before wipe: K'land, JellyLand (deleted), Portal (deleted), HighCaillou, HIVE, Headquarters, batcave, MyLawn, TheArchitect. Nations: disabled. Wars: none.

Server State Post-Migration

• Running: ✅ Health check passing
• Plugins loaded: 24 (Lands removed, LandClaimPlugin 2.0.4 added — net 1 swap)
• Claims: 0 (clean slate)
• World: ✅ Preserved intact (all 3 dimensions)
• Land bank balances: WIPE COMPLETE — not transferable to new system
• Backup location: /opt/backups/lands-migration-20260424/
  • all-plugins.tar.gz (446MB) — full plugin archive
  • lands-complete.tar.gz (2.6MB) — Lands JAR + all data
  • database_v2.db (168KB) — raw SQLite for emergency restore
  • config.yml — pre-migration Lands config

Post-Migration TODO

1. Announce migration complete in Discord + in-game MOTD
2. Monitor logs for first 2h — watch for claim-related errors
3. At 48h: announce grace period ending, optionally enable economy
4. At 7d: delete Lands backup or move to cold storage
5. Update /opt/docker/backup.sh to include LandClaimPlugin data in daily backups

Notes During Execution

• Lands had accumulated ~43 players in cache across 9 named lands
• Two lands were deleted for INACTIVITY (JellyLand 2025-05-30, Portal 2025-09-11) — confirms the cleanup system was working
• Land bank deposits ranged from $10 to $10,000 (HIVE). These balances are NOT recoverable in the new system — it doesn't use land banks at all. This is a feature, not a loss: the new system is simpler and economy-free by default.
• LandClaimPlugin had two startup warnings:
  1. NullPointerException: serverConnectionMethod is null — minor, plugin continues loading
  2. You are running an unsupported server version! — cosmetic, plugin works fine on Purpur 1.21.10
• Both warnings are non-fatal and don't affect functionality.

---

Migration executed: 2026-04-24 01:21 BST Migration duration: ~10 minutes (stop → swap → restart) Server: nullstone (192.168.0.100) Operator: veilor.uk