GroupeZ Docs

Data Migration

Migrate data from other plugins to zEssentials

zEssentials includes built-in data converters that allow you to migrate player data from other popular plugins. Each converter reads data from the source plugin's storage format and imports it into the zEssentials database.

Prerequisites

All converters require zEssentials to be configured with SQL storage (SQLITE, MYSQL, MARIADB or HIKARICP). The JSON storage is not supported as a target for data migration. Ensure your database is configured and working before running any converter. For production, use MySQL/MariaDB rather than SQLite.

Before You Start

  1. Back up your database before running any converter.
  2. Close the server to players (e.g. with the whitelist) or ensure no players are online during migration to prevent data conflicts.
  3. Verify that the source plugin's data files are accessible from the server.
  4. Run the converter from the server console for best results.

Command

All converters are started with the same command:

/zessentials convert <plugin>
ArgumentValues
<plugin>essentialsx, cmi, sunlight, playervaultx, coinsengine, huskhomes, axvaults
  • Aliases: /ess convert, /zessentials conv, /zessentials c
  • Permission: essentials.convert

The conversion runs asynchronously. Progress and the final result (You have just converted your ... data to zEssentials !) are sent to the command sender.

Homes only from EssentialsX

If you only want to import the homes of EssentialsX (without balances), you can also use /homeimport essentialsx (permission essentials.home.import). It reads the same plugins/Essentials/userdata/ files, skips homes whose world does not exist, and works with every storage type. See the Home module.

EssentialsX

Migrates player data from EssentialsX to zEssentials.

Data Migrated

Data TypeDetails
UsersPlayer UUID and last known username
EconomyPlayer money balances
HomesAll player homes with full location data

How It Works

The converter reads from EssentialsX's flat-file storage located at plugins/Essentials/userdata/. Each file in this directory is named after a player's UUID (e.g., 550e8400-e29b-41d4-a716-446655440000.yml) and contains that player's data.

From each player file, the converter extracts:

  • money -- The player's economy balance
  • last-account-name -- The player's last known username
  • homes -- A map of home names, each containing:
    • world-name -- The world the home is in
    • x, y, z -- The coordinates
    • yaw, pitch -- The player's facing direction

Prerequisites

  • EssentialsX userdata files must be present at plugins/Essentials/userdata/
  • zEssentials must be configured with SQL storage

Usage

  1. Ensure the plugins/Essentials/userdata/ directory contains the player .yml files
  2. Run /zessentials convert essentialsx from the console
  3. The converter will iterate through all .yml files and import each player's data

CMI

Migrates player data from CMI to zEssentials.

Data Migrated

Data TypeDetails
UsersPlayer UUID and username
EconomyPlayer money balances
HomesAll player homes with full location data

How It Works

The converter reads from CMI's SQLite database file (cmi.sqlite.db). This file must be placed in the plugins/zEssentials/ folder before running the converter.

Home locations in CMI are stored as serialized strings. The converter parses these strings to extract the world name, coordinates, yaw, and pitch for each home.

Prerequisites

  • Copy cmi.sqlite.db from the CMI plugin folder into plugins/zEssentials/
  • zEssentials must be configured with SQL storage

Usage

  1. Copy the cmi.sqlite.db file to plugins/zEssentials/
  2. Run /zessentials convert cmi from the console
  3. The converter will read the CMI database and import users, balances, and homes

CoinsEngine

Migrates multi-currency balances from CoinsEngine to zEssentials.

Data Migrated

Data TypeDetails
EconomyAll multi-currency balances per player

How It Works

