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
    homes.json        - Player home locations
    warps.json        - Server warp locations
    back.json         - Player back locations (previous positions)
    spawn.json        - Server spawn location
    kits.json         - Kit definitions
    kit_claims.json   - Player kit claim tracking
    motd.json         - Message of the Day content
    rules.json        - Server rules content
    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",
    "createdBy": "EliteScouter",
    "createdAt": 1704067200000
  },
  "arena": {
    "name": "arena",
    "location": {
      "world": "world",
      "x": 1000.0,
      "y": 80.0,
      "z": 1000.0
    },
    "permission": "OP",
    "createdBy": "Admin",
    "createdAt": 1704153600000
  }
}

Structure:

• Top-level keys are warp names (lowercase)
• permission is either ALL or OP
• createdBy is the player name who created the warp
• createdAt is Unix timestamp in milliseconds

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

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

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