Essentials Plus - v1.20.0

Appearance

📚 Tutorials ​

This page provides step-by-step tutorials for common configuration tasks in EssentialsPlus.

Migration from Other Mods ​

EssentialsPlus provides a powerful migration system to import data from other popular Essentials mods, making it easy to switch without losing your server's data.

Supported Mods ​

EssentialsPlus can migrate data from the following mods:

Mod NameVersion TestedStatus
Hyssentialsv2.3.5✅ Fully Supported
EliteEssentialsv2.0.7✅ Fully Supported (JSON, SQLite, MySQL, H2 (deprecated))
EssentialsCorev1.5.5✅ Fully Supported
HomesPlusv2.1.8✅ Fully Supported
HomeManagerv1.3.2✅ Fully Supported
KuksoHyWarpsv1.2.0✅ Fully Supported
HyEssentialsXv1.1.4HF✅ Fully Supported (SQLite)
HytHomesv1.2.0✅ Fully Supported
KG Warpsv1.0.5✅ Fully Supported
HyCommandsv1.5.0✅ Fully Supported
TheEconomyv1.0.8.1-beta✅ Fully Supported (JSON)

What Gets Migrated ​

The following data types are automatically migrated:

Data TypeDescriptionNotes
✅ WarpsAll server warp pointsIncluding position, rotation, and world data
✅ HomesAll player home locationsPer-player homes with names and coordinates
✅ SpawnsServer spawn pointsMain spawn and per-world spawns
✅ UsersPlayer dataUUID, username, nickname, first/last join, playtime, balance, ignore list, IP history
✅ KitsStarter kits and itemsSupported for EliteEssentials — requires manual recreation for all other mods

Kits Migration

Kit migration is currently only supported when migrating from EliteEssentials (v1.1.19+).

For all other mods, kits are not migrated and must be recreated manually in EssentialsPlus after migration.

Migration Commands ​

EssentialsPlus provides dedicated migration commands for each supported mod.

Command Syntax ​

bash
# Hyssentials Migration
/essentialsplus migrate hyssentials [true|false]

# EliteEssentials Migration
/essentialsplus migrate eliteessentials [true|false]

# EssentialsCore Migration
/essentialsplus migrate essentialscore [true|false]

# HomesPlus Migration
/essentialsplus migrate homesplus [true|false]

# HomeManager Migration
/essentialsplus migrate homemanager [true|false]

# KuksoHyWarps Migration
/essentialsplus migrate kuksohywarps [true|false]

# HyEssentialsX Migration
/essentialsplus migrate hyessentialsx [true|false]

# HytHomes Migration
/essentialsplus migrate hythomes [true|false]

# KGWarps Migration
/essentialsplus migrate kgwarps [true|false]

# HyCommands Migration
/essentialsplus migrate hycommands [true|false]

# TheEconomy Migration
/essentialsplus migrate theeconomy [true|false]

Parameter: Merge Mode ​

The command requires a boolean parameter that controls merge behavior:

  • true - Merge Mode (Recommended)

    • Combines migrated data with existing data
    • Existing warps/homes with the same name are kept (not overwritten)
    • User data is intelligently merged (keeps older first join, newer last join)
    • Safe to run multiple times
    • Example: /essentialsplus migrate hyssentials true

  • false - Replace Mode (Use with Caution)

    • Replaces all existing data with migrated data
    • ⚠️ Warning: All existing warps and homes will be deleted
    • Only use this for a fresh migration
    • User data is still merged to preserve existing player information
    • Example: /essentialsplus migrate hyssentials false

Step-by-Step Migration Guide ​

Important: Backup First!

EssentialsPlus automatically creates a backup of your current data before migration, but it's highly recommended to create a full server backup manually as well.

Step 1: Prepare Your Server ​

  1. Stop your Hytale server

    bash
    # Stop the server completely

  2. Create a full backup

    bash
    # Backup your entire server directory, especially:
# - mods/fof1092_EssentialsPlus/
# - mods/[OldMod]/

  3. Verify source mod data

    • Ensure the old mod's data directory exists
    • Check that data files (warps.json, homes.json, etc.) are present
    • Default locations:
      • Hyssentials: mods/com.leclowndu93150_Hyssentials/
      • EliteEssentials: mods/EliteEssentials/
      • EssentialsCore: mods/com.nhulston_Essentials/
      • HomesPlus: mods/HomesPlus/
      • HomeManager: mods/homemanager-data/
      • KuksoHyWarps: mods/KuksoHyWarps/
      • HyEssentialsX: mods/HyEssentialsX/ (SQLite database)
      • HytHomes: mods/games.player.home_HytHome/
      • KG Warps: mods/KG_WarpSystem/
      • HyCommands: mods/HyCommands/
      • TheEconomy: universe/EconomySystem/

