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)

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

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