🔄 Updating & Upgrade Path

Most EssentialsPlus updates are straightforward – the plugin automatically handles required migrations during startup without any manual steps. However, for very large version jumps, following a recommended upgrade path helps ensure all historical migrations run correctly and reduces unexpected behavior.

Automatic Migrations

In most cases, no special manual steps are needed. EssentialsPlus automatically runs all required migrations when it loads.

When Do You Need This Guide?

You should follow this guide if you are:

• Making a large version jump (e.g., skipping multiple intermediate releases)

🔍 Check Your Current Version

To find out which version of EssentialsPlus your server is currently running, use this command in-game:

/essentialsplus

This displays your current version in the mod information.

📊 Recommended Upgrade Path

For safe updates across major structural changes, use this upgrade path:

flowchart TD
    A["v1.0.0 - v1.13.2"]
    B["v1.14.0 - v1.16.5<br/>"]
    C["v1.17.0+<br/>"]

    A -->|#1 Update| B -->|#2 Update| C

Why This Path?

v1.14.0–1.16.5

The Command Interception System was introduced (unified warmup, cooldown, and economy pricing)

• Converts old warp settings: if warp.enabled was previously set to false, this gets migrated into the disabledCommands list
• This ensures the /warp command stays disabled with your previous settings First Join configuration was reorganized
• Moves First Join kits to a new location in the config

For detailed migration notes, see Changelog v1.14.0

v1.17.0+ (Current)

The latest versions assume all previous migrations already happened.

📌 Real-World Example

Scenario: You're running EssentialsPlus v1.0.0 and want to update to v1.17.0.

❌ Don't do this: 1.0.0 → 1.17.0 (skipping all the bridge versions)

✅ Do this instead:

1. Update to v1.16.5 (or any version between 1.14.0–1.16.5)
2. Restart the server and let it run the migrations
3. Then update to v1.17.0
4. Restart again

Why? When you skip the bridge versions, the old migration code that converts your old settings never runs. This leaves old settings in your files that don't work anymore, and new features don't get the values they expect.

⚠️ What Happens If You Skip the Bridge Versions?

Skipping directly from very old versions to current releases usually won't crash your server, but you may experience:

Symptom	Cause
Unexpected default values in some features	Old migration paths don't run in modern code
Older settings still in config files but ignored	Config structures aren't converted completely
Missing behavior or features not working as expected	Values aren't mapped to their new equivalents

📋 General Update Best Practices

Regardless of your version jump size, follow these practices for smooth updates:

• Prefer incremental updates when possible, especially for large version gaps
• Always create backups before every update step
• Review the changelog before updating – look for migration notes or breaking changes
• Test on a staging server before applying to production