Data Storage

Data Storage

EliteEssentials stores all persistent data in JSON files within the mod's data folder.

Data Folder Location

mods/
  EliteEssentials/
    config.json         - Configuration settings
    messages.json       - Customizable messages (localization)
    homes.json          - Player home locations
    warps.json          - Server warp locations
    back.json           - Player back locations (previous positions)
    spawn.json          - Per-world spawn locations
    kits.json           - Kit definitions
    kit_claims.json     - Player kit claim tracking
    motd.json           - Message of the Day content
    rules.json          - Server rules content
    discord.json        - Discord info content
    autobroadcast.json  - Auto broadcast configuration
    aliases.json        - Command aliases
    players.json        - Player data cache (economy, play time)
    first_join.json     - First join tracking

File Formats

homes.json

Stores all player home locations indexed by player UUID.

{
  "550e8400-e29b-41d4-a716-446655440000": {
    "base": {
      "name": "base",
      "location": {
        "world": "world",
        "x": 100.5,
        "y": 64.0,
        "z": -200.5
      },
      "createdAt": 1704067200000
    },
    "mine": {
      "name": "mine",
      "location": {
        "world": "world",
        "x": 500.0,
        "y": 12.0,
        "z": 300.0
      },
      "createdAt": 1704153600000
    }
  }
}

Structure:

• Top-level keys are player UUIDs
• Each player has a map of home name to home object
• Home names are stored lowercase
• createdAt is Unix timestamp in milliseconds

warps.json

Stores all server warp locations.

{
  "shop": {
    "name": "shop",
    "location": {
      "world": "world",
      "x": 0.0,
      "y": 64.0,
      "z": 0.0
    },
    "permission": "ALL",
    "description": "Server shop - buy and sell items!",
    "createdBy": "EliteScouter",
    "createdAt": 1704067200000
  },
  "arena": {
    "name": "arena",
    "location": {
      "world": "world",
      "x": 1000.0,
      "y": 80.0,
      "z": 1000.0
    },
    "permission": "OP",
    "description": "",
    "createdBy": "Admin",
    "createdAt": 1704153600000
  }
}

Structure:

• Top-level keys are warp names (lowercase)
• permission is either ALL or OP
• description is optional text shown in the warp GUI (set via /warpsetdesc)
• createdBy is the player name who created the warp
• createdAt is Unix timestamp in milliseconds

spawn.json

Stores per-world spawn locations.

{
  "default": {
    "world": "default",
    "x": 0.0,
    "y": 64.0,
    "z": 0.0,
    "yaw": 0.0,
    "pitch": 0.0
  },
  "explore": {
    "world": "explore",
    "x": 100.0,
    "y": 80.0,
    "z": -50.0,
    "yaw": 90.0,
    "pitch": 0.0
  }
}

Structure:

• Top-level keys are world names
• Each world can have its own spawn point set via /setspawn
• yaw and pitch control the direction the player faces after teleporting
• Spawn protection is applied to each world that has a spawn set

players.json

Stores player data cache including economy balances and play time.

{
  "550e8400-e29b-41d4-a716-446655440000": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "EliteScouter",
    "firstJoin": 1704067200000,
    "lastSeen": 1704153600000,
    "wallet": 1500.0,
    "playTime": 36000
  }
}

Structure:

• Top-level keys are player UUIDs
• name is the player's current username (updated on each login)
• firstJoin is Unix timestamp of first server join
• lastSeen is Unix timestamp of last logout (or current time if online)
• wallet is the player's economy balance (requires economy enabled)
• playTime is total play time in seconds

aliases.json

Stores custom command aliases.

{
  "explore": {
    "command": "warp explore",
    "permission": "everyone",
    "silent": true
  },
  "hub": {
    "command": "warp spawn",
    "permission": "everyone",
    "silent": false
  },
  "staffwarp": {
    "command": "warp staff",
    "permission": "op",
    "silent": false
  }
}

Structure:

• Top-level keys are alias names (the command players type)
• command is the command to execute (without leading /)
• permission is "everyone", "op", or a custom permission node
• silent when true, suppresses teleport confirmation messages (warmup countdown still shows)

back.json

Stores player back location history.

{
  "550e8400-e29b-41d4-a716-446655440000": [
    {
      "world": "world",
      "x": 100.0,
      "y": 64.0,
      "z": -200.0
    },
    {
      "world": "world",
      "x": 50.0,
      "y": 70.0,
      "z": -100.0
    }
  ]
}

Structure:

• Top-level keys are player UUIDs
• Each player has an array of locations (most recent first)
• Array size is limited by back.maxHistory config

messages.json

Stores all customizable player-facing messages (localization).

{
  "prefix": "[EliteEssentials] ",
  "noPermission": "You don't have permission to use this command.",
  "playerNotFound": "Player not found.",
  "commandDisabled": "This command is disabled.",
  "onCooldown": "You must wait {seconds} seconds before using this command again.",
  "warmupStarted": "Teleporting in {seconds} seconds. Don't move!",
  "warmupCancelled": "Teleport cancelled - you moved!",
  "warmupCountdown": "Teleporting in {seconds}...",
  "homeSet": "Home '{name}' has been set!",
  "homeTeleported": "Teleported to home '{name}'."
}

Structure:

• Key-value pairs where key is the message identifier
• Values support placeholders like {player}, {seconds}, {name}
• Supports color codes (&a, &c, &l, &o, &r)
• See Placeholders for complete message reference

Note: Messages were moved from config.json to messages.json in version 1.0.9. Existing messages are automatically migrated on first startup.

Location Object

All location objects share the same structure:

{
  "world": "world",
  "x": 100.5,
  "y": 64.0,
  "z": -200.5
}

