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)
    warps.json            - Server warp locations
    spawn.json            - Per-world spawn locations
    kits.json             - Kit definitions
    motd.json             - Message of the Day content
    rules.json            - Server rules content
    discord.json          - Discord info content
    autobroadcast.json    - Auto broadcast configuration
    groupchat.json        - Group chat channel configuration
    aliases.json          - Command aliases
    playtime_rewards.json - PlayTime reward definitions
    playtime_claims.json  - PlayTime reward claim tracking
    players/              - Per-player data files
      <uuid>.json         - Individual player data

File Formats

Player Data (players/.json)

Each player has their own data file stored by UUID. This contains all player-specific data.

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "EliteScouter",
  "firstJoin": 1704067200000,
  "lastSeen": 1704153600000,
  "wallet": 1500.0,
  "playTime": 36000,
  "homes": {
    "base": {
      "name": "base",
      "world": "default",
      "x": 100.5,
      "y": 64.0,
      "z": -200.5,
      "yaw": 90.0,
      "pitch": 0.0,
      "createdAt": 1704067200000
    }
  },
  "backLocations": [
    {
      "world": "default",
      "x": 100.0,
      "y": 64.0,
      "z": -200.0,
      "yaw": 0.0,
      "pitch": 0.0
    }
  ],
  "kitClaims": {
    "starter": 1704067200000,
    "vip": 1704153600000
  },
  "mail": [
    {
      "id": "abc123",
      "from": "Steve",
      "fromUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "message": "Hey, want to trade?",
      "timestamp": 1704067200000,
      "read": false
    }
  ],
  "playTimeRewardsClaimed": ["hourly_bonus", "100h_vip"]
}

Structure:

• uuid - Player's UUID
• name - Player's current username (updated on each login)
• firstJoin - Unix timestamp of first server join
• lastSeen - Unix timestamp of last logout
• wallet - Economy balance (requires economy enabled)
• playTime - Total play time in seconds
• homes - Map of home name to home object
• backLocations - Array of previous locations (most recent first)
• kitClaims - Map of kit ID to last claim timestamp
• mail - Array of mail messages
• playTimeRewardsClaimed - Array of claimed one-time reward IDs

warps.json

Stores all server warp locations.

{
  "shop": {
    "name": "shop",
    "location": {
      "world": "default",
      "x": 0.0,
      "y": 64.0,
      "z": 0.0,
      "yaw": 0.0,
      "pitch": 0.0
    },
    "permission": "ALL",
    "description": "Server shop - buy and sell items!",
    "createdBy": "EliteScouter",
    "createdAt": 1704067200000
  }
}

Structure:

• Top-level keys are warp names (lowercase)
• permission is either ALL or OP
• description is optional text shown in the warp GUI
• 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
• Spawn protection is applied to each world that has a spawn set

kits.json

Stores kit definitions.

[
  {
    "id": "starter",
    "name": "Starter Kit",
    "cooldownSeconds": 0,
    "oneTime": true,
    "items": [
      {
        "itemId": "hytale:wooden_sword",
        "quantity": 1,
        "slot": "hotbar"
      },
      {
        "itemId": "hytale:bread",
        "quantity": 16,
        "slot": "storage"
      }
    ]
  }
]

Structure:

• Array of kit objects
• id - Unique identifier (used in permissions)
• name - Display name
• cooldownSeconds - Time between claims (0 = no cooldown)
• oneTime - If true, can only be claimed once ever
• items - Array of items in the kit

aliases.json

Stores custom command aliases.

