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
```bash
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
```bash
# 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
```bash
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
```bash
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
```bash
# 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)
```bash
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
```bash
# Edit the generated config
nano /opt/docker/minecraft/plugins/LandClaimPlugin/config.yml
```

**Critical config changes recommended:**
```yaml
# --- 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
```bash
# 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
```bash
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
```bash
# 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.
```

```bash
# 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:

```bash
# 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`:

```bash
#!/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*