The converter reads from two sources:

  1. plugins/CoinsEngine/data.db -- The SQLite database containing player balance data
  2. plugins/CoinsEngine/currencies/*.yml -- Currency configuration files used to determine the column names in the database

Each currency defined in CoinsEngine maps to a column in the database. The converter reads the column names from the currency configuration files and extracts the corresponding balance values for each player.

Prerequisites

  • The CoinsEngine data file must be present at plugins/CoinsEngine/data.db
  • Currency configuration files must be present at plugins/CoinsEngine/currencies/
  • All currencies must already exist in your zEssentials economy configuration before running the converter. Create matching currencies in zEssentials first, then run the migration.
  • zEssentials must be configured with SQL storage

Usage

  1. Ensure plugins/CoinsEngine/data.db and plugins/CoinsEngine/currencies/ are accessible
  2. Create all matching currencies in the zEssentials economy module configuration
  3. Run /zessentials convert coinsengine from the console
  4. The converter will map each CoinsEngine currency to its zEssentials equivalent and import all balances

HuskHomes

Migrates player data from HuskHomes to zEssentials.

Data Migrated

Data TypeDetails
UsersPlayer UUID and username
HomesAll player homes with full location data

How It Works

The converter reads from HuskHomes' SQLite database (HuskHomesData.db) if the file is present in plugins/zEssentials/, otherwise it reads the HuskHomes tables from the zEssentials database (useful when both plugins share the same MySQL database). The converter reads four tables:

  1. huskhomes_users -- Contains player UUIDs and usernames
  2. huskhomes_homes -- Contains home names and owner references
  3. huskhomes_saved_positions -- Links each home to a position
  4. huskhomes_position_data -- Contains the actual coordinates (world, x, y, z, yaw, pitch)

These tables are combined to reconstruct each player's complete home data.

Prerequisites

  • Either copy HuskHomesData.db from the HuskHomes plugin folder into plugins/zEssentials/, or ensure zEssentials can access the existing HuskHomes database tables
  • zEssentials must be configured with SQL storage

Usage

  1. Copy the HuskHomesData.db file to plugins/zEssentials/ (or configure access to the shared database)
  2. Run /zessentials convert huskhomes from the console
  3. The converter will combine the users, homes, and positions tables and import all player home data

PlayerVaultX

Migrates vault items from PlayerVaultX to zEssentials.

Data Migrated

Data TypeDetails
VaultsAll player vault contents (items)

How It Works

The converter reads from PlayerVaultX's flat-file storage located at plugins/PlayerVaults/newvaults/. Each file contains a player's vault data with items stored as Base64-encoded ItemStack arrays using the CardboardBoxSerialization format.

The converter decodes each Base64 string back into Minecraft ItemStack objects and imports them into the zEssentials vault system.

Prerequisites

  • PlayerVaultX data files must be present at plugins/PlayerVaults/newvaults/
  • The PlayerVaults plugin must be enabled on the server (required for the CardboardBoxSerialization deserialization classes)
  • zEssentials must be configured with SQL storage

Usage

  1. Ensure the PlayerVaults plugin is installed and enabled on the server
  2. Verify that plugins/PlayerVaults/newvaults/ contains the player vault .yml files
  3. Run /zessentials convert playervaultx from the console
  4. The converter will decode and import all vault items for each player

AxVaults

Migrates vault items from AxVaults to zEssentials.

Data Migrated

Data TypeDetails
VaultsAll player vault contents (items)

How It Works

The converter reads vault data directly from the AxVaults database. It uses Java reflection to access the AxVaults plugin's internal database connection, then queries the vault tables to retrieve all stored items for each player.

Prerequisites

  • The AxVaults plugin must be enabled on the server (required for database connection access via reflection)
  • zEssentials must be configured with SQL storage

Usage

  1. Ensure the AxVaults plugin is installed and enabled on the server
  2. Run /zessentials convert axvaults from the console
  3. The converter will access the AxVaults database connection and import all vault items

Sunlight

Migrates player data from Sunlight to zEssentials.

Data Migrated

Data TypeDetails
UsersPlayer UUID and username
HomesAll player homes with full location data

How It Works

The converter reads from Sunlight's SQLite database (data.db). This file must be placed in the plugins/zEssentials/ folder before running the converter.

Sunlight stores location data in a different format than zEssentials. The converter handles the format translation:

Sunlight FormatzEssentials Format
x, y, z, pitch, yaw, worldworld, x, y, z, yaw, pitch

The converter remaps the fields to match the zEssentials location structure during import.

Prerequisites

  • Copy data.db from the Sunlight plugin folder into plugins/zEssentials/
  • zEssentials must be configured with SQL storage

Usage

  1. Copy the data.db file to plugins/zEssentials/
  2. Run /zessentials convert sunlight from the console
  3. The converter will read the Sunlight database, translate the location format, and import users and homes

Summary

ConverterUsersEconomyHomesVaultsSource FormatFile Placement
EssentialsXYesYesYes--Flat-file YAMLplugins/Essentials/userdata/ (in-place)
CMIYesYesYes--SQLiteCopy cmi.sqlite.db to plugins/zEssentials/
CoinsEngine--Yes----SQLite + YAMLplugins/CoinsEngine/ (in-place)
HuskHomesYes--Yes--SQLite / MySQLCopy HuskHomesData.db to plugins/zEssentials/ or use a shared database
PlayerVaultX------YesFlat-file YAML (Base64)plugins/PlayerVaults/newvaults/ (in-place)
AxVaults------YesDatabase (via reflection)Plugin must be enabled
SunlightYes--Yes--SQLiteCopy data.db to plugins/zEssentials/

All converters require an SQL storage (SQLITE, MYSQL, MARIADB or HIKARICP) to be configured in zEssentials. The JSON storage cannot be used as the target storage for migrations.

Database

Database architecture, tables, and storage backends for zEssentials

Main Configuration

Main configuration file (config.yml) for zEssentials

On this page

CommandEssentialsXData MigratedHow It WorksPrerequisitesUsageCMIData MigratedHow It WorksPrerequisitesUsageCoinsEngineData MigratedHow It WorksPrerequisitesUsageHuskHomesData MigratedHow It WorksPrerequisitesUsagePlayerVaultXData MigratedHow It WorksPrerequisitesUsageAxVaultsData MigratedHow It WorksPrerequisitesUsageSunlightData MigratedHow It WorksPrerequisitesUsageSummary
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.