Field	Type	Description
world	string	World/dimension name
x	double	X coordinate
y	double	Y coordinate (height)
z	double	Z coordinate

motd.json

Stores the Message of the Day content with color code support.

{
  "lines": [
    "",
    "&e&lWelcome to {server}, {player}!",
    "&7There are &a{playercount}&7 players online.",
    "&7You are in world &b{world}&7.",
    "",
    "&6> Server Resources:",
    "&7* Type &a/help&7 for commands",
    "&7* Type &a/rules&7 for rules",
    "",
    "&7EliteEssentials is brought to you by: &bEliteScouter",
    "&9https://github.com/EliteScouter/EliteEssentials",
    ""
  ]
}

Structure:

• Array of strings, each representing a line
• Supports color codes (&a, &c, &l, &o, &r)
• Supports placeholders: {player}, {server}, {world}, {playercount}
• URLs are automatically detected and made clickable

rules.json

Stores the server rules content with color code support.

{
  "lines": [
    "",
    "&c&l========================================",
    "&e&l              SERVER RULES",
    "&c&l========================================",
    "",
    "&a1. &7Be Respectful to others",
    "&a2. &7No Cheating / Hacking",
    "&a3. &7No Griefing",
    "&a4. &7Have fun!",
    "",
    "&6Breaking these rules may result in a ban.",
    ""
  ]
}

Structure:

• Array of strings, each representing a line
• Supports color codes for formatting
• Fully customizable content

first_join.json

Tracks which players have joined the server before.

{
  "players": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  ]
}

Structure:

• Array of player UUIDs who have joined before
• Used to determine if a player is joining for the first time
• Enables special first-join messages

discord.json

Stores the server discord information with color code support.

{
  "lines": [
    "",
    "&b&l========================================",
    "&e&l         JOIN OUR DISCORD!",
    "&b&l========================================",
    "",
    "&aWELCOME TO Our Server!",
    "",
    "&7Please join our discord at:",
    "&bhttps://discord.gg/YourInvite",
    "",
    "&7Click the link above to join!",
    ""
  ]
}

Structure:

• Array of strings, each representing a line
• Supports color codes for formatting
• URLs are automatically detected and made clickable
• Fully customizable content

autobroadcast.json

Stores automatic broadcast configurations.

{
  "broadcasts": [
    {
      "id": "example",
      "enabled": true,
      "intervalSeconds": 600,
      "prefix": "",
      "random": false,
      "requirePlayers": true,
      "messages": [
        "&5&l[Discord]&7 - &fJoin our community!\n&7Chat, updates & support.\n&bhttps://discord.gg/YourInvite",
        "&6&l[Tip]&7 - &fNeed help?\n&7Check out &e/help &7for commands."
      ]
    }
  ]
}

Structure:

• broadcasts - Array of broadcast group objects
• Each broadcast group has:
  • id - Unique identifier
  • enabled - Whether this broadcast is active
  • intervalSeconds - Time between broadcasts
  • prefix - Optional prefix (supports color codes)
  • random - If true, picks random message; if false, cycles sequentially
  • requirePlayers - Only broadcast when players are online
  • messages - Array of messages (use \n for multi-line)

Data Persistence

When Data is Saved

• Homes - Saved immediately after each /sethome or /delhome
• Warps - Saved immediately after each /setwarp or /delwarp
• Back - Saved periodically and on server shutdown
• MOTD - Loaded on startup and when /ee reload is used
• Rules - Loaded on startup and when /ee reload is used
• Discord - Loaded on startup and when /ee reload is used
• Auto Broadcast - Loaded on startup and when /ee reload is used
• First Join - Saved immediately when a new player joins
• All Data - Saved on server shutdown

Automatic Saving

EliteEssentials automatically saves all data when:

• The server shuts down gracefully
• A home or warp is created/deleted
• The /eliteessentials reload command is run

Data Safety

• Data files use atomic writes to prevent corruption
• Existing data is preserved during mod updates
• Invalid JSON entries are logged and skipped (not deleted)

Backup Recommendations

It is recommended to regularly backup the mods/EliteEssentials/ folder, especially:

1. Before updating EliteEssentials
2. Before making major configuration changes
3. As part of your regular server backup routine

Backup Command Example

# Linux/Mac
cp -r mods/EliteEssentials/ backups/EliteEssentials-$(date +%Y%m%d)/

# Windows
xcopy mods\EliteEssentials backups\EliteEssentials-%date:~-4,4%%date:~-10,2%%date:~-7,2% /E /I

Manual Data Editing

You can manually edit the JSON files while the server is stopped. Be careful to:

1. Stop the server first - Editing while running may cause data loss
2. Validate JSON syntax - Use a JSON validator before saving
3. Maintain structure - Keep the same field names and types
4. Use valid UUIDs - Player UUIDs must be valid format

Finding Player UUIDs

Player UUIDs can be found:

• In server logs when players join
• Using online UUID lookup tools with player names
• In the existing data files

Data Migration

When updating EliteEssentials:

• Existing data files are preserved
• New fields are added with default values
• Deprecated fields are ignored (not deleted)

No manual migration is required when updating.

Troubleshooting

Data Not Saving

1. Check file permissions on the data folder
2. Ensure the server has write access
3. Check server logs for error messages
4. Verify disk space is available

Corrupted Data File

If a data file becomes corrupted:

1. Stop the server
2. Check the file for JSON syntax errors
3. Fix the syntax or restore from backup
4. Start the server

Missing Data After Update

1. Check if the data folder location changed
2. Look for data in both old and new locations
3. Manually copy data files if needed

Performance Considerations

• Data files are loaded into memory on server start
• Large numbers of homes/warps may increase memory usage
• Consider periodic cleanup of unused data for very large servers