Best Practice

Always test the migration on a local development server first before running it on your production server!

  1. Copy your server to a local machine

    • Include both the old and new Essentials mod data

  2. Start the local server

    bash
    # Start your local test server

  3. Run the migration command

    bash
    /essentialsplus migrate [modname] true

  4. Verify the migrated data

    • Check warps: /warp [name]
    • Check homes: /homes
    • Check spawns: /spawn
    • Review user data in mods/fof1092_EssentialsPlus/users/

  5. Review the migration log

    • Check console output for any warnings or errors
    • Look for skipped items or failed migrations

Step 3: Production Migration ​

Once you've verified the migration works correctly on your local server:

  1. Stop your production server

    bash
    # Stop the server completely

  2. Create a backup (again!)

    bash
    # Create a timestamped backup of your server

  3. Start the server

    bash
    # Start your production server

  4. Run the migration command

    bash
    /essentialsplus migrate [modname] true

  5. Monitor the migration

    • Watch the console for progress messages
    • Check for any errors or warnings
    • Review the migration summary when complete

Step 4: Verify and Clean Up ​

  1. Verify migrated data

    • Test warps, homes, and spawns
    • Check player data and permissions
    • Confirm user balances (if using economy features)

  2. Check kits

    • EliteEssentials: Kits are migrated automatically — verify them with /kit list
    • All other mods: Review old kit configurations and recreate them manually in EssentialsPlus

  3. Remove old mod (optional)

    • Only after confirming everything works
    • Keep backups of the old mod's data

Migration Options Explained ​

Usage: /essentialsplus migrate [modname] true

Behavior:

  • ✅ Warps: Existing warps are kept, new warps are added
  • ✅ Homes: Existing homes are kept, new homes are added
  • ✅ Spawns: Existing spawns are kept, new spawns are added (per world)
  • ✅ Users: Intelligently merged
    • Keeps oldest first join timestamp
    • Uses newest last join timestamp
    • Updates username and nickname when available
    • Merges playtime
    • Merges ignore list and IP history
    • Adds balances together (if both exist)

Best for:

  • Updating from an old migration
  • Combining data from multiple sources
  • Preserving custom configurations

Example Output:

[EssentialsPlus] Applied warps: 5 added, 2 skipped
[EssentialsPlus] Applied homes: 23 added, 8 skipped
[EssentialsPlus] Applied spawns: 1 added, 0 skipped
[EssentialsPlus] Applied users: 15 added, 10 updated

Replace Mode: false (Use with Caution) ​

Usage: /essentialsplus migrate [modname] false

Behavior:

  • ⚠️ Warps: All existing warps are deleted, replaced with migrated data
  • ⚠️ Homes: All existing homes are deleted, replaced with migrated data
  • ⚠️ Spawns: All existing spawns are deleted, replaced with migrated data
  • ✅ Users: Still merged intelligently (never fully deleted)

Best for:

  • Fresh start migration
  • First-time migration from another mod
  • Cleaning up corrupted data

Example Output:

[EssentialsPlus] Cleared existing warps
[EssentialsPlus] Applied warps: 5 added, 0 skipped
[EssentialsPlus] Cleared existing homes
[EssentialsPlus] Applied homes: 23 added, 0 skipped

Automatic Backup ​

Before each migration, EssentialsPlus automatically creates a backup:

Backup Location:

mods/EssentialsPlus-Backups/EssentialsPlus-Backup_[timestamp].zip

Backup Contents:

  • warps.json - Current warps
  • homes.json - Current homes
  • spawns.json - Current spawns
  • users/ - All user files

Restoring from Backup:

  1. Stop the server
  2. Copy backup files from mods/EssentialsPlus-Backups/ to mods/fof1092_EssentialsPlus/
  3. Start the server

Troubleshooting ​

Migration Command Not Found ​

Problem: /essentialsplus migrate not recognized

Solution:

  • Check if you have the latest version of EssentialsPlus
  • Ensure you have the required permission: essentialsplus.migrate
  • Verify EssentialsPlus is loaded: /plugins or check console

No Data Migrated ​

Problem: Migration completes but no data is imported

Solution:

  • Verify source mod directory exists and contains data files
  • Check file permissions
  • Review console for error messages about missing files
  • Ensure source mod data format is compatible

World Not Found Errors ​

Problem: Console shows "Unknown world" errors during migration

