Essentials Plus - v1.15.13

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
EliteEssentialsv1.1.19✅ Fully Supported
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

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, first/last join, balance
✅ 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+). All kits including their items, slot layout, inventory sections, and cooldowns are imported automatically.

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]

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/

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 if changed
    • 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] 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 ​