{
  "explore": {
    "command": "warp explore",
    "permission": "everyone",
    "silent": true
  },
  "hub": {
    "command": "warp spawn",
    "permission": "everyone",
    "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

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.",
  "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)
• Supports hex colors (&#RRGGBB)
• See Placeholders for complete message reference

motd.json

Stores the Message of the Day content with per-world support.

{
  "lines": [
    "&e&lWelcome to {server}, {player}!",
    "&7There are &a{playercount}&7 players online."
  ],
  "worldMotds": {
    "explore": {
      "enabled": true,
      "showAlways": false,
      "lines": [
        "&a=== Welcome to Explore! ===",
        "&7This is the exploration world."
      ]
    }
  }
}

Structure:

• lines - Global MOTD shown on first join
• worldMotds - Per-world MOTDs
  • enabled - Enable/disable this world's MOTD
  • showAlways - Show every time (true) or once per session (false)
  • lines - Array of message lines

rules.json

Stores the server rules content.

{
  "lines": [
    "&c&l========================================",
    "&e&l              SERVER RULES",
    "&c&l========================================",
    "&a1. &7Be Respectful to others",
    "&a2. &7No Cheating / Hacking"
  ]
}

discord.json

Stores the server discord information.

{
  "lines": [
    "&b&l========================================",
    "&e&l         JOIN OUR DISCORD!",
    "&b&l========================================",
    "&bhttps://discord.gg/YourInvite"
  ]
}

URLs are automatically made clickable.

groupchat.json

Stores group chat channel configurations.

[
  {
    "groupName": "admin",
    "displayName": "Admin Chat",
    "prefix": "[ADMIN]",
    "color": "#f85149",
    "enabled": true,
    "requiresGroup": true
  },
  {
    "groupName": "trade",
    "displayName": "Trade Chat",
    "prefix": "[TRADE]",
    "color": "#f0c674",
    "enabled": true,
    "requiresGroup": false
  }
]

Structure:

• groupName - Chat identifier (case-insensitive)
• displayName - Friendly name shown in messages
• prefix - Prefix shown before messages
• color - Hex color for the prefix
• enabled - Whether this chat is active
• requiresGroup - true for LuckPerms group-based, false for permission-based

autobroadcast.json

Stores automatic broadcast configurations.

{
  "broadcasts": [
    {
      "id": "discord",
      "enabled": true,
      "intervalSeconds": 600,
      "prefix": "",
      "random": false,
      "requirePlayers": true,
      "messages": [
        "&5&l[Discord]&7 - Join us!\n&bhttps://discord.gg/YourInvite"
      ]
    }
  ]
}

Structure:

• 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)

playtime_rewards.json

Stores playtime reward definitions.

[
  {
    "id": "hourly_bonus",
    "name": "Hourly Bonus",
    "minutesRequired": 60,
    "repeatable": true,
    "enabled": true,
    "message": "&a[Reward] &fYou received your hourly bonus!",
    "commands": ["eco add {player} 100"]
  },
  {
    "id": "100h_vip",
    "name": "100 Hour VIP",
    "minutesRequired": 6000,
    "repeatable": false,
    "enabled": true,
    "message": "&d[Milestone] &f100 hours played! VIP unlocked!",
    "commands": [
      "lp user {player} group set vip",
      "eco add {player} 5000"
    ]
  }
]

Structure:

• id - Unique identifier for tracking claims
• name - Display name
• minutesRequired - Minutes of playtime required
• repeatable - If true, triggers every X minutes; if false, one-time
• enabled - Enable/disable this reward
• message - Message sent when reward is granted
• commands - Commands to execute (supports {player} placeholder)

Location Object

All location objects share the same structure:

{
  "world": "default",
  "x": 100.5,
  "y": 64.0,
  "z": -200.5,
  "yaw": 0.0,
  "pitch": 0.0
}

Field	Type	Description
world	string	World/dimension name
x	double	X coordinate
y	double	Y coordinate (height)
z	double	Z coordinate
yaw	float	Horizontal rotation (0-360)
pitch	float	Vertical rotation (-90 to 90)

Data Persistence

When Data is Saved

• Player Data - Saved immediately after changes (homes, kit claims, mail)
• Warps - Saved immediately after each create/delete
• Spawn - Saved immediately after /setspawn
• Config Files - Loaded on startup and when /ee reload is used
• All Data - Saved on server shutdown

Automatic Saving

EliteEssentials automatically saves all data when:

• The server shuts down gracefully
• A home, warp, or other data 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)
• Thread-safe file operations using synchronized blocks

Legacy Data Migration

EliteEssentials automatically migrates data from older formats:

• homes.json (legacy) -> players/<uuid>.json
• back.json (legacy) -> players/<uuid>.json
• kit_claims.json (legacy) -> players/<uuid>.json
• first_join.json (legacy) -> players/<uuid>.json
• players.json (legacy) -> players/<uuid>.json

Migration happens automatically on first startup after updating.

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 from Other Plugins

EliteEssentials supports migration from other essentials plugins:

• EssentialsCore - Use /eemigration essentialscore
• EssentialsPlus - Use /eemigration essentialsplus
• HomesPlus - Use /eemigration homesplus
• Hyssentials - Use /eemigration hyssentials

Migration imports homes, warps, and player data where applicable.

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
4. Check for migration logs in server console

Performance Considerations

• Per-player data files reduce memory usage for large servers
• Data files are loaded on-demand when players join
• Consider periodic cleanup of inactive player data for very large servers
• Use the debug mode to monitor file I/O if experiencing issues