Solution:

  • Ensure all worlds from the old mod exist on your server
  • Check world names match exactly (case-sensitive)
  • Migrate to a server with the same world configuration

User Balance Issues ​

Problem: User balances incorrect after migration

Explanation:

  • In merge mode, balances are added together
  • This may result in unexpected totals if users exist in both systems

Solution:

  • Review user JSON files in users/ directory
  • Manually adjust balances if needed
  • Use replace mode for first-time migration to avoid duplication

Migration Examples ​

Example 1: First-Time Migration from Hyssentials ​

bash
# Scenario: Switching from Hyssentials to EssentialsPlus for the first time

# 1. Backup
/backup create

# 2. Migrate with replace mode (fresh start)
/essentialsplus migrate hyssentials false

# Expected Output:
[EssentialsPlus] Starting migration from Hyssentials...
[EssentialsPlus] Cleared existing warps
[EssentialsPlus] Applied warps: 8 added, 0 skipped
[EssentialsPlus] Cleared existing homes
[EssentialsPlus] Applied homes: 45 added, 0 skipped
[EssentialsPlus] Applied spawns: 1 added, 0 skipped
[EssentialsPlus] Applied users: 32 added, 0 updated
[Hyssentials Migration] Success - Warps: 8, Homes: 45, Spawns: 1, Users: 32

Example 2: Updating Migration from EliteEssentials ​

bash
# Scenario: Re-running migration after adding new data to EliteEssentials

# 1. Migrate with merge mode (preserve existing)
/essentialsplus migrate eliteessentials true

# Expected Output:
[EssentialsPlus] Starting migration from EliteEssentials...
[EssentialsPlus] EliteEssentials storage auto-detection from config: SQLITE
[EssentialsPlus] Applied warps: 3 added, 8 skipped
[EssentialsPlus] Applied homes: 12 added, 45 skipped
[EssentialsPlus] Applied spawns: 0 added, 1 skipped
[EssentialsPlus] Applied users: 5 added, 32 updated
[EliteEssentials Migration] Success - Warps: 11, Homes: 57, Spawns: 1, Users: 37

Example 3: Migration from EssentialsCore ​

bash
# Scenario: Migrating from EssentialsCore with existing EssentialsPlus data

# 1. Merge to combine data from both sources
/essentialsplus migrate essentialscore true

# Expected Output:
[EssentialsPlus] Starting migration from EssentialsCore...
[EssentialsCore Migration] Loaded 6 warps
[EssentialsCore Migration] Loaded 38 homes from 12 player files
[EssentialsCore Migration] Loaded spawn location from spawn.json
[EssentialsCore Migration] Found kits.toml - automatic kit migration not implemented yet!
[EssentialsCore Migration] Please review and manually migrate kits from: [path]
[EssentialsPlus] Applied warps: 2 added, 4 skipped
[EssentialsPlus] Applied homes: 15 added, 23 skipped
[EssentialsPlus] Applied spawns: 0 added, 1 skipped
[EssentialsPlus] Applied users: 8 added, 12 updated
[EssentialsCore Migration] Success - Warps: 6, Homes: 38, Spawns: 1, Kits: 0, Users: 20

Post-Migration Checklist ​

After completing the migration, verify the following:

  • Warps work correctly

    • Test teleporting to all important warps
    • Verify warp list: /warps

  • Homes are accessible

    • Ask players to check their homes: /homes
    • Test home teleportation: /home [name]

  • Spawn points function

    • Test main spawn: /spawn
    • Verify per-world spawns if configured

  • User data preserved

    • Check player first/last join dates: /seen [player]
    • Verify balances (if using economy)

  • Permissions still work

    • Test permission groups
    • Verify chat formats

  • Kits recreated

    • Manually recreate all kits from the old mod
    • Test kit claiming: /kit [name]

  • Backup created

    • Verify backup exists in backups/migration_[timestamp]/
    • Test restoration process on a local server

Migration Best Practices ​

  1. Always backup before migration

    • Create full server backup
    • Keep old mod data until migration is verified

  2. Test on local server first

    • Never migrate directly on production
    • Verify all data is transferred correctly

  3. Use merge mode for safety

    • Preserves existing data
    • Can re-run migration multiple times safely

  4. Monitor console output

    • Watch for errors or warnings
    • Note which items are skipped

  5. Verify incrementally

    • Check warps first
    • Then homes
    • Then user data
    • Finally spawns and other features

  6. Document your process

    • Note any issues encountered
    • Record custom configurations that need manual transfer

  7. Keep backups accessible

    • Store backups off-server
    • Maintain multiple backup versions

Additional Resources ​