Persistent Content & Player Data

If your game has a persistent world, the save data is the most valuable thing on the server. A lost or corrupted world save is a catastrophic event for the players who built in it. How you store, protect, and manage save data determines how much trust players and Hosting Providers can place in your server.

Save File Location

Put your save data in a predictable, configurable location. Hosting platforms mount specific directories for persistent storage. If your server writes save data to an unexpected location, that data will be lost when the container restarts.

Recommended:

• Default to a ./worlds/ or ./saves/ directory relative to the server executable
• Allow the path to be overridden via startup argument or config (-savedir /data/worlds)
• Use a subdirectory per world (e.g., ./worlds/my_world/)

Avoid:

• Writing saves to the system temp directory
• Scattering save files across multiple unrelated directories
• Using absolute paths that assume a specific OS layout
• Saving alongside the server executable with no option to separate them

File Format

Your choice of save format affects corruption resistance, debugging, and hosting automation.

Binary formats are compact and fast to load, but:

• Corrupted binary files are usually unrecoverable
• Debugging requires custom tools
• Version migration is harder (no human-readable structure to inspect)

Text-based formats (JSON, custom text) are larger but:

• Partially corrupted files may still be readable
• Developers and admins can inspect them
• Version migration is more straightforward

Many games use binary for world data (performance matters) and text-based formats for metadata and manifests. This is a reasonable split.

Whichever format you use, include a version header in every save file so your server can detect save format versions and migrate them.

Auto-Save Strategy

Your server should auto-save at regular intervals. Do not rely on players or admins to manually save.

Frequency: Every 5-15 minutes is typical for most games. Shorter intervals mean less data loss on crash but more disk I/O.

Atomic writes: Never write directly to the active save file. If the server crashes mid-write, the save file is corrupted and gone.

Instead:

1. Write to a temporary file (e.g., world.sav.tmp)
2. When the write completes successfully, rename the temp file to replace the active save (world.sav.tmp to world.sav)

File rename is an atomic operation on most filesystems. This guarantees the save file is always either the previous complete save or the new complete save, never a half-written mess.

Backup rotation: Keep the last N saves (e.g., world.sav, world.sav.1, world.sav.2). If the current save is somehow corrupted, admins can roll back to a previous version. 3-5 backups is a reasonable default.

Backup-Friendly Design

Hosting platforms need to back up server data regularly. They do this by copying the save directory to another location or taking filesystem snapshots.

Your server should:

• Tolerate files being copied while running. If a backup tool copies your save files mid-game, it should not crash the server or corrupt the backup.
• Support a save-and-pause command. A console command like save that flushes all pending writes to disk gives backup tools a clean snapshot point.
• Keep save data self-contained. Everything needed to restore a world should be in one directory. If your save data is split across multiple unrelated locations, backups will miss pieces.

World Migration Between Versions

When you release a game update that changes the save format, existing worlds need to survive the upgrade.

Include a version field in every save file. Your server checks this at load time:

• Same version: load normally
• Older version: migrate to the current format, then load
• Newer version: refuse to load (the server is out of date) and tell the admin why

Test migration on real-world saves. Players create worlds that stress every edge case. Test your migration code against saves from community servers, not just your internal test data.

Never silently discard data. If migration cannot preserve everything, tell the admin what was lost and why. “Your world was loaded but 3 custom structures could not be migrated. See migration.log for details.” is far better than a world that loads with chunks missing.

World Portability

Players expect to be able to:

• Download their world from a hosted server to play locally or move to another host
• Upload a world from local play to a hosted server
• Transfer worlds between Hosting Providers

This works automatically if your save format is self-contained (one directory, no external dependencies, no absolute paths baked into the save data).

Test the workflow: create a world on a local server, copy the directory to a hosted server, start the server, and verify the world loads correctly. If it doesn’t, something in your save format is environment-dependent and needs to be fixed.

Multiple Worlds

If your game supports multiple worlds or maps per server:

• Each world should be its own subdirectory under the saves directory
• Include a manifest file (e.g., world.json) in each world directory with metadata:

  {
    "name": "My World",
    "created": "2026-01-10T08:00:00Z",
    "last_played": "2026-01-15T14:45:02Z",
    "version": "1.2.3",
    "seed": 12345
  }

• Support switching between worlds without restarting the server (if feasible for your game)
• Allow admins to create, delete, and rename worlds via